Fuente: ddx-documentation/README.md
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 9670 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](/es/docs/features) | Feature map per audience and portal role, each row citing its route file | written (lane C, repo-alignment) | | [setup.md](/es/docs/setup) | Prerequisites, install, env files (names only), `./ddx-manage.sh` verbs, seeded logins | | | [deploy/FLOW.md](/es/docs/deploy/FLOW) | Production state, request path, full deploy flow, verification proof, fixes and open items for the next session | written (osprey-deploy) | | [deploy/CHECKLIST.md](/es/docs/deploy/CHECKLIST) | Quick checklist to ship the next Osprey update: facts, before, preflight, deploy, verify, extras, diagnosis knowledge, traps | written (osprey-deploy) | | [deploy/README.md](/es/docs/deploy/README) | Deploy runbook: targets, first deploy, deploy, rollback, route, remote logs, boot setup, secrets, deployment report, demo data, diagnosis knowledge, shared-host neighbours | written (deploy-pipeline, osprey-deploy) | | [ports.md](/es/docs/ports) | The one 96XX port map (service, port, owner, env key) | | | [versions.md](/es/docs/versions) | The one version pin table | | | [shell-tree.md](/es/docs/shell-tree) | SiteShell / PortalShell tree, provider cascade, segment files | | | [patterns.md](/es/docs/patterns) | Pattern P1-P23 and groups A-K → inventory id → gallery link → file | | | [entity-kernel.md](/es/docs/entity-kernel) | Entity kernel guide: field catalog, projections, access, capabilities, events, attachments, view modes, gate EK0-EK8, add-an-entity recipe | | | [realtime.md](/es/docs/realtime) | Centrifugo-only realtime: Postgres authority, outbox relay, SSE first with `/emulation` and WS fallback, resnapshot by revision, token routes, CSP | written (osprey-engine 038) | | [osprey-engine.md](/es/docs/osprey-engine) | Osprey engine: router, lanes, Tool-RAG, plan compiler, failure ladder, recovery, permissions header and role map, measured eval | written (osprey-engine 038) | | [observability.md](/es/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](/es/docs/naming-constitution) | The naming standard for every layer: domains, files, symbols, keys, env, source-file headers and tag values (`N-HEADER`, `N-TAG`); gate `./ddx-manage.sh naming` | written (harness-alignment 001) | | [settings.md](/es/docs/settings) | UnifiedSettings tiers (default → platform → org → user), resolve model, branding keys, "Add a setting key" recipe | written (harness-alignment 035) | | [debug-overlay.md](/es/docs/debug-overlay) | Dev-only debug overlay: `useDebugAttrs`, ids, toggle, panel, zero production footprint | written (harness-alignment 022) | | [inventory.md](/es/docs/inventory) | Every registry entry: props, axes, variants, tokens | GENERATED — `./ddx-manage.sh docs` (`pnpm -C ddx-web inventory:docs`) | | [api/osprey-api.openapi.yaml](./api/osprey-api.openapi.yaml) | ddx-api `/realtime/*` token routes and `/osprey/*` command routes (not yet in `openapi.json`) | hand-written (osprey-engine 038) | | [api/osprey-engine.openapi.yaml](./api/osprey-engine.openapi.yaml) | Engine gateway on `127.0.0.1:9630` (`/sessions`, `/runs`, identity and permission headers) | hand-written (osprey-engine 038) | | `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/](/es/docs) ADRs are records: a later decision supersedes one, it never rewrites one. | ADR | Decision | Status | |---|---|---| | [0001](/es/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](/es/docs/adr/0002-auth-better-auth) | Auth: better-auth 1.7 in ddx-api | accepted | | [0003](/es/docs/adr/0003-route-shape) | Route shape: org slug, role, `[entity]/[id]`, `?view=` | accepted | | [0004](/es/docs/adr/0004-database-split) | One Postgres 18 instance, six databases | accepted | | [0005](/es/docs/adr/0005-frameworks) | Frameworks and the approved dependency table | accepted | | [0006](/es/docs/adr/0006-factory) | API clients come from one factory | accepted | | [0007](/es/docs/adr/0007-di-container) | Typed service container (DI / IoC) | accepted | | [0008](/es/docs/adr/0008-singleton-scope) | Singleton scope: what may live at module level | accepted | | [0009](/es/docs/adr/0009-variant-api) | One variant API for every inventory component | accepted | | [0010](/es/docs/adr/0010-media-path) | Media path (presigned URLs) | superseded by 0011 | | [0011](/es/docs/adr/0011-media-proxy) | Media proxy: MinIO only through ddx-api; browser media via the BFF, no presigned URL | accepted | | [0012](/es/docs/adr/0012-density-names) | Density names `compact · cosy · large` (supersedes the density values of 0009) | accepted | | [0013](/es/docs/adr/0013-super-admin-platform-role) | Platform super-admin acts as org-admin of the target org; `OrgSlugGuard` stage | accepted | | [0014](/es/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](/es/docs/adr/0015-entity-kernel) | Entity kernel: one descriptor, one access seam, one projection, one proof chain | accepted | | [0016](/es/docs/adr/0016-sse-bus) | SSE bus: Redis log + pub/sub, one ACL seam, leader tab, signed webhooks | superseded by Centrifugo in plan osprey-engine; read [realtime.md](/es/docs/realtime) | | [0017](/es/docs/adr/0017-bff-layered) | Layered BFF: one route table, route classes, read models, browser auth allow-list | accepted | | [0018](/es/docs/adr/0018-cluster-node-registry) | Cluster node registry in Redis, Ed25519 node identity + node token, hot plug and drain | accepted | | [0019](/es/docs/adr/0019-tenant-branding) | Tenant branding: five `portal.branding.*` keys, vendored registry palettes on `data-brand`, `next/font` pairs, client-generated logo, public `GET /platform/branding` | accepted; font-face widening and first-paint flash NEEDS_REVIEW | | [0021](/es/docs/adr/0021-diagnosis-engine) | Diagnosis engine: model-free scoring core, versioned disease cards, step-suspend doctor questions, fail-closed safety, reviewed curation behind a gold-set gate | accepted | | [0022](/es/docs/adr/0022-ibis-pack-reuse) | IBIS pack reuse: pinned content import, estimate provenance and banner, fail-closed drug safety | accepted | | [0023](/es/docs/adr/0023-dx-assistant) | Dudoxx Dx assistant: model talks, core decides; grounding guard, pattern cards, Qdrant v2 and 3D map, de-identified dossier, MCP server, PENDING-only self-curation | accepted | | [0024](/es/docs/adr/0024-card-folders) | Card folders: `osprey-dx-card/1`, media in the engine blob store, versioned install + rollback, self-heal in the miners job | accepted | ## Research pages — [research/](/es/docs) Each page cites a source (path or URL + date) per finding (G10.4). | Page | Question | |---|---| | [rq1-versions.md](/es/docs/research/rq1-versions) | Which release is "latest", and does it differ from the canon? | | [rq2-route-shape.md](/es/docs/research/rq2-route-shape) | Route group or dynamic org slug? | | [rq3-auth-matrix.md](/es/docs/research/rq3-auth-matrix) | better-auth 1.7 vs Auth.js v5 feature matrix | | [rq4-db-split.md](/es/docs/research/rq4-db-split) | Separate databases or separate schemas? | | [rq5-frameworks.md](/es/docs/research/rq5-frameworks) | Which frameworks beyond shadcn earn a place? | | [rq6-di-scope.md](/es/docs/research/rq6-di-scope) | DI, IoC and Singleton across RSC, client bundles and NestJS | | [rq7-cache-classes.md](/es/docs/research/rq7-cache-classes) | Server cache vs TanStack Query, and how each is invalidated | | [rq8-media-path.md](/es/docs/research/rq8-media-path) | Media path: presigned URLs vs streaming through the BFF (decision: ADR 0011) | | [rq10-sse-through-bff.md](/es/docs/research/rq10-sse-through-bff) | SSE through the Next.js BFF route handler (desk half) | | [template-triage.md](/es/docs/research/template-triage) | Template triage: create-nextjs code in ddx-web | --- Last reconciled: 2026-10-28 · plan osprey-engine task 038
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 9670
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.
Generated files are never edited by hand. Re-run ./ddx-manage.sh docs after a change to
the inventory or the API.
ADRs are records: a later decision supersedes one, it never rewrites one.
Each page cites a source (path or URL + date) per finding (G10.4).
Last reconciled: 2026-10-28 · plan osprey-engine task 038
adr/
deploy/
research/