Il problema che nessuno vuole ammettere
Trello è troppo semplice. Jira è troppo complesso. Notion fa tutto ma non fa niente bene. ClickUp ha così tante funzioni che il primo onboarding dura mezza giornata. Questa è la realtà che sento raccontare dalla maggior parte delle PMI italiane quando parliamo di gestione dei progetti interni.
Il problema non è la mancanza di strumenti — è l'eccesso. Gli strumenti generalisti si portano dietro anni di feature aggiunte per compiacere ogni tipo di cliente, e il risultato è un'interfaccia che spaventa i nuovi utenti e rallenta chi dovrebbe semplicemente spostare un task da "in corso" a "fatto".
Ho deciso di costruire Kyoma: un sistema di gestione task opinionato, progettato per team piccoli e medi, con esattamente le funzioni necessarie e nessuna di quelle superflue. Questo articolo racconta le decisioni prese durante la progettazione — non solo il cosa, ma il perché.
Partire dai requisiti, non dalla tecnologia
Prima di aprire un editor ho passato tempo a definire cosa deve fare lo strumento. Le domande che mi sono posto sono le stesse che faccio ai clienti quando valutiamo un software gestionale:
- Chi usa lo strumento e con quale frequenza?
- Quali sono i flussi di lavoro reali, non quelli teorici?
- Cosa deve essere visibile subito, senza navigare?
- Dove finisce la gestione task e dove inizia qualcosa di diverso?
L'architettura: poche scelte, motivate bene
Next.js 15 con App Router è la base. Non perché sia alla moda — perché risolve un problema reale: avere API, pagine server-rendered e componenti interattivi nello stesso progetto, senza gestire due codebase separate. Per un tool interno che ha sia logica di business che interfaccia ricca, questa coesione vale.
Il database è Prisma con SQLite in sviluppo e PostgreSQL in produzione. SQLite non va sottovalutato: per team fino a 20-30 persone regge senza problemi e azzera la complessità di setup locale. Il passaggio a PostgreSQL in produzione è una modifica di una riga nel file di configurazione — Prisma astrae tutto il resto.
Lo schema dati ha sei entità principali: User, Team, Project, Task, Comment, Activity. La parte interessante è Task che ha un campo parentId che punta a se stesso — questo permette i sotto-task senza aggiungere una tabella separata. Ogni task ha position per il riordinamento kanban e status come stringa enum tra todo, in_progress e done.
La validazione di tutti gli input in entrata passa per Zod — non per eleganza, ma perché un campo mancante in una POST non validata che arriva in produzione è un bug che si trova a mezzanotte.
Il Kanban e il drag & drop: dove la semplicità inganna
La board Kanban sembra la parte più semplice. È invece quella con più insidie. Il drag & drop interattivo richiede una libreria dedicata — ho scelto @dnd-kit perché è accessibile, leggera e non impone strutture DOM rigide. Ma il punto critico non è il drag, è cosa succede al rilascio.
Quando un utente sposta una card da "Da fare" a "In corso", l'interfaccia deve reagire immediatamente — non dopo che il server ha risposto. Questo si chiama ottimistic update: aggiorni lo stato locale della UI prima di fare la chiamata API, e fai rollback solo in caso di errore. Senza questo pattern, su una connessione lenta il drag sembra rotto anche quando funziona.
Il codice che gestisce questo flusso in KanbanBoard.tsx è circa 40 righe. La logica è: salva lo stato precedente, applica il nuovo stato, chiama PATCH /api/tasks/:id, e in caso di errore ripristina lo stato precedente mostrando un toast di errore. Semplice da descrivere, facile da sbagliare se non ci si pensa prima.
L'import CSV: una feature che vale il 30% dell'adozione
Ogni tool di gestione task che viene introdotto in un'azienda parte con lo stesso problema: i dati esistono già, in qualche forma. Un foglio Excel condiviso su Drive, una lista su Notion, un file Word con i task del progetto scritti a mano. Se obblighi le persone a reinserire tutto manualmente, il nuovo strumento viene abbandonato in due settimane.
L'import CSV risolve questo problema. Il flusso è deliberatamente semplice: l'utente carica un file, l'app mostra un'anteprima con la validazione riga per riga — le righe valide in verde, quelle con errori in rosso con il motivo specifico — e l'utente importa solo quelle valide. Nessuna magia, nessuna mappatura complessa di colonne.
Il parsing avviene client-side con papaparse prima di mandare qualsiasi dato al server. Questo significa che l'utente vede il feedback di validazione istantaneamente, senza round trip. Il server riceve solo { projectId, rows[] } e applica una validazione indipendente — non ci si fida mai solo del client.
Le colonne supportate sono sei: titolo (obbligatorio), descrizione, stato, priorità, scadenza, assegnatari. Gli assegnatari vengono risolti per email — se l'utente non esiste nel sistema viene ignorato silenziosamente con una nota nel risultato dell'importazione.
La documentazione di progetto: dove la decisione è più importante del codice
Questa è la parte del progetto dove ho passato più tempo a ragionare prima di scrivere una riga. Il requisito era chiaro: documentazione collegata al progetto e ai singoli task, senza uscire dall'applicazione. La prima risposta istintiva è "costruiamo un editor interno". È quasi sempre la risposta sbagliata.
Costruire storage proprietario significa gestire upload, quota, versioning, permessi per file, preview di PDF e DOCX, e aggiornamenti di sicurezza per tutto questo stack. Significa anche che quando un utente vuole modificare un documento deve farlo dentro la tua app — non in Word, non in Google Docs, non nell'ambiente in cui lavora già.
La risposta corretta per il contesto di una PMI italiana nel 2025 è Google Drive. Non perché sia la soluzione più elegante, ma perché risolve il problema reale: i documenti esistono già, le persone sanno già come usare Drive, il versioning è già lì, la collaborazione è già lì. Kyoma diventa il punto di accesso e di organizzazione — Drive fa il lavoro pesante dello storage. Zero infrastruttura da costruire e mantenere.
Autenticazione: la scelta che condiziona tutto il resto
Il progetto nasce con autenticazione GitHub tramite NextAuth.js. È la scelta rapida per un tool orientato ai developer. Ma appena si allarga la conversazione a chi realmente usa un task manager in azienda — project manager, designer, commerciali, clienti — il limite diventa evidente: non tutti hanno GitHub, ma tutti hanno Google.
La soluzione è offrire entrambi i provider senza duplicare gli account. Se un utente si registra con GitHub usando mario@azienda.it e poi accede con Google usando la stessa email, il sistema riconosce l'email e collega i due account allo stesso profilo. NextAuth v5 supporta questo nativamente.
La logica di accesso a Drive diventa conseguente: chi accede con Google o collega un account Google dal proprio profilo sblocca automaticamente la sezione documentazione. Chi usa solo GitHub la vede disabilitata con un invito a collegare Google. Nessuna funzione nascosta, nessuna sorpresa — una scelta consapevole dell'utente con benefici chiari.
I limiti che nessuno ti dice prima
Ogni scelta tecnica porta con sé dei compromessi. Eccoli in modo diretto.
- L'integrazione Drive dipende dal token Google dell'owner del progetto: se revoca i permessi all'app, la cartella smette di essere accessibile per tutti i membri
- I token Google scadono ogni ora e il refresh automatico va gestito esplicitamente — non è garantito da NextAuth out of the box
- Il refresh token viene emesso da Google una sola volta: se lo perdi per qualsiasi motivo, l'utente deve ricollegare manualmente l'account
- Le policy Google Workspace aziendali possono bloccare la condivisione di file con account esterni — un 403 che devi intercettare e comunicare bene
- SQLite in sviluppo e PostgreSQL in produzione richiedono attenzione sulle differenze di tipo — evita Decimal se vuoi mantenere compatibilità cross-database
Cosa resta fuori e perché
Kyoma non ha notifiche real-time, non ha un editor rich-text interno, non ha Gantt, non ha time tracking. Non perché queste funzioni siano inutili — perché non erano nel requisito iniziale e aggiungerle avrebbe spostato il focus dal problema che si voleva risolvere.
Questa è la lezione più importante di questo progetto: uno strumento utile non è quello che fa di più, è quello che fa bene le cose giuste per il suo contesto. Un task manager per un team di dieci persone non ha bisogno delle stesse funzioni di un project management enterprise da centomila utenti. Ha bisogno di funzionare senza richiedere un manuale, di adattarsi ai flussi di lavoro esistenti e di non diventare esso stesso un progetto da gestire.
--- Vuoi approfondire come valutare uno strumento IT rispetto alle esigenze reali della tua azienda? Leggi anche Come scegliere il consulente IT giusto e Quando esternalizzare l'IT della tua azienda.