ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot

Status

Accepted 2026-10-23 (owner Q9, confirmed by Q13). Outcome: delivered by task 006 (create-nextjs + create-nestjs scaffolds; see progress/006.md).

Context

The root dudoxx-web-boot is empty. It needs ddx-web, ddx-api, two docker folders and ./ddx-manage.sh (00_JOB problem 1). The dudoxx-sandbox-creator composes these from the harness templates, but its default port band is 3400-3490 and its docker files publish the upstream default ports on the host. Failure mode 5 says a scaffolder that ignores the overrides makes services collide with the sibling HMS stack. The workspace is dev-only with no remote (Q4).

Decision

Compose through dudoxx-sandbox-creator with:

• per-service port overrides from ../ports.md (16300, 16310, 16330, 16350/16351; 16370 reserved);
• --no-push (no GitHub remote, Q4);
• versions from ../versions.md.

Fallback: if the creator cannot take the overrides, run create-nextjs (ddx-web) and create-nestjs (ddx-api) by hand, then write the docker folders and ./ddx-manage.sh against the port map.

Rejected alternative

Hand-scaffold from the start (create-nextjs + create-nestjs only). Rejected: it skips the creator's lifecycle script and docker wiring, so more glue is written by hand. It stays the fallback only.

Consequences

• AC1.4 greps every compose file for a host-side default port and must find none (map in ../ports.md).
• AC1.5 checks that ./ddx-manage.sh status shows 16300.
• Any creator default left in place is a defect, not a choice.

Outcome

Task 006, 2026-10-23. Route used: the fallback (create-nextjs + create-nestjs).

Why the creator was not used. Its in-place dry-run accepted every 163XX override (web 16300, api 16310, postgres 16330, minio 16350/16351) and --no-push. But:

• Phase 7 writes the root .claude/ when .claude/agents/ is absent. Task 004 owned .claude/ at that time.
• --with-api always adds Redis to the root compose.yaml (a WS1 NOT item).
• It also writes seeder/usage packages, a root compose and the manage script. Task 007 owns the docker folders and ./ddx-manage.sh.

Commands (run in /tmp/w006-scaffold, then moved into the root):

DDX_BRAND_TOKENS_DIR=$HOME/.claude/skills/_shared-brand-tokens \  npx --yes tsx <create-nextjs>/scripts/create-project.ts --name ddx-web \  --display-name "Dudoxx Web Boot" --trigram dwb --port 16300 --api-port 16310 \  --db-port 16330 --brand dudoxx --skip-install~/.claude/skills-vault/create-nestjs/scripts/scaffold.sh ddx-api --no-wizard \  --trigram dwb --auth jwks --no-docker --port 16310 --db-port 16330 \  --cwd /tmp/w006-scaffold/ddx-api

What the scaffolders could not do, and the fix applied:

• create-nextjs aborts: its template design-reference/operational-workspaces/DESIGN.md does not match its own manifest.json hash. The run used a /tmp copy of the skill with the self-consistent package ~/.claude/design/operational-workspaces (65 of 65 hashes match). The harness copy is not fixed here.
• Both scaffolders run git init (create-nextjs also commits). Built outside the repo; the nested .git folders were removed before the move.
• Per-app pnpm-workspace.yaml and ddx-web/pnpm-lock.yaml were removed. Their allowBuilds moved to the root pnpm-workspace.yaml. One lockfile at the root.
• .env.example files and ddx-api/test/setup-e2e.ts kept 3400/3450 values and Redis/LiveKit/Qdrant lines. Changed to 16300/16350; the three unused lines removed.
• The brand file moved from src/styles/brand.css to src/styles/brands/dudoxx.css (imports in globals.css and docs updated).
• Still open for task 007: ddx-web/compose.yaml and ddx-web/Dockerfile are per-app files (host ports 16300/16330 only).

Notes

• 2026-10-23: the workspace now has a private remote, git@github.com:Dudoxx/dudoxx-web-boot.git (owner order); the port and scaffold decision is unchanged.