# 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](./product-promise.md) 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**.

| Name        | Package                 | Responsibility                                                                 | `availability` |
| ----------- | ----------------------- | ------------------------------------------------------------------------------ | -------------- |
| **Tara**    | `@oshun/domain-tara`    | Rituals, practices, breathwork, meditation, teachers, contemplative continuity | `active`       |
| **Arete**   | `@oshun/domain-arete`   | Goals, habits, routines, journaling, weekly review, humane streak/recovery     | `active`       |
| **Veritas** | `@oshun/domain-veritas` | Grounded stories, claims, sources, evidence, counterclaims, topic hubs         | `active`       |
| **Nyx**     | `@oshun/domain-nyx`     | Sky events, observation windows, awe-and-perspective, calendar integrations    | `beta`         |
| **Nisaba**  | `@oshun/domain-nisaba`  | Scholarly passages, sources, lexicon, morphology, concept graph, notebooks     | `beta`         |
| **Metis**   | `@oshun/domain-metis`   | Courses, tutoring, BYOM study, assessments, knowledge-graph promotion, LMS     | `planned`      |

### 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:

```jsonc
{
  "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.

| Name       | Engine monorepo (no root pkg) | V1 adapter lib                   | Responsibility                                                                         |
| ---------- | ----------------------------- | -------------------------------- | -------------------------------------------------------------------------------------- |
| **Sophia** | `libs/sophia/`                | `@oshun/evidence-sophia`         | Grounded answers, evidence packs, citation trails, retrieval/synthesis labeling        |
| **Iris**   | `libs/iris/`                  | `@oshun/memory-iris`             | Assistant memory, identity boundaries, consent, deletion/export, admin inspection      |
| **Psyche** | `libs/psyche/`                | `@oshun/embodiment-psyche`       | Real-time text/voice/avatar runtime: envelope, turn-taking, lip sync, recovery         |
| **Lilith** | `libs/lilith/`                | `@oshun/persona-policy-lilith`   | Contemplative tone, persona safety, crisis-aware behavior, voice abuse policy          |
| **Isis**   | `libs/isis/`                  | `@oshun/generation-control-isis` | Governed generation control plane: templates, registries, gates, failover, rollback    |
| **Aje**    | `libs/aje/`                   | `@oshun/payments-bridge`         | Library-only non-custodial settlement, merchant invoices, per-chain providers, wallets |

### 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/`.

| Name        | Lib             | Role                                                                                                          |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Aja**     | `libs/aja/`     | Embodied-instruction services (movement/practice pedagogy), consumed via `@oshun/embodiment-aja`              |
| **Yemaya**  | `libs/yemaya/`  | Rendering substrate for media surfaces consumed by V1 domains                                                 |
| **Themis**  | `libs/themis/`  | Academic-integrity adjudication for Metis assessments & tutoring                                              |
| **Bellona** | `libs/bellona/` | Studio-only engine-bridge and build substrate (Unity/Unreal/Godot/Blender/DaVinci, OpenUSD, build/export, XR) |
| **Hathor**  | `libs/hathor/`  | Studio-only narrative, world, and lore-authoring substrate                                                    |
| **Neith**   | `libs/neith/`   | Studio-only inverse-modeling substrate (image-to-parameter estimation)                                        |

### 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.**

| Surface                                       | Package(s)                                            |
| --------------------------------------------- | ----------------------------------------------------- |
| Oshun Web (customer)                          | `apps/oshun/web/`                                     |
| Oshun Mobile (customer)                       | `apps/oshun/mobile/`                                  |
| Oshun BFF                                     | `apps/oshun/bff/`                                     |
| Oshun Admin Web                               | `apps/oshun/admin/`                                   |
| Oshun Admin Mobile                            | `apps/oshun/admin-mobile/`                            |
| Oshun Studio                                  | `apps/oshun/web/src/app/studio/` (subroute)           |
| Oshun Tenant Console                          | `apps/oshun/tenant-admin` (standalone Next app; § 20) |
| Oshun Telegram Bot                            | `apps/oshun/telegram-bot/` (§ 26)                     |
| Oshun Telegram Mini App                       | `apps/oshun/telegram-miniapp/` (§ 26)                 |
| Oshun Public Web and Distribution             | `apps/oshun/web/src/app/landing/` + listings          |
| Metis Web / Admin / Gateway / Mobile / Worker | `apps/metis/{web,admin,api-gateway,mobile,worker}/`   |

### 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](./product-promise.md) — what these subsystems
  collectively promise, and the same tiering reconciliation.
- [High-Level Architecture](./high-level-architecture.md) — the diagram these
  names label (and the `/v1/<domain>` route correction).
- [Customer-Facing Domains](./customer-domains.md) — the six domains in depth.
- [Sophia — Grounding Substrate](./substrate-sophia.md),
  [Iris — Assistant Memory Substrate](./substrate-iris.md),
  [Psyche — Real-Time Runtime Substrate](./substrate-psyche.md),
  [Lilith — Contemplative Policy Substrate](./substrate-lilith.md),
  [Isis — Generation Control Substrate](./substrate-isis.md),
  [Aje — Non-Custodial Payment Substrate](./substrate-aje.md).
- [Cross-Domain Support](./cross-domain-support.md) — Aja, Yemaya, Themis,
  Bellona, Hathor, Neith.
- [Product Surfaces](./product-surfaces.md) — the apps and sub-apps table in
  depth.
- [../ARCHITECTURE.md](../ARCHITECTURE.md) — the architecture hub.