ddx-documentation — dudoxx-web-boot

Plain Markdown, the R&D record of this workspace. The ddx-web docs route renders every `.md` file here at `/[locale]/docs/<path>` (Q8); this page is `/[locale]/docs`. Port 16370 stays reserved and unused — there is no separate docs server. Links between pages are relative (`./setup.md`). A link to a ddx-web page uses the `/[locale]/...` form; the docs route fills in the active locale. ## Pages | Page | What it holds | Source | | --- | --- | --- | | [features.md](/en/docs/features) | Feature map per audience and portal role, each row citing its route file | written (lane C, repo-alignment) | | [setup.md](/en/docs/setup) | Prerequisites, install, env files (names only), `./ddx-manage.sh` verbs, seeded logins | | | [deploy/README.md](/en/docs/deploy/README) | Deploy runbook: targets, first deploy, deploy, rollback, route, remote logs, boot setup, secrets, deployment report | written (deploy-pipeline) | | [ports.md](/en/docs/ports) | The one 163XX port map (service, port, owner, env key) | | | [versions.md](/en/docs/versions) | The one version pin table | | | [shell-tree.md](/en/docs/shell-tree) | SiteShell / PortalShell tree, provider cascade, segment files | | | [patterns.md](/en/docs/patterns) | Pattern P1-P23 and groups A-K → inventory id → gallery link → file | | | [entity-kernel.md](/en/docs/entity-kernel) | Entity kernel guide: field catalog, projections, access, capabilities, events, attachments, view modes, gate EK0-EK8, add-an-entity recipe | | | [sse-events.md](/en/docs/sse-events) | SSE event catalog (generated by `scripts/sse-catalog.mjs`): event types, channels, inbound/outbound webhooks; decision in [ADR 0016](/en/docs/adr/0016-sse-bus) | written (sse-bus) | | [observability.md](/en/docs/observability) | Pretty log layout, shared theme, `LOG_*` key table, non-blocking queue, `LOG_HTTP_HEADERS`, `logs` filters and `logs req` | written (unified-logging) | | [naming-constitution.md](/en/docs/naming-constitution) | The naming standard for every layer: domains, files, symbols, keys, env, headers; gate `./ddx-manage.sh naming` | written (harness-alignment 001) | | [settings.md](/en/docs/settings) | UnifiedSettings tiers (default → platform → org → user), resolve model, "Add a setting key" recipe | written (harness-alignment 035) | | [debug-overlay.md](/en/docs/debug-overlay) | Dev-only debug overlay: `useDebugAttrs`, ids, toggle, panel, zero production footprint | written (harness-alignment 022) | | [inventory.md](/en/docs/inventory) | Every registry entry: props, axes, variants, tokens | GENERATED — `./ddx-manage.sh docs` (`pnpm -C ddx-web inventory:docs`) | | `api/openapi.json` | ddx-api OpenAPI document | GENERATED — `./ddx-manage.sh docs` (`pnpm -C ddx-api openapi:export`) | Generated files are never edited by hand. Re-run `./ddx-manage.sh docs` after a change to the inventory or the API. ## Architecture decision records — [adr/](/en/docs) ADRs are records: a later decision supersedes one, it never rewrites one. | ADR | Decision | Status | |---|---|---| | [0001](/en/docs/adr/0001-scaffold-route) | Scaffold through dudoxx-sandbox-creator with 163XX overrides | accepted; route used = the fallback (create-nextjs + create-nestjs by hand, see its Outcome section; the status line at the top predates it) | | [0002](/en/docs/adr/0002-auth-better-auth) | Auth: better-auth 1.7 in ddx-api | accepted | | [0003](/en/docs/adr/0003-route-shape) | Route shape: org slug, role, `[entity]/[id]`, `?view=` | accepted | | [0004](/en/docs/adr/0004-database-split) | One Postgres 18 instance, six databases | accepted | | [0005](/en/docs/adr/0005-frameworks) | Frameworks and the approved dependency table | accepted | | [0006](/en/docs/adr/0006-factory) | API clients come from one factory | accepted | | [0007](/en/docs/adr/0007-di-container) | Typed service container (DI / IoC) | accepted | | [0008](/en/docs/adr/0008-singleton-scope) | Singleton scope: what may live at module level | accepted | | [0009](/en/docs/adr/0009-variant-api) | One variant API for every inventory component | accepted | | [0010](/en/docs/adr/0010-media-path) | Media path (presigned URLs) | superseded by 0011 | | [0011](/en/docs/adr/0011-media-proxy) | Media proxy: MinIO only through ddx-api; browser media via the BFF, no presigned URL | accepted | | [0012](/en/docs/adr/0012-density-names) | Density names `compact · cosy · large` (supersedes the density values of 0009) | accepted | | [0013](/en/docs/adr/0013-super-admin-platform-role) | Platform super-admin acts as org-admin of the target org; `OrgSlugGuard` stage | accepted | | [0014](/en/docs/adr/0014-unified-settings) | Unified settings: one registry, tiers platform → org → user, resolved once in ddx-api | accepted; `public`-persona access for org-admin NEEDS_REVIEW | | [0015](/en/docs/adr/0015-entity-kernel) | Entity kernel: one descriptor, one access seam, one projection, one proof chain | accepted | | [0016](/en/docs/adr/0016-sse-bus) | SSE bus: Redis log + pub/sub, one ACL seam, leader tab, signed webhooks | accepted | | [0017](/en/docs/adr/0017-bff-layered) | Layered BFF: one route table, route classes, read models, browser auth allow-list | accepted | | [0018](/en/docs/adr/0018-cluster-node-registry) | Cluster node registry in Redis, Ed25519 node identity + node token, hot plug and drain | accepted | ## Research pages — [research/](/en/docs) Each page cites a source (path or URL + date) per finding (G10.4). | Page | Question | |---|---| | [rq1-versions.md](/en/docs/research/rq1-versions) | Which release is "latest", and does it differ from the canon? | | [rq2-route-shape.md](/en/docs/research/rq2-route-shape) | Route group or dynamic org slug? | | [rq3-auth-matrix.md](/en/docs/research/rq3-auth-matrix) | better-auth 1.7 vs Auth.js v5 feature matrix | | [rq4-db-split.md](/en/docs/research/rq4-db-split) | Separate databases or separate schemas? | | [rq5-frameworks.md](/en/docs/research/rq5-frameworks) | Which frameworks beyond shadcn earn a place? | | [rq6-di-scope.md](/en/docs/research/rq6-di-scope) | DI, IoC and Singleton across RSC, client bundles and NestJS | | [rq7-cache-classes.md](/en/docs/research/rq7-cache-classes) | Server cache vs TanStack Query, and how each is invalidated | | [rq8-media-path.md](/en/docs/research/rq8-media-path) | Media path: presigned URLs vs streaming through the BFF (decision: ADR 0011) | | [rq10-sse-through-bff.md](/en/docs/research/rq10-sse-through-bff) | SSE through the Next.js BFF route handler (desk half) | | [template-triage.md](/en/docs/research/template-triage) | Template triage: create-nextjs code in ddx-web | --- Last reconciled: 2026-10-25 · plan deploy-pipeline task 022