Files
ZitPlane/project/FILE-MAP.md
T

7.6 KiB

File and module ownership map

Baseline: commit 40af500 with documentation phase DOCS-01 in progress. This is an exact first-party role map plus pointers to the complete upstream source inventory. See SOURCE-INVENTORY.md for the individual paths of all Git-tracked files, including the imported upstream.

Repository root / governance

Path Purpose / when to change
README.md Entry point, project status, quick navigation; update whenever phase/status changes
AGENTS.md Mandatory coding/AI rules, scope, docs-first updates and security boundaries
.gitignore Prevent local secrets/build data from being staged; change only with explicit review
.editorconfig Editor line ending/indentation defaults
.env.example Non-secret sample keys for P02 backend helper; never commit actual root .env
notes/ Pre-change plans, decisions, chronological implementation and evidence logs
project/ Developer explanations, module/function/page map and actual source inventory
docs/ End-user how-to, setup, features, existing phase/evidence documents

P02 backend + deployment

Path What it actually owns Phase
core/backend/zitadel/dev.py Python stdlib helper init, config, up, check, ps, down; creates ignored local secrets and invokes Compose, readiness probe P02
core/backend/zitadel/README.md Dev-only infrastructure setup guidance, assumptions and warnings P02
deployment/docker/compose.backend.dev.yaml Named postgres, zitadel-api, zitadel-login (prebuilt), proxy; Postgres/Bootstrap volumes, Docker network, local port, health checks P02
deployment/README.md Deployment scope/hardening placeholder; no production Compose exists P01
tests/test_backend_dev.py Prior three focused Python stdlib static/secret-generation checks; NOT a live Docker acceptance test P02
tests/README.md Test folder introduction P01
scripts/README.md Placeholder for future scripts; no standalone project scripts yet P01

P03 imported official ZITADEL Login V2

Path Responsibility What to change
auth/ui/v2/apps/login/src/app/ Official Next.js login route/page implementation; login, registration, challenges, IDP and recovery Only within approved Login UI phase; auth behavior protected
auth/ui/v2/apps/login/src/components/ Official reusable form/UI components Later visual phase with regression checks
auth/ui/v2/apps/login/src/styles/ Official Login presentation styling Later visual phase
auth/ui/v2/apps/login/public/ Login static assets, logos, favicons Later branding phase
auth/ui/v2/apps/login/locales/ Upstream translations Later translation phase
auth/ui/v2/apps/login/src/lib/ Protected login backend/session helpers Separate security-scoped approval
auth/ui/v2/apps/login/src/proxy.ts Official Next.js request/proxy route handling Protected routing code
auth/ui/v2/apps/login/package.json Login scripts/dependencies, workspace linkages Version/security phase only
auth/ui/v2/apps/login/project.json Nx targets and dependencies Build infrastructure phase
auth/ui/v2/apps/login/Dockerfile Official Login UI image definition Image-build integration phase
auth/ui/v2/packages/zitadel-client/ Upstream ZITADEL JS client Do not edit for visual UI
auth/ui/v2/packages/zitadel-proto/ Upstream generated API type project Generated output; not hand-edit
auth/ui/v2/proto/ Upstream protocol definitions No UI edit
auth/ui/v2/pnpm-lock.yaml Original upstream dependency graph; frozen-build compatibility pending CI Dependency phase only
auth/ui/v2/pnpm-workspace.yaml, nx.json, package.json Original workspace structure/tooling Dependency/build phase
auth/ui/v2/LICENSING.md, LICENSE Upstream licensing terms; preserve Legal compliance
auth/ui/v2/README.md ZitPlane import/user-maintainer guide When upstream login source changes

Upstream import: official ZITADEL v4.20.4 / Git 384bb9ec96b501ad39dc232ee2061a40fe180bbd. Imported files are intentionally byte-for-byte identical except two excluded upstream environment files. No source edit was performed in P03. See docs/P03-SOURCE-IMPORT.md.

P04 Account Portal (first-party) — complete source file map

Source Purpose
users/ui/package.json Next.js/React/Auth.js dependency versions and dev/build/start/typecheck scripts; lockfile not yet generated
users/ui/tsconfig.json TypeScript strict configuration and @/* alias
users/ui/next-env.d.ts Next.js TypeScript references
users/ui/next.config.ts Standalone output, security-related response headers, strict React mode
users/ui/.env.example Configuration key names only; never real secrets
users/ui/.gitignore Ignore Next.js build output, node_modules, and env data
users/ui/src/auth.ts Auth.js ZITADEL provider/callbacks and encrypted cookie session integration; protected security logic
users/ui/src/lib/env.ts Validates OIDC issuer/portal origin/client credentials/secret
users/ui/src/lib/identity.ts requireIdentity() and issuer-derived ZITADEL self-service link
users/ui/src/types/next-auth.d.ts Session user ID and JWT subject/expiry type augmentation
users/ui/src/app/layout.tsx Root page shell, metadata, global stylesheet import
users/ui/src/app/page.tsx / redirects to /account
users/ui/src/app/signin/page.tsx Sign-in form; server action triggers Auth.js ZITADEL OIDC redirect
users/ui/src/app/(protected)/layout.tsx Mandatory server-side account identity gate + sidebar shell
users/ui/src/app/(protected)/account/page.tsx Account overview cards and identity greeting
users/ui/src/app/(protected)/account/profile/page.tsx Read-only profile fields and ZITADEL account link
users/ui/src/app/(protected)/account/security/page.tsx Password/MFA/passkey informational rows and ZITADEL security link
users/ui/src/app/api/auth/[...nextauth]/route.ts Auth.js handlers for sign-in/callback/session support
users/ui/src/app/api/account/me/route.ts GET current user ID/name/email, or 401
users/ui/src/components/account-shell.tsx Responsive sidebar/topbar/footer/sign-out form
users/ui/src/components/account-card.tsx Reusable overview Card and profile DataRow
users/ui/src/styles/globals.css Design tokens, compact layout, responsive/mobile/light-dark styling
users/ui/README.md Beginner maintainer guide, routes/config/security contract

These paths describe source, not a verified running app. Do not infer API compatibility or production availability from files existing.

Other first-party folders

packages/README.md: intentionally empty shared-package placeholder, not the upstream auth/ui/v2/packages/. users/ui/public/: currently no public assets registered. project/ and docs/ files are indexed by their own MINIFEST.md.

Exact-file maintenance workflow

For any approved update:

  1. Find target in this map, then open the actual source file and verify current behavior.
  2. Record before/after and Scope Lock in notes/.
  3. Change only approved files. Update relevant function/feature and user docs in the same phase.
  4. Add change record to project/CHANGELOG.md and sync MINIFEST.md / source inventory if structure changes.
  5. Do not rewrite or claim knowledge of every upstream function without examining it. Imported source internals stay officially sourced until audited for an approved edit.