Status: Accepted v1.0
Date: March 23, 2026
Owners: OSHUN Engineering, OSHUN Platform, Domain Leads
Related:
docs/releases/v1/specs/domain-service-consolidation-strategy.mddocs/releases/v1/specs/todos.mdapps/oshun/bff/src/app.tsapps/oshun/bff/src/config/domain-service-discovery.tsapps/oshun/bff/.env.example
1. Purpose#
This document defines the canonical traffic-routing and service-discovery rules
for shell-serving domain APIs behind apps/oshun/bff.
It exists because the repository already had BFF adapter code and multiple standalone domain backends, but it did not yet define:
- which upstream origins are configured explicitly versus inferred
- how development routing differs from staging and production
- what discovery contract the BFF is allowed to rely on for shell-serving domain APIs
This document closes V1-ARCH-085. It does not close V1-ARCH-086 through
V1-ARCH-089.
2. Repo-Informed Current State#
The current repository shows all of the following:
apps/oshun/bffis the mandatory ingress for shell traffic.- The active BFF adapter set is Tara, Veritas, Nyx, Arete, Nisaba, and Metis.
apps/oshun/bff/src/app.tspreviously embedded upstream defaults directly in code with no discovery policy beyond localhost literals.apps/oshun/bff/.env.examplepreviously used a different variable naming scheme than the running BFF code.- Tara, Veritas, Nyx, Nisaba, Iris, and Metis all expose real service runtimes in the repo, but they do not share identical health or readiness paths today.
- Arete is not a standalone app tree in this snapshot; shell-facing Arete capabilities are adapter-backed and still need a canonical BFF endpoint contract.
That combination is acceptable for early scaffolding, but not for launch-grade environment parity or operational clarity.
3. Governing Discovery Rules#
The following rules are mandatory for OSHUN V1:
- Shell clients do not discover or call domain origins directly. Only the BFF discovers shell-serving domain services.
- Discovery for active BFF adapters is environment-variable driven. The BFF must not synthesize upstream hostnames from domain ids at runtime.
- Development and test may use checked-in localhost defaults so the shell can boot with predictable local adapter ports.
- Staging and production must set explicit upstream origins for every active adapter. Missing non-development origins are a deployment error and must fail fast at BFF startup.
- Compatibility aliases may exist temporarily for migration, but the canonical
naming scheme for BFF upstream discovery is
OSHUN_<DOMAIN>_API_BASE_URL. - The same explicit-origin rule applies to future shell adapters for Iris and Lilith once they are connected to the BFF.
4. Canonical Active Adapter Discovery Contract#
| Service | Canonical env var | Temporary alias | Development/test default | Staging rule | Production rule |
|---|---|---|---|---|---|
| Tara | OSHUN_TARA_API_BASE_URL |
TARA_API_URL |
http://localhost:4101 |
required explicit origin | required explicit origin |
| Veritas | OSHUN_VERITAS_API_BASE_URL |
VERITAS_API_URL |
http://localhost:4201 |
required explicit origin | required explicit origin |
| Nyx | OSHUN_NYX_API_BASE_URL |
NYX_API_URL |
http://localhost:4301 |
required explicit origin | required explicit origin |
| Arete | OSHUN_ARETE_API_BASE_URL |
ARETE_API_URL |
http://localhost:4401 |
required explicit origin | required explicit origin |
| Nisaba | OSHUN_NISABA_API_BASE_URL |
NISABA_API_URL |
http://localhost:4501 |
required explicit origin | required explicit origin |
| Metis | OSHUN_METIS_API_BASE_URL |
METIS_API_URL |
http://localhost:4601 |
required explicit origin | required explicit origin |
Additional rules:
- Origins must be absolute
http://orhttps://URLs. - The BFF strips trailing slashes before constructing requests.
OSHUN_RUNTIME_ENV=staging|productionis the canonical switch for non-development discovery policy.NODE_ENV=testcontinues to use local defaults unless explicit upstream origins are provided.
5. Environment Routing Posture#
5.1 Development#
Development routing is allowed to use canonical loopback adapter ports so that the shell can run without a full deployment fabric.
Those ports are BFF-facing adapter endpoints, not necessarily the native port numbers of the standalone domain runtimes themselves. A local proxy, compose stack, port-forward, or domain-specific dev shim may sit between the BFF and the raw domain service process as long as the BFF still targets the canonical adapter origin configured above.
5.2 Staging#
Staging must use explicit environment-specific origins. The BFF may not fall back to localhost and may not assume a naming convention beyond the configured origin value.
This keeps staging topology flexible while preserving a hard guarantee that staging traffic is deliberate and auditable.
5.3 Production#
Production follows the same explicit-origin rule as staging, with the added expectation that:
- origins are HTTPS
- service ownership and on-call mapping are known
- rollout and failover are handled by deployment infrastructure, not ad hoc BFF host construction
6. Upstream Surface Audit#
The current repo does not yet expose a uniform health/readiness contract across all shell-serving backends. The current observed state is:
| Service runtime | Observed entrypoint in repo | Observed health/readiness surfaces |
|---|---|---|
| Tara API | apps/tara/api/src/index.ts |
/health, /ready |
| Veritas API | apps/veritas/api/src/main.ts |
/health, /healthz, /readyz, /health/detailed |
| Nyx API | apps/nyx/api/src/index.ts |
/health |
| Iris API | apps/iris/api/src/index.ts |
/health, /health/live, /health/ready, /health/detailed |
| Nisaba API | domain-owned shell adapter surface | /healthz, /readyz, /health/detailed |
| Metis API gateway | apps/metis/api-gateway/src/app.ts and services/metis/src/metis/main.py |
/healthz, /readyz, /health/detailed; /health, /ready may exist on older gateway deployments |
| Metis worker | apps/metis/worker/src/main.ts |
/health, /healthz, /ready, /readyz on worker health port |
This is a routing concern because discovery and reachability are only reliable
when the BFF knows which origin it should target and future readiness policy can
be layered consistently on top of that. The observed health/readiness
inconsistencies are handled separately by V1-ARCH-088.
7. Implications for Future Adapters and Downstream Workers#
The following future shell-serving backends or downstream service families must follow the same discovery model when connected:
- Iris capability adapters over
apps/iris/api - Lilith shell-facing capability facades
- Metis worker reachability remains a downstream dependency of the active Metis gateway adapter rather than a shell-discovered origin
For those services, the governing rule is already fixed by this document: non-development environments require explicit origins and the BFF must not derive hostnames implicitly.
8. Acceptance Record#
The OSHUN V1 program accepts the following routing and discovery posture:
- localhost defaults are allowed only for development and test
- canonical BFF discovery names use
OSHUN_*_API_BASE_URL - staging and production require explicit origins and fail fast when missing
- BFF routing policy is centralized and typed rather than hidden in ad hoc literals
This acceptance closes V1-ARCH-085.