4.2 KiB
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)
- Browser visits portal at
/account.users/ui/src/app/(protected)/layout.tsxcallsrequireIdentity()insrc/lib/identity.ts. - Missing or expired user identity redirects to
/signin; public form uses Auth.jssignIn("zitadel"). - Auth.js provider is defined in
users/ui/src/auth.tsusing configured issuer, client ID/secret, PKCE/state/nonce andopenid profile emailscopes. - 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. - The
sub/providerAccountIdis the immutable identity key used by the portal; email is only display data. - Protected pages and
GET /api/account/mecheck for nonemptysession.user.id. The session callback clears that ID if token expiry is absent or in the past. - 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.