ADR 0006 — API clients come from one factory

• 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
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• 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)
• Binds: G3.3, G6.3, G6.4, invariant 1 (no browser → ddx-api call)
• Related: 0007, 0008, RQ6

Context

A Server Component and a Client Component reach ddx-api in two different ways. The server goes to ddx-api directly with gateway headers (server-only). The browser goes to the same-origin BFF /api/v1/* only. If components build their own clients, the base URL, headers, error envelope and auth handling get copied many times — and one copy will call ddx-api from the browser.

Decision

1. One factory: createApiClient({ side: 'server' | 'client', ... }).
   • side: 'server' — lives in a module that starts with import 'server-only'. Base URL = internal ddx-api URL from the server env. Adds the session JWT and gateway headers. Never importable from a 'use client' file.
   • side: 'client' — base URL = same-origin /api/v1. Sends cookies only. No env read.
2. Both sides return the same typed interface (ApiClient), built from the @ddx/contracts schemas. Entity clients (createEntityClient(api, 'patients')) wrap it.
3. Responses are parsed with the contract Zod schema and returned as a Result (neverthrow); errors use the house error envelope.
4. Components never construct a client. No createApiClient, no fetch to an API path, no new of a client inside a component or hook body. They receive services from the container (ADR 0007): getServerContainer().get('entities') on the server, useService('entities') on the client.
5. The factory is the only place that knows the base URL. NEXT_PUBLIC_API_URL must not exist.

Rejected alternative

• Per-component fetch helpers (HMS style): rejected — duplicates headers and envelopes, and makes invariant 1 unverifiable.
• One isomorphic client that checks typeof window: rejected — it would pull server env and gateway code into the client bundle; server-only cannot guard it.

Consequences

• One file to audit for auth headers and base URL per side.
• Tests inject a fake ApiClient through the container, not through module mocks.

Check

! rg -n 'NEXT_PUBLIC_API_URL|localhost:16310' ddx-web/src! rg -n 'createApiClient\(' ddx-web/src/components ddx-web/src/app --glob '*.tsx'rg -l "import 'server-only'" ddx-web/src/lib/api   # server factory module carries the marker