# OSHUN V1 Domain Service Consolidation Strategy

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

- `docs/adr/ADR-0007-oshun-shell-architecture-and-domain-adapters.md`
- `docs/releases/v1/specs/program-charter.md`
- `docs/releases/v1/reports/subsystem-ownership-matrix.md`
- `docs/releases/v1/specs/todos.md`
- `apps/oshun/bff/src/adapters/domain-service-adapters.ts`

---

## 1. Purpose

This document is the canonical consolidation policy for standalone domain apps
that serve the unified OSHUN shell.

It exists to close the governance gap identified in `V1-GOV-028`: the repo had
an accepted adapter pattern and multiple standalone domain app trees, but no
single policy that said which of those apps are shell-serving backends, which
remain specialist or legacy frontends, and which ingress path is mandatory for
the shell.

This document closes `V1-GOV-028`, `V1-ARCH-083`, and `V1-ARCH-084`. Together
with the BFF adapter registry, shell-to-service integration tests, and
platform-foundation release gates, it is the V1 Section 27 consolidation source
of truth.

## 2. Repo-Informed Current State

The current repository shows all of the following at once:

- `apps/oshun/web` and `apps/oshun/mobile` are the intended unified shell
  surfaces.
- `apps/oshun/bff` already implements shell-facing domain service adapters for
  Tara, Veritas, Nyx, Arete, Nisaba, and Metis.
- standalone domain app trees still exist for `tara`, `veritas`, `nyx`, `iris`,
  `lilith`, and `metis`.
- some of those trees contain domain-native web/mobile/admin surfaces that are
  still useful as legacy products, specialist operator tools, or source
  references.
- active domain backends expose BFF adapter boundaries, while substrate
  capabilities such as Iris and Lilith are consumed through named server-side
  adapters instead of direct shell dependencies on standalone frontends.

The governance problem is not whether these standalone trees may exist. The
problem is preventing them from becoming ad hoc alternate shell backends or
undocumented direct dependencies.

## 3. Governing Decision

For OSHUN V1, the only canonical shell integration path is:

`apps/oshun/web` or `apps/oshun/mobile` `-> apps/oshun/bff`
`-> explicit domain/substrate adapters`
`-> domain-owned backend APIs, gateways, workers, or substrate services`

The following rules are mandatory:

1. The OSHUN shell must not call standalone domain web or mobile frontends as
   data sources.
2. The OSHUN shell must not depend on direct client-to-domain API calls that
   bypass `apps/oshun/bff`, unless a separate accepted exception document
   exists.
3. Standalone domain frontends may remain in the repo, but they are not
   canonical shell surfaces unless the charter explicitly says otherwise.
4. Domain-owned backend APIs, gateways, and workers may remain independent
   deployable systems if they serve the shell through typed BFF adapter
   boundaries.
5. Shared substrate domains such as Iris and Lilith must serve shell needs
   through named capability adapters or BFF-owned facades, not through direct
   shell embedding of their standalone UIs.

## 4. Consolidation Taxonomy

### 4.1 Canonical Shell Surfaces

- `apps/oshun/web`
- `apps/oshun/mobile`

These are the only canonical user-facing shell containers for V1.

### 4.2 Shell-Serving Backends

These are independent domain-owned services or gateways that may remain separate
deployables while still serving the shell:

- Tara API surfaces
- Veritas API surfaces
- Nyx API surfaces
- Metis API gateway and worker surfaces
- Iris API capability surfaces
- Lilith capability services that back persona, media, voice, or policy behavior

### 4.3 Specialist, Legacy, or Parallel Frontends

These are allowed to remain as domain-native surfaces, but they are not the
source of truth for shell routing or shell data contracts:

- `apps/tara/mobile`, `apps/tara/web`
- `apps/veritas/mobile`, `apps/veritas/web`
- `apps/nyx/mobile`, `apps/nyx/ar-sky`, `apps/nyx/star-map`,
  `apps/nyx/vr-planetarium`
- `apps/iris/dashboard`, `apps/iris/web`, `apps/iris/mobile`,
  `apps/iris/desktop`
- `apps/lilith/web`, `apps/lilith/mobile`, `apps/lilith/desktop`
- `apps/metis/web`, `apps/metis/admin`

Their continued existence does not change the consolidation rule: the unified
OSHUN shell talks to backends through the BFF and adapters.

## 5. Canonical Integration Map

### 5.1 Service Integration Matrix

| Domain  | Standalone App Reality                                                                                                     | Shell-Serving Backend of Record                      | Canonical Shell Ingress                                            | Current Adapter Status                                                              | Frontend Consolidation Posture                                                                                                                |
| ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Tara    | `apps/tara/api`, `apps/tara/mobile`, `apps/tara/web`, `apps/tara/content`                                                  | `apps/tara/api`                                      | `apps/oshun/bff` Tara adapter                                      | implemented in `apps/oshun/bff`                                                     | Tara web/mobile may remain parallel products during migration, but shell data and launch contracts come from the BFF-backed Tara API path.    |
| Veritas | `apps/veritas/api`, `apps/veritas/web`, `apps/veritas/mobile`, plus domain workers/tools                                   | `apps/veritas/api`                                   | `apps/oshun/bff` Veritas adapter                                   | implemented in `apps/oshun/bff`                                                     | Veritas frontends remain domain-native until shell parity is complete; they are not a backdoor around shell contracts.                        |
| Nyx     | `apps/nyx/api`, `apps/nyx/mobile`, `apps/nyx/star-map`, `apps/nyx/ar-sky`, `apps/nyx/vr-planetarium`, `apps/nyx/pipelines` | `apps/nyx/api` plus domain-owned pipelines behind it | `apps/oshun/bff` Nyx adapter                                       | implemented in `apps/oshun/bff`                                                     | Nyx may keep specialist immersive clients, but shell continuity still routes through adapter-resolved launches and API-backed cards.          |
| Nisaba  | no standalone app tree in this repo snapshot; domain code is library-backed                                                | domain-owned Nisaba service or adapter surface       | `apps/oshun/bff` Nisaba adapter                                    | implemented in `apps/oshun/bff`                                                     | Nisaba shell reading/notebook flows are mediated by the BFF; future standalone study tools must not become alternate shell data sources.      |
| Iris    | `apps/iris/api` plus standalone Iris UI surfaces (`dashboard`, `web`, `mobile`, `desktop`, `marketplace`)                  | `apps/iris/api` and memory capability libraries      | `libs/oshun/memory-iris` substrate adapter or BFF facade           | substrate adapter implemented; not a shell navigation-domain adapter                | Iris standalone UIs are specialist products; the shell consumes memory/profile capabilities through server-side adapters only.                |
| Lilith  | `apps/lilith/*` includes many independent services plus standalone web/mobile/desktop clients                              | Lilith capability services, not Lilith frontends     | `libs/oshun/persona-policy-lilith` substrate adapter or BFF facade | substrate adapter implemented; facades are capability-specific, not frontend routes | Lilith frontends are not shell surfaces. The shell may consume Lilith-backed capabilities only through explicit server-side adapters/facades. |
| Metis   | `apps/metis/api-gateway`, `apps/metis/worker`, `apps/metis/web`, `apps/metis/admin`                                        | `apps/metis/api-gateway` plus `apps/metis/worker`    | BFF-backed Metis adapter required for unified shell                | implemented in `apps/oshun/bff`                                                     | Metis web/admin may remain specialist or parallel surfaces, but shell-facing educational flows must converge on the BFF + adapter path.       |

### 5.2 Interpretation Rules

This matrix is the authoritative map for how standalone domain app trees serve
the shell:

1. the `Shell-Serving Backend of Record` column names the service boundary the
   shell is allowed to depend on
2. the `Canonical Shell Ingress` column names the required mediation layer
3. the `Current Adapter Status` column distinguishes what is already wired in
   code from what is accepted policy but still pending implementation
4. the `Frontend Consolidation Posture` column prevents standalone domain
   frontends from being mistaken for shell sources of truth

## 6. Current Implementation vs. Accepted Target

### 6.1 Already Present in Code

- Tara, Veritas, Nyx, Nisaba, and Metis already have concrete shell-facing BFF
  adapters in `apps/oshun/bff/src/adapters/domain-service-adapters.ts`.
- Arete already follows the same shell-facing adapter posture even though it is
  not part of the standalone-app consolidation problem.
- Metis, Iris, and Lilith already exist as standalone service or application
  trees in the repo and therefore have explicit consolidation policy instead of
  implicit direct shell coupling.

### 6.2 Required by This Strategy

- Metis shell flows now converge on a BFF-backed adapter instead of relying on
  `apps/metis/web` or `apps/metis/admin` directly.
- Iris shell capabilities route through named server-side adapters or BFF
  facades over `apps/iris/api` and `libs/oshun/memory-iris`.
- Lilith-backed shell capabilities route through named substrate adapters or
  BFF-owned facades, including `libs/oshun/persona-policy-lilith`, rather than
  direct shell-to-service fan-out from the client.
- standalone domain frontends must be classified explicitly as canonical shell
  surfaces, specialist surfaces, or sunset candidates before GA.

### 6.3 Service Disposition and Rationale

| Domain or Capability Family      | Shell-Boundary Disposition                                              | Rationale                                                                                                                                                                   |
| -------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tara                             | remain an independent backend API behind a BFF adapter                  | Tara is a first-class product domain with domain-owned business logic, content, and release cadence. The shell needs normalized contracts, not Tara-internal coupling.      |
| Veritas                          | remain an independent backend API behind a BFF adapter                  | Veritas has domain-specific verification, source, and editorial logic that should remain domain-owned while the shell consumes normalized feeds and actions.                |
| Nyx                              | remain an independent backend API behind a BFF adapter                  | Nyx includes domain-specific astronomy data, immersive clients, and pipeline logic that should not collapse into generic shell services.                                    |
| Metis                            | remain an independent backend gateway/worker stack behind a BFF adapter | Metis is both a first-class domain and the educational substrate; it needs domain-owned backend depth while still presenting shell-safe contracts through BFF mediation.    |
| Iris shell-facing capabilities   | fold into shared Oshun service facades at the shell boundary            | Iris is a substrate capability, not a shell navigation peer. The shell should consume memory/profile capability contracts, not expose Iris topology directly.               |
| Lilith shell-facing capabilities | fold into shared Oshun service facades at the shell boundary            | Lilith provides persona, voice, media, and policy-adjacent capabilities. Treating those as direct shell-facing domain APIs would leak internal topology and blur ownership. |

Note:

- "fold into shared Oshun services" refers to the shell-facing contract and
  ingress layer, not to deleting the underlying domain-owned Iris or Lilith
  runtimes.
- Arete is not part of this decision because it does not currently exist as a
  standalone app tree in the same sense as the six scoped domains above.

## 7. Operational Guardrails

The following governance guardrails apply immediately:

1. New shell features may not introduce direct web/mobile client dependencies on
   standalone domain origins.
2. New shell-facing domain endpoints must be described as BFF adapter contracts
   first, then implemented behind that boundary.
3. Any standalone domain frontend that is superseded by shell parity must have
   deprecation and sunset criteria written before GA.
4. Any standalone domain app that assumes process-local auth, config, or state
   incompatible with backend-only serving must be treated as architecture work,
   not ignored as incidental debt.

## 8. Acceptance Record

The OSHUN V1 program accepts the following as the governing consolidation
strategy:

- OSHUN ships one shell, not a federation of direct-linked domain clients.
- Standalone domain app trees may continue to exist, but shell-serving behavior
  must be normalized behind `apps/oshun/bff` and typed adapters.
- Independent backend ownership is preserved where it helps domain velocity, so
  long as shell ingress, contracts, and deprecation posture remain centralized
  and explicit.

This acceptance closes `V1-GOV-028`, `V1-ARCH-083`, and `V1-ARCH-084`, and the
current BFF/service-discovery/contract verification suite closes the related V1
Section 27 implementation requirements.
