clienthub/.planning/research/ARCHITECTURE.md

Architecture — ClientHub Freelancer Client Portal

Project: ClientHub (welcomeclient.iamcavalli.net) Researched: 2026-05-09 Confidence: HIGH

---

Component Boundaries

Single Next.js application on Vercel. No separate backend. All server logic lives in Route Handlers (/api/**). One Postgres database (Neon serverless) accessed via Drizzle ORM. Admin auth via env-var secret + cookie. Client access via UUID token in URL — no auth library needed for clients.

Component	Responsibility	Communicates With
Client Portal /c/[token]	Read-only view: status, phases, tasks, deliverables, payments, documents	API Routes (GET only)
Admin Dashboard /admin	List all clients with status summary	API Routes (full CRUD)
Admin Client Workspace /admin/clients/[id]	Edit phases, tasks, deliverables, payments, documents	API Routes (full CRUD)
Service Catalog Manager /admin/catalog	CRUD on service items + unit prices	API Routes (catalog entity)
Quote Builder /admin/clients/[id]/quote	Compose quote from catalog items, write accepted_total to client row	Catalog + API Routes
Comments System	Client posts on task/deliverable; admin replies	API Route POST
Approval Flow	Client PATCHes a deliverable to approved	API Route, validates token ownership
API Routes /api/**	Validate token or admin session; query/mutate DB; return JSON	Postgres only
Database	Single source of truth	API Routes only — never queried from browser

---

Data Flow

Client reading their dashboard:

Browser → GET /c/[token]
→ Next.js server component
→ DB: clients WHERE token = [token] → 404 if missing
→ JOIN: project + phases + tasks + deliverables + payments + documents
→ Omit: quote_items, service prices
→ Render read-only portal

Client posting a comment:

Browser → POST /api/comments { token, entity_type, entity_id, body }
→ Validate token → write comment { author: 'client' }
→ 201 → re-fetch thread

Client approving a deliverable:

Browser → PATCH /api/deliverables/[id]/approve { token }
→ Validate token owns deliverable → set status='approved', approved_at=now()
→ Return updated deliverable

Admin editing:

Browser (admin) → PATCH /api/admin/tasks/[id] + admin cookie
→ Validate session → update row → return updated task

Quote building:

Admin UI selects services → computes line items
→ POST /api/admin/clients/[id]/quote { line_items[], accepted_total }
→ Write quote_items rows + write clients.accepted_total (denormalized)
→ Client portal reads clients.accepted_total — never touches quote_items

---

Data Model

clients
  id              UUID PK
  name            TEXT
  brand_name      TEXT
  brief           TEXT
  token           UUID UNIQUE   ← the secret link key (separate from PK!)
  accepted_total  NUMERIC       ← denormalized; only price client ever sees
  created_at      TIMESTAMPTZ

phases
  id              UUID PK
  client_id       UUID → clients.id
  title           TEXT
  sort_order      INT
  status          TEXT  (upcoming | active | done)

tasks
  id              UUID PK
  phase_id        UUID → phases.id
  title           TEXT
  description     TEXT
  status          TEXT  (todo | in_progress | done)
  sort_order      INT

deliverables
  id              UUID PK
  task_id         UUID → tasks.id
  title           TEXT
  url             TEXT          ← external link (Google Drive, PDF, etc.)
  status          TEXT  (pending | submitted | approved)
  approved_at     TIMESTAMPTZ  ← immutable audit trail

comments
  id              UUID PK
  entity_type     TEXT  (task | deliverable)
  entity_id       UUID
  author          TEXT  (client | admin)
  body            TEXT
  created_at      TIMESTAMPTZ

payments
  id              UUID PK
  client_id       UUID → clients.id
  label           TEXT  ("Acconto 50%" / "Saldo 50%")
  amount          NUMERIC
  status          TEXT  (da_saldare | inviata | saldato)
  paid_at         TIMESTAMPTZ

documents
  id              UUID PK
  client_id       UUID → clients.id
  label           TEXT
  url             TEXT
  created_at      TIMESTAMPTZ

service_catalog
  id              UUID PK
  name            TEXT
  description     TEXT
  unit_price      NUMERIC
  active          BOOLEAN

quote_items
  id              UUID PK
  client_id       UUID → clients.id
  service_id      UUID → service_catalog.id
  quantity        NUMERIC
  unit_price      NUMERIC       ← snapshot at time of quote
  subtotal        NUMERIC
  -- NEVER exposed via client API

Key design decisions:

• clients.token is the only secret. Rotation = single UPDATE. No session store needed.
• clients.accepted_total is deliberately denormalized so client API never touches quote_items.
• Approval approved_at stored as immutable audit trail — disputes resolved by timestamp.
• comments use entity_type + entity_id polymorphic pair — correct at this scale.
• payments always two rows per client (created when quote is finalized).

---

Suggested Build Order

1. DB schema + migrations
   └─ everything depends on this

2. API: token lookup + project read (GET only)
   └─ unblocks client portal

3. Client portal UI /c/[token]
   └─ the core deliverable; clients need this first

4. Admin auth middleware (env-var secret, cookie check)
   └─ gate before admin routes go live

5. Admin: client list + client workspace CRUD
   └─ phases, tasks, status, documents, payments

6. Comments system + deliverable approval
   └─ depends on both client portal and admin workspace

7. Service catalog CRUD  ← can run parallel with step 5
   └─ independent of client-facing features

8. Quote builder
   └─ depends on catalog + client entity

9. Claude onboarding flow (v2)
   └─ depends on all CRUD APIs being complete

---

Roadmap Implications

• Phase 1: DB schema + token API + client portal (all three coupled)
• Phase 2: Admin auth + CRUD management + comments + approvals
• Phase 3: Service catalog + quote builder
• Phase 4 (v2): Claude onboarding flow