#FE: Foundation (from backend Phase 1)
What the backend's Phase 1: Foundation Setup (prepared by Pair 1, flow defined 2026-10-01, not built) means for the frontend, and the frontend foundation that has to exist before any feature screen. V8 requirement
#Backend Phase 1 → frontend consequences
| Backend step | Backend rule | Frontend consequence |
|---|---|---|
| 1.1 MariaDB | sv_central_2 for Pair 2 | None directly. Our base URL must stay sa-central-api-2 (each pair has its own database) |
| 1.2 Redis | Cache, sessions, queue on Redis | None directly |
| 1.3 Horizon | Queues default, notifications, emails | Emails (verification, reset, invites, IP approval) are queued. Screens say "We've sent an email" right away and offer resend after a cooldown, not "sending…" |
| 1.4 Passport | Access 15 d, refresh 30 d, personal token 6 months. Central issues the access + refresh token itself after all login checks pass (2.9), not through Passport's OAuth password flow; the exact method is decided in the backend's Phase 2 plan V8 requirement 2026-10-03 | Token handling (see D-1 below). The frontend is unaffected by how the token is made — it only needs the login/refresh response fields below. Personal token = "API access" (3.13); migrated V7 tokens keep working |
| 1.5 Telescope | Local only | Never linked from the frontend |
| 1.6 CORS | Only the configured frontend URL. api/* + oauth/*. Authorization header allowed. No wildcards | The backend must list https://sa-central-2.167-233-229-184.nip.io. If we use the BFF (server-to-server), CORS only matters for any direct browser calls |
| 1.7 Mail & logging | MAIL_MAILER=log in development | In development, emails go to the backend log. Testers need the backend team to share links from it |
| 1.8 Security | HTTPS URLs, secure cookies, trusted proxy | The frontend is served over HTTPS. Cookies Secure |
| 1.9 Final check | Protected Passport route works | First frontend smoke test: call that route through the BFF |
| Not in phase | "Next.js login flow (how the frontend gets and stores the Passport token): decided later" | Decision D-1 is needed before frontend Phase 1 |
#D-1: Passport token in Next.js (frontend proposal for the backend team)
Browser formPOST /api/auth/login (Next route handler)POST <central-api>/… loginaccess + refresh tokenSet-Cookie httpOnly (access, refresh)Browser gets user + organizations only
- Tokens live only in
httpOnly; Secure; SameSite=Laxcookies set by Next.js route handlers. - Server components and route handlers add
Authorization: Bearerwhen calling sa-central-api-2. - On 401: one refresh (2.9) in the route handler, then retry once. If that fails, clear the cookies → login.
- What the frontend needs from the backend: the login/refresh responses must return
access_token,refresh_token,expires_inin the body (not only as cookies), plus a refresh endpoint that rotates and revokes (2.9).
#Frontend foundation (frontend Phase 0)
| Item | Detail | Dependency status |
|---|---|---|
| i18n | next-intl, app/[locale], middleware (cookie → URL → Accept-Language), messages/{en,es,de,fr,pt,ja,ru,hi}.json | next-intl to be added (required by project rules) |
| App shell | Sidebar groups, top bar, mobile drawer, breadcrumbs, organization switcher slot | shadcn primitives present |
| Theme | next-themes, light/dark/system | present |
| API layer | lib/api/ axios instance (server side) + route handlers (BFF). Error normaliser, GET retry, abort, Accept-Language | axios present |
| Forms | react-hook-form + zod resolvers | react-hook-form to be added |
| Tables | TanStack Table v8 | to be added |
| States | loading.js / error.js / not-found.js per group, skeletons, empty-state component | — |
| Tests | Vitest + Testing Library. Playwright + axe | to be added |
| Env | .env.local: CENTRAL_API_URL (server only). No secrets in NEXT_PUBLIC_* | — |
Every new dependency is justified in the Phase 0 plan and needs approval before it's added.