# Oshun Monorepo — Architecture Overview

Rewritten 2026-07-16 from the measured state of the repository (audit R-21,
`docs/audits/MONOREPO_ARCHITECTURE_AUDIT_2026-07-16.md`). The previous version
of this document described the April 2026 architecture and predated most of the
current domains. Machine-readable domain facts live in `domains.json`; this
document is the narrative view.

## The shape of the system

Oshun is one polyglot monorepo carrying **ten products (V1–V10)** on a shared
platform of **48 domain libraries**, four platform library groups, and ~34
application groups:

- **Products.** V1 (Oshun platform) is the customer/admin/assistant platform
  built from `apps/` + `libs/`. V2–V9 are distinct products (fighting game,
  metaverse, tactical universe, open-world narrative, companions, creator
  republic, detective universe, learning flagship) living in `V<n>/` trees (UE
  content, docs, ops) with TypeScript/Rust halves under `apps/v<n>` and
  `libs/v<n>` for V3 and V6–V9. V10 ("The Rail") is the ambient companion layer
  over all of them. `V_SERIES.md` carries the machine-derived status of each
  product.
- **Domain libraries** (`libs/<domain>/<lib>`) are the platform's capability
  layer — 3,000+ Nx projects across 48 mythology-named domains (matrix below).
  Domains publish under per-domain npm scopes (`@isis/*`, `@neith/*`, …) and are
  isolated by Nx tags + eslint boundary rules.
- **Platform libraries**: `libs/shared` (56 `@oshun/*` foundation libs —
  logging, http-client, database, cache, config, resilience, math, ids,
  collections, …), `libs/contracts` (cross-domain schemas, including the V10
  rail channel contract), `libs/proto`, `libs/openapi`.
- **Applications** (`apps/<domain>/<surface>`): product surfaces (web, mobile,
  admin, BFF, services). Three deployables still live under `services/`
  (concordia, metis, psyche) pending the R-9 consolidation.

## Domain Responsibilities Matrix

Generated from `domains.json` (run `node tools/domains/check-registry.mjs` to
verify it is current). Projects = Nx projects in the domain.

| Domain       | Projects | npm scope  | Responsibility                                                                                                                             |
| ------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `aglaea`     | 93       | @aglaea    | The `libs/aglaea/` area: 93 Nx libraries that make up Aglaea, the AI-powered fashion, beauty, skincare, haircare and personal-styling dom… |
| `airmid`     | 19       | @airmid    | The `libs/airmid/` area: nineteen Nx libraries that together form an evidence-based phytotherapy and botanical-intelligence platform — fr… |
| `aja`        | 40       | @aja       | The `libs/aja/` area: forty Nx libraries that make up the motion-capture → 3D-pose → retargeting → avatar-animation pipeline behind Lilit… |
| `aje`        | 39       | @aje       | The `libs/aje/` area: ~39 Nx libraries that make up Oshun's multi-chain **blockchain / Web3 infrastructure** stack — from low-level crypt… |
| `annapurna`  | 21       | @annapurna | The `libs/annapurna/` area: twenty-one Nx libraries implementing the **autonomous restaurant and culinary operations** domain — a `@annap… |
| `aphrodite`  | 184      | @aphrodite | The `libs/aphrodite/` area: 184 Nx libraries that make up Aphrodite, the intimate live-performance / adult creator-economy domain — strea… |
| `arete`      | 12       | @arete     | The `libs/arete/` area: twelve Nx libraries that implement the **personal-development / life-mastery domain** — habits, goals, journaling… |
| `asase`      | 28       | @asase     | The `libs/asase/` area: 28 Nx libraries implementing **food & agriculture operations intelligence for Ghana's value chain** — a shared do… |
| `athena`     | 42       | @athena    | The `libs/athena/` area: forty Nx libraries that implement **Athena**, the maker / workshop-manufacturing domain — parametric CAD, CAM/CN… |
| `bellona`    | 40       | @bellona   | The `libs/bellona/` area: ~40 Nx libraries that make up Bellona, Oshun's engine-bridge / DCC-automation / remote-creative-control-plane d… |
| `brigid`     | 24       | @brigid    | The `libs/brigid/` area: 24 Nx libraries implementing **Brigid**, the industrial-automation intelligence domain — deterministic engineeri… |
| `calliope`   | 30       | @calliope  | The `libs/calliope/` area: thirty Nx libraries that build and operate **autonomous fictional music artists** — birthing a persona, giving… |
| `cybele`     | 19       | @cybele    | The `libs/cybele/` area: nineteen Nx libraries implementing the **Ghana real estate, construction, and proptech domain** — from geodesy a… |
| `demeter`    | 27       | @demeter   | The `libs/demeter/` area: twenty-seven Nx libraries that make up the domain logic of **Demeter, the home-gardening platform** — from the … |
| `euterpe`    | 50       | @euterpe   | The `libs/euterpe/` area: ~49 Nx libraries that make up Oshun's music-and-audio domain — everything from music-theory primitives and a pu… |
| `freya`      | 26       | @freya     | The `libs/freya/` area: 26 Nx libraries implementing the **Freya luxury-goods & fashion intelligence** domain — an Africa/Ghana-centred l… |
| `gaia`       | 9        | @gaia      | GraphCast/GenCast-class forecast models, cyclone tracking, nowcasting, and GRIB2 codec infrastructure in TypeScript and Rust               |
| `galatea`    | 37       | @galatea   | The `libs/galatea/` area: a humanoid-robotics software stack for fashion-retail and entertainment robots — kinematics, whole-body control… |
| `hathor`     | 19       | @hathor    | The `libs/hathor/` area: eighteen Nx libraries that make up **Hathor, the "World Builder" domain** — engine-agnostic worldbuilding, narra… |
| `hestia`     | 14       | @hestia    | The `libs/hestia/` area: fourteen Nx libraries that implement **Hestia, the culinary-intelligence platform** — from a shared domain core … |
| `iris`       | 262      | @iris      | The `libs/iris/` area: ~262 Nx libraries that make up **Iris**, Oshun's AI-assistant domain — the conversation engine, agent runtime, kno… |
| `isis`       | 76       | @isis      | The `libs/isis/` area: ~75 Nx libraries that make up **Isis, the generative factory** — the AI/LLM provider plane, the ComfyUI/job orches… |
| `kalika`     | 194      | @kalika    | The `libs/kalika/` area: ~96 Nx projects making up Oshun's scientific-research platform — a symbolic-algebra core, two Rust compute kerne… |
| `kuanyin`    | 17       | @kuanyin   | The `libs/kuanyin/` area: sixteen Nx libraries implementing **Kuan Yin**, the compassionate-guardianship moderation domain — intent preco… |
| `lakshmi`    | 24       | @lakshmi   | The `libs/lakshmi/` area: 24 Nx libraries that implement the **personal finance intelligence platform** — every financial engine (budgeti… |
| `lilith`     | 9        | @lilith    | The `libs/lilith/` area: nine Nx libraries that are the shared building blocks — infra spine, client SDKs, event-bus integration, a cross… |
| `maat`       | 18       | @maat      | The `libs/maat/` area: eighteen Nx libraries that make up **Maat**, the business-intelligence and operating-system layer for a Ghana/Afri… |
| `maya`       | 163      | @maya      | The `libs/maya/` area: ~100 Nx projects that make up Maya, the metaverse / world-building domain — a large Rust engine workspace plus a c… |
| `meditation` | 8        | @oshun     | The `libs/meditation/` area: eight content-agnostic Nx libraries that provide the shared meditation **engine primitives** — timer, breath… |
| `metis`      | 26       | @metis     | The `libs/metis/` area: ~25 Nx libraries that make up **Metis**, Oshun's AI-powered educational-content platform — the agents, LLM orches… |
| `mnemosyne`  | 19       | @mnemosyne | The `libs/mnemosyne/` area: nineteen Nx domain libraries that together form a humanistic-learning and cultural-intelligence platform — sp… |
| `neith`      | 597      | @neith     | The `libs/neith/` area: 312 Nx projects that make up **Neith**, Oshun's from-scratch ("sovereign") creative-technology stack — a runtime … |
| `nisaba`     | 23       | @nisaba    | The `libs/nisaba/` area: ~23 Nx libraries implementing a full digital-philology platform — ancient-script processing, canonical reference… |
| `nous`       | 52       | @nous      | The `libs/nous/` area: ~21 Nx libraries that make up Oshun's in-house AI/ML platform layer — inference runtime, training stack, LLM orche… |
| `nyx`        | 75       | @nyx       | The `libs/nyx/` area: ~75 Nx libraries that make up **Nyx**, Oshun's cosmic observatory domain — astronomical constants, coordinate/time … |
| `oshun`      | 56       | @oshun     | The `libs/oshun/` area: ~49 Nx libraries that make up the Oshun **product platform** — the cross-domain app shell, the canonical domain/s… |
| `oya`        | 18       | @oya       | The `libs/oya/` area: eighteen Nx projects that make up the platform-side of **Oya, the embodied-robotics "hive" domain** — a large legac… |
| `phoebe`     | 30       | @phoebe    | The `libs/phoebe/` area: four Nx libraries implementing the typed, standards-grounded core of the **Phoebe** domain — the science and med… |
| `psyche`     | 134      | @psyche    | The `libs/psyche/` area: ~133 Nx projects that make up the Psyche hyper-realistic AI virtual-assistant platform — a Python service founda… |
| `saraswati`  | 24       | @saraswati | The `libs/saraswati/` area: twenty-four Nx libraries that implement Oshun's **advanced-technology / industrial deep-tech** domain — manuf… |
| `seshat`     | 11       | @seshat    | The `libs/seshat/` area: eleven Nx libraries implementing the **dwelling arts & craftsmanship** domain — spatial harmony, interior design… |
| `shakti`     | 28       | @shakti    | The `libs/shakti/` area: 28 Nx libraries that make up **Shakti**, a physical-discipline and movement-intelligence platform — yoga, streng… |
| `sophia`     | 28       | @sophia    | The `libs/sophia/` area: ~27 Nx libraries that make up Sophia, the Oshun **Knowledge Engine** — the research, ingestion, indexing, retrie… |
| `tara`       | 8        | @tara      | The `libs/tara/` area: eight Nx libraries that make up the full vertical slice of **Tara**, the app-store-safe meditation / mindfulness p… |
| `themis`     | 71       | @themis    | The `libs/themis/` area: ~71 Nx libraries that split into two systems under one name — a **digital-governance platform** (DAOs, voting, c… |
| `uzume`      | 22       | @uzume     | The `libs/uzume/` area: a live-event / show-control platform built as one core foundation library, a protocol-bridging library, a Rust lo… |
| `veritas`    | 65       | @veritas   | The `libs/veritas/` area: ~64 Nx libraries that build **Veritas, an AI-native news agency for Ghana and pan-Africa** — from RSS ingestion… |
| `yemaya`     | 57       | @yemaya    | The `libs/yemaya/` area: 57 Nx libraries that make up Yemaya, Oshun's end-to-end AI movie- and game-production platform — from the agent/… |

Platform groups (not domains): `shared` (56 projects, `@oshun/*`), `contracts`,
`proto`, `openapi`. Products with library halves: `v3`, `v6`–`v10`.

## Data Ownership Matrix

Domain isolation extends to storage: every domain owns its database and no
domain reads another domain's tables. Cross-domain data moves through APIs and
events, never through shared schemas.

| Store                    | Owner        | Notes                                           |
| ------------------------ | ------------ | ----------------------------------------------- |
| `oshun_dev` (PostgreSQL) | V1 platform  | pgvector enabled                                |
| `yemaya`                 | yemaya       | studio production                               |
| `lilith`                 | lilith       | consciousness experience                        |
| `isis`                   | isis         | generation factory                              |
| `sophia`                 | sophia       | research/knowledge                              |
| `hathor`                 | hathor       | worldbuilding/narrative                         |
| `bellona`                | bellona      | build & bridge                                  |
| Redis (:6379)            | shared infra | cache/queues via `@oshun/cache`, `@oshun/queue` |
| MinIO (:9000)            | shared infra | object storage via `@oshun/storage`             |

Local infrastructure comes up with
`docker compose -f docker/docker-compose.dev.yml up -d`; optional profiles add
Elasticsearch, Qdrant, Kafka, Neo4j, and observability stacks.

## Event Flow

Cross-domain integration is event-driven where it is asynchronous and
API-mediated where it is synchronous:

1. Domain services publish envelope-versioned events through `@oshun/event-bus`
   (Redis streams locally; broker profiles for scale).
2. Consumers in other domains subscribe by contract — payload schemas live in
   `libs/contracts`, never ad-hoc.
3. Long-running generation work (isis pipelines, yemaya studio jobs) dispatches
   through queues (`@oshun/queue`, BullMQ) with GPU work brokered by
   `@oshun/gpu-dispatcher` / `@oshun/runpod-client`.
4. The V10 Rail consumes product channel events under the rail channel contract
   (`libs/contracts/src/v10`), which keeps delivery, batching, loudness, and
   elevation authority on the Rail side.

## API Gateway & BFF layer

North-south traffic enters through per-product BFFs (`apps/oshun/bff` is the
richest: auth, entitlements, idempotency, abuse protection) rather than one
central gateway; Traefik fronting is configured by `@oshun/gateway` (a Traefik
config CLI — naming predates the BFFs). The four existing BFFs share no
substrate yet; extracting `apps/oshun/bff`'s middleware into a shared kit is
audit item R-13c. Server framework policy (fastify/hono sanctioned;
express/NestJS frozen) lives in
`docs/conventions/server-frameworks-and-deps.md`.

## Build system

- **Nx** drives ~3,400 projects; affected-based CI (`ci.yml`) runs
  lint/typecheck/build/test against merge-base SHAs. Boundary governance: every
  project is scope-tagged and `@nx/enforce-module-boundaries` depConstraints
  keep domains isolated (registry-checked in CI).
- **Rust** (1,400+ crates: neith engine/DCC parity, maya engine kernels, kalika
  materials science, product services) builds per-workspace via
  `nx:run-commands`; workspace consolidation is tracked as audit R-18.
- **Python** (83 projects: psyche, metis ML services, repo tooling) runs ruff +
  pytest per project.
- **pnpm** with a version catalog (`pnpm-workspace.yaml`) and the isolated node
  linker; exact versions, curated hoist patterns.
- Generated outputs (docs-center HTML, SwiftPM `.build`, Hardhat `build-info`)
  are build artifacts and stay out of git — `scripts/check-forbidden-paths.sh`
  enforces this in CI.

## Infrastructure

Three live IaC roots are mapped authoritatively in `infra/README.md`:
`infra/terraform-v1` (canonical V1 ECS Fargate platform, state-backend owner),
`infra/terraform` (iris + RunPod + GitHub-OIDC subsystems), and `infra/hetzner`
(single-box deployment). Kubernetes remnants exist only for maya orchestration;
the platform is serverless-container based.

## Where to look next

- `domains.json` — machine-readable domain registry (R-19)
- `docs/audits/MONOREPO_ARCHITECTURE_AUDIT_2026-07-16.md` — the full audit this
  rewrite is grounded in, with execution logs for P0–P3
- `docs/conventions/` — coding and dependency conventions
- `infra/README.md` — live infrastructure map
- [TODOS.md](TODOS.md) and `TODOS/` — the migration checklist history