# OSHUN V1 Domain Service Routing and Discovery Rules

Status: Accepted v1.0  
Date: March 23, 2026  
Owners: OSHUN Engineering, OSHUN Platform, Domain Leads  
Related:

- `docs/releases/v1/specs/domain-service-consolidation-strategy.md`
- `docs/releases/v1/specs/todos.md`
- `apps/oshun/bff/src/app.ts`
- `apps/oshun/bff/src/config/domain-service-discovery.ts`
- `apps/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/bff` is the mandatory ingress for shell traffic.
- The active BFF adapter set is Tara, Veritas, Nyx, Arete, Nisaba, and Metis.
- `apps/oshun/bff/src/app.ts` previously embedded upstream defaults directly in
  code with no discovery policy beyond localhost literals.
- `apps/oshun/bff/.env.example` previously 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:

1. Shell clients do not discover or call domain origins directly. Only the BFF
   discovers shell-serving domain services.
2. Discovery for active BFF adapters is environment-variable driven. The BFF
   must not synthesize upstream hostnames from domain ids at runtime.
3. Development and test may use checked-in localhost defaults so the shell can
   boot with predictable local adapter ports.
4. 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.
5. Compatibility aliases may exist temporarily for migration, but the canonical
   naming scheme for BFF upstream discovery is `OSHUN_<DOMAIN>_API_BASE_URL`.
6. 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://` or `https://` URLs.
- The BFF strips trailing slashes before constructing requests.
- `OSHUN_RUNTIME_ENV=staging|production` is the canonical switch for
  non-development discovery policy.
- `NODE_ENV=test` continues 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`.
