Files

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)

  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.