# Yemaya Architecture

> **Canonical source:** the canonical architecture document for this domain is
> [`deep-dive/architecture.md`](./deep-dive/architecture.md), rendered in the
> docs center. This file is its operational companion (service topology, APIs,
> schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).

> System Architecture for the Creative Production Studio Platform

This document describes the technical architecture of the Yemaya domain,
covering its service topology, API design, database schema, worker
infrastructure, cross-domain integration, and the library ecosystem that
supports end-to-end creative production workflows for film, games, animation,
and interactive media.

---

## Table of Contents

1. [System Overview](#system-overview)
2. [Service Architecture](#service-architecture)
3. [Application Layer](#application-layer)
4. [Library Layer](#library-layer)
5. [API Architecture](#api-architecture)
6. [Database Schema](#database-schema)
7. [Worker Architecture](#worker-architecture)
8. [Cross-Domain Integration](#cross-domain-integration)
9. [Real-Time Collaboration](#real-time-collaboration)
10. [AI Agent Architecture](#ai-agent-architecture)
11. [External Integrations](#external-integrations)
12. [Data Flow](#data-flow)
13. [Deployment Architecture](#deployment-architecture)
14. [Technology Stack](#technology-stack)

---

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

```
┌──────────────────────────────────────────────────────────────────┐
│                          CLIENTS                                   │
│  Studio Web (React/Vite) │ Studio Desktop (Electron) │ CLI        │
└──────────────────────────────┬───────────────────────────────────┘
                               │
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
         ┌──────────┐   ┌──────────┐   ┌──────────┐
         │ REST API │   │WebSocket │   │ Webhooks │
         │  (Hono)  │   │  (WSS)   │   │(external)│
         │  :3000   │   │  :3000   │   │  :3000   │
         └─────┬────┘   └─────┬────┘   └─────┬────┘
               │              │              │
         ┌─────┴──────────────┴──────────────┴──────┐
         │              API SERVICE                    │
         │  Routes: 44 resource groups                 │
         │  Middleware: Auth, RBAC, Rate Limit,        │
         │    GDPR, SOC2, Circuit Breaker              │
         └─────┬──────────────────────────────────────┘
               │
     ┌─────────┼─────────────────────────────┐
     ▼         ▼                             ▼
┌──────────┐ ┌──────────────┐      ┌──────────────┐
│PostgreSQL│ │    Redis      │      │   Workers    │
│ (Prisma) │ │  (BullMQ +   │      │  (BullMQ)   │
│  yemaya  │ │   Event Bus) │      │  5 types    │
└──────────┘ └──────────────┘      └──────────────┘
     │              │                      │
     └──────────────┴──────────────────────┘
                    │
        ┌───────────┴───────────────┐
        ▼                           ▼
┌──────────────┐          ┌──────────────┐
│ MinIO (S3)   │          │ Event Bus    │
│ (Assets)     │          │ (Cross-domain│
└──────────────┘          │  Redis)      │
                          └──────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
   ┌──────────┐         ┌──────────┐         ┌──────────┐
   │   Isis   │         │  Hathor  │         │  Sophia  │
   │(Generate)│         │(Worlds)  │         │(Research)│
   └──────────┘         └──────────┘         └──────────┘
```

---

## Service Architecture

### Applications (5)

| Application        | Directory                    | Type    | Port | Framework      | Description                                      |
| ------------------ | ---------------------------- | ------- | ---- | -------------- | ------------------------------------------------ |
| **API**            | `apps/yemaya/api`            | Server  | 3000 | Hono + OpenAPI | REST + WebSocket API for all platform operations |
| **Workers**        | `apps/yemaya/workers`        | Worker  | --   | BullMQ         | Background job processing (5 worker types)       |
| **Studio Web**     | `apps/yemaya/studio-web`     | Web App | 5173 | Vite + React   | Browser-based production studio interface        |
| **Studio Desktop** | `apps/yemaya/studio-desktop` | Desktop | --   | Electron       | Native desktop studio with local GPU access      |
| **CLI**            | `apps/yemaya/cli`            | CLI     | --   | Commander      | Command-line project and asset management        |

---

## Application Layer

### API Server (`apps/yemaya/api`)

The monolithic API server built with Hono provides 44 route groups covering
every aspect of the production pipeline:

```
apps/yemaya/api/src/
├── index.ts                    # Server bootstrap + event bus init
├── app.ts                      # Hono application with middleware chain
├── middleware/
│   ├── auth.ts                 # JWT authentication
│   ├── rate-limit.ts           # Rate limiting
│   ├── security.ts             # Security headers, CORS
│   ├── 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/                     # 44 route files (see API Architecture)
├── schemas/                    # Zod-OpenAPI request/response schemas
├── services/                   # Business logic layer
├── email/                      # Email templates and service
└── analytics/                  # Registration analytics
```

**Event Bus Integration:** On startup, the API server connects to the
`@oshun/event-bus` (Redis-backed) to subscribe to cross-domain events from Isis,
Hathor, Sophia, and Bellona. This enables reactive updates when, for example, a
3D generation job completes in Isis or a world is published in Hathor.

### Workers (`apps/yemaya/workers`)

Background job processing using BullMQ with Redis as the queue backend:

| Worker Type       | Queue Name             | Purpose                                       |
| ----------------- | ---------------------- | --------------------------------------------- |
| **Agent**         | `yemaya:agent`         | AI agent task execution                       |
| **Media**         | `yemaya:media`         | Video/audio transcoding, thumbnail generation |
| **Asset**         | `yemaya:asset`         | Asset processing, format conversion, indexing |
| **Notification**  | `yemaya:notification`  | Email, push, in-app notification delivery     |
| **3D Generation** | `yemaya:generation-3d` | 3D model generation pipeline                  |

Workers are configurable: set `WORKER_TYPE=all` to run all workers in one
process, or `WORKER_TYPE=media` to run a single specialized worker. Concurrency
is configurable via `WORKER_CONCURRENCY`.

### Studio Web (`apps/yemaya/studio-web`)

A Vite + React single-page application providing the browser-based studio
interface. Built with `@nx/vite:build`. Connects to the API via REST and
WebSocket for real-time collaboration features.

### Studio Desktop (`apps/yemaya/studio-desktop`)

An Electron-based desktop application that wraps the web studio and provides
additional native capabilities: local file system access, GPU-accelerated
rendering via local engine bridges, and offline project support.

### CLI (`apps/yemaya/cli`)

Command-line interface for scripted and CI/CD workflows: project creation, asset
upload, batch operations, and API interaction.

---

## Library Layer

### 24 Libraries Organized by Concern

#### Core Platform (7)

| Library    | Package            | Purpose                                  |
| ---------- | ------------------ | ---------------------------------------- |
| `core`     | `@yemaya/core`     | Types, validation, utilities, constants  |
| `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`   | AI safety, content filtering, ethical AI |
| `activity` | `@yemaya/activity` | Activity logging, audit trails           |

#### Project and Asset Management (5)

| 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)

| Library           | Package                   | Purpose                                     |
| ----------------- | ------------------------- | ------------------------------------------- |
| `collaboration`   | `@yemaya/collaboration`   | Real-time sync, presence, cursors, comms    |
| `event-handlers`  | `@yemaya/event-handlers`  | Cross-domain event handling                 |
| `event-publisher` | `@yemaya/event-publisher` | Domain event publishing                     |
| `community`       | `@yemaya/community`       | Forums, showcase, tutorials, certifications |

#### AI and Orchestration (3)

| 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 components                       |

#### Multi-Language SDKs (2)

| Library      | Package              | Purpose                                   |
| ------------ | -------------------- | ----------------------------------------- |
| `sdk`        | `@yemaya/sdk`        | TypeScript/JavaScript SDK                 |
| `sdk-cpp`    | `@yemaya/sdk-cpp`    | C++ SDK for engine integrations           |
| `sdk-python` | `@yemaya/sdk-python` | Python SDK for scripting and ML workflows |

### Library Dependency Graph

```
@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)
```

---

## API Architecture

### Route Groups (44 resource endpoints)

#### Core Platform Routes

| Route File         | Base Path           | Description                                 |
| ------------------ | ------------------- | ------------------------------------------- |
| `auth.ts`          | `/v1/auth`          | Login, register, password reset, OAuth, 2FA |
| `users.ts`         | `/v1/users`         | User profiles, preferences, API keys        |
| `organizations.ts` | `/v1/organizations` | Organizations, teams, invitations, members  |
| `admin.ts`         | `/v1/admin`         | Platform administration                     |
| `analytics.ts`     | `/v1/analytics`     | Usage analytics, registration metrics       |
| `search.ts`        | `/v1/search`        | Full-text search across entities            |
| `webhooks.ts`      | `/v1/webhooks`      | Webhook management and delivery             |
| `plugins.ts`       | `/v1/plugins`       | Plugin marketplace and installation         |
| `versioning.ts`    | `/v1/versioning`    | API version negotiation                     |

#### Project Management Routes

| Route File       | Base Path         | Description                        |
| ---------------- | ----------------- | ---------------------------------- |
| `projects.ts`    | `/v1/projects`    | CRUD, members, comments, activity  |
| `assets.ts`      | `/v1/assets`      | Asset upload, versioning, metadata |
| `scripts.ts`     | `/v1/scripts`     | Screenplay/script management       |
| `storyboards.ts` | `/v1/storyboards` | Storyboard creation and annotation |
| `characters.ts`  | `/v1/characters`  | Character profiles and designs     |
| `worlds.ts`      | `/v1/worlds`      | World and environment definitions  |
| `location.ts`    | `/v1/locations`   | Location scouting and management   |

#### Production Management Routes

| Route File                 | Base Path                   | Description                     |
| -------------------------- | --------------------------- | ------------------------------- |
| `schedules.ts`             | `/v1/schedules`             | Production scheduling           |
| `schedule-optimization.ts` | `/v1/schedule-optimization` | AI-optimized scheduling         |
| `schedule-sharing.ts`      | `/v1/schedule-sharing`      | Schedule distribution           |
| `call-sheets.ts`           | `/v1/call-sheets`           | Daily call sheet generation     |
| `crew.ts`                  | `/v1/crew`                  | Crew management and assignments |
| `budgets.ts`               | `/v1/budgets`               | Budget management               |
| `budget-line-items.ts`     | `/v1/budget-line-items`     | Budget detail lines             |
| `budget-templates.ts`      | `/v1/budget-templates`      | Reusable budget templates       |
| `cost-prediction.ts`       | `/v1/cost-prediction`       | AI cost prediction              |
| `variance-tracking.ts`     | `/v1/variance-tracking`     | Budget vs. actual tracking      |
| `multi-currency.ts`        | `/v1/multi-currency`        | Multi-currency budget support   |

#### Engine Integration Routes

| Route File   | Base Path     | Description                          |
| ------------ | ------------- | ------------------------------------ |
| `blender.ts` | `/v1/blender` | Blender bridge (scene import/export) |
| `godot.ts`   | `/v1/godot`   | Godot engine integration             |
| `unreal.ts`  | `/v1/unreal`  | Unreal Engine bridge                 |
| `houdini.ts` | `/v1/houdini` | Houdini procedural integration       |

#### AI and Generation Routes

| Route File              | Base Path                | Description                         |
| ----------------------- | ------------------------ | ----------------------------------- |
| `ai-generation.ts`      | `/v1/ai-generation`      | AI content generation (text, image) |
| `3d-generation.ts`      | `/v1/3d-generation`      | 3D model generation                 |
| `gaussian-splatting.ts` | `/v1/gaussian-splatting` | 3D Gaussian splat generation        |
| `agent-management.ts`   | `/v1/agents`             | AI agent creation and management    |
| `gpu-jobs.ts`           | `/v1/gpu-jobs`           | GPU job submission and monitoring   |

#### Interactive and Media Routes

| Route File              | Base Path                | Description                              |
| ----------------------- | ------------------------ | ---------------------------------------- |
| `gameplay.ts`           | `/v1/gameplay`           | Gameplay mechanics definitions           |
| `npc.ts`                | `/v1/npc`                | NPC behavior and dialogue                |
| `video.ts`              | `/v1/video`              | Video processing and editing             |
| `audio.ts`              | `/v1/audio`              | Audio processing and mixing              |
| `virtual-production.ts` | `/v1/virtual-production` | Virtual production stage control         |
| `xr.ts`                 | `/v1/xr`                 | XR/VR/AR experience management           |
| `collaboration.ts`      | `/v1/collaboration`      | Real-time collaboration sessions         |
| `websocket.ts`          | `/ws`                    | WebSocket upgrade and session management |

---

## Database Schema

Yemaya uses PostgreSQL with Prisma ORM. The schema is focused on the core
platform; capability domain data lives in separate databases (Isis, Hathor,
Sophia, Bellona) with API-based cross-references.

### Schema Modules

#### Users and Authentication

| Model            | Key Fields                                        | Purpose                 |
| ---------------- | ------------------------------------------------- | ----------------------- |
| `User`           | id, email, displayName, status, locale, timezone  | User identity           |
| `UserPreference` | userId, theme, compactMode, notifyEmail, autoSave | Per-user settings       |
| `Account`        | userId, provider, providerAccountId, tokens       | OAuth provider accounts |
| `Session`        | userId, token, expiresAt, ipAddress, userAgent    | Active sessions         |
| `ApiKey`         | userId, keyHash, keyPrefix, scopes, expiresAt     | API key authentication  |

#### Organizations and Teams

| Model                    | Key Fields                                               | Purpose             |
| ------------------------ | -------------------------------------------------------- | ------------------- |
| `Organization`           | id, name, slug, plan (FREE/STARTER/PRO/ENTERPRISE)       | Org identity        |
| `OrganizationMember`     | organizationId, userId, role (OWNER/ADMIN/MEMBER/VIEWER) | Membership          |
| `OrganizationInvitation` | organizationId, email, role, token, expiresAt            | Pending invitations |
| `Team`                   | organizationId, name, slug, color, settings              | Sub-team grouping   |
| `TeamMember`             | teamId, userId, role (LEAD/MEMBER)                       | Team membership     |
| `TeamProject`            | teamId, projectId, access (VIEW/EDIT/ADMIN)              | Team-project access |

#### Projects

| Model           | Key Fields                                                      | Purpose                |
| --------------- | --------------------------------------------------------------- | ---------------------- |
| `Project`       | id, name, slug, type, status, visibility, ownerId               | Project container      |
| `ProjectMember` | projectId, userId, role (OWNER/ADMIN/EDITOR/CONTRIBUTOR/VIEWER) | Project access         |
| `ProjectTag`    | projectId, tagId                                                | Project categorization |

**Project Types:** FILM, GAME, ANIMATION, COMMERCIAL, MUSIC_VIDEO, DOCUMENTARY,
OTHER

**Project Status:** DRAFT, ACTIVE, REVIEW, COMPLETED, ARCHIVED

**Cross-Domain References (stored as JSON/varchar, not FK):**

- `hathorWorldId` -- Reference to Hathor worldbuilding data
- `isisWorkflowIds` -- Array of Isis generation workflow IDs
- `sophiaPackIds` -- Array of Sophia knowledge pack IDs

#### Assets

| Model        | Key Fields                                                        | Purpose              |
| ------------ | ----------------------------------------------------------------- | -------------------- |
| `Asset`      | id, projectId, creatorId, name, type, status, storageKey, version | Digital assets       |
| `AssetTag`   | assetId, tagId                                                    | Asset categorization |
| `AssetUsage` | assetId, context, entityId                                        | Asset usage tracking |
| `Folder`     | projectId, parentId, name, sortOrder                              | Hierarchical folders |
| `Tag`        | organizationId, name, slug, color                                 | Tag definitions      |

**Asset Types:** IMAGE, VIDEO, AUDIO, MODEL_3D, DOCUMENT, SCRIPT, STORYBOARD,
CHARACTER_DESIGN, ENVIRONMENT_DESIGN, ANIMATION, VFX, MATERIAL, TEXTURE, FONT,
OTHER

**Asset Status:** DRAFT, PROCESSING, REVIEW, APPROVED, REJECTED, ARCHIVED

**Cross-Domain References:**

- `isisGenerationId` -- Reference to Isis generation job that created this asset
- `bellonaAssetId` -- Reference to Bellona-processed asset version

#### Activity and Notifications

| Model          | Key Fields                                   | Purpose               |
| -------------- | -------------------------------------------- | --------------------- |
| `Activity`     | userId, type, entityType, entityId, metadata | Activity stream       |
| `Notification` | userId, type, title, body, read, actionUrl   | User notifications    |
| `Comment`      | userId, assetId, body, parentId              | Threaded comments     |
| `AuditLog`     | userId, action, resource, details            | GDPR/SOC2 audit trail |

#### Billing and Subscriptions

| Model               | Key Fields                                           | Purpose             |
| ------------------- | ---------------------------------------------------- | ------------------- |
| `Subscription`      | organizationId, plan, status, currentPeriodStart/End | Org subscriptions   |
| `SubscriptionPlan`  | name, price, interval, features                      | Available plans     |
| `Invoice`           | subscriptionId, amount, status, paidAt               | Billing invoices    |
| `UsageRecord`       | organizationId, metric, quantity, recordedAt         | Usage metering      |
| `CreditBalance`     | organizationId, balance, reservedCredits             | GPU/compute credits |
| `CreditTransaction` | balanceId, type, amount, description                 | Credit ledger       |

#### Plugin Marketplace

| Model                | Key Fields                                | Purpose               |
| -------------------- | ----------------------------------------- | --------------------- |
| `Plugin`             | id, name, category, status, pricing       | Plugin registry       |
| `PluginVersion`      | pluginId, version, changelog, downloadUrl | Version history       |
| `PluginInstallation` | pluginId, organizationId, installedAt     | Installation tracking |
| `PluginReview`       | pluginId, userId, rating, comment         | User reviews          |

---

## Worker Architecture

### BullMQ Job Processing

```
API Server                    Redis (BullMQ)               Workers
    │                              │                          │
    ├── enqueue job ──────────────►│                          │
    │   (media:transcode)          │                          │
    │                              ├── dequeue ──────────────►│
    │                              │                          │
    │                              │   ◄── progress(50%) ─────┤
    │                              │                          │
    │                              │   ◄── completed ─────────┤
    │                              │                          │
    │   ◄── webhook/event ────────┤                          │
    │                              │                          │
```

### Worker Types

| Worker        | Queue                  | Concurrency | Job Types                                        |
| ------------- | ---------------------- | ----------- | ------------------------------------------------ |
| Agent         | `yemaya:agent`         | 3           | AI task execution, agent conversations           |
| Media         | `yemaya:media`         | 5           | Video transcode, audio mix, thumbnail generation |
| Asset         | `yemaya:asset`         | 10          | Format conversion, checksum, metadata extraction |
| Notification  | `yemaya:notification`  | 10          | Email, push notification, in-app delivery        |
| 3D Generation | `yemaya:generation-3d` | 2           | 3D model generation, Gaussian splatting          |

### Worker Configuration

| Environment Variable | Default     | Description                                                                |
| -------------------- | ----------- | -------------------------------------------------------------------------- |
| `WORKER_TYPE`        | `all`       | Worker type to run (all, agent, media, asset, notification, generation-3d) |
| `WORKER_CONCURRENCY` | varies      | Max concurrent jobs per worker                                             |
| `REDIS_HOST`         | `localhost` | Redis host for BullMQ                                                      |
| `REDIS_PORT`         | `6379`      | Redis port                                                                 |
| `LOG_LEVEL`          | `info`      | Logging level                                                              |
| `LOG_PRETTY`         | `false`     | Pretty-print logs                                                          |

---

## Cross-Domain Integration

Yemaya delegates specialized capabilities to other Oshun domains through the
`@oshun/event-bus` (Redis Streams-based):

### Event Bus Architecture

```
Yemaya API                              Event Bus (Redis)
    │                                        │
    ├── publish: yemaya.asset.created ──────►│
    │                                        │
    │                                        ├──► Isis (subscribe: generation request)
    │                                        │
    │   ◄── isis.generation.completed ───────┤
    │                                        │
    ├── publish: yemaya.project.created ────►│
    │                                        │
    │                                        ├──► Hathor (subscribe: world creation)
    │                                        │
    │   ◄── hathor.world.published ──────────┤
    │                                        │
```

### Capability Domain Delegation

| Domain      | Package Prefix | Responsibility                                       | Integration Point                                         |
| ----------- | -------------- | ---------------------------------------------------- | --------------------------------------------------------- |
| **Isis**    | `@isis/*`      | AI generation jobs, GPU execution, workflows         | `isisGenerationId` on Asset, `isisWorkflowIds` on Project |
| **Hathor**  | `@hathor/*`    | Worldbuilding, narrative, pre-production, scheduling | `hathorWorldId` on Project                                |
| **Sophia**  | `@sophia/*`    | Research, knowledge bases, reference materials       | `sophiaPackIds` on Project                                |
| **Bellona** | `@bellona/*`   | Engine integration, build pipelines, optimization    | `bellonaAssetId` on Asset                                 |

### Event Bus Configuration

```typescript
const eventBus = createEventBus({
  redisUrl: 'redis://localhost:6379',
  sourceDomain: 'yemaya',
  keyPrefix: 'oshun:events',
  persistence: true,
  eventTtl: 86400, // 24 hours
  defaultRetry: {
    maxAttempts: 3,
    initialDelay: 1000,
    maxDelay: 30000,
    multiplier: 2,
    strategy: 'exponential',
  },
  defaultDeadLetter: {
    enabled: true,
    maxRetention: 604800000, // 7 days
    maxEntries: 1000,
  },
});
```

---

## Real-Time Collaboration

### WebSocket Architecture

The API server provides WebSocket connections at `/ws` for real-time
collaboration features provided by `@yemaya/collaboration`:

| Feature       | Protocol  | Description                            |
| ------------- | --------- | -------------------------------------- |
| Presence      | WebSocket | Online/offline status, active document |
| Cursors       | WebSocket | Multi-user cursor positions            |
| Document sync | WebSocket | CRDT-based conflict-free editing       |
| Chat          | WebSocket | Project and team messaging             |
| Notifications | WebSocket | Real-time in-app notifications         |
| Job progress  | WebSocket | Worker job progress updates            |

### Session Lifecycle

```
Client ── WS Connect ──► Server
Client ── auth { jwt } ──► Server (validate token)
Server ── session_ack ──► Client
Client ── join_project { id } ──► Server
Server ── presence_update { users } ──► All project members
Client ── cursor_move { x, y, doc } ──► Server ──► Other members
Client ── edit { ops } ──► Server ──► CRDT merge ──► Other members
```

---

## AI Agent Architecture

Yemaya supports three modes of operation:

1. **Human-driven** -- Traditional manual workflows
2. **AI-assisted** -- AI suggestions with human approval (HITL)
3. **Fully autonomous** -- AI agents execute complete production pipelines

### Agent Orchestration (`@yemaya/agents`)

Built on LangGraph and CrewAI patterns with human-in-the-loop:

```
User Request
    │
    ▼
┌──────────────────────┐
│  Agent Orchestrator   │
│  (LangGraph graph)    │
└──────────┬───────────┘
           │
    ┌──────┼──────────────┐
    ▼      ▼              ▼
┌───────┐ ┌───────┐ ┌──────────┐
│Script │ │Visual │ │Production│
│Agent  │ │Agent  │ │Agent     │
└───┬───┘ └───┬───┘ └────┬─────┘
    │         │           │
    ▼         ▼           ▼
┌───────────────────────────────┐
│  Human-in-the-Loop Checkpoint │
│  (approve / modify / reject)  │
└──────────────┬────────────────┘
               │
               ▼
        Execute approved actions
```

### Autonomous Pipelines (`@yemaya/autonomous-pipelines`)

Pre-built production pipeline templates:

- **Film Pipeline** -- Script analysis, shot list generation, scheduling,
  budgeting
- **Game Pipeline** -- Game design document, asset generation, level design
- **Animation Pipeline** -- Storyboarding, character rigging, scene composition

---

## External Integrations

### Engine Bridges

| Engine              | Route         | Capabilities                                    |
| ------------------- | ------------- | ----------------------------------------------- |
| **Blender**         | `/v1/blender` | Scene import/export, material sync, render jobs |
| **Godot**           | `/v1/godot`   | Project sync, scene management, export          |
| **Unreal Engine**   | `/v1/unreal`  | Level streaming, asset import, Niagara VFX      |
| **Houdini**         | `/v1/houdini` | Procedural generation, simulation export        |
| **DaVinci Resolve** | via SDK       | Color grading, editing timeline sync            |

### AI Service Providers

| Provider           | Usage                                              |
| ------------------ | -------------------------------------------------- |
| Claude (Anthropic) | Script analysis, creative writing, code generation |
| GPT-4o (OpenAI)    | Dialogue generation, scene descriptions            |
| Gemini (Google)    | Multi-modal content analysis                       |
| Local LLMs         | On-premise inference for sensitive content         |

### Storage Providers

| Provider   | Usage                             |
| ---------- | --------------------------------- |
| MinIO (S3) | Asset storage (local development) |
| AWS S3     | Asset storage (production)        |
| CloudFront | CDN for asset delivery            |

---

## Data Flow

### Asset Upload Flow

```
1. Client uploads file → API (POST /v1/assets)
2. API validates metadata, checks RBAC permissions
3. File streamed to MinIO/S3 → storageKey generated
4. Asset record created in PostgreSQL (status: PROCESSING)
5. Asset processing job enqueued → BullMQ (yemaya:asset)
6. Asset Worker:
   a. Extract metadata (dimensions, duration, codec)
   b. Generate thumbnail
   c. Generate preview (for video/audio)
   d. Compute checksum
   e. Update Asset record (status: DRAFT)
7. Event published: yemaya.asset.created → Event Bus
8. If AI-assisted: Isis picks up generation request
9. WebSocket notification pushed to project members
```

### Project Creation Flow

```
1. User creates project → API (POST /v1/projects)
2. API validates org membership, plan limits
3. Project record created (status: DRAFT)
4. Default folder structure created
5. Activity logged, notification sent to org admins
6. Event published: yemaya.project.created → Event Bus
7. Hathor may auto-create world scaffolding
8. Sophia may attach relevant knowledge packs
```

---

## Deployment Architecture

### Container Layout

```
┌──────────────────────────────────────────────────────────────┐
│                      Kubernetes Cluster                        │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │  yemaya-api       │  │  yemaya-studio    │                  │
│  │  (Deployment x3)  │  │  (Deployment x2)  │                  │
│  │  port: 3000       │  │  (static + nginx)  │                  │
│  └──────────────────┘  └──────────────────┘                  │
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │  workers-media   │  │  workers-agent    │                  │
│  │  (Deployment x3) │  │  (Deployment x2)  │                  │
│  └──────────────────┘  └──────────────────┘                  │
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │  workers-asset   │  │  workers-notif    │                  │
│  │  (Deployment x3) │  │  (Deployment x2)  │                  │
│  └──────────────────┘  └──────────────────┘                  │
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │  PostgreSQL      │  │  Redis            │                  │
│  │  (StatefulSet)   │  │  (StatefulSet)    │                  │
│  │  schema: yemaya  │  │  BullMQ + Events  │                  │
│  └──────────────────┘  └──────────────────┘                  │
│                                                                │
│  ┌──────────────────┐                                        │
│  │  MinIO / S3      │                                        │
│  │  (Asset storage) │                                        │
│  └──────────────────┘                                        │
│                                                                │
└──────────────────────────────────────────────────────────────┘
```

### Environment Variables

| Variable              | Default                                              | Description             |
| --------------------- | ---------------------------------------------------- | ----------------------- |
| `PORT`                | `3000`                                               | API HTTP port           |
| `HOST`                | `0.0.0.0`                                            | API bind address        |
| `YEMAYA_DATABASE_URL` | `postgresql://oshun:oshun_dev@localhost:5432/yemaya` | PostgreSQL connection   |
| `REDIS_URL`           | `redis://localhost:6379`                             | Redis (BullMQ + events) |
| `S3_ENDPOINT`         | `http://localhost:9000`                              | MinIO/S3 endpoint       |
| `S3_ACCESS_KEY`       | `minioadmin`                                         | S3 access key           |
| `S3_SECRET_KEY`       | `minioadmin`                                         | S3 secret key           |
| `JWT_ACCESS_SECRET`   | --                                                   | JWT signing secret      |
| `JWT_REFRESH_SECRET`  | --                                                   | Refresh token secret    |
| `WORKER_TYPE`         | `all`                                                | Worker type to run      |
| `WORKER_CONCURRENCY`  | varies                                               | Max concurrent jobs     |

---

## Technology Stack

| Component      | Technology                             |
| -------------- | -------------------------------------- |
| Language       | TypeScript (Node.js)                   |
| API Framework  | Hono with `@hono/zod-openapi`          |
| Database       | PostgreSQL with Prisma ORM             |
| Queue          | BullMQ (Redis-backed)                  |
| Event Bus      | `@oshun/event-bus` (Redis Streams)     |
| Object Storage | MinIO (dev) / AWS S3 (prod)            |
| Cache          | Redis                                  |
| Real-time      | WebSocket (native ws)                  |
| Desktop        | Electron                               |
| Web Frontend   | Vite + React                           |
| CLI            | Commander                              |
| AI Agents      | LangGraph, CrewAI patterns, HITL       |
| Build System   | Nx + tsup (services), Vite (web)       |
| Testing        | Vitest                                 |
| Logging        | Pino                                   |
| Validation     | Zod schemas with OpenAPI               |
| Authentication | JWT (access + refresh), OAuth2         |
| Authorization  | RBAC (org/team/project role hierarchy) |
| Compliance     | GDPR audit logging, SOC2 audit trails  |
