Files

48 lines
4.2 KiB
Markdown

# ZitPlane developer architecture
**Reviewed source baseline:** `40af5007503501643d1e9ad2ab3939ba57dab5f9` (2026-11-22). **Build/runtime/deploy acceptance: pending.**
## 1. Component ownership
| Layer | Source of truth | Responsibility | Status |
| --- | --- | --- | --- |
| Identity backend | Official ZITADEL `ghcr.io/zitadel/zitadel:v4.20.4` pinned in `deployment/docker/compose.backend.dev.yaml` | Identity/OIDC, policies, built-in Console; not copied into Git | Development Compose source only |
| Data | `postgres:17.10-alpine` in same Compose | Local disposable-but-persistent ZITADEL database | Configured; runtime not verified |
| Login UI V2 | `auth/ui/v2/apps/login/` + nested workspace deps | Official upstream Next.js login/recovery/MFA UI | Import-only, upstream `v4.20.4`, original behavior, build pending |
| User account portal | `users/ui/` | Separate Next.js read-only user profile and security landing pages, Auth.js OIDC relying party | Source implemented; build/flows pending |
| Dev proxy | Traefik `v3.7.7` in P02 Compose | `127.0.0.1:8080` loopback entry to prebuilt Login V2 + ZITADEL API | Configured; live routing pending |
| Production stack | Not present | Future Coolify routing/TLS/volumes/backups | NOT IMPLEMENTED |
## 2. Identity and session flow (designed/implemented in source, not proven)
1. Browser visits portal at `/account`. `users/ui/src/app/(protected)/layout.tsx` calls `requireIdentity()` in `src/lib/identity.ts`.
2. Missing or expired user identity redirects to `/signin`; public form uses Auth.js `signIn("zitadel")`.
3. Auth.js provider is defined in `users/ui/src/auth.ts` using configured issuer, client ID/secret, PKCE/state/nonce and `openid profile email` scopes.
4. Browser is redirected to ZITADEL's identity/login service (external issuer). Auth.js handles callback at `/api/auth/callback/zitadel`, JWT session cookies and local portal session.
5. The `sub` / `providerAccountId` is the immutable identity key used by the portal; **email is only display data**.
6. Protected pages and `GET /api/account/me` check for nonempty `session.user.id`. The session callback clears that ID if token expiry is absent or in the past.
7. Portal sign-out calls Auth.js `signOut`; it does **not** guarantee ZITADEL-wide SSO logout. Token refresh, federated logout and user edits are future work.
**Boundary:** P02 Compose still uses the official **prebuilt** `zitadel-login` image. It does **not** build or run the imported P03 Login UI source, and does **not** run the P04 account portal. These are P05+ integration tasks.
## 3. Configuration and data flow
`core/backend/zitadel/dev.py` -> ignored root `.env` (local random secrets only) -> `deployment/docker/compose.backend.dev.yaml` -> local Postgres/ZITADEL/prebuilt Login/Traefik.
`users/ui/.env.example` is **documentation only** for `ZITADEL_ISSUER`, `ZITADEL_CLIENT_ID`, `ZITADEL_CLIENT_SECRET`, `AUTH_SECRET`, `AUTH_URL`, `AUTH_TRUST_HOST`. Runtime credentials must not be committed. The portal has **no own database** in P04.
## 4. Safety properties and constraints
- Keep production and development secrets/volumes entirely separate; never use loopback HTTP Compose publicly.
- No browser-side admin PAT/master key; Account Portal uses its own confidential OIDC client.
- Authentication logic, cookies, session/expiry, callbacks and passkey behavior are protected from UI-only edits.
- Login V2 upstream code is vendor-imported under its exact workspace-relative paths; preserve provenance and license notices.
- Later production must verify trusted proxy headers, HTTPS origin, cookie scope, WebAuthn domain and ZITADEL health/readiness.
- ZITADEL Console handles identity admin; app-specific billing and entitlements stay in external SaaS apps.
## 5. Implementation status versus acceptance
P01 folder foundation committed. P02 local Compose source completed (prior 3/3 static tests; no Docker). P03 source import integrity audited (638/638 Git blobs), but no build. P04 Account Portal scope audit passed; no dependency install, lockfile, TypeScript build, E2E or CI run. All runtime behavior remains **unverified**.
See `docs/PHASES.md`, `docs/P02-EVIDENCE.md`, `docs/P03-SOURCE-IMPORT.md` and `docs/P04-ACCOUNT-PORTAL.md` for exact historical evidence.