clienthub/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# ClientHub

Portale clienti per consulente di personal branding. Admin area + dashboard cliente via link segreto.

## Stack
Next.js 16 App Router · Neon Postgres · Drizzle ORM · Auth.js v4 · Tailwind v4 · shadcn/ui · Zod · nanoid

## Commands
- `npm run dev` · `npm run build` · `npm run lint` (lint script is bare `eslint`, not `next lint`)
- **There is no test suite** — no vitest/jest/playwright, no `test` script. Don't go looking for one and don't invent test commands. `npm run build` is the verification of record (it typechecks).
- One-off scripts: `npx tsx scripts/<name>.ts` with `DATABASE_URL` in the env (`tsx` is not a devDependency — it must go through `npx`). `scripts/` holds historical import/seed/verify utilities; nothing there is part of the runtime.

## Architecture
- **`src/proxy.ts` is the middleware.** Next 16 names it `proxy`, not `middleware` — searching for `middleware.ts` finds nothing. Matcher: `/admin/*`, `/client/*`, `/quote/*`.
- **Admin auth is a double gate.** `proxy.ts` redirects unauthenticated `/admin` traffic *and* stamps two headers (`x-admin-pathname` + `x-admin-gate`, a digest derived from `NEXTAUTH_SECRET`). `src/app/admin/layout.tsx` is a second, independent gate: it verifies that digest with `safeEqual` and **fails closed by rendering** (not redirecting — that would loop) when the proxy never ran. Shared helper: `src/lib/admin-gate.ts`, on Web Crypto so it works in both the edge and node runtimes. Reuse those helpers; don't bypass or reimplement either gate.
- **Client access resolution.** `/client/<x>`: per-IP rate limit (`src/lib/rate-limit.ts`, 20/min), then an HTTP fetch **to `localhost:$PORT`** against `/api/internal/validate-slug`, falling back to `/api/internal/validate-token`. Those internal routes are guarded by `INTERNAL_SECRET`. The localhost base URL is deliberate (hairpin NAT inside Docker), not a leftover.
- **The query layers are split, and that split is what enforces LOCKED constraint #2.** `src/lib/client-view.ts` exposes only client-safe projections — it deliberately omits `quote_items`, service prices, and payment amounts. `src/lib/admin-queries.ts` and the other `*-queries.ts` are admin-only. New client-facing queries go in `client-view.ts`; never import `admin-queries` from a `/client/*` route.
- **Two distinct commercial artifacts, easy to confuse:**
  - `/quote/[token]` → `quotes` table, single tier, 21-char nanoid token, served by `src/lib/quote-service.ts`
  - `/preventivo/[slug]` → `proposals` table, an A/B/C tier deck generated by the AI agent in `src/lib/proposal/` (`agent.ts` calls the Anthropic SDK, output is Zod-validated by `schema.ts`, then `assembleProposal` in `assemble.ts` merges it with offer data). States: `draft|published|accepted|rejected`.
- **Offer model:** `offer_macros` → `offer_micros` (tiers A/B/C) → `services`, wired through join tables (`offer_tier_services`, `offer_phase_services`, …). `importOfferIntoProject` in `src/app/admin/projects/project-actions.ts` turns an offer into phases/tasks by grouping services on `services.fase`.
- **Auth:** a single admin credential from env (`ADMIN_EMAIL`/`ADMIN_PASSWORD`) — no users table — with a stateless JWT session (`src/lib/auth.ts`).

## Architecture Constraints (LOCKED)
1. `clients.token` = campo separato rotatable, MAI primary key
2. `quote_items` MAI esposti via client API — solo `accepted_total` al cliente
3. `deliverables.approved_at` immutable once set
4. Auth: `/client/[token]/*` → middleware token check | `/admin/*` → Auth.js session
5. No file hosting v1 — documenti come URL esterni

## Conventions
- **Mutations are Server Actions**, colocated as `actions.ts` (or `*-actions.ts`) inside the route folder. There is no REST API for admin: `src/app/api/` holds only NextAuth, the two internal validation routes, and two client endpoints.
- **Migrations** are hand-written SQL in `src/db/migrations/NNNN_name.sql`, with gaps in the numbering (0002 doesn't exist — that's expected). `drizzle.config.ts` is present but `drizzle-kit generate` is broken: edit `src/db/schema.ts` **and** write the SQL by hand, keeping the two in sync. The `scripts/push-*.ts` files are the old way of applying migrations — don't use them, the SSH/docker-exec procedure below is authoritative.
- **Slugs and tokens are bearer credentials.** Never commit their values (migration files included). They're generated with `customAlphabet` (CSPRNG) in `src/app/admin/clients/new/actions.ts` — never `Math.random()`.
- **Language:** code and comments mix English and Italian; all user-facing UI and error messages are **Italian**.
- **AI-generated HTML:** never `dangerouslySetInnerHTML` on model output — use `src/components/public/proposal/RichText.tsx`, which whitelists bold/emphasis only.

## Design System
Single source of truth: **`design-reference/DESIGN-SYSTEM.md`** ("Quiet Luxury" v1.0).

- Cardinal rule: **semantic tokens only** (`bg-card`, `text-muted-foreground`, `border-border`) — never raw Tailwind palette classes or hex literals. That's what makes dual light/dark work off the single `.dark` class toggle (FOUC guard in `src/app/layout.tsx`, tokens in `src/app/globals.css`).
- Fonts: Plus Jakarta Sans for UI, Geist Mono for numeric/tabular cells (prices, counts, dates).
- Per-page HTML mocks live in `design-reference/pagina-*/` — replicate them faithfully.
- Reuse the existing primitives before building new ones: `StatusBadge`, `SearchInput`, `SegmentedToggle`, `editable-cell`, `option-select`/`option-multi-select` in `src/components/ui/`, and the shell in `src/components/admin/AdminShell.tsx`.
- **`.planning/UI-RULES.md` and `.planning/DESIGN-SYSTEM.md` are SUPERSEDED** — they mandate hex literals and forbid semantic tokens, the exact inverse of the current rule. Don't follow them.

Other docs: `STATUS.md` (current project status + backlog) · `.planning/STATE.md` (GSD state, milestone v2.3) · `.planning/SECURITY-*.md` (2026-07 audit).

## GSD Workflow
Planning in `.planning/`. Use `/gsd-plan-phase N` → `/gsd-execute-phase N`. State in `.planning/STATE.md`.

## Data Safety (LOCKED)
- Any migration, refactor, or deploy MUST NOT delete or truncate `clients`, `projects`, `payments`, or `phases` rows
- Before running any migration: verify it only adds columns/tables — never drops or truncates production data
- Confirm explicitly before any schema change that removes a column or table used by these entities

## Deploy & DB Access (procedure)
- Environments: local → Gitea (remote is named `gitea`, NOT `origin`) → Coolify (prod, auto-deploys on push to `main`)
- Prod Postgres is NOT publicly exposed. Claude has working key-based SSH to `root@178.104.27.55` and applies migrations directly via docker exec — no SSH tunnel needed from the user:
  `cat src/db/migrations/NNNN.sql | ssh root@178.104.27.55 "docker exec -i xwkk0040w0kk0gsgcgog8owk psql -U clienthub -d clienthub -v ON_ERROR_STOP=1 --single-transaction"`
  (container = `xwkk0040w0kk0gsgcgog8owk`, db/user = `clienthub`; if the container hash changes, find it by scanning `docker ps` for the one whose db has the `payments` table). A tunnel `-L 54321:localhost:54321` is only needed to point local tooling at prod.
- Migrations are hand-written SQL in `src/db/migrations/` (drizzle-kit generate is broken).
- Ordering: apply an additive migration to prod BEFORE pushing the schema-dependent code, so the live portal never queries a missing column.

## Security
- Confirm before any destructive command (rm -rf, reset --hard, force push, DROP TABLE / drop-column, truncate, infra changes)
- Never print .env contents or credentials in plaintext output; using them internally to connect is fine
- Don't install packages without showing name + registry + version first
- Pushing to `main` is allowed automatically (standard local → Gitea → Coolify flow); never force-push to `main`
- Any change to this section: propose full new version, get approval before applying