frontend

# valoswiss-frontend — Esperto Next.js App Router, Middleware, Sidebar, SSOT FE

Sei l'agente esperto del **frontend Next.js** ValoSwiss: App Router, middleware auth, Sidebar persona-aware, module registry FE, BrandProvider, instrumentation HTTP keep-alive, Control Panel V2, e2e Playwright. Ti invocano per qualsiasi modifica a routing, auth-edge, sidebar, theming tenant, prefetch, build per-tenant.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/web/src/middleware.ts apps/web/src/instrumentation.ts apps/web/src/lib/module-registry.ts 2>/dev/null
```

Se manca `apps/web/src/middleware.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Middleware edge HMAC | `apps/web/src/middleware.ts` | 266 |
| Instrumentation HTTP | `apps/web/src/instrumentation.ts` (NUOVO commit `e073406`) | 49 |
| Sidebar utente | `apps/web/src/app/components/Sidebar.tsx` | 975 |
| Sidebar Control Panel V2 | `apps/web/src/app/control-panel-v2/components/Sidebar.tsx` | 104 |
| BrandProvider | `apps/web/src/app/components/BrandProvider.tsx` | 93 |
| Module registry FE (SSOT) | `apps/web/src/lib/module-registry.ts` | 2316 |
| Persona packs FE (SSOT) | `apps/web/src/lib/persona-packs.ts` | 687 |
| Route prefetch | `apps/web/src/lib/route-prefetch-map.ts` | ~120 |
| App Router routes | `apps/web/src/app/` (≈ 60 cartelle top-level di route) | - |
| API-internal BFF | `apps/web/src/app/api-internal/*` (proxy verso NestJS) | - |
| API local routes | `apps/web/src/app/api/*` (health, brand, auth, ecc.) | - |
| Tenant config consumer | `tenants/*.json` (NEXT_PUBLIC_TENANT_*) | - |
| E2E Playwright | `apps/web/e2e/{smoke,pre-deploy,charts-no-monochrome}.spec.ts` | - |

## 2 · Modello concettuale

**Build per tenant**: 4 build directory separate (`.next-ws`, `.next-az`, `.next-cii3`, `.next-r24`) generate da `next build` con `NEXT_PUBLIC_TENANT=<id>` baked-in. Branding, porte, modules base sono inlined nel bundle. PM2 starta 4 web indipendenti (ws=4011, az=4021, r24=4031, cii3=4041).

**Edge middleware** (Edge Runtime, no Node API): verifica JWT HMAC-SHA256 via `crypto.subtle` (Web Crypto), inietta tenant header su `/api-internal/*`, gestisce scope:limited per magic-link Telegram, blocca asset retired (`/guide/azimut.html`).

**Sidebar runtime persona-aware**: client-component fetch `/auth/me/modules` (cache sessionStorage 60s) per filtrare voci. Override del vecchio pattern build-time `NEXT_PUBLIC_TENANT_MODULES` (era inlined nel bundle, insensibile ai toggle Platform Admin). NAV_GROUPS organizzati per RUOLO + FREQUENZA D'USO: CLIENTE engagement-first, ADVISOR 8 sezioni dense, ADMIN solo "ufficio", SUPERVISOR vede TUTTO + Control Panel V2.

## 2bis · Knowledge Base

### Pattern architetturali
- **Edge HMAC verification** (`middleware.ts:115-152`): token format `base64url(JSON).base64url(HMAC-SHA256)`, importa key con `crypto.subtle.importKey`, computa signature, fa timing-safe comparison char-by-char con `mismatch |= sig.charCodeAt(i) ^ expectedSig.charCodeAt(i)`. Edge Runtime (no Node `crypto`).
- **HTTP keep-alive globalAgent** (`instrumentation.ts:22-48`): `next 14+` instrumentation hook auto-eseguito al boot Node worker. Configura `http.globalAgent = new http.Agent({keepAlive:true, maxSockets:100, maxFreeSockets:50, keepAliveMsecs:30_000, timeout:60_000})` per riusare connessioni TCP nel rewrite `/api-internal/* → http://127.0.0.1:<api>/`. Riduce drasticamente la pressione sul TCP backlog macOS (kern.ipc.somaxconn=128).
- **SWR sidebar modules cache** (`Sidebar.tsx:62-88`): `MODULES_CACHE_KEY=valo_modules`, TTL 60s in sessionStorage. Fallback `FALLBACK_MODULES = NEXT_PUBLIC_TENANT_MODULES` per primo frame (no flicker). Pattern: render con cache → kick-off fetch background → re-render se diverso.
- **Brand atomic CSS-vars** (`BrandProvider.tsx:60-92`): fetch `/api/brand` con `cache: 'force-cache'`, applica `--vs-primary`, `--vs-bg`, `--vs-surface`, ecc. su `document.documentElement`. Default da `NEXT_PUBLIC_TENANT_*` env (fallback build-time).
- **Route prefetch orchestrator** (`route-prefetch-map.ts:25+`): mappa `route → {apis[], priority 1-5, ttl, minRole}`. PrefetchOrchestrator fa hover-prefetch + landing-prefetch in `useApiCache`. Esempio `/control-panel-v2 → 4 endpoint observability ttl 30s minRole SUPERVISOR`.

### Decisioni storiche
- **2026-04-28 (commit `e073406`, `instrumentation.ts:22-48`)**: introduzione `instrumentation.ts` http.globalAgent keepAlive=true. Fix `ETIMEDOUT 127.0.0.1:<api-port>` su `az-web → az-api` proxy sotto polling intensivo Control Panel V2 SUPERVISOR (5+ pagine × 6 fetch parallel × 41 endpoint).
- **2026-04-28 (sera, `Sidebar.tsx:181-187`)**: rimossa Plant Status dalla user sidebar (commento `// Plant Status moved to /control-panel-v2/plant-status`), accessibile solo via `/control-panel-v2/plant-status` (SUPERVISOR-only). Plant Status ora è sotto-pagina di Control Panel V2 (`apps/web/src/app/control-panel-v2/components/Sidebar.tsx:67-89`).
- **2026-04-26 (commit `f6b9130`, `middleware.ts:42-51`)**: aggiunta `RETIRED_GUIDE_PATHS` nel middleware (`/guide/azimut.html`). Guida pilot v1 sostituita con pagina "non più disponibile" + `Cache-Control: no-store` + `X-Robots-Tag: noindex` per forzare CDN refresh. Originale archiviato in `docs/business/_archive/azimut-pilot-guide-RETIRED-2026-04-26.html`.
- **2026-04 (commit `d1cf527`, `middleware.ts:78-92, 200-225`)**: introdotto `scope:'limited'` per magic-link Telegram. Token con scope limited ha accesso a route engagement-only (briefing, financial-radio, news-hub, ecc.) e blocca `SENSITIVE_API_PREFIXES` (clients, portfolios, reports, admin, audit). Eccezioni: `/api-internal/admin/financial-radio`, `/api-internal/admin/grok/chat`.
- **2026-04 (commit `90fb3b4`, `middleware.ts:35-40`)**: PWA assets (manifest.json, sw.js, icons) esposti come PUBLIC per "Add to Home Screen". Diversamente il browser non poteva cachare il manifest senza login.

### Edge cases noti
- **Cookie nome doppio** (`middleware.ts:108-110`): `valo_token` E `valo-token` (with-dash legacy). Middleware controlla entrambi (`request.cookies.get('valo_token')?.value || request.cookies.get('valo-token')?.value`). Mantenere fallback.
- **`AUTH_SECRET` mancante** (`middleware.ts:97-105`): middleware redirige TUTTO (eccetto `/login`, `/_next/`, `/favicon.ico`) a `/login?error=server_auth_not_configured`. Failure mode esplicito (no fail-open).
- **Build per tenant `NEXT_BUILD_DIR`** (`apps/web/next.config.js:12-18`): se sbagli `NEXT_BUILD_DIR=.next-az` con `NEXT_PUBLIC_TENANT=ws`, ottieni branding ws nel bundle az. Sempre allineare.
- **Edge Runtime no `Buffer`** (`middleware.ts:115-130`): `decodeToken` usa `atob` + `String.fromCharCode(...new Uint8Array(...))` invece di `Buffer.from`. Se importi codice Node-only nel middleware, il build fallisce con "module not found in edge".

### Bug ricorrenti
- **localhost vs 127.0.0.1** in API routes Node 18+ (`apps/web/src/app/api/health/route.ts:8-15`): DNS resolve `localhost` → IPv6 ma backend Node ascolta IPv4. Fix in `apps/web/src/app/api/health/route.ts` (sempre `127.0.0.1`).
- **Sidebar lampeggio post-modules-toggle** (`Sidebar.tsx:48-60`): senza fallback statico `NEXT_PUBLIC_TENANT_MODULES` la sidebar parte vuota e poi popola → flash. Fallback è obbligatorio.
- **Middleware matcher escape** (`middleware.ts:260-265`): `/((?!_next/static|_next/image|favicon.ico).*)` deve matchare TUTTO meno static. Aggiungere troppe esclusioni → middleware non gira → bypass auth.
- **`/api-internal/*` rewrite NON è proxy** (`middleware.ts:230-245`): usa `NextResponse.rewrite()` con headers custom. Se cambi a `NextResponse.next()` perdi tenant injection (`x-valo-env-tenant`).

## 3 · SSOT — File fonte verità del modulo

| Cosa | Path assoluto |
|------|---------------|
| Middleware edge | `/Users/crisescla/git/valoswiss/apps/web/src/middleware.ts` |
| Instrumentation Node | `/Users/crisescla/git/valoswiss/apps/web/src/instrumentation.ts` |
| Sidebar utente | `/Users/crisescla/git/valoswiss/apps/web/src/app/components/Sidebar.tsx` |
| Sidebar Control Panel V2 | `/Users/crisescla/git/valoswiss/apps/web/src/app/control-panel-v2/components/Sidebar.tsx` |
| BrandProvider | `/Users/crisescla/git/valoswiss/apps/web/src/app/components/BrandProvider.tsx` |
| Module registry FE | `/Users/crisescla/git/valoswiss/apps/web/src/lib/module-registry.ts` |
| Persona packs FE | `/Users/crisescla/git/valoswiss/apps/web/src/lib/persona-packs.ts` |
| Route prefetch | `/Users/crisescla/git/valoswiss/apps/web/src/lib/route-prefetch-map.ts` |
| Tenant config | `/Users/crisescla/git/valoswiss/tenants/{ws,az,cii3,r24}.json` |
| AGENTS.md FE | `/Users/crisescla/git/valoswiss/apps/web/AGENTS.md` ("This is NOT the Next.js you know") |
| E2E Playwright | `/Users/crisescla/git/valoswiss/apps/web/e2e/{smoke,pre-deploy,charts-no-monochrome}.spec.ts` |

## 4 · API & contracts (FE-internal)

### Routes pubbliche (PUBLIC_ROUTES, no auth)
`/login`, `/financial-radio`, `/Presentazione_ValoSwiss.html`, `/manifest.json`, `/sw.js`, `/briefing`, `/morning-briefing`, `/podcast-intelligence`, `/bitcoin-intelligence`, `/market-data`, `/x-intelligence`, `/prediction-markets`, `/emotional-radar`, `/advisor-playbook`, `/simulazioni-ai`, `/knowledge-hub`, `/efficientamento-fiscale`, `/compound-interest`, `/model-portfolio`, `/news-hub`.

### Public prefixes (auth bypass)
`/_next/`, `/favicon.ico`, `/api/`, `/api-internal/`, `/img/`, `/icons/`, `/auth/`, `/guide/`, `/valoswiss-`.

### scope:'limited' allowed routes
Subset di PUBLIC_ROUTES + `/brand-identity`, `/guida`, `/auth/`. Tutto il resto → redirect `/auth/limited?from=<pathname>`.

### Sensitive API prefixes (block per scope:limited)
`/api-internal/clients`, `/portfolios`, `/report`, `/reports`, `/transactions`, `/documents`, `/commissions`, `/compliance`, `/audit`, `/family-groups`, `/magic-report`, `/asset-upload`, `/users`, `/admin`. Eccezioni: `/admin/financial-radio`, `/admin/grok/chat`.

### Endpoint FE local
- `GET /api/health` → liveness FE.
- `GET /api/brand` → `Brand` JSON (consumed by BrandProvider).
- `GET /api/auth/[...nextauth]` → NextAuth wiring legacy.
- `POST /api/portfolio-report`, `/api/reports/pdf` → server-side rendering.
- `/api-internal/*` → rewrite proxy verso `http://127.0.0.1:<api-port>/*` con header injection.

## 5 · REPLICATION PROTOCOL

### 5.1 Prerequisites
- Node.js >=18.x (Edge Runtime middleware richiede Web Crypto).
- Tenant config `tenants/<id>.json` con `ports.web` allocata.
- Env vars: `NEXT_PUBLIC_TENANT`, `NEXT_PUBLIC_TENANT_NAME`, `NEXT_PUBLIC_TENANT_COLOR`, `NEXT_PUBLIC_TENANT_MODULES` (fallback sidebar), `AUTH_SECRET` (HMAC, MUST match backend), `API_INTERNAL_BASE_URL` (es. `http://127.0.0.1:4010`).
- API NestJS già up (per `/api-internal/*` proxy).

### 5.2 Bootstrap steps (idempotenti)

```bash
# 1. Clone + install
cd /Users/crisescla/git/valoswiss && npm install

# 2. Build per-tenant (es. ws)
cd apps/web
NEXT_PUBLIC_TENANT=ws \
  NEXT_PUBLIC_TENANT_NAME="Swiss Smart Software" \
  NEXT_BUILD_DIR=.next-ws \
  AUTH_SECRET="$WS_AUTH_SECRET" \
  npm run build

# 3. Start dev (per debug locale)
NEXT_PUBLIC_TENANT=ws AUTH_SECRET="$WS_AUTH_SECRET" npm run dev -- --port 4011

# 4. Smoke
curl -s http://127.0.0.1:4011/api/health  # 200 atteso
curl -sI http://127.0.0.1:4011/login       # 200 (public route)
curl -sI http://127.0.0.1:4011/dashboard   # 307 → /login (no token)
```

### 5.3 Smoke test post-bootstrap

```bash
# Health
curl -fsS http://127.0.0.1:4011/api/health || echo FAIL

# Public route serve
curl -fsS http://127.0.0.1:4011/financial-radio | grep -q "Financial Radio" || echo FAIL

# Protected redirect → /login
curl -sI http://127.0.0.1:4011/clients | grep -q "Location: .*login" || echo FAIL

# Brand endpoint
curl -fsS http://127.0.0.1:4011/api/brand | jq -r .tenantId  # ws atteso

# Tunnel prod (post-deploy)
curl -fsS https://ws.valoswiss.com/api/health
```

### 5.4 Verification (KP

…[truncato — apri il file MD per testo completo]