# 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.