96 lines
7.6 KiB
Markdown
96 lines
7.6 KiB
Markdown
# 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.
|