FlowBoard — Kanban Board con AI Assistant

Cos'è

FlowBoard è una Kanban board interattiva con un assistente AI contestuale integrato. Permette di organizzare task in tre colonne (Todo, In Progress, Done) con supporto a priorità, tag, scadenze e drag & drop. L'AI assistant conosce in tempo reale lo stato della board e risponde in linguaggio naturale a domande come "quali task sono in ritardo?" o "scrivi una descrizione per questo task".

Problema che risolve rispetto a una Kanban classica: le board tradizionali richiedono di ricordare tutto. FlowBoard permette di interrogare direttamente la board e ottenere suggerimenti contestuali senza uscire dall'interfaccia.

---

Perché queste scelte tecnologiche

Tecnologia	Perché
Flask invece di Django	Django porta con sé ORM, admin, autenticazione e molto altro — qui non servono. Flask è un micro-framework: zero overhead, ideale per un'app senza database.
Groq + Llama 3	API gratuita senza carta di credito, con latenza molto bassa grazie all'hardware LPU proprietario. Llama 3.1-8b è ottimo per task conversazionali brevi come rispondere a domande sulla board.
localStorage invece di un DB	Zero setup, zero migrazioni, portabilità totale. La board non è multi-utente, quindi la persistenza client-side è la scelta più semplice e corretta.
HTML5 Drag & Drop nativo	Dimostra padronanza diretta delle API del browser, senza dipendenze esterne (niente jQuery UI, SortableJS, ecc.).
JavaScript vanilla	L'app ha una complessità gestibile senza framework: controllo totale, nessun bundle step, nessun virtual DOM.

---

Architettura

Browser (client)
  ├── Rendering board        → JS vanilla + DOM
  ├── Drag & Drop            → HTML5 DnD API
  ├── Filtri / Ricerca       → JS client-side (nessuna chiamata al server)
  ├── Persistenza            → localStorage (aggiornato ad ogni modifica)
  └── AI Assistant
        └── POST /api/ask ──► Flask (proxy)
                                └── Groq API (llama-3.1-8b-instant)
                                      └── risposta JSON ──► typing animation

Flusso board:

1. L'utente aggiunge/modifica/sposta/elimina una card
2. JS aggiorna l'array cards in memoria
3. saveBoard() serializza in localStorage
4. renderBoard() ri-renderizza le tre colonne applicando i filtri attivi

Flusso AI Assistant:

1. L'utente scrive una domanda e preme Invia
2. JS chiama getBoardSnapshot() → oggetto JSON con lo stato attuale
3. fetch('/api/ask', {body: {question, board}}) → Flask
4. Flask costruisce il prompt con stato board + data odierna → Groq
5. Groq risponde → Flask restituisce {answer: "..."}
6. JS mostra la risposta con animazione typing (12ms/carattere)

---

Come funziona il codice

Struttura dati delle card

{
  id:        "k3x9f2ab",    // uid() — timestamp + random
  col:       "todo",        // "todo" | "wip" | "done"
  title:     "Titolo task",
  desc:      "Descrizione opzionale",
  priority:  "alta",        // "alta" | "media" | "bassa"
  tags:      ["ux","api"],  // max 3, no duplicati
  due:       "2024-03-15",  // ISO date o stringa vuota
  createdAt: 1710000000000  // timestamp unix ms
}

Drag & Drop

• dragstart: memorizza l'id della card in draggedId, aggiunge classe .dragging
• dragover sulla colonna: e.preventDefault() abilita il drop, aggiunge .drag-over
• dragleave: rimuove .drag-over solo se il cursore esce dalla colonna (check contains)
• drop: aggiorna card.col, chiama saveBoard() + renderBoard()

Costruzione del prompt contestuale (Python)

system_prompt = f"""You are a productivity assistant...
The user's current board state is:
{board_json}        # JSON con tutte le card
Today's date is: {today}
Answer concisely in the same language the user uses."""

Il contesto completo va nel system message; la domanda va nel user message.

Rendering e filtri

renderBoard() filtra cards in base ai tre filtri (testo, priorità, scadenza) — tutti in AND e tutti client-side — poi per ogni colonna chiama buildCardEl(card) che costruisce il DOM con innerHTML, usando escHtml() per prevenire XSS.

---

Come ottenere la API key Groq

1. Vai su console.groq.com
2. Registrati con Google o GitHub (gratuito)
3. API Keys → Create API Key
4. Inserisci la chiave nel file .env

Il tier gratuito include ~14.400 richieste/giorno — più che sufficiente per uso personale.

---

Come avviare

cd flowboard
cp .env.example .env
# Modifica .env e inserisci la tua GROQ_API_KEY
pip install -r requirements.txt
python app.py

Apri il browser su http://localhost:5001.