Files
ZitPlane/project/FILE-MAP.md
T

96 lines
7.6 KiB
Markdown
Raw Normal View History

# 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](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.