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.mddocs/releases/v1/specs/program-charter.mddocs/releases/v1/reports/subsystem-ownership-matrix.mddocs/releases/v1/specs/todos.mdapps/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/webandapps/oshun/mobileare the intended unified shell surfaces.apps/oshun/bffalready 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, andmetis. - 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:
- The OSHUN shell must not call standalone domain web or mobile frontends as data sources.
- 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. - Standalone domain frontends may remain in the repo, but they are not canonical shell surfaces unless the charter explicitly says otherwise.
- Domain-owned backend APIs, gateways, and workers may remain independent deployable systems if they serve the shell through typed BFF adapter boundaries.
- 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/webapps/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/webapps/veritas/mobile,apps/veritas/webapps/nyx/mobile,apps/nyx/ar-sky,apps/nyx/star-map,apps/nyx/vr-planetariumapps/iris/dashboard,apps/iris/web,apps/iris/mobile,apps/iris/desktopapps/lilith/web,apps/lilith/mobile,apps/lilith/desktopapps/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:
- the
Shell-Serving Backend of Recordcolumn names the service boundary the shell is allowed to depend on - the
Canonical Shell Ingresscolumn names the required mediation layer - the
Current Adapter Statuscolumn distinguishes what is already wired in code from what is accepted policy but still pending implementation - the
Frontend Consolidation Posturecolumn 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/weborapps/metis/admindirectly. - Iris shell capabilities route through named server-side adapters or BFF
facades over
apps/iris/apiandlibs/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:
- New shell features may not introduce direct web/mobile client dependencies on standalone domain origins.
- New shell-facing domain endpoints must be described as BFF adapter contracts first, then implemented behind that boundary.
- Any standalone domain frontend that is superseded by shell parity must have deprecation and sunset criteria written before GA.
- 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/bffand 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.