# Yemaya — Architecture > Technical architecture for the Creative Production Studio Platform. --- Yemaya is the creative production studio at the center of the Oshun platform. It acts as the orchestrator: it owns the project workspace, the asset library, the collaborative editing surface, and the autonomous production pipeline scheduler. It does not own generation (Isis), worldbuilding (Hathor), research (Sophia), or engine execution (Bellona) — it delegates to those domains and coordinates their outputs into a coherent production. This document covers how that orchestration is built: the five applications, the 47 libraries, the data flows through the system, and the design choices that keep Yemaya loosely coupled to the capability domains it depends on. --- ## System Overview Yemaya is a comprehensive creative production studio platform designed for end-to-end movie, game, animation, and interactive media creation. The architecture is built around five core principles: 1. **Modular production pipeline** — Project management, asset management, scripting, storyboarding, scheduling, and budgeting compose into complete production workflows. 2. **Multi-engine integration** — Native bridges to Blender, Godot, Unreal Engine, Houdini, and DaVinci Resolve enable professional-grade rendering and editing without vendor lock-in. 3. **AI-assisted creation** — Multi-agent orchestration (LangGraph, CrewAI patterns) with human-in-the-loop for AI-assisted and fully autonomous production modes. 4. **Real-time collaboration** — WebSocket-based presence, cursors, and CRDT-based document sync for distributed teams. 5. **Cross-domain delegation** — Capability domains (Isis for generation, Hathor for worldbuilding, Sophia for research, Bellona for engines) handle specialized processing through the `@oshun/event-bus` and a synchronous reverse proxy (`/v1/capabilities/{domain}`). ### High-Level Topology The diagram below shows how clients reach the API, how the API fans work out to background queues and storage, and how the event bus connects Yemaya to the four capability domains. ``` ┌──────────────────────────────────────────────────────────────────┐ │ CLIENTS │ │ Studio Web (React/Vite) │ Studio Desktop (Electron) │ CLI │ └──────────────────────────────┬───────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ REST API │ │WebSocket │ │ Webhooks │ │ (Hono) │ │ (WSS) │ │(external)│ │ :3000 │ │ :3000 │ │ :3000 │ └─────┬────┘ └─────┬────┘ └─────┬────┘ │ │ │ ┌─────┴──────────────┴──────────────┴──────┐ │ API SERVICE │ │ 30 mounted routers, 24 base paths │ │ Middleware: Auth, Rate Limit, GDPR, │ │ SOC2, Circuit Breaker, Versioning │ └─────┬──────────────────────────────────────┘ │ ┌─────────┼────────────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │PostgreSQL│ │ Redis │ │ Workers │ │ (Prisma) │ │ (BullMQ + │ │ (BullMQ) │ │ yemaya │ │ Event Bus) │ │ 5 queues │ └──────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────┴────────────────────┘ │ ┌───────────┴───────────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ │ MinIO (S3) │ │ Event Bus │ │ (Assets) │ │ (@oshun/event-bus)│ └──────────────┘ │ Redis-backed │ └──────────────────┘ │ ┌─────────────────────┼──────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Isis │ │ Hathor │ │ Sophia │ │(Generate)│ │(Worlds) │ │(Research)│ └──────────┘ └──────────┘ └──────────┘ ``` --- ## Service Topology Yemaya ships five distinct applications that together cover browser, desktop, command-line, and background-processing surfaces. ### Applications (5) | Application | Directory | Type | Port | Framework | Description | | ------------------ | ---------------------------- | ------- | ---- | -------------- | ------------------------- | | **API** | `apps/yemaya/api` | Server | 3000 | Hono + OpenAPI | REST + WebSocket API | | **Workers** | `apps/yemaya/workers` | Worker | — | BullMQ | Background job processing | | **Studio Web** | `apps/yemaya/studio-web` | Web App | 5173 | Vite + React | Browser-based studio | | **Studio Desktop** | `apps/yemaya/studio-desktop` | Desktop | — | Electron | Native desktop studio | | **CLI** | `apps/yemaya/cli` | CLI | — | Commander.js | Command-line tooling | --- ## Application Layer ### API Server (`apps/yemaya/api`) The API server is the front door to all Yemaya functionality. It is a monolithic `OpenAPIHono` (`@hono/zod-openapi`) application that mounts 30 routers across 24 base paths. A layered middleware chain runs before every request, handling concerns from request identity to compliance logging before any business logic executes. ``` apps/yemaya/api/src/ ├── index.ts # Server bootstrap + event bus init ├── app.ts # Hono application + middleware chain ├── middleware/ │ ├── auth.ts # JWT authentication │ ├── proxy-auth.ts # Capability-proxy auth claims │ ├── rate-limit.ts # Per-route rate limiting │ ├── security.ts # Security headers, CORS │ ├── sanitization.ts # Input sanitization │ ├── problem-details.ts # RFC 7807 error responses │ ├── request-id.ts # X-Request-ID propagation │ ├── performance-metrics.ts # Response timing │ ├── circuit-breaker.ts # External service circuit breaker │ ├── gdpr-compliance.ts # GDPR audit logging │ └── soc2-compliance.ts # SOC2 audit logging ├── routes/ # 30 router files ├── schemas/ # Zod-OpenAPI request/response schemas ├── services/ # Business logic layer ├── versioning/ # API version negotiation ├── websocket/ # WebSocket session management ├── email/ # Email templates and delivery └── analytics/ # Usage analytics collection ``` On startup, the API server connects to the `@oshun/event-bus` to subscribe to cross-domain completion events from Isis, Hathor, Sophia, and Bellona, enabling reactive project updates without polling. ### Workers (`apps/yemaya/workers`) The workers process background jobs from five BullMQ queues, each backed by Redis. An important boundary: capability-domain execution queues live with their owning domains (Isis owns generative and 3D execution; Bellona owns media, render, export, and engine execution). Yemaya workers only coordinate those domains' outputs and process studio-level events. | Queue | Worker process | Purpose | | --------------------- | ----------------------------------- | ----------------------------------------- | | `yemaya:notification` | `notification-worker.ts` | Email, webhook, push, and digest delivery | | `yemaya:rendering` | `rendering-orchestration-worker.ts` | Rendering orchestration | | `yemaya:export` | `export-orchestration-worker.ts` | Export orchestration | | `yemaya:pipeline` | `pipeline-orchestration-worker.ts` | Pipeline orchestration | | `yemaya:event` | `event-consumer.ts` | Cross-domain event consumption | The worker type is selected by a `--worker=` process argument (default `all`). Valid values: `all`, `notification`, `rendering`, `export`, `pipeline`, `event-consumer`, `orchestration`. Concurrency per worker is set via `WORKER_CONCURRENCY` (1–100, default 5). ### Studio Web (`apps/yemaya/studio-web`) A Vite + React single-page application providing the primary browser-based studio interface. It connects to the API via REST for CRUD operations and via WebSocket for real-time collaboration presence and document sync. It is also designed as a Progressive Web App (PWA) for install-to-desktop support. ### Studio Desktop (`apps/yemaya/studio-desktop`) An Electron-based desktop application that wraps the web studio and provides additional native capabilities: local filesystem access, GPU-accelerated rendering via locally-installed engine bridges, and offline project support with sync-on-reconnect. ### CLI (`apps/yemaya/cli`) Commander.js CLI for scripted and CI/CD workflows: project creation, asset upload, batch operations, pipeline execution, and API interaction. --- ## Library Layer `libs/yemaya/` contains 47 libraries (TypeScript unless noted). The groups below list the foundational platform set; the remaining specialist libraries follow. ### Core Library Set #### Core Platform (8) These eight libraries provide the shared infrastructure that every other Yemaya library builds on: monitoring and encryption in `@yemaya/core`, type-safe ID primitives in `@yemaya/types`, the Prisma database client, and the cross-cutting concerns of auth, access control, user management, safety, and audit logging. | Library | Package | Purpose | | ---------- | ------------------ | ----------------------------------------------------------- | | `core` | `@yemaya/core` | Monitoring, resilience, cost management, config, encryption | | `types` | `@yemaya/types` | Branded ID primitives and `Result` helpers | | `database` | `@yemaya/database` | Prisma ORM client, schema, migrations | | `auth` | `@yemaya/auth` | JWT authentication, session management | | `rbac` | `@yemaya/rbac` | Role-based access control | | `users` | `@yemaya/users` | User management service | | `safety` | `@yemaya/safety` | Content filtering and AI ethics enforcement | | `activity` | `@yemaya/activity` | Activity logging, audit trails | #### Project and Asset Management (5) The production-workspace libraries: projects and assets form the primary data model, while `@yemaya/asset-library` provides curated cross-project views and `@yemaya/organizations` handles multi-tenant grouping. | Library | Package | Purpose | | --------------- | ----------------------- | -------------------------------------------- | | `projects` | `@yemaya/projects` | Project management, workspaces, versioning | | `assets` | `@yemaya/assets` | Digital asset management, storage, pipelines | | `asset-library` | `@yemaya/asset-library` | Curated asset views, packaging, distribution | | `organizations` | `@yemaya/organizations` | Organization and team management | | `sdk` | `@yemaya/sdk` | Official TypeScript SDK | #### Collaboration and Events (4) Real-time collaboration is powered by Yjs CRDTs (`@yemaya/collaboration`). Events flow in both directions through the event bus: `@yemaya/event-publisher` emits Yemaya domain events, and `@yemaya/event-handlers` handles completion events arriving from other domains. | Library | Package | Purpose | | ----------------- | ------------------------- | ------------------------------------------- | | `collaboration` | `@yemaya/collaboration` | Real-time sync, presence, cursors, comms | | `event-handlers` | `@yemaya/event-handlers` | Cross-domain event subscription handling | | `event-publisher` | `@yemaya/event-publisher` | Domain event publishing to event bus | | `community` | `@yemaya/community` | Forums, showcase, tutorials, certifications | #### AI and Orchestration (3) These three libraries together cover the full autonomous production stack: `@yemaya/agents` owns the multi-agent graph; `@yemaya/orchestration` executes individual pipeline steps in topological order; `@yemaya/autonomous-pipelines` provides ready-made film and game pipeline factories. | Library | Package | Purpose | | ---------------------- | ------------------------------ | -------------------------------------------- | | `agents` | `@yemaya/agents` | Multi-agent orchestration (LangGraph/CrewAI) | | `orchestration` | `@yemaya/orchestration` | Pipeline execution, workflow coordination | | `autonomous-pipelines` | `@yemaya/autonomous-pipelines` | Film/game production automation | #### Enterprise and Marketplace (3) | Library | Package | Purpose | | ------------- | --------------------- | ------------------------------------------ | | `enterprise` | `@yemaya/enterprise` | Enterprise deployment, analytics, training | | `marketplace` | `@yemaya/marketplace` | Asset/plugin/AI-model marketplace | | `ui` | `@yemaya/ui` | Shared UI component library | #### Multi-Language SDKs (2) Two additional SDKs extend Yemaya's reach beyond TypeScript: the C++ SDK targets engine plugin developers who need to integrate with Unreal Engine or custom engines, while the Python SDK serves ML pipeline authors and DCC tool scripters. | Library | Package | Purpose | | ------------ | -------------------- | ----------------------------------------- | | `sdk-cpp` | `@yemaya/sdk-cpp` | C++ SDK for engine plugin development | | `sdk-python` | `@yemaya/sdk-python` | Python SDK for ML and scripting workflows | ### Additional Specialist Libraries Beyond the core set, `libs/yemaya/` contains these specialist libraries that cover advanced production capabilities: - `asset-generation` — coordinated multi-modal asset generation orchestration - `av-sync` — audio/video synchronization utilities - `blend-kernel` — Living Scenes blend kernel (typed transitions) - `budget-management` — production budget tracking - `canon-enforcement` — canon, style, and character consistency enforcement - `comfyui-integration` — ComfyUI workflow integration - `d3-visualizations` — D3.js data visualization components - `diagram-renderer` — production diagram rendering - `human-override` — human-in-the-loop override and emergency-stop mechanisms - `living-scenes-runtime` — Living Scenes runtime (score schema, conductor, determinism harness, segment adapters) - `podcast-generator` — automated podcast episode production - `pre-production` — screenplay/script parsing and export utilities - `presentation-compiler` — slide presentation compilation - `production-verification` — completeness, AAA benchmark, and sign-off checks - `project-obsidian` — Project Obsidian franchise configuration - `remote-film-capture` — remote actor home-capture infrastructure - `remote-film-mannequin` — remote-film mannequin hardware/motion integration - `rendering-pipelines` — content rendering and visual compositing - `self-improvement` — production outcome learning and agent performance tracking - `style-transfer` — AI visual style transfer and brand management - `tts-integration` — text-to-speech for production voiceover - `video-generation` — AI video generation workflows ### Library Dependency Graph Libraries depend on each other in layers. The SDK, UI, and collaboration libraries sit at the top, consuming the mid-tier project and asset libraries, which in turn rest on the foundational core, database, auth, and RBAC libraries. The shared Oshun libraries (`@oshun/database`, `@oshun/event-bus`, `@oshun/logging`) form the true foundation shared across all domains. ``` @yemaya/sdk @yemaya/ui @yemaya/collaboration │ │ │ ▼ ▼ ▼ @yemaya/projects @yemaya/assets @yemaya/agents │ │ │ ├───────────────┼────────────────┤ ▼ ▼ ▼ @yemaya/orchestration @yemaya/event-publisher │ │ ├────────────────────────┤ ▼ ▼ @yemaya/core @yemaya/database @yemaya/auth @yemaya/rbac │ │ │ │ └───────────────┼────────────────┼───────────────┘ ▼ @oshun/shared libraries (@oshun/database, @oshun/event-bus, @oshun/logging) ``` --- ## Data Flow ### Asset Upload Flow When a client uploads an asset, the API immediately streams it to object storage and creates a database record in a `PROCESSING` state, then delegates all format-specific processing work to the appropriate capability domain via the event bus. This keeps the API response fast and avoids tying up the API process with CPU-bound media operations. ``` Client │ ▼ POST /v1/projects/{projectId}/assets (multipart) API Server │ validate JWT, sanitize asset metadata │ stream to MinIO → get storageKey │ create Asset record (Prisma, status: PROCESSING) │ ▼ return Asset{id, status: PROCESSING} YemayaEventPublisher │ publish yemaya.asset.uploaded (targets: Isis, Bellona) │ ▼ Capability domains │ Bellona / Isis perform media processing in their own queues │ completion flows back via isis.asset.generated / bellona.* events ``` Media transcoding and asset processing run in the owning capability domains' queues, not in a Yemaya-owned asset queue. ### AI Generation Request Flow Generation requests reach Isis through two paths: synchronously via the `/v1/capabilities/isis/...` reverse proxy (for interactive use), or asynchronously as pipeline steps (for batch production). Either way, the result arrives back in Yemaya as an event on the bus. ``` Client / pipeline step │ POST /v1/capabilities/isis/... (proxy) OR isis:* pipeline step │ ▼ API Server (capabilities proxy) / orchestration │ forward request to Isis with service-auth headers │ ▼ Isis domain │ run generation job │ emit isis.asset.generated (or isis.job.failed) on the event bus │ ▼ @yemaya/event-handlers │ handleIsisAssetGenerated — ingest asset into project library │ handleIsisJobFailed — surface failure to the project dashboard ``` ### Autonomous Pipeline Execution An autonomous pipeline encodes the full dependency graph of a production. Yemaya's orchestration layer walks the graph in topological order, dispatching each step to the domain that owns it and collecting results before starting the next dependent step. ``` User triggers pipeline │ ▼ @yemaya/autonomous-pipelines │ build CreatePipelineInput step graph with dependencies │ @yemaya/orchestration — execute steps in topological order: │ ├── sophia:* → research / analyze / summarize / embed ├── hathor:* → create_character / create_location / compile_lore ├── isis:* → generate_image / generate_3d / generate_audio / ... ├── bellona:* → export / build / sync / convert ├── mcp:* → execute_dcc and voice-steerable DCC orchestration └── yemaya:* → internal review / approve / publish / notify │ ▼ Pipeline complete → notify stakeholders ``` --- ## Cross-Domain Integration Yemaya acts as the creative orchestrator, delegating to capability domains via the `@oshun/event-bus` (Redis-backed) and a synchronous reverse proxy (`/v1/capabilities/{domain}`). Domain isolation is maintained by storing cross-domain references as IDs, never as database foreign keys. This design choice means no Yemaya query can ever break because a Hathor or Isis record was deleted — the worst outcome is a stale ID that resolves to a 404 at query time, which surfaces cleanly rather than cascading into referential integrity failures. ``` Yemaya Project │ ├── hathorWorldId ──────→ Hathor API /worlds/{id} │ (worldbuilding, lore, narrative) │ ├── isisWorkflowIds[] ──→ Isis API /api/v1/workflows/{id} │ (image, 3D, audio, video generation) │ ├── sophiaPackIds[] ────→ Sophia API /packs/{id} │ (research, knowledge, analysis) │ └── (Asset) bellonaAssetId → Bellona API /assets/{id} (engine-processed asset versions) ``` ### Event Bus Architecture The `@oshun/event-bus` package is the asynchronous communication backbone between Yemaya and the capability domains. It is Redis-backed (`ioredis`): it fans events out over Redis pub/sub, persists each envelope under a TTL-bounded key for replay, schedules delayed/retried delivery through a durable sorted set, and supports consumer groups for at-most-once delivery. It provides typed publishing and consuming with per-domain event namespaces: - Yemaya publishes 12 `yemaya.*` events (`YemayaEventTypes` in `@oshun/contracts`). - Yemaya subscribes to 6 events: `isis.asset.generated`, `isis.job.failed`, `sophia.document.ingested`, `hathor.world.published`, `bellona.build.completed`, `bellona.export.ready`. --- ## Real-Time Collaboration Architecture ### WebSocket Server The WebSocket server runs on the same Hono process as the REST API, listening on `/ws`. This co-location keeps operational complexity low: there is one service to deploy and one TLS endpoint for clients to connect to. Connection authentication uses the same JWT middleware as the REST routes. ### CRDT Document Sync (Yjs) Yemaya uses Yjs Conflict-free Replicated Data Types for collaborative editing. CRDTs allow any number of concurrent edits from different users to be merged automatically without conflicts — each client maintains its own replica and the server reconciles them. The sequence below shows a two-client sync: ``` Client A Server Client B │ │ │ ├── connect /ws ───────►│ │ │ │◄── connect /ws ─────┤ │ │ │ ├── Y.Doc update ──────►│ merge CRDT state │ │ ├───────────────────►│ broadcast │ │ │ │ │ persist snapshot │ │ │ to Redis │ ``` CRDT state snapshots are periodically persisted to Redis so that new connections can bootstrap from a recent state rather than replaying the full history. For large documents, selective sync allows clients to subscribe to specific subdocuments rather than the entire document tree. ### Presence System User presence (cursors, activity state, focus context) is managed by the `@yemaya/collaboration` library using Yjs awareness. Presence is intentionally not persisted to PostgreSQL: it is ephemeral, tied to the WebSocket session lifetime, and has no value after a session ends. --- ## AI Agent Architecture ### Multi-Agent Orchestration Yemaya's AI production system uses the LangGraph state machine pattern. Each agent type (scripting, storyboard, asset generation, etc.) is a node in a directed graph. Conditional edges between nodes implement the human-in-the-loop approval gates that allow any step to pause and wait for human confirmation before proceeding. ``` @yemaya/agents │ ├── Orchestrator Agent (LangGraph graph) │ │ │ ├── Scripting Agent │ ├── Storyboard Agent │ ├── Asset Generation Agent ──→ Isis API │ ├── Character Design Agent ──→ Hathor API │ ├── Review Agent (human-in-the-loop gate) │ └── Export Agent ───────────→ Bellona API │ └── Human override at any node ``` Agent state is persisted to Redis so long-running pipelines can be suspended, resumed, and recovered after failures without restarting from the beginning. --- ## Deployment Architecture ### Production Services Each Yemaya service scales independently. The API is stateless and horizontally scalable behind a load balancer. Workers scale per queue depth — notification and export workers can scale independently of pipeline workers. Studio Web is a static asset bundle distributed via CDN. | Service | Scaling | Notes | | ---------- | ------------------------------ | ---------------------------------- | | API | Horizontal (stateless) | Load balanced | | Workers | Horizontal (per-type) | Scale independently by queue depth | | Studio Web | CDN-distributed | Static assets on CDN | | PostgreSQL | Single primary + read replicas | Prisma connection pooling | | Redis | Sentinel or Cluster | BullMQ + event bus | | MinIO/S3 | Managed S3 in production | Asset storage | ### Container Structure ``` apps/yemaya/api → Docker image: yemaya-api apps/yemaya/workers → Docker image: yemaya-workers apps/yemaya/studio-web → Static build → CDN ``` --- ## Technology Stack Every technology choice in the stack was made to serve a specific constraint: Hono for lightweight TypeScript-native routing, Prisma for type-safe database access, BullMQ for durable queue-based job processing, and Yjs for mathematically sound collaborative editing. | Layer | Technology | Rationale | | -------------- | -------------------------- | ----------------------------------------------------- | | API Framework | Hono | Lightweight, TypeScript-native, Cloudflare-compatible | | ORM | Prisma | Type-safe queries, migrations, generated client | | Database | PostgreSQL | Relational integrity, JSONB for metadata | | Job Queue | BullMQ | Redis-backed, reliable job processing | | Event Bus | Redis (`@oshun/event-bus`) | Cross-domain async messaging (ioredis pub/sub) | | Real-Time | Yjs (CRDTs) + WebSocket | Conflict-free collaborative editing | | Object Storage | MinIO (dev) / S3 (prod) | S3-compatible asset storage | | Web Client | Vite + React | Fast HMR, modern React with concurrent features | | Desktop Client | Electron | Native OS integration, local engine bridges | | CLI | Commander.js | Standard Node.js CLI framework | | Validation | Zod + `@hono/zod-openapi` | Runtime validation + OpenAPI generation | | TypeScript SDK | TypeScript | Typed client for API consumers | | C++ SDK | C++ | Engine plugin development (Unreal, custom) | | Python SDK | Python | ML pipeline and DCC tool integration | --- ## Design Principles These five principles are the architectural decision rules. When a new feature is being designed and two reasonable approaches exist, these principles break the tie. 1. **Domain isolation** — Yemaya's PostgreSQL database contains no foreign keys to other domain databases. Cross-domain references are stored as IDs and resolved at query time via internal API calls. 2. **Event-driven coordination** — Asynchronous work is coordinated via the event bus, not synchronous service calls. This makes pipelines resilient to downstream service unavailability. 3. **Progressive AI autonomy** — The same production pipeline supports human-driven, AI-assisted, and fully autonomous modes. The level of autonomy is controlled at the pipeline configuration level, not hardcoded. 4. **Storage abstraction** — All file storage goes through the asset pipeline which handles format normalization, metadata extraction, and thumbnail generation before committing assets to the library. 5. **Compliance by design** — GDPR audit logging and SOC2 audit trails are middleware-level concerns, applied uniformly across all routes, not ad hoc.