9.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.
P05 CI verification files
| Path | Purpose / scope |
|---|---|
.gitea/workflows/p05-ci.yml |
Manual Gitea Actions workflow with Account, Login, dependency security and disposable backend jobs |
.gitea/README.md, .gitea/MINIFEST.md, .gitea/workflows/README.md, .gitea/workflows/MINIFEST.md |
Ownership, controls and file register for new CI configuration |
tests/ci/source_contract.py |
CI-only lockfile/importer and first-party security guard structural assertions |
tests/ci/oidc_discovery.py |
CI-only disposable ZITADEL readiness, discovery and public JWKS probes (not interactive login) |
tests/ci/README.md, tests/ci/MINIFEST.md |
CI tool scope and direct-child register |
users/ui/package-lock.json |
P05 account npm lock v3, generated metadata-only; reconciles users/ui/package.json |
auth/ui/v2/pnpm-workspace.yaml |
P05 selected 3 imported workspace members only, no source logic changes |
auth/ui/v2/pnpm-lock.yaml |
P05 retained 4 matching importers (root, Login, Client, Proto), package snapshots preserved |
project/CI-ARCHITECTURE.md |
Runner/CI security and runtime-verification boundaries |
notes/P05-CI-01.md, docs/P05-CI-01.md |
Pre-change plan and operator-facing CI evidence |
P05-CI-02 file ownership update
| Path | Verified narrow function |
|---|---|
users/ui/src/auth.ts |
callbacks.session optional JWT subject type narrowing; no change to provider, policy or PKCE/state/nonce |
.gitea/workflows/p05-ci.yml |
CI-only Account negative smoke, Postgres restart persistence, registry advisory JSON collection and cleanup status |
tests/ci/account_negative.py |
Anonymous API 401 and protected route redirect CI probe |
tests/ci/advisory_triage.py |
Nonmutating npm/pnpm vulnerability inventory with IDs and patch availability |
tests/ci/oidc_discovery.py |
Read-only disposable issuer/JWKS negative validation and live metadata smoke |
notes/P05-CI-02.md, docs/P05-CI-02.md |
Pre-change Scope Lock, actual Gitea CI results and user/operator limitations |
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:
- Find target in this map, then open the actual source file and verify current behavior.
- Record before/after and Scope Lock in
notes/. - Change only approved files. Update relevant function/feature and user docs in the same phase.
- Add change record to
project/CHANGELOG.mdand syncMINIFEST.md/ source inventory if structure changes. - 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.