Subsystem Glossary

This glossary fixes the vocabulary used everywhere in V1 — package names, route prefixes, surface tables, and admin taxonomy all inherit from these names. It serves engineers and architects who need to know which lib or app a name resolves to, and product/governance leads who need to know what each subsystem is responsible for. It sits beside the V1 Product Promise at the top of the architecture docs: the promise says what V1 is; this glossary names the parts. Every name below was verified against a real package.json or directory under libs/ and apps/; where the prose and the code disagree on framing (tiering, surface counts), the code wins and the discrepancy is called out.

How to read this glossary#

Two layers share these names, and confusing them is the most common mistake:

• Substrate engines are the sprawling, multi-package monorepos under top-level libs/{sophia,iris,psyche,lilith,isis} and libs/aje. These have no root package.json — they are not @oshun/* packages. libs/sophia/, for example, is a tree of independent packages: agents/, citation-analysis/, citation-graph/, credibility/, corpus/, crawling/, and ~20 more.
• V1 adapter libs are the thin @oshun/<verb>-<substrate> packages under libs/oshun/ that V1 actually consumes. These are the seams the BFF and domains call: @oshun/evidence-sophia, @oshun/memory-iris, @oshun/embodiment-psyche, @oshun/persona-policy-lilith, @oshun/generation-control-isis, @oshun/payments-bridge.

When a customer-facing surface "uses Sophia," it imports @oshun/evidence-sophia, not libs/sophia/ directly. The glossary names the responsibility; the adapter lib is the integration point.

Customer-facing domains#

The six domains are the customer surface area of V1. Each resolves to a real @oshun/domain-* package and to an entry in the domain registry (libs/oshun/domain-registry/src/registry.ts), which is the single source of truth for identity, auth, routing, and availability tier.

Availability tiering is real — domains are not co-equal#

The doc prose historically called all six domains "first-class … with no tiering." The registry encodes a real tiering via DomainAvailability = 'active' | 'beta' | 'planned' (registry.ts:14). The per-domain statuses are: Tara active (registry.ts:166), Veritas active (:225), Arete active (:355), Nyx beta (:290), Nisaba beta (:420), Metis planned (:489).

This tiering has teeth. getAvailableDomains() (registry.ts:503) filters out every 'planned' domain (availability !== 'planned'), so the canonical launch configuration is five domains, not six. getDefaultShellDomainConfiguration() returns:

{
  "primaryDomain": "tara",
  "enabledDomains": ["tara", "veritas", "nyx", "arete", "nisaba"],
  "companionDomains": ["veritas", "nyx", "arete", "nisaba"],
  "betaDomains": ["nyx", "nisaba"],
  "domainCount": 5,
}

Metis is excluded from launch configuration but kept visible in shell navigation: getShellNavigationDomains() (registry.ts:507) returns all six (['tara', 'veritas', 'nyx', 'arete', 'nisaba', 'metis']). The registry test pins exactly this: index.test.ts:103 asserts the registry "exposes planned Metis in shell navigation without enabling it for launch configuration," and index.test.ts:96 asserts getAvailableDomains() excludes Metis. This contradicts the product doc's framing of Metis as "launch-blocking V1 scope." The honest reading: Metis is the most developed domain (it owns its own apps/metis/ and libs/metis/ stacks) and is a committed V1 ambition, but its registry status is planned and it is not launch-enabled. Read "first-class" throughout these docs as "shares the shell, BFF, design tokens, and assistant" — not as "same availability tier."

Each registry entry also carries far more than a name: a DomainAuthPolicy (required, sessionKind of 'customer' | 'learner' | 'reader' | 'operator', OAuth-style scopes, and step-up actions), a per-domain analytics-id (e.g. oshun.domain.tara), notification-channel (e.g. oshun.tara.rituals), assistant-context-key (e.g. taraRitualContext), deep-link-prefix (e.g. oshun://tara), an admin-taxonomy (owner subsystem, review queues, audit category, content classes), an offlineFallback card, a launchContract, a shellNarrative, and a capabilities list (Tara's is ['meditation', 'courses', 'audio', 'favorites']).

Platform substrates#

The substrates supply the cross-cutting capabilities every domain leans on. Five are product substrates; Aje is the payment substrate, promoted into V1 scope in the 2026-05-11 update — six platform substrates in total. Each substrate is a large engine monorepo with no root package.json, fronted by a thin @oshun/* adapter lib that V1 consumes.

Sophia, the grounding substrate#

libs/sophia/ is one of the largest monorepos in the codebase — its packages include agents, citation-analysis, citation-graph, credibility, corpus, crawling, embeddings, indexing, ingestion, knowledge-graph, research-engine, semantic-search, verification, and more. V1 consumes it through @oshun/evidence-sophia, the seam where "ground claims through Sophia" becomes a call. It backs every grounding promise: evidence packs, citation trails, and the retrieval-versus-synthesis labeling that lets the customer see whether an answer is sourced or generated.

Iris, Psyche, Lilith, Isis#

• Iris (@oshun/memory-iris) owns assistant memory and the consent boundary around it — profile/session/notebook memory, consent records, deletion and export, privacy-aware suppression, and policy-controlled admin inspection. It is the seam behind "make memory and consent visible."
• Psyche (@oshun/embodiment-psyche) owns the real-time text/voice/avatar runtime: session envelope, turn-taking, interruption, transcript sync, lip sync, expression coherence, and continuity under reconnect. It is what keeps "interrupted sessions degrade safely" true.
• Lilith (@oshun/persona-policy-lilith) owns contemplative tone policy, teacher-persona safety, crisis-aware behavior, voice-quality and voice-abuse policy, and spiritual-domain boundaries. Lilith also lends its name to the design system the shell rooms are built in.
• Isis (@oshun/generation-control-isis) is the governed generation control plane: workflow templates, model/provider registries, environment promotion, provenance bundles, release gates, failover, and rollback. It is what makes "premium media only through governed paths" enforceable.

Aje, the payment substrate#

libs/aje/ (named for the Yoruba orisha of wealth, commerce, and the marketplace) is a large standalone Web3 monorepo with no root package.json — 30+ subdirectories including chains, contracts, payments, settlement-escrow, wallets, defi, nft, zkp, account-abstraction, bridges, bitcoin, appchains, and more. It is library-only: non-custodial settlement, merchant invoices, per-chain providers, and wallet management.

V1 consumes Aje only through @oshun/payments-bridge (libs/oshun/payments-bridge), which is where the bridge between entitlements and on-chain settlement lives. Its src/ is itself well-shaped, with admin-surface, customer-surface, entitlement-bus, oracle-aggregator, receipt-signer, security-gates, state-mapper, and a cold-spend-queue. Customers and operators never touch libs/aje/ directly — the bridge is the governed boundary.

Cross-domain support#

These top-level libs back domain and Studio work without owning a customer-facing domain of their own. All exist as real directories under libs/.

Aja, the embodied-instruction adapter#

Aja is consumed via @oshun/embodiment-aja, whose src/adapter.ts imports from @oshun/contracts/aja/index.js and declares SUPPORTED_DOMAINS = ['fitness', 'yoga', 'dance', 'martial-arts', 'sports', 'rehabilitation']. This is the seam that Metis (and movement-oriented Tara practices) hooks into for demonstration plans and stable-contract discovery of embodied instruction.

Bellona, Hathor, and Neith are Studio-only#

Bellona, Hathor, and Neith have no dedicated customer-facing surface — they are Studio-only V1 substrates. (They were absent from the original domain lists because of that, and were folded in when the V1 route scope was reconciled on 2026-05-29; that reconciliation is now part of current state, not a pending change.) Their surfaces are inventoried under the Studio walkthrough, not under the customer shell.

Surfaces#

The surfaces are the deployable apps and sub-apps. Most customer-facing domains render through the two consumer apps via the shared shell and the BFF; Metis is the exception — it carries its own dedicated app and microservice stack.

Metis owns its own stack — including a mobile app#

Metis is the only V1 domain with its own dedicated apps and microservice stack beneath apps/metis/; every other customer-facing domain renders through apps/oshun/web and apps/oshun/mobile via the shared shell and the BFF. The real apps/metis/ tree contains five entries: admin, api-gateway, mobile, web, and worker — the mobile app is real but was historically omitted from the architecture surface table, which listed only {web, admin, api-gateway, worker}. Metis also has the deepest library tree of any domain: libs/metis/ holds ~25 packages including adaptive, assessment, course, gradebook, knowledge-graph, llm-client, model-registry, tutoring, verification, and an api-client subpackage (the renamed adapter referenced via § 1.3).

The shared consumer shell#

The non-Metis domains compose into a single shared shell built from @oshun/shell-* libs: shell-core, shell-assistant, shell-routines, shell-achievements, shell-desktop, and shell-wearable. The apps/oshun/web/src/app/domains/[domainId] catch-all serves the deeper power-user workspaces (including Nisaba and Metis surfaces), while consumer-hub rooms (TaraRoom, AreteRoom, etc.) render the calm Lilith-design-system home.

Route prefixes — registry advertises one path, the BFF mounts another#

There is a real, easy-to-miss discrepancy between the registry's advertised base path and the BFF's mounted routes, and it is worth pinning down because the high-level-architecture diagram historically got it wrong.

• Each registry entry carries a bff-base-path of the form /api/oshun/domains/<domain> (e.g. '/api/oshun/domains/tara' at registry.ts:116). This is the advertised, registry-level base path.
• The canonical BFF runtime routes are mounted at /v1/<domain>/*, not /api/oshun/domains/<domain>/*. For example, apps/oshun/bff/src/tara/ambient-audio-routes.ts:114 registers /v1/tara/sessions/:sessionId/guidance. The BFF assembles these in apps/oshun/bff/src/app.ts, which mounts registerDomainsRoutes (app.ts:603) plus per-domain registrars registerNisabaRoutes (:637), registerAreteRoutes (:640), and registerTaraRoutes (:641).
• A literal /api/oshun/domains/veritas/... path does exist, but only for one feature: the Veritas retraction cascade (apps/oshun/bff/src/server.ts:587 and veritas/retraction-cascade-runtime.ts:68 register POST /api/oshun/domains/veritas/sources/:id/retract). It is the exception, not the generic prefix.

So when a diagram or doc says "the BFF exposes per-domain routes under /api/oshun/domains/{...}," read it as the registry-advertised base path; the mounted per-domain prefix in code is /v1/<domain>.

Launch locales#

The launch language scope is fixed in code at libs/oshun/i18n/src/index.ts: OSHUN_LAUNCH_LOCALES = ['en-US', 'es-US', 'fr-FR', 'de-DE', 'ar', 'he', 'ja-JP', 'pt-BR'] (eight locales, including the RTL ar and he), with OSHUN_DEFAULT_LAUNCH_LOCALE = 'en-US'. Every customer-facing string the shell renders is scoped to this set, and the RTL locales are part of why the design system carries directionality from the start.

A note on staleness#

The source glossary is dated 2026-05-11 and anchors several counts and "today" assertions to that date. The codebase has materially evolved since: the apps/oshun/web/src/app/domains/[domainId] catch-all now serves Nisaba and Metis surfaces, shell-desktop and shell-achievements libs have been added, and the apps/metis/mobile app exists. The 2026-05-29 reconciliation note about Bellona/Hathor/Neith is a settled fact, not a pending change. Treat the registry, BFF route files, and libs/oshun/i18n as the live source of truth; this page reflects state verified on 2026-06-24.

Related#

• V1 Product Promise — what these subsystems collectively promise, and the same tiering reconciliation.
• High-Level Architecture — the diagram these names label (and the /v1/<domain> route correction).
• Customer-Facing Domains — the six domains in depth.
• Sophia — Grounding Substrate, Iris — Assistant Memory Substrate, Psyche — Real-Time Runtime Substrate, Lilith — Contemplative Policy Substrate, Isis — Generation Control Substrate, Aje — Non-Custodial Payment Substrate.
• Cross-Domain Support — Aja, Yemaya, Themis, Bellona, Hathor, Neith.
• Product Surfaces — the apps and sub-apps table in depth.
• ../ARCHITECTURE.md — the architecture hub.