infra(04-00): route /c/ → /client/, Dockerfile, Gitea deploy

- Rename src/app/c/[token] → src/app/client/[token] - Update proxy.ts, ClientRow, admin client detail with /client/ path - Add output: "standalone" to next.config.ts for Docker build - Add Dockerfile (multi-stage, node:20-alpine) and .dockerignore - Push schema to Coolify Postgres via SSH tunnel (drizzle-kit push ✓) - Update CLAUDE.md constraint 4 to reflect /client/ route - Add Phase 4 planning artifacts (04-00, 04-RESEARCH, 04-PATTERNS) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-21 16:12:05 +02:00
parent 49ef45da83
commit 5bf5dfce71
21 changed files with 3164 additions and 63 deletions
@@ -0,0 +1,371 @@
+---
+phase: 04-progetti-multi-project
+plan: "00"
+type: execute
+wave: 0
+depends_on: []
+files_modified:
+  - src/app/client/[token]/layout.tsx
+  - src/app/client/[token]/page.tsx
+  - src/proxy.ts
+  - src/components/admin/ClientRow.tsx
+  - src/app/admin/clients/[id]/page.tsx
+  - Dockerfile
+  - .env.example
+autonomous: false
+
+must_haves:
+  truths:
+    - "La route /client/[token] esiste e risponde correttamente (cartella rinominata da /c/)"
+    - "src/proxy.ts controlla /client/ invece di /c/ nel guard e nel matcher"
+    - "ClientRow.tsx e admin/clients/[id]/page.tsx usano /client/ nei link generati"
+    - "Il Dockerfile produce un build Next.js funzionante (exit code 0)"
+    - "DATABASE_URL in .env punta al Postgres self-hosted su Coolify (non Neon)"
+    - "drizzle-kit push sul nuovo DB completes con exit code 0"
+    - "L'app risponde su hub.iamcavalli.net dopo il deploy su Coolify"
+  artifacts:
+    - path: "src/app/client/[token]/page.tsx"
+      provides: "Dashboard cliente alla nuova route"
+      contains: "export default"
+    - path: "src/proxy.ts"
+      provides: "Middleware aggiornato per /client/"
+      contains: "pathname.startsWith(\"/client/\")"
+    - path: "Dockerfile"
+      provides: "Container image per Coolify"
+      contains: "FROM node:"
+  key_links:
+    - from: "src/proxy.ts"
+      to: "src/app/client/[token]/"
+      via: "matcher: ['/admin/:path*', '/client/:path*']"
+      pattern: "/client/:path*"
+    - from: "src/components/admin/ClientRow.tsx"
+      to: "src/app/client/[token]/"
+      via: "href={`/client/${client.token}`}"
+      pattern: "/client/"
+---
+
+<objective>
+Infrastruttura pre-Phase 4: migrazione da Neon a Postgres self-hosted su Coolify (Hetzner), rinomina route cliente da /c/ a /client/, Dockerfile per deploy, dominio hub.iamcavalli.net.
+
+Questo piano esegue PRIMA di 04-01 per garantire che tutto il codice Phase 4 venga scritto e testato sull'infrastruttura finale. Nessun refactor post-esecuzione.
+
+Output: App deployata su hub.iamcavalli.net con DB Postgres su Coolify, route /client/[token] funzionante.
+</objective>
+
+<context>
+@/Users/simonecavalli/IAMCAVALLI/.planning/ROADMAP.md
+@/Users/simonecavalli/IAMCAVALLI/CLAUDE.md
+
+<interfaces>
+<!-- Riferimenti correnti da aggiornare -->
+
+proxy.ts riga 32: `if (pathname.startsWith("/c/"))`
+proxy.ts riga 33: `pathname.match(/^\/c\/([a-zA-Z0-9_-]+)/)`
+proxy.ts riga 63: `matcher: ["/admin/:path*", "/c/:path*"]`
+
+ClientRow.tsx riga 59: `href={\`/c/${client.token}\`}`
+admin/clients/[id]/page.tsx riga 46: `href={\`/c/${client.token}\`}`
+
+Cartella da rinominare: src/app/c/ → src/app/client/
+</interfaces>
+</context>
+
+<threat_model>
+T-00-01: Redirect loop dopo rinomina — mitigazione: aggiornare proxy.ts prima di rinominare la cartella, verificare matcher.
+T-00-02: DB connection string esposta — mitigazione: .env mai committato, .env.example con placeholder.
+T-00-03: Dati di test persi durante migrazione DB — accettabile: tutti i dati attuali sono test data (CONTEXT.md).
+T-00-04: Coolify deploy fallisce silenziosamente — mitigazione: verificare health check dopo deploy.
+</threat_model>
+
+<tasks>
+
+<task id="1" type="execute" autonomous="false">
+<name>Task 1: Postgres su Coolify + migrazione DATABASE_URL</name>
+
+<read_first>
+- .env (connection string Neon attuale — non committare)
+- drizzle.config.ts (per confermare che legge DATABASE_URL)
+</read_first>
+
+<action>
+**A. Crea Postgres su Coolify (manuale — non automatizzabile)**
+
+Nel pannello Coolify su Hetzner:
+1. New Resource → Database → PostgreSQL
+2. Nome: `clienthub-db`
+3. Version: 16
+4. Salva le credenziali generate (host, port, user, password, dbname)
+5. Abilita "Public port" se necessario per drizzle-kit push da locale
+
+**B. Aggiorna .env locale**
+
+Sostituisci la riga DATABASE_URL con la connection string Coolify:
+```
+DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
+```
+
+Mantieni la vecchia riga commentata come backup:
+```
+# DATABASE_URL=postgresql://neon... (backup)
+```
+
+**C. Aggiorna .env.example**
+
+Sostituisci il placeholder Neon con quello generico:
+```
+DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require
+```
+
+**D. Push schema al nuovo DB**
+
+```bash
+npx drizzle-kit push
+```
+
+Il DB è fresh — nessuna migrazione soft necessaria, tutti i dati attuali sono test data.
+</action>
+
+<verify>
+<automated>npx drizzle-kit push 2>&1; echo "Exit: $?"</automated>
+</verify>
+
+<acceptance_criteria>
+- drizzle-kit push completes con exit code 0
+- .env contiene DATABASE_URL che punta a Coolify (non neon.tech)
+- .env.example non contiene credenziali reali
+- npx tsc --noEmit non produce errori legati al DB
+</acceptance_criteria>
+</task>
+
+<task id="2" type="execute" autonomous="true">
+<name>Task 2: Rinomina route /c/ → /client/ + aggiorna reference</name>
+
+<read_first>
+- src/proxy.ts (middleware completo — LEGGERE PRIMA di modificare)
+- src/components/admin/ClientRow.tsx (link generato riga 59)
+- src/app/admin/clients/[id]/page.tsx (link generato riga 46)
+- src/app/c/[token]/page.tsx (dashboard cliente da spostare)
+- src/app/c/[token]/layout.tsx (layout da spostare)
+</read_first>
+
+<action>
+**A. Rinomina cartella App Router**
+
+```bash
+mv src/app/c src/app/client
+```
+
+Questo sposta automaticamente page.tsx e layout.tsx alla nuova route.
+
+**B. Aggiorna src/proxy.ts**
+
+Tre sostituzioni esatte:
+
+Riga 32 — cambia:
+```typescript
+if (pathname.startsWith("/c/")) {
+```
+in:
+```typescript
+if (pathname.startsWith("/client/")) {
+```
+
+Riga 33 — cambia:
+```typescript
+const tokenMatch = pathname.match(/^\/c\/([a-zA-Z0-9_-]+)/);
+```
+in:
+```typescript
+const tokenMatch = pathname.match(/^\/client\/([a-zA-Z0-9_-]+)/);
+```
+
+Riga 63 — cambia:
+```typescript
+matcher: ["/admin/:path*", "/c/:path*"],
+```
+in:
+```typescript
+matcher: ["/admin/:path*", "/client/:path*"],
+```
+
+**C. Aggiorna ClientRow.tsx**
+
+Riga 59 — cambia:
+```typescript
+href={`/c/${client.token}`}
+```
+in:
+```typescript
+href={`/client/${client.token}`}
+```
+
+**D. Aggiorna admin/clients/[id]/page.tsx**
+
+Riga 46 — cambia:
+```typescript
+href={`/c/${client.token}`}
+```
+in:
+```typescript
+href={`/client/${client.token}`}
+```
+</action>
+
+<verify>
+<automated>grep -r '"/c/' src/ --include="*.ts" --include="*.tsx" 2>&1; echo "---"; grep -r "'/c/" src/ --include="*.ts" --include="*.tsx" 2>&1; echo "---"; grep -r '/c/:path' src/ --include="*.ts" --include="*.tsx" 2>&1</automated>
+</verify>
+
+<acceptance_criteria>
+- `src/app/client/[token]/page.tsx` esiste (ls conferma)
+- `src/app/c/` NON esiste più (ls conferma)
+- `grep '"/c/' src/ -r` produce zero risultati
+- `grep "startsWith(\"/client/\")" src/proxy.ts` produce un match
+- `grep "/client/:path\*" src/proxy.ts` produce un match
+- `npx tsc --noEmit` exit code 0
+</acceptance_criteria>
+</task>
+
+<task id="3" type="execute" autonomous="true">
+<name>Task 3: Dockerfile per Coolify</name>
+
+<read_first>
+- package.json (script build, versione Node richiesta)
+- next.config.ts (per verificare se output: standalone è già presente)
+- .gitignore (per confermare che .env non è committato)
+</read_first>
+
+<action>
+**A. Aggiungi output standalone a next.config.ts**
+
+Next.js standalone mode produce un bundle minimale ottimale per Docker.
+
+In next.config.ts, aggiungi dentro l'oggetto config:
+```typescript
+output: "standalone",
+```
+
+**B. Crea Dockerfile nella root del progetto**
+
+```dockerfile
+FROM node:20-alpine AS base
+
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXTAUTH_URL=https://hub.iamcavalli.net
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+CMD ["node", "server.js"]
+```
+
+**C. Crea .dockerignore nella root**
+
+```
+.env
+.env.local
+node_modules
+.next
+.git
+.planning
+```
+
+**D. Aggiungi variabili d'ambiente su Coolify**
+
+Nel pannello Coolify → app → Environment Variables, aggiungere:
+```
+DATABASE_URL=postgresql://...  (la stessa del .env locale)
+NEXTAUTH_SECRET=...
+NEXTAUTH_URL=https://hub.iamcavalli.net
+ADMIN_EMAIL=...
+ADMIN_PASSWORD=...
+```
+
+**E. Configura dominio su Coolify**
+
+Nel pannello Coolify → app → Domains:
+- Aggiungi: `hub.iamcavalli.net`
+- Abilita SSL automatico (Let's Encrypt)
+</action>
+
+<verify>
+<automated>docker build -t clienthub-test . 2>&1 | tail -5; echo "Exit: $?"</automated>
+</verify>
+
+<acceptance_criteria>
+- `Dockerfile` esiste nella root del progetto
+- `.dockerignore` esiste e contiene `.env`
+- `next.config.ts` contiene `output: "standalone"`
+- `docker build` completes con exit code 0 (se Docker disponibile localmente)
+- In alternativa: `npm run build` exit code 0 (verifica il build Next.js)
+- Il file `.env` NON appare in `git status` (confermato da .gitignore)
+</acceptance_criteria>
+</task>
+
+<task id="4" type="checkpoint" subtype="human-verify" autonomous="false">
+<name>Checkpoint: verifica deploy su hub.iamcavalli.net</name>
+
+<what_was_built>
+- Postgres self-hosted su Coolify con schema applicato
+- Route /client/[token] funzionante (rinominata da /c/)
+- Dockerfile per deploy su Coolify
+- Dominio hub.iamcavalli.net configurato
+</what_was_built>
+
+<how_to_verify>
+1. Apri https://hub.iamcavalli.net — deve rispondere (anche con pagina 404 standard Next.js)
+2. Apri https://hub.iamcavalli.net/admin/login — deve mostrare la schermata di login
+3. Fai login come admin — deve accedere alla lista clienti
+4. Copia il link di un cliente — deve essere nella forma `hub.iamcavalli.net/client/[token]`
+5. Apri il link cliente — la dashboard deve caricare correttamente
+6. Verifica che il vecchio link `/c/[token]` restituisca 404 (non più attivo)
+</how_to_verify>
+
+<resume_signal>
+Digita "hub ok" quando tutti i controlli passano.
+</resume_signal>
+</task>
+
+</tasks>
+
+<verification>
+1. `src/app/c/` non esiste — `src/app/client/[token]/` esiste
+2. `grep -r '"/c/' src/` produce zero risultati
+3. `grep "startsWith(\"/client/\")" src/proxy.ts` produce un match
+4. `npx drizzle-kit push` exit code 0 sul nuovo DB
+5. `npm run build` exit code 0
+6. https://hub.iamcavalli.net risponde dopo deploy Coolify
+7. https://hub.iamcavalli.net/client/[token] carica la dashboard cliente
+</verification>
+
+<summary_template>
+## Plan 04-00 Complete
+
+**Infrastruttura migrata:**
+- DB: Neon → Postgres self-hosted su Coolify (Hetzner)
+- Route: /c/[token] → /client/[token]
+- Deploy: Vercel → Coolify via Docker
+- Dominio: hub.iamcavalli.net attivo
+
+**File modificati:** src/proxy.ts, src/components/admin/ClientRow.tsx, src/app/admin/clients/[id]/page.tsx, next.config.ts
+**File creati:** Dockerfile, .dockerignore
+**File spostati:** src/app/c/ → src/app/client/
+</summary_template>
@@ -0,0 +1,921 @@
+# Phase 04: Progetti — Multi-Project per Cliente - Research
+
+**Researched:** 2026-05-21
+**Domain:** Data model refactoring + multi-tier architecture (DB schema migration, API routing, client/admin UI)
+**Confidence:** HIGH
+
+## Summary
+
+Phase 04 transforms ClientHub from a single-project-per-client model to a multi-project model. This is a **breaking schema migration** where the `projects` table becomes the primary work container, and 6 existing tables (`phases`, `payments`, `quote_items`, `time_entries`, `documents`, `notes`) move their FK from `client_id` to `project_id`. The `clients` table gains a `slug` field and loses denormalized fields that move to the project level.
+
+All existing data is test data — hard migration (drop/recreate tables) is acceptable and planned.
+
+**Key insight:** This is NOT a typical multi-tenancy refactor. It's a structural deepening: clients now own projects, and projects own the work. The middleware routing pattern (`/c/[slug-or-token]`) stays the same, but resolves at the client level and then queries to find projects.
+
+**Primary recommendation:** Use vertical slice approach (Wave 0 schema, Wave 1 core routing/queries, Wave 2 admin UI, Wave 3 client UI + analytics). All 5 locked architectural decisions are already finalized in CONTEXT.md — implement them as-is, no discretion needed.
+
+---
+
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+**Schema & Data Model**
+- D-01: New `projects` table with `id`, `client_id` FK, `name` (brand/project name), `archived`, `created_at`. No direct `accepted_total` — denormalized from `quote_items` per project.
+- D-02: Six tables move FK from `client_id` → `project_id`: `phases`, `payments`, `quote_items`, `time_entries`, `documents`, `notes`. `comments` stays polymorphic on `entity_id` (unchanged).
+- D-03: `clients` table loses project-scoped fields. Retains: `id`, `name`, `brand_name`, `token`, `slug` (new), `archived`, `created_at`. `accepted_total` moves to `projects`.
+- D-04: `slug` field added to `clients` — optional, unique, URL-safe (e.g., `mario-rossi`). Middleware tries slug first, falls back to token.
+- D-05: `projects.accepted_total` denormalized (text, nullable), admin sets manually in project Preventivo tab.
+
+**Link & Access**
+- D-06: Token stays on `clients` for auth middleware. Middleware checks slug first (DB lookup), then token (existing pattern). Both grant access.
+- D-07: Slug is set in `/admin/clients/[id]/edit` (new form field, optional, with link preview).
+- D-08: Route `/c/[token-or-slug]` unchanged in path — middleware resolves both.
+
+**Client Dashboard**
+- D-09: 1 project → direct view (no selector).
+- D-10: 2+ projects → tabs with brand names (shadcn Tabs, already in codebase).
+- D-11: Project view identical to current client dashboard but scoped to one project.
+
+**Admin — Client List View**
+- D-12: `/admin/clients` shows client name + project brands as secondary text (e.g., "Mario Rossi" / "Brand Blu | Brand Verde"). LTV = sum of all project `accepted_total`.
+- D-13: Clicking a client opens `/admin/clients/[id]` showing project cards/rows (not workspace directly).
+
+**Admin — Project List & Workspace**
+- D-14: New `/admin/projects` (NavBar link) — all projects with: Name, Parent Client, Value (accepted_total), Acconto, Saldo, Timer, €/h.
+- D-15: Timer in projects list shows play/stop for each project. Only one timer active at a time (scoped to project now).
+- D-16: `/admin/projects/[id]` workspace identical to current `/admin/clients/[id]` but project-level: Panoramica, Fasi, Documenti, Pagamenti, Note, Preventivo, Timer, Commenti tabs.
+
+**Project Creation**
+- D-17: Create project from: (1) `/admin/clients/[id]` with "+ Nuovo Progetto" button, or (2) `/admin/projects` with "+ Nuovo Progetto" → select client.
+- D-18: Creation form: Project Name (brand) + Client (if from list). No other fields at creation time.
+
+**Timer & Analytics**
+- D-19: `time_entries.client_id` → `time_entries.project_id`. Timer now per-project.
+- D-20: Analytics profittabilità in project Timer tab: total hours, accepted_total, €/h real (accepted ÷ hours), target rate × hours (ideal cost), delta (gain/loss vs target).
+- D-21: `target_hourly_rate` is global (e.g., 50€/h) stored in `settings` table or env var. New "Impostazioni" page in NavBar for admin to set.
+- D-22: Statistiche page shows aggregated profitability for all projects + breakdown per client.
+
+### Claude's Discretion
+
+- **Settings table structure:** key-value (simplest) vs. dedicated columns. Recommendation: `settings(key text PK, value text)`.
+- **Tab order in project detail:** Follow current client detail order.
+- **Project card style in client detail:** Reuse existing UI patterns.
+
+### Deferred Ideas (OUT OF SCOPE)
+
+- Automatic invoice generation per project.
+- PDF export for quotes.
+- AI Onboarding (Phase 5 — requires this phase as prerequisite).
+- Email notifications when phases change.
+
+---
+
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| PROJ-01 | Every client can have N independent projects; each project has its own workspace (phases, payments, quote, timer) accessible from /admin/projects/[id] | Schema migration (D-01, D-02), Query refactor (getProjectFullDetail), Admin workspace pages (/admin/projects/[id]) |
+| PROJ-02 | Client dashboard shows tabs for 2+ projects; 1 project shows direct workspace without selector | Client view refactor for multi-project detection, Tabs UI pattern (shadcn already available), Client page routing logic |
+| PROJ-03 | /admin/projects lists all projects with €/h calculated and timer play/stop; /admin/projects/[id] is the project workspace | New project list page and detail page templates (clone from ClientRow/Client detail), Timer refactor (client_id → project_id) |
+| PROJ-04 | Client link supports custom slug (/c/mario-rossi) with fallback to token; slug settable from /admin/clients/[id]/edit | Middleware slug resolution (internal API route for DB lookup), Clients edit form, Link preview component |
+| PROJ-05 | Profitability analytics per project: hours tracked, accepted_total, €/h real vs target_hourly_rate global | Analytics card in Timer tab (formula: accepted ÷ hours = €/h real, target × hours = ideal cost, delta = profit/loss), Settings table for global target rate |
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Project CRUD (create, read, update, archive) | API / Backend | Admin Browser | Server actions + DB operations live in API tier; admin calls via form actions |
+| Timer start/stop for projects | API / Backend | Admin Browser | Timer logic (duration calculation, active session tracking) is backend; UI shows state via server actions |
+| Multi-project dashboard routing | Frontend Server (SSR) | Browser | Server chooses 1-project direct view vs. 2+ project tabs; browser renders tabs (Tabs component is client-side) |
+| Slug lookup & resolution | API / Backend + Edge Middleware | — | Middleware calls internal API route to resolve slug → client_id; API accesses DB (can't do direct queries in Edge runtime) |
+| Profitability analytics calculation | API / Backend | Admin Browser | Formula applied server-side (accepted_total ÷ duration_seconds), displayed in admin workspace |
+| Client project visibility | API / Backend | Browser | Client API (`/c/[token]/*`) queries projects belonging to the resolved client; client browser renders what API returns |
+
+---
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Next.js App Router | 16 | Meta-framework for API routes + SSR + auth middleware | Established in project; Edge middleware pattern for token/slug resolution |
+| Neon Postgres | current | Primary database | Established; supports both pooled (API routes) and direct (drizzle-kit) connections |
+| Drizzle ORM | current | Type-safe query builder + schema management | Established; `drizzle-kit push` handles migrations without manual SQL |
+| Auth.js v4 | current | Admin session authentication | Established; `/admin/*` routes use Auth.js session guard |
+| Tailwind v4 | current | Styling | Established; Tailwind scanning configured to include project source |
+| shadcn/ui | current | UI components library | Established; Tabs component already used for admin workspaces |
+| Zod | current | Input validation | Established for form validation |
+| nanoid | current | Random ID generation | Established; used for all entity IDs |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| react-hook-form | (check package.json) | Form state management | Forms in admin (create project, edit client slug) |
+| @radix-ui/tabs | (check package.json) | Underlying Tabs component | shadcn Tabs wrapper — already available |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| `settings` key-value table | Hardcode target_hourly_rate as env var | Env var: simpler, no DB call. Table: more flexible, admin can change via UI. Recommendation: start with table for flexibility. |
+| Slug as optional field in clients | Always-require slug, generate from name | Optional is better: gradual migration, existing clients keep token links, new clients can have slug. |
+| Clone workspace from client detail | Build project detail from scratch | Cloning is faster: tabs, layout, queries already proven. Reduces bugs. |
+
+**Installation:**
+```bash
+# No new packages needed — all standard stack already installed
+npm ls next neon drizzle-orm next-auth tailwindcss shadcn-ui zod nanoid
+```
+
+**Version verification:**
+All versions are in the existing `package.json` and `drizzle.config.ts`. No new dependencies required for Phase 04 schema/routing. Any new UI components (if needed) are installed via `npx shadcn-ui@latest add [component]`.
+
+---
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         CLIENT BROWSER                               │
+│  ┌──────────────┐  ┌──────────────────────────────────────────────┐ │
+│  │  /c/[slug]   │  │  Client Dashboard (multi-project)             │ │
+│  │  or /c/[tok] │──│  ├─ 1 project: direct view                   │ │
+│  │              │  │  └─ 2+: tabs per brand name                  │ │
+│  └──────────────┘  │     ├─ Phases, Tasks, Deliverables           │ │
+│                    │     ├─ Payments & Status                      │ │
+│                    │     └─ Documents & Notes                       │ │
+│                    └──────────────────────────────────────────────┘ │
+│  ┌──────────────┐  ┌──────────────────────────────────────────────┐ │
+│  │ /admin/*     │  │ Admin Area (multi-workspace)                 │ │
+│  │ (Auth.js)    │──│  ├─ /admin/clients: list + LTV               │ │
+│  │              │  │  ├─ /admin/clients/[id]: projects cards       │ │
+│  └──────────────┘  │  ├─ /admin/projects: all projects + timer    │ │
+│                    │  ├─ /admin/projects/[id]: workspace (tabs)   │ │
+│                    │  └─ /admin/impostazioni: target_hourly_rate  │ │
+│                    └──────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────┘
+                              ↓
+                  ┌──────────────────────────┐
+                  │   Edge Middleware        │
+                  │ (proxy.ts / middleware) │
+                  │ ├─ Resolve /c/[slug]     │
+                  │ │  → call /api/internal/ │
+                  │ │    validate-slug       │
+                  │ ├─ Fallback /c/[token]   │
+                  │ │  → existing pattern    │
+                  │ └─ Admin session check   │
+                  └──────────────────────────┘
+                              ↓
+          ┌──────────────────────────────────────────┐
+          │  Next.js API Routes (Node.js runtime)   │
+          │  ├─ /api/internal/validate-token        │
+          │  ├─ /api/internal/validate-slug (NEW)  │
+          │  ├─ /api/auth/* (NextAuth)              │
+          │  └─ Server Actions (form submissions)   │
+          └──────────────────────────────────────────┘
+                              ↓
+          ┌──────────────────────────────────────────┐
+          │  Drizzle ORM Query Layer                │
+          │  ├─ getAllProjectsWithPayments (NEW)     │
+          │  ├─ getProjectFullDetail (NEW)           │
+          │  ├─ getClientWithProjects (NEW)          │
+          │  ├─ slugToClientId (NEW, for resolution) │
+          │  └─ timer-actions refactored             │
+          │     (client_id → project_id)             │
+          └──────────────────────────────────────────┘
+                              ↓
+          ┌──────────────────────────────────────────┐
+          │  Neon Postgres Database                 │
+          │  ├─ clients (+ slug field NEW)           │
+          │  ├─ projects (NEW, client_id FK)         │
+          │  ├─ phases (FK: project_id instead)      │
+          │  ├─ tasks (unchanged, phase_id FK)       │
+          │  ├─ payments (FK: project_id instead)    │
+          │  ├─ quote_items (FK: project_id instead) │
+          │  ├─ time_entries (FK: project_id NEW)    │
+          │  ├─ documents (FK: project_id instead)   │
+          │  ├─ notes (FK: project_id instead)       │
+          │  ├─ settings (NEW, key-value table)      │
+          │  ├─ comments (entity_id, unchanged)      │
+          │  ├─ deliverables (unchanged)             │
+          │  └─ service_catalog (unchanged)          │
+          └──────────────────────────────────────────┘
+```
+
+**Data flow for client dashboard:**
+1. Browser requests `/c/mario-rossi`
+2. Middleware intercepts, calls `/api/internal/validate-slug?slug=mario-rossi`
+3. API resolves slug → client_id via `slugToClientId()`
+4. Server component calls `getClientWithProjects(client_id)`
+5. If 1 project: render direct project view (call `getProjectFullDetail(project_id)`)
+6. If 2+: render tabs, each tab calls `getProjectFullDetail(project_id)`
+7. Browser displays project workspace with phases, payments, documents, notes
+
+**Data flow for admin projects list:**
+1. Admin visits `/admin/projects`
+2. Server calls `getAllProjectsWithPayments()`
+3. Returns projects with: parent client name, accepted_total, payment statuses, active timer info, calculated €/h
+4. Renders ProjectRow for each (clone of ClientRow pattern)
+
+---
+
+## Runtime State Inventory
+
+> This phase involves renaming + moving FK relationships from `client_id` to `project_id`. Verify all runtime state.
+
+| Category | Items Found | Action Required |
+|----------|-------------|------------------|
+| **Stored data** | Current DB has ~13 tables. Hard migration acceptable (drop/recreate from schema). Test data only — no customer data to preserve. | Code edit: `src/db/schema.ts` (new `projects` table, update FK on 6 tables, add `slug` to clients, new `settings` table). Execute `drizzle-kit push` to apply to Neon. |
+| **Live service config** | No external service configuration (n8n workflows, webhooks, etc.) references client_id or project structure explicitly. | None — if services are added in future phases, ensure they use project_id. |
+| **OS-registered state** | None — this is a web application with no local task scheduling or registered executables. | None required. |
+| **Secrets/env vars** | `.env` currently has: DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL. No references to client/project IDs. New `target_hourly_rate` will be stored in DB `settings` table (not env var). | None for secrets. If admins prefer env var, add `TARGET_HOURLY_RATE=50` to `.env` and read in analytics component. Recommendation: use DB table for flexibility. |
+| **Build artifacts** | No build artifacts reference client_id or project structure. Next.js builds are stateless. | None required. Fresh build after schema migration. |
+
+**Conclusion:** All data is test data. Hard migration is acceptable. No runtime state inventory concerns blocking execution.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Incomplete FK Migration Across Tables
+**What goes wrong:** Missing one table's FK migration (e.g., forgetting to update `time_entries.client_id` → `project_id`), causing orphaned records or failed queries in admin workspace when drilling into a specific project.
+
+**Why it happens:** 6 tables need updating. Easy to miss one if checklist is informal.
+
+**How to avoid:** 
+1. List all 6 tables in schema migration PR title: `phases, payments, quote_items, time_entries, documents, notes`.
+2. After `drizzle-kit push`, verify each table with `\dt public.*` in psql and spot-check that old client_id FK is gone, new project_id FK is present.
+3. In planner, create a Wave 0 schema-only task + verification subtasks for each table.
+
+**Warning signs:** 
+- `getProjectFullDetail()` returns empty phases/payments even though they exist in the DB.
+- Timer actions fail with "project_id not found" FK violation on insert.
+
+### Pitfall 2: Client Middleware Resolution Order (Slug vs. Token)
+**What goes wrong:** Middleware checks token first and finds a match before trying slug, so `/c/mario-rossi` is treated as an invalid token and returns 404 even though the slug exists.
+
+**Why it happens:** Easy to reverse the order in `validate-slug` or middleware logic.
+
+**How to avoid:**
+1. Middleware must call `/api/internal/validate-slug?slug=...` FIRST.
+2. Only if slug lookup fails (404 from API), fall back to existing token validation.
+3. Document the order in code comment.
+
+**Warning signs:** 
+- Slug links return 404 even though slug is in the DB and client can access via token link.
+- Creating a new slug for an existing client breaks the old token link (should not).
+
+### Pitfall 3: Admin Workspace Queries Not Scoped to Current Project
+**What goes wrong:** `getProjectFullDetail()` accidentally returns data from multiple projects or from the wrong project due to missing WHERE clause on project_id.
+
+**Why it happens:** Copy-pasting from `getClientFullDetail()` and forgetting to update the WHERE conditions.
+
+**How to avoid:**
+1. After writing `getProjectFullDetail()`, trace through each query: phases, tasks, deliverables, payments, documents, notes, comments, quote_items.
+2. Verify each has `.where(eq(table.project_id, projectId))` or is a child query that's already filtered.
+3. Add a comment above each query stating what it filters on.
+
+**Warning signs:** 
+- Workspace shows phases/tasks from sibling projects.
+- Clicking into a project workspace, then switching projects, shows the same data.
+
+### Pitfall 4: Timer Still Checks for Global "Only One Active" Instead of Per-Project
+**What goes wrong:** Admin starts timer for Project A, then clicks timer for Project B, and Project A's timer is stopped. User expects independent timers.
+
+**Why it happens:** Current `startTimer()` stops ALL running sessions. Must be updated to allow one timer per project (or clarify that "global only one timer" is the design).
+
+**How to avoid:**
+1. Decision: Are timers per-project OR global (only one active per admin account)?
+2. From CONTEXT (D-15): "Only one timer active at a time (scoped to project now)" suggests global is intended (one active total).
+3. Keep current logic but verify: when admin starts project B's timer, project A's should auto-stop.
+4. Add test: start timer A, start timer B, verify A is stopped and B is running.
+
+**Warning signs:** 
+- Two projects have active timers simultaneously (duration_seconds null on both).
+
+### Pitfall 5: Client Slug Field Validation Too Strict or Too Loose
+**What goes wrong:** Slug regex rejects valid inputs (e.g., "mario-rossi-2") or accepts invalid ones (e.g., spaces, special chars).
+
+**Why it happens:** Regex written without testing against edge cases.
+
+**How to avoid:**
+1. Define slug rule: lowercase alphanumeric + hyphens only, 3-50 chars, must be unique.
+2. Zod schema: `slug: z.string().regex(/^[a-z0-9-]{3,50}$/).optional().or(z.null())`
+3. Test form submission with: "mario-rossi", "mario-rossi-2", "MARIO" (should fail), "m--r" (ok?), "m" (too short), "m " (space, should fail).
+
+**Warning signs:** 
+- Admin can't set a slug they expect to work (form rejects it).
+- Middleware crashes on malformed slug from DB.
+
+### Pitfall 6: "Settings" Table Key Mismatches in Code
+**What goes wrong:** Code reads `settings.value WHERE key = 'hourly_rate'` but admin wrote it as `'target_hourly_rate'`, returning null and falling back to a hardcoded default.
+
+**Why it happens:** Settings keys are strings with no schema enforcement. Easy to have typos or inconsistent naming.
+
+**How to avoid:**
+1. Define an enum or constant for all settings keys:
+   ```typescript
+   const SETTINGS_KEYS = {
+     TARGET_HOURLY_RATE: 'target_hourly_rate',
+   } as const;
+   ```
+2. Always read via constant: `getSetting(SETTINGS_KEYS.TARGET_HOURLY_RATE)`.
+3. Admin form submits value for this constant key only.
+
+**Warning signs:** 
+- Analytics always shows a hardcoded rate (default value) instead of what admin set.
+- Changing the setting has no effect.
+
+---
+
+## Code Examples
+
+Verified patterns from the existing codebase and applied to Phase 04 context:
+
+### Database Schema Refactor (Drizzle)
+```typescript
+// src/db/schema.ts (NEW projects table + updated FKs)
+
+// Clients now has slug field (optional, unique)
+export const clients = pgTable("clients", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  name: text("name").notNull(),
+  brand_name: text("brand_name").notNull(),
+  brief: text("brief").notNull(),
+  token: text("token").notNull().unique().$defaultFn(() => nanoid()),
+  slug: text("slug").unique(), // NEW — optional, unique, URL-safe
+  archived: boolean("archived").notNull().default(false),
+  created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// NEW projects table
+export const projects = pgTable("projects", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  client_id: text("client_id").notNull().references(() => clients.id, { onDelete: "cascade" }),
+  name: text("name").notNull(), // brand/project name
+  accepted_total: numeric("accepted_total", { precision: 10, scale: 2 }).default("0"), // denormalized
+  archived: boolean("archived").notNull().default(false),
+  created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// Phases: FK now points to projects, not clients
+export const phases = pgTable("phases", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  title: text("title").notNull(),
+  sort_order: integer("sort_order").notNull().default(0),
+  status: text("status").notNull().default("upcoming"),
+});
+
+// Payments: FK now points to projects, not clients
+export const payments = pgTable("payments", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  label: text("label").notNull(),
+  amount: numeric("amount", { precision: 10, scale: 2 }).notNull(),
+  status: text("status").notNull().default("da_saldare"),
+  paid_at: timestamp("paid_at", { withTimezone: true }),
+});
+
+// Quote items: FK now points to projects, not clients
+export const quote_items = pgTable("quote_items", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  service_id: text("service_id").references(() => service_catalog.id, { onDelete: "restrict" }),
+  quantity: numeric("quantity", { precision: 10, scale: 2 }).notNull(),
+  unit_price: numeric("unit_price", { precision: 10, scale: 2 }).notNull(),
+  subtotal: numeric("subtotal", { precision: 10, scale: 2 }).notNull(),
+  custom_label: text("custom_label"),
+});
+
+// Time entries: FK now points to projects, not clients
+export const time_entries = pgTable("time_entries", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  started_at: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
+  ended_at: timestamp("ended_at", { withTimezone: true }),
+  duration_seconds: integer("duration_seconds"),
+});
+
+// Documents: FK now points to projects, not clients
+export const documents = pgTable("documents", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  label: text("label").notNull(),
+  url: text("url").notNull(),
+  created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// Notes: FK now points to projects, not clients
+export const notes = pgTable("notes", {
+  id: text("id").primaryKey().$defaultFn(() => nanoid()),
+  project_id: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }), // CHANGED from client_id
+  body: text("body").notNull(),
+  created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// NEW settings table for global admin settings (e.g., target hourly rate)
+export const settings = pgTable("settings", {
+  key: text("key").primaryKey(),
+  value: text("value").notNull(),
+  updated_at: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// Relations updated
+export const projectsRelations = relations(projects, ({ one, many }) => ({
+  client: one(clients, { fields: [projects.client_id], references: [clients.id] }),
+  phases: many(phases),
+  payments: many(payments),
+  documents: many(documents),
+  notes: many(notes),
+  quote_items: many(quote_items),
+}));
+```
+
+### Admin Query Layer — getProjectFullDetail
+```typescript
+// src/lib/admin-queries.ts (NEW function, following getClientFullDetail pattern)
+
+export type ProjectFullDetail = {
+  project: Project & { client: Client };
+  phases: Array<Phase & { tasks: Array<Task & { deliverables: Deliverable[] }> }>;
+  payments: Payment[];
+  documents: Document[];
+  notes: Note[];
+  comments: Comment[];
+  quoteItems: QuoteItemWithLabel[];
+  activeServices: ServiceCatalog[];
+  totalTrackedSeconds: number; // for profitability calc
+};
+
+export async function getProjectFullDetail(id: string): Promise<ProjectFullDetail | null> {
+  const projectRows = await db
+    .select()
+    .from(projects)
+    .where(eq(projects.id, id))
+    .limit(1);
+  
+  if (projectRows.length === 0) return null;
+  const project = projectRows[0];
+
+  // Fetch parent client
+  const clientRows = await db
+    .select()
+    .from(clients)
+    .where(eq(clients.id, project.client_id))
+    .limit(1);
+  const client = clientRows[0] || null;
+
+  // Fetch all phases for this PROJECT (not client)
+  const phasesRows = await db
+    .select()
+    .from(phases)
+    .where(eq(phases.project_id, id))
+    .orderBy(asc(phases.sort_order));
+
+  const phaseIds = phasesRows.map((p) => p.id);
+
+  // Fetch tasks scoped to this project's phases
+  const tasksRows = phaseIds.length === 0
+    ? []
+    : await db
+        .select()
+        .from(tasks)
+        .where(inArray(tasks.phase_id, phaseIds))
+        .orderBy(asc(tasks.sort_order));
+
+  const taskIds = tasksRows.map((t) => t.id);
+
+  // Fetch deliverables scoped to this project's tasks
+  const deliverablesRows = taskIds.length === 0
+    ? []
+    : await db
+        .select()
+        .from(deliverables)
+        .where(inArray(deliverables.task_id, taskIds));
+
+  // Payments for this PROJECT (not client)
+  const paymentsRows = await db
+    .select()
+    .from(payments)
+    .where(eq(payments.project_id, id));
+
+  // Documents for this PROJECT (not client)
+  const documentsRows = await db
+    .select()
+    .from(documents)
+    .where(eq(documents.project_id, id))
+    .orderBy(asc(documents.created_at));
+
+  // Notes for this PROJECT (not client)
+  const notesRows = await db
+    .select()
+    .from(notes)
+    .where(eq(notes.project_id, id))
+    .orderBy(asc(notes.created_at));
+
+  // Comments (polymorphic on entity_id) — collect all tasks, deliverables, and the project itself
+  const allEntityIds = [id, ...taskIds, ...deliverablesRows.map((d) => d.id)];
+  const commentsRows = allEntityIds.length === 0
+    ? []
+    : await db
+        .select()
+        .from(comments)
+        .where(inArray(comments.entity_id, allEntityIds))
+        .orderBy(asc(comments.created_at));
+
+  // Quote items for this PROJECT (not client)
+  const quoteItemRows: QuoteItemWithLabel[] = await db
+    .select({
+      id: quote_items.id,
+      label: sql<string>`COALESCE(${service_catalog.name}, ${quote_items.custom_label})`,
+      custom_label: quote_items.custom_label,
+      service_id: quote_items.service_id,
+      quantity: quote_items.quantity,
+      unit_price: quote_items.unit_price,
+      subtotal: quote_items.subtotal,
+    })
+    .from(quote_items)
+    .leftJoin(service_catalog, eq(quote_items.service_id, service_catalog.id))
+    .where(eq(quote_items.project_id, id))
+    .orderBy(asc(quote_items.id));
+
+  // Active services (unchanged)
+  const activeServiceRows = await db
+    .select()
+    .from(service_catalog)
+    .where(eq(service_catalog.active, true))
+    .orderBy(asc(service_catalog.name));
+
+  // Total tracked seconds for this PROJECT (for profitability calc)
+  const totalRes = await db
+    .select({
+      total: sql<string>`coalesce(sum(${time_entries.duration_seconds}), 0)`,
+    })
+    .from(time_entries)
+    .where(eq(time_entries.project_id, id));
+
+  const totalTrackedSeconds = totalRes[0] ? parseInt(totalRes[0].total) : 0;
+
+  // Rebuild hierarchy
+  const phasesWithTasks = phasesRows.map((phase) => ({
+    ...phase,
+    tasks: tasksRows
+      .filter((t) => t.phase_id === phase.id)
+      .map((task) => ({
+        ...task,
+        deliverables: deliverablesRows.filter((d) => d.task_id === task.id),
+      })),
+  }));
+
+  return {
+    project: { ...project, client } as any,
+    phases: phasesWithTasks,
+    payments: paymentsRows,
+    documents: documentsRows,
+    notes: notesRows,
+    comments: commentsRows,
+    quoteItems: quoteItemRows,
+    activeServices: activeServiceRows,
+    totalTrackedSeconds,
+  };
+}
+```
+
+### Slug Resolution in Middleware
+```typescript
+// src/proxy.ts (UPDATED for slug-first resolution)
+
+export async function proxy(request: NextRequest) {
+  const pathname = request.nextUrl.pathname;
+
+  // ── ADMIN GUARD ──────────────────────────────────────────────────────────
+  if (pathname.startsWith("/admin")) {
+    if (pathname === "/admin/login" || pathname.startsWith("/api/auth")) {
+      return NextResponse.next();
+    }
+    const token = await getToken({
+      req: request,
+      secret: process.env.NEXTAUTH_SECRET,
+    });
+    if (!token) {
+      const loginUrl = new URL("/admin/login", request.url);
+      loginUrl.searchParams.set("callbackUrl", pathname);
+      return NextResponse.redirect(loginUrl);
+    }
+    return NextResponse.next();
+  }
+
+  // ── CLIENT TOKEN/SLUG GUARD ─────────────────────────────────────────────
+  if (pathname.startsWith("/c/")) {
+    const slugOrTokenMatch = pathname.match(/^\/c\/([a-zA-Z0-9_-]+)/);
+    if (!slugOrTokenMatch) {
+      return NextResponse.rewrite(new URL("/not-found", request.url));
+    }
+
+    const slugOrToken = slugOrTokenMatch[1];
+
+    try {
+      // TRY SLUG FIRST — call internal API to resolve slug → client
+      const validateUrl = new URL(
+        `/api/internal/validate-slug?slug=${encodeURIComponent(slugOrToken)}`,
+        request.url
+      );
+      let res = await fetch(validateUrl.toString());
+
+      // If slug not found, fall back to TOKEN validation (existing pattern)
+      if (!res.ok) {
+        const validateTokenUrl = new URL(
+          `/api/internal/validate-token?token=${encodeURIComponent(slugOrToken)}`,
+          request.url
+        );
+        res = await fetch(validateTokenUrl.toString());
+      }
+
+      if (!res.ok) {
+        return NextResponse.rewrite(new URL("/not-found", request.url));
+      }
+
+      return NextResponse.next();
+    } catch {
+      return NextResponse.rewrite(new URL("/not-found", request.url));
+    }
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/admin/:path*", "/c/:path*"],
+};
+```
+
+### New Internal API Route for Slug Validation
+```typescript
+// src/app/api/internal/validate-slug/route.ts (NEW)
+
+import { NextRequest, NextResponse } from "next/server";
+import { db } from "@/db";
+import { clients } from "@/db/schema";
+import { eq } from "drizzle-orm";
+
+export async function GET(request: NextRequest) {
+  const slug = request.nextUrl.searchParams.get("slug");
+
+  if (!slug) {
+    return NextResponse.json({ error: "slug required" }, { status: 400 });
+  }
+
+  const rows = await db
+    .select({ id: clients.id })
+    .from(clients)
+    .where(eq(clients.slug, slug))
+    .limit(1);
+
+  if (rows.length === 0) {
+    return NextResponse.json({ error: "not found" }, { status: 404 });
+  }
+
+  return NextResponse.json({ clientId: rows[0].id }, { status: 200 });
+}
+```
+
+### Timer Actions Refactored for Project Scope
+```typescript
+// src/app/admin/timer-actions.ts (UPDATED for project_id)
+
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { db } from "@/db";
+import { time_entries } from "@/db/schema";
+import { eq, isNull } from "drizzle-orm";
+import { nanoid } from "nanoid";
+
+export async function startTimer(projectId: string): Promise<{ entryId: string }> {
+  // Stop any currently running session (still global: only one timer active per admin)
+  const running = await db
+    .select({ id: time_entries.id })
+    .from(time_entries)
+    .where(isNull(time_entries.ended_at));
+
+  for (const r of running) {
+    const now = new Date();
+    const entry = await db
+      .select({ started_at: time_entries.started_at })
+      .from(time_entries)
+      .where(eq(time_entries.id, r.id))
+      .limit(1);
+    if (entry[0]) {
+      const secs = Math.round((now.getTime() - new Date(entry[0].started_at).getTime()) / 1000);
+      await db
+        .update(time_entries)
+        .set({ ended_at: now, duration_seconds: secs })
+        .where(eq(time_entries.id, r.id));
+    }
+  }
+
+  // Create new entry scoped to PROJECT (not client)
+  const id = nanoid();
+  await db.insert(time_entries).values({ id, project_id: projectId });
+  revalidatePath("/admin");
+  return { entryId: id };
+}
+
+export async function stopTimer(entryId: string): Promise<void> {
+  const rows = await db
+    .select({ started_at: time_entries.started_at })
+    .from(time_entries)
+    .where(eq(time_entries.id, entryId))
+    .limit(1);
+
+  if (!rows[0]) return;
+
+  const now = new Date();
+  const secs = Math.round((now.getTime() - new Date(rows[0].started_at).getTime()) / 1000);
+  await db
+    .update(time_entries)
+    .set({ ended_at: now, duration_seconds: secs })
+    .where(eq(time_entries.id, entryId));
+
+  revalidatePath("/admin");
+}
+```
+
+### Profitability Analytics Card (Component Pattern)
+```typescript
+// src/components/admin/ProfitabilityCard.tsx (NEW)
+
+import { Project } from "@/db/schema";
+
+export function ProfitabilityCard({
+  project,
+  totalTrackedSeconds,
+  targetHourlyRate,
+}: {
+  project: Project & { accepted_total: string };
+  totalTrackedSeconds: number;
+  targetHourlyRate: number; // e.g., 50 €/h
+}) {
+  const hours = totalTrackedSeconds / 3600;
+  const acceptedTotal = parseFloat(project.accepted_total || "0");
+
+  // €/h real = accepted_total ÷ hours
+  const realHourlyRate = hours > 0 ? acceptedTotal / hours : 0;
+
+  // Ideal cost = target_rate × hours
+  const idealCost = targetHourlyRate * hours;
+
+  // Delta = profit/loss
+  const delta = acceptedTotal - idealCost;
+  const deltaIsProfit = delta >= 0;
+
+  return (
+    <div className="bg-white rounded-lg border border-[#e5e7eb] p-4 space-y-3">
+      <h3 className="font-medium text-[#1a1a1a]">Profittabilità</h3>
+      
+      <div className="grid grid-cols-2 gap-3 text-sm">
+        <div>
+          <p className="text-[#71717a] text-xs">Ore lavorate</p>
+          <p className="font-mono font-semibold text-[#1a1a1a]">{hours.toFixed(1)}h</p>
+        </div>
+        <div>
+          <p className="text-[#71717a] text-xs">Importo accettato</p>
+          <p className="font-mono font-semibold text-[#1a1a1a]">€{acceptedTotal.toFixed(2)}</p>
+        </div>
+      </div>
+
+      <div className="border-t border-[#f4f4f5] pt-3 space-y-2 text-sm">
+        <div className="flex justify-between">
+          <span className="text-[#71717a]">€/h reale</span>
+          <span className="font-mono font-semibold text-[#1a1a1a]">€{realHourlyRate.toFixed(2)}/h</span>
+        </div>
+        <div className="flex justify-between">
+          <span className="text-[#71717a]">€/h target</span>
+          <span className="font-mono font-semibold text-[#71717a]">€{targetHourlyRate.toFixed(2)}/h</span>
+        </div>
+        <div className="flex justify-between">
+          <span className="text-[#71717a]">Costo ideale</span>
+          <span className="font-mono font-semibold text-[#1a1a1a]">€{idealCost.toFixed(2)}</span>
+        </div>
+      </div>
+
+      <div className={`border-t border-[#f4f4f5] pt-3 flex justify-between items-center`}>
+        <span className="text-[#71717a]">Delta (guadagno/perdita)</span>
+        <span className={`font-mono font-bold ${deltaIsProfit ? "text-green-600" : "text-red-600"}`}>
+          {deltaIsProfit ? "+" : ""}€{delta.toFixed(2)}
+        </span>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Single project per client | Multi-project per client | Phase 04 | Clients can now manage multiple independent brands/projects with separate workspaces and profitability tracking |
+| Client as primary work container | Project as primary work container | Phase 04 | Admin workspace structure mirrors project, not client. Client API queries projects, not client directly |
+| Timer at client level | Timer at project level | Phase 04 | Hours tracked independently per project, enabling per-project profitability analysis |
+| Token-only client links | Token + slug client links | Phase 04 | More user-friendly URLs (e.g., /c/mario-rossi instead of /c/xyzabc123). Token remains as fallback. |
+| Hardcoded profitability target | Global settings table for target rate | Phase 04 | Admin can adjust target hourly rate from UI without changing code. Flexible for future settings. |
+
+**Deprecated/outdated:**
+- Client-level `accepted_total` field remains in schema for backward compat but becomes unused; project-level accepted_total is the source of truth.
+- Old client detail workspace layout is cloned for project detail; both exist but admin only uses project workspace going forward.
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | "Only one timer active globally (per admin)" is the design intent, not per-project independence | Locked Decision D-15, Timer Pitfall | If per-project timers are expected, timer-actions refactor is wrong; need concurrent timer support instead of auto-stop logic. Clarify with user before implementing. |
+| A2 | Hard migration (drop/recreate tables) is acceptable because all data is test data | Runtime State Inventory | If there are production customer records, hard migration will cause data loss. Verify no production data exists before schema push. |
+| A3 | `settings` table with key-value structure is acceptable over env vars | Claude's Discretion | If user later requires non-DB storage for settings (e.g., Redis cache, config file), table approach is still compatible; no blocking constraint. |
+| A4 | Slug-first middleware resolution (slug lookup before token fallback) is the intended order | Locked Decision D-06, D-08 | If token validation should be checked first (for legacy reasons), middleware order is reversed. Test both slug and token paths after implementation. |
+| A5 | `comments` table remains polymorphic (entity_id) and does NOT move to project_id | Locked Decision D-02 | If comments should be scoped per-project (unlikely), add project_id FK and update all comment queries. Currently comments are global per entity, which is correct. |
+
+**If this table is empty:** Not applicable — all claims verified against CONTEXT.md locked decisions.
+
+---
+
+## Open Questions
+
+1. **Profitability analytics default target rate?**
+   - What we know: User mentioned 50€/h as an example; needs global setting.
+   - What's unclear: Should there be a fallback default (e.g., 50€/h) if settings table is empty, or should admin be forced to set it?
+   - Recommendation: Initialize settings table with `target_hourly_rate = '50.00'` as default during first project workspace load. Admin can override from /admin/impostazioni.
+
+2. **Multi-project client dashboard routing — how should it work?**
+   - What we know: 1 project = direct view, 2+ projects = tabs.
+   - What's unclear: Should the URL path for client dashboard change? Stay `/c/[token]` for all projects, or add `/c/[token]/projects/[id]`?
+   - Recommendation: Keep URL `/c/[token]` (or `/c/[slug]`), let server-side logic choose whether to render single project view or tabs. Tabs can have internal navigation (e.g., URL hash or search param) to switch between projects without page reload.
+
+3. **Analytics page aggregation scope?**
+   - What we know: D-22 says "Statistiche page shows aggregated profitability for all projects + breakdown per client."
+   - What's unclear: Should /admin/analytics show global profitability (sum of all projects for all clients) or be filterable by client/date range?
+   - Recommendation: Start simple: global profitability table with columns: Client, Projects, Total Hours, Total Revenue, Avg €/h, Profit/Loss. Filter by client optional (defer to Phase 4.1 if needed).
+
+4. **Project archival behavior?**
+   - What we know: `projects.archived` field exists; D-13 doesn't mention archival UI.
+   - What's unclear: Should archived projects be hidden from /admin/projects list or filtered to separate tab?
+   - Recommendation: Hide archived projects by default (like clients list), add "Mostra archiviati" toggle link. Archival doesn't delete data, just hides it.
+
+---
+
+## Environment Availability
+
+(Phase 04 is code/DB changes only — no external dependencies.)
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Neon Postgres | Schema migration + queries | ✓ | Active (from Phase 1) | — |
+| Next.js API routes | Slug validation route | ✓ | 16 (installed) | — |
+| Drizzle ORM | Schema migration + query building | ✓ | Current (installed) | — |
+| Auth.js v4 | Admin session check (existing) | ✓ | Current (installed) | — |
+| shadcn/ui Tabs | Multi-project dashboard tabs | ✓ | Current (installed) | Could fall back to native `<select>` dropdown, but Tabs is already in use |
+
+**Missing dependencies with no fallback:** None.
+
+**Missing dependencies with fallback:** Tabs component could be replaced with a `<select>` dropdown if shadcn/ui is ever removed, but this is a UI detail, not a blocker.
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- **CONTEXT.md** (Phase 04 decisions) — All 22 locked decisions directly from user's discuss phase. D-01 through D-22, Claude's Discretion, Deferred Ideas sections.
+- **Codebase inspection** — Verified existing schema (schema.ts), admin queries (admin-queries.ts), middleware pattern (proxy.ts), timer actions (timer-actions.ts), client view pattern (client-view.ts), admin workspace layout (clients/[id]/page.tsx).
+- **REQUIREMENTS.md** — PROJ-01 through PROJ-05 mapped to implementation guidance.
+- **ROADMAP.md** — Phase 04 goal and success criteria verified.
+
+### Secondary (MEDIUM confidence)
+- **Next.js 16 App Router patterns** — Edge middleware, server actions, API routes all verified against existing project structure.
+- **Drizzle ORM query patterns** — Relations, WHERE scoping, parallel queries all verified against Phase 1–3 implementation (getAllClientsWithPayments, getClientFullDetail, timer-actions).
+- **shadcn/ui Tabs component** — Already in use in admin workspace (clients/[id]/page.tsx); no additional research needed.
+
+### Tertiary (LOW confidence)
+- None — all findings tied to locked decisions and verified codebase patterns.
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- **Standard stack:** HIGH — all libraries already installed and used; no new dependencies.
+- **Architecture:** HIGH — locked decisions in CONTEXT.md eliminate discretion; patterns clone from existing workspaces.
+- **Pitfalls:** HIGH — identified from common FK migration mistakes, middleware routing, query scoping issues observed in similar refactors.
+- **Environment:** HIGH — no external dependencies; Neon, Next.js, Drizzle all active and verified.
+
+**Research date:** 2026-05-21
+**Valid until:** 2026-06-04 (14 days — architecture stable, no fast-moving libraries)
+
+**Next phase:** `/gsd-plan-phase 04` will create 4–5 plans for vertical-slice execution (Schema Wave 0 → Core Routing → Admin UI → Client UI + Analytics).