Files
ZitPlane/docs/ARCHITECTURE.md
T

2.9 KiB

ZitPlane architecture (proposed)

Responsibility

ZitPlane is a central identity and account-management platform, not a billing or SaaS business backend.

  • ZITADEL (official Go server): identities, authentication, OIDC, security policies, projects, admin console.
  • Login V2 (customized upstream Next.js app): branded signup, sign-in, recovery and challenge screens.
  • Account portal (P04 separate Next.js App Router source at users/ui/): standard ZITADEL OIDC + Auth.js, server-protected overview/read-only profile/security navigation, user-scoped API. Real user editing and security-device management are not implemented yet; CI and live integration remain pending.
  • PostgreSQL: persistent ZITADEL storage. Do not expose directly to the Internet.
  • Coolify / Compose: one Git deployment definition, isolated services and persistent volumes.

Production routing (target, not configured)

  • https://auth.vib.tools/: ZITADEL OIDC discovery, OAuth/OIDC, API and management console; login routes must explicitly proxy to Login V2.
  • https://account.vib.tools/: independent account portal using standard OIDC login.
  • Clean /login is a target route requiring matched login app routes, ZITADEL Login Base URI and proxy; never assume a proxy rewrite alone is sufficient.
  • Verify reverse-proxy h2c/HTTP2 needs, cookies, OIDC callbacks, CSRF and WebAuthn relying-party/domain behavior before release.

Source ownership

  • Do not copy the complete ZITADEL backend Go tree into core/backend/zitadel/; use immutable/version-locked official image and maintain deployment config here.
  • P03 imported the official v4.20.4 Login V2 source at upstream commit 384bb9ec96b501ad39dc232ee2061a40fe180bbd, including apps/login, packages/zitadel-client, packages/zitadel-proto, proto and workspace files under auth/ui/v2/. Source build and runtime integration await future CI/P05 approval; see docs/P03-SOURCE-IMPORT.md.
  • Share only presentation components/tokens across login and account projects unless explicitly approved. No shared browser-side admin credentials.

Environments

  • Development: local Docker PostgreSQL/ZITADEL, non-production test identities; Next.js hot reload; optional mock-only UI preview.
  • Production: dedicated persistent PostgreSQL, protected secrets, hardened ZITADEL configuration, built Next.js apps, HTTPS, backups, health checks and controlled updates.
  • Local dev settings and production config must never share databases, master keys or user records.
  • A production Docker stack is not automatically secure simply because NODE_ENV=production is set.

SaaS applications

Each external SaaS authenticates through ZITADEL using OIDC authorization code + PKCE when appropriate and validates tokens on its backend. Each app owns its own billing, subscription, business database, API keys and entitlement enforcement. Key users by stable issuer + subject identity, not email.