Files
ZitPlane/project/FILE-MAP.md
T

165 lines
13 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.
## 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, portless Compose config and cleanup status |
| `tests/ci/compose.portless.override.yaml` | Post-run CI-only removal of inherited developer Traefik host port 8080; unverified until next CI run |
| `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:
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.
## P05-CI-03 backend-only CI map
| Path | Actual role / ownership |
| --- | --- |
| `.gitea/workflows/p05-backend-acceptance.yml` | New manual backend-only Gitea job; excludes redundant Account/Login suites; bounded Alpine Git/Docker prerequisite, acceptance and always cleanup |
| `tests/ci/backend_acceptance.sh` | CI project collision checks, portless effective Compose, four services, disposable PostgreSQL restart, OIDC/JWKS smoke; **CI only** |
| `tests/ci/backend_cleanup.sh` | Cleanup gated on CI-generated ownership marker; down -v for that Compose project and orphan/volume/network checks |
| `tests/ci/compose.portless.override.yaml` | Existing P05-CI-02 CI-only reset of inherited P02 Traefik host binding; read-only in this phase |
| `tests/ci/oidc_discovery.py` | Existing negative and live metadata/JWKS verification; read-only in this phase |
| `docs/P05-CI-03.md`, `notes/P05-CI-03.md` | Public-facing CI procedure and accurate implementation/run evidence |
P02 dev Compose, core backend helper, Login V2 source, Account Portal and all dependency manifests remain unmodified.
## P05-SEC-01 — Dependency security file ownership
| Path | Exact authorized behavior |
| --- | --- |
| `users/ui/package.json` and `users/ui/package-lock.json` | Account Portal direct Next.js 16.4.6 security pin and npm v3 metadata-only lock |
| `auth/ui/v2/apps/login/package.json` | Official Login V2 dependency **declaration only**: Next.js/ESLint plugin and coordinated OpenTelemetry SDK/auto instrumentation; original app/auth source untouched |
| `auth/ui/v2/pnpm-lock.yaml` | Reproducible PNPM v10.30.3 resolution with pruned unreachable snapshots from former large upstream workspace |
| `.gitea/workflows/p05-security-acceptance.yml` | Manual four-job CI: independent Account/Login frozen builds and Account/Login production advisory gates |
| `tests/ci/security_advisory_gate.py` | Rejects malformed npm/pnpm JSON or any Moderate/High/Critical audit record; never suppresses or changes packages |
| `project/DEPENDENCY-SECURITY.md` | Detailed GHSA/group/parent/versions/patch/risk and CI disposition |
| `notes/P05-SEC-01.md`, `docs/P05-SEC-01.md` | Pre-change plan, source patch provenance, actual run results and operator guidance |
**Read-only:** `auth/ui/v2/pnpm-workspace.yaml`, all `users/ui/src/**`, original Login V2 components/logic, backend/Compose and unrelated monorepo packages.
## P05-SEC-02 — focused transitive dependency file map
| Path | Exact responsibility |
| --- | --- |
| `auth/ui/v2/pnpm-workspace.yaml` | Seven exact **parent-targeted** glob/minimatch major fixes; previous workspace overrides unchanged |
| `auth/ui/v2/pnpm-lock.yaml` | Pinned PNPM v10.30.3 lock metadata, patched transitive versions, original four importers |
| `.gitea/workflows/p05-security-acceptance.yml` | Optional `login_only=true` manual dispatch, no Account rerun; Login install/build/unit and independent production strict security audit |
| `tests/ci/transitive_override_contract.py` | CI checks only seven exact parent overrides; old affected package versions absent; parents resolve patched version |
| `notes/P05-SEC-02.md`, `docs/P05-SEC-02.md` | Pre-edit parent-chain evidence, exact patch and actual run outcome |
Official Login V2 user/auth source, user Account Portal, backend Compose and production infrastructure remain unmodified.