Eve library

OSHUN V1 Domain Service Consolidation Strategy

Spec

Revision 1

On this page

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.