Eve library

Oshun Monorepo — Architecture Overview

Architecture

Revision 1

On this page

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 and TODOS/ — the migration checklist history