clienthub/.planning/phases/01-foundation-client-dashboard/01-CONTEXT.md

Phase 1: Foundation & Client Dashboard - Context

Gathered: 2026-05-13 Status: Ready for planning

## Phase Boundary

Costruire il DB schema, il token API e la dashboard cliente read-only. Al termine di questa fase, un link segreto è condivisibile con un cliente reale che può aprirlo su mobile o desktop e vedere lo stato completo del suo progetto — senza login, senza admin, senza interazione. L'admin area (CRUD, auth, commenti, approvazioni) è Phase 2.

## Implementation Decisions

Database & Infrastruttura

• D-01: Database su Coolify (Hetzner) — Postgres istanza gestita da Coolify sul server Hetzner già pagato. Zero costo aggiuntivo. Neon è scartato in favore del self-hosting già disponibile.
• D-02: ORM invariato — Drizzle ORM con driver postgres-js (invece di neon-http). Schema e migrazioni identici, solo il driver di connessione cambia.
• D-03: DNS in Phase 1 — Configurare welcomeclient.iamcavalli.net come CNAME verso Vercel nella Phase 1, non alla fine. Propagazione va verificata subito.

Brand & Visual Design

• D-04: Brand hardcoded in Phase 1 — Colori e logo iamcavalli fissi nel codice. La personalizzazione admin (tabella brand_settings, pannello colori/logo) è demandata a Phase 2.
• D-05: Stile light & clean — Sfondo chiaro, typography forte, layout professionale e leggibile su mobile.
• D-06: Header dashboard — Logo iamcavalli piccolo in un angolo (es. top-right o top-left), nome del brand cliente (brand_name) in primo piano e prominente. Non il nome del cliente, il nome del suo brand.

Layout Fasi e Task

• D-07: Timeline laterale per le fasi — Indicatore temporale/progressione a sinistra, contenuto fase sulla destra. Trasmette senso di avanzamento sequenziale del progetto.
• D-08: Barra progresso per fase — In cima a ogni fase, una barra % calcolata dai task completati. Sotto la barra, lista dei task.
• D-09: Barra progresso globale in cima — Progress bar globale del progetto nella parte alta della dashboard, derivata dal totale dei task completati su tutti i task. Il cliente vede subito "sei al X%".

Stato Pagamenti

• D-10: Pagamenti sempre visibili — Sezione pagamenti sempre in vista nella dashboard (non nascosta in accordion). Mostra: totale accettato + stato acconto 50% + stato saldo 50%.
• D-11: Stati pagamento — Tre stati per ogni payment row: da_saldare / inviata / saldato. Mai i prezzi singoli dei servizi — solo accepted_total.

Storico Decisioni (DASH-10)

• D-12: Admin scrive, cliente legge — Le note/decisioni del log storico sono scritte solo dall'admin. Il cliente le vede in sola lettura nella sua dashboard. La UI per scrivere note è in Phase 2 (admin area). In Phase 1 il campo body è in schema e la visualizzazione lato cliente è già presente; sarà vuota finché Phase 2 non porta l'admin.

Primo Cliente (Testing)

• D-13: Seed script — Uno script TypeScript (scripts/seed.ts) per inserire il primo cliente reale con dati completi (fasi, task, pagamenti, documenti). Eseguibile una volta con npx tsx scripts/seed.ts. Nessun form admin o SQL manuale necessario per Phase 1.

Claude's Discretion

• Scelta del componente UI specifico per la timeline laterale (build custom vs. shadcn primitives)
• Struttura CSS delle card fasi e task (spaziatura, bordi, hover state)
• Schema colori specifico light & clean (bianco puro, grigi, quale accent color in attesa del brand panel)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Progetto & Requisiti

• .planning/PROJECT.md — Contesto progetto, Core Value, decisioni chiave e vincoli
• .planning/REQUIREMENTS.md — REQ-IDs Phase 1: DASH-01 through DASH-04, DASH-07 through DASH-10
• .planning/ROADMAP.md — Success criteria Phase 1

Ricerca tecnica

• .planning/research/STACK.md — Stack raccomandato (nota: database cambiato da Neon a Coolify Postgres)
• .planning/research/ARCHITECTURE.md — Data model completo, component boundaries, build order
• .planning/research/PITFALLS.md — Pitfall critici: token-as-PK, ClientView enforcement, data model day-one decisions

Istruzioni progetto

• CLAUDE.md — Architectural constraints LOCKED (token separato dalla PK, accepted_total denormalizzato, approved_at immutabile, due path auth isolati)

No external specs beyond the above — requirements fully captured in decisions above.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• Nessun codice esistente — progetto greenfield.

Established Patterns

• Next.js 15 App Router: Server Components per la dashboard read-only (zero client-side waterfalls per rendering dati)
• Drizzle ORM con postgres-js invece di neon-http (Coolify Postgres connection string via env var DATABASE_URL)
• nanoid per generazione token: nanoid() → 21 char, URL-safe, ~126 bit di entropia

Integration Points

• Dashboard cliente: route /c/[token] — Middleware valida token → 404 se mancante → Server Component legge DB e renderizza
• Seed script: scripts/seed.ts — inserisce dati cliente reale, genera token, stampa URL condivisibile
• DNS: CNAME welcomeclient.iamcavalli.net → cname.vercel-dns.com (da configurare su domain registrar)

</code_context>

## Specific Ideas

• Il portale deve sembrare professionale e in linea con il brand iamcavalli — light & clean, non un SaaS generico
• Logo iamcavalli piccolo in corner + nome brand cliente prominente nell'header
• Progress bar globale del progetto in cima alla dashboard (percentuale)
• Timeline laterale per le fasi (non accordion, non card flat) — trasmette sequenzialità e avanzamento
• Barra progresso per singola fase, calcolata da task completati
• Personalizzazione colori/logo dal pannello admin è demandata a Phase 2 — in Phase 1 brand hardcoded

## Deferred Ideas

• Brand customization panel (colori background, testi, logo upload dall'admin) → Phase 2, da aggiungere come requisito nell'area admin
• Three.js / animazioni 3D → Non necessario per questo tipo di portale. UI curata con Tailwind è sufficiente.
• Commenti e approvazioni cliente → Phase 2 (DASH-05, DASH-06)
• Auth admin → Phase 2

---

Phase: 1-Foundation & Client Dashboard Context gathered: 2026-05-13