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 inV<n>/trees (UE content, docs, ops) with TypeScript/Rust halves underapps/v<n>andlibs/v<n>for V3 and V6–V9. V10 ("The Rail") is the ambient companion layer over all of them.V_SERIES.mdcarries 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 underservices/(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:
- Domain services publish envelope-versioned events through
@oshun/event-bus(Redis streams locally; broker profiles for scale). - Consumers in other domains subscribe by contract — payload schemas live in
libs/contracts, never ad-hoc. - 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. - 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-boundariesdepConstraints 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, Hardhatbuild-info) are build artifacts and stay out of git —scripts/check-forbidden-paths.shenforces 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–P3docs/conventions/— coding and dependency conventionsinfra/README.md— live infrastructure map- TODOS.md and
TODOS/— the migration checklist history