# Yemaya Domain

> **Yemaya** - Creative Production Studio Platform

Yemaya is the world's most comprehensive platform for creating movies, games,
animation, and interactive entertainment -- from AAA blockbusters to indie
projects. Named after the Yoruba goddess of the ocean and creativity, Yemaya
unifies professional production tools, AI-assisted workflows, and real-time
collaboration into a single cohesive ecosystem.

---

## Table of Contents

1. [Overview](#overview)
2. [Key Features](#key-features)
3. [Applications](#applications)
4. [Library Ecosystem](#library-ecosystem)
5. [Getting Started](#getting-started)
6. [Development Setup](#development-setup)
7. [API Overview](#api-overview)
8. [Database](#database)
9. [Cross-Domain Integration](#cross-domain-integration)
10. [Architecture](#architecture)
11. [Legacy Documentation](#legacy-documentation)
12. [Related Documentation](#related-documentation)

---

## Overview

Yemaya provides an end-to-end creative production pipeline:

- **Pre-production**: Scripts, storyboards, characters, worlds, locations,
  scheduling, budgeting, crew management
- **Production**: Asset management, engine integration (Blender, Godot, Unreal,
  Houdini), real-time collaboration, virtual production
- **Post-production**: Video editing, audio mixing, VFX, color grading
- **AI assistance**: Multi-agent orchestration for AI-assisted and fully
  autonomous production workflows
- **Distribution**: Asset marketplace, plugin ecosystem, enterprise deployment

### Three Modes of Operation

1. **Human-driven** -- Traditional manual workflows with professional tools
2. **AI-assisted** -- AI suggestions with human-in-the-loop approval
3. **Fully autonomous** -- AI agents execute complete production pipelines

### Target Users

| User Type                | Primary Use Cases                                |
| ------------------------ | ------------------------------------------------ |
| AAA Studios              | Large-scale blockbuster game and film production |
| Indie Developers         | Small team projects with professional output     |
| Solo Creators            | Individual artists leveraging AI assistance      |
| Film Production Houses   | Feature films, commercials, virtual production   |
| Educational Institutions | Teaching game/film development                   |

---

## Key Features

### Project Management

- Project creation with types: Film, Game, Animation, Commercial, Music Video,
  Documentary
- Role-based access: Owner, Admin, Editor, Contributor, Viewer
- Organization and team-based collaboration
- Version control for all assets

### Asset Management

- 15 asset types: Image, Video, Audio, 3D Model, Document, Script, Storyboard,
  Character Design, Environment Design, Animation, VFX, Material, Texture, Font
- Hierarchical folder organization
- Automatic metadata extraction, thumbnails, and checksums
- Asset versioning and usage tracking

### Engine Integration

- **Blender**: Scene import/export, material sync, render jobs
- **Godot**: Project sync, scene management, export
- **Unreal Engine**: Level streaming, asset import, Niagara VFX
- **Houdini**: Procedural generation, simulation export
- **DaVinci Resolve**: Color grading, editing timeline sync (via SDK)

### AI and Automation

- Multi-agent orchestration (LangGraph, CrewAI patterns)
- AI content generation (text, image, 3D models, Gaussian splatting)
- NPC behavior and dialogue generation
- Schedule optimization and cost prediction
- Autonomous production pipelines (film, game, animation)

### Production Management

- Scheduling with AI-optimized suggestions
- Budget management with multi-currency support
- Cost prediction and variance tracking
- Crew management and call sheet generation
- Location scouting and management

### Real-Time Collaboration

- Multi-user presence and cursors
- CRDT-based conflict-free document editing
- Project and team messaging
- Real-time job progress updates

### Enterprise

- Organization plans: Free, Starter, Professional, Enterprise
- RBAC with organization/team/project role hierarchy
- GDPR and SOC2 compliance (audit logging)
- Plugin marketplace
- API key management with scoped permissions

---

## Applications

| Application        | Directory                    | Description                                             |
| ------------------ | ---------------------------- | ------------------------------------------------------- |
| **API**            | `apps/yemaya/api`            | REST + WebSocket API (Hono, 44 route groups, port 3000) |
| **Workers**        | `apps/yemaya/workers`        | Background job processing (5 worker types via BullMQ)   |
| **Studio Web**     | `apps/yemaya/studio-web`     | Browser-based studio interface (Vite + React)           |
| **Studio Desktop** | `apps/yemaya/studio-desktop` | Native desktop application (Electron)                   |
| **CLI**            | `apps/yemaya/cli`            | Command-line interface (Commander)                      |

---

## Library Ecosystem

Yemaya has 24 libraries organized by concern:

### Core Platform

| Library    | Package            | Description                             |
| ---------- | ------------------ | --------------------------------------- |
| `core`     | `@yemaya/core`     | Types, validation, utilities, constants |
| `database` | `@yemaya/database` | Prisma ORM client and schema            |
| `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            |
| `activity` | `@yemaya/activity` | Activity logging, audit trails          |

### Project and Asset Management

| Library         | Package                 | Description                                |
| --------------- | ----------------------- | ------------------------------------------ |
| `projects`      | `@yemaya/projects`      | Project management, workspaces, versioning |
| `assets`        | `@yemaya/assets`        | Digital asset management and pipelines     |
| `asset-library` | `@yemaya/asset-library` | Curated asset views and distribution       |
| `organizations` | `@yemaya/organizations` | Organization and team management           |

### Collaboration and Events

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

### AI and Orchestration

| Library                | Package                        | Description                           |
| ---------------------- | ------------------------------ | ------------------------------------- |
| `agents`               | `@yemaya/agents`               | Multi-agent orchestration (LangGraph) |
| `orchestration`        | `@yemaya/orchestration`        | Pipeline execution and coordination   |
| `autonomous-pipelines` | `@yemaya/autonomous-pipelines` | Film/game production automation       |

### Enterprise and SDKs

| Library       | Package               | Description                         |
| ------------- | --------------------- | ----------------------------------- |
| `enterprise`  | `@yemaya/enterprise`  | Enterprise deployment and analytics |
| `marketplace` | `@yemaya/marketplace` | Asset/plugin/AI-model marketplace   |
| `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     |
| `ui`          | `@yemaya/ui`          | Shared UI components                |

---

## Getting Started

### Prerequisites

- Node.js v20+
- pnpm v10+
- Docker (for PostgreSQL, Redis, MinIO)

### Quick Start

```bash
# Clone and install
git clone git@github.com:GreyChimp/oshun.git
cd oshun
pnpm install

# Start infrastructure
docker compose -f docker/docker-compose.dev.yml up -d

# Start the API server
pnpm nx serve @yemaya/api

# Start the web studio
pnpm nx dev @yemaya/studio-web

# Start all workers
pnpm nx serve @yemaya/workers
```

---

## Development Setup

### Building

```bash
# Build all Yemaya projects
pnpm nx run-many -t build --projects=tag:scope:yemaya

# Build a specific library
pnpm nx build @yemaya/core
```

### Testing

```bash
# Run all Yemaya tests
pnpm nx run-many -t test --projects=tag:scope:yemaya

# Test a specific library
pnpm nx test @yemaya/auth
```

### Linting

```bash
# Lint all Yemaya projects
pnpm nx run-many -t lint --projects=tag:scope:yemaya
```

---

## API Overview

The Yemaya API provides 44 route groups covering the entire production pipeline.
See the [Architecture document](./architecture.md) for the complete route
listing.

**Key endpoint groups:**

| Area           | Routes                                                  |
| -------------- | ------------------------------------------------------- |
| Authentication | `/v1/auth` -- login, register, OAuth, 2FA               |
| Projects       | `/v1/projects` -- CRUD, members, activity               |
| Assets         | `/v1/assets` -- upload, versioning, metadata            |
| Scripts        | `/v1/scripts` -- screenplay management                  |
| Storyboards    | `/v1/storyboards` -- visual planning                    |
| Characters     | `/v1/characters` -- character design                    |
| Scheduling     | `/v1/schedules`, `/v1/call-sheets`                      |
| Budgets        | `/v1/budgets`, `/v1/cost-prediction`                    |
| Engine bridges | `/v1/blender`, `/v1/godot`, `/v1/unreal`, `/v1/houdini` |
| AI generation  | `/v1/ai-generation`, `/v1/3d-generation`, `/v1/agents`  |
| Real-time      | `/ws` -- WebSocket for collaboration                    |

**API documentation:** `GET /api/docs` (Swagger UI)

---

## Database

**Engine:** PostgreSQL with Prisma ORM

**Connection:** `YEMAYA_DATABASE_URL` (default:
`postgresql://oshun:oshun_dev@localhost:5432/yemaya`)

**Key models:** User, Organization, Team, Project, Asset, Folder, Tag, Comment,
Activity, Notification, Subscription, Plugin, AuditLog

Capability domain data (AI generation, worldbuilding, research, engine builds)
is stored in separate databases:

| Domain  | Database  | Responsibility                            |
| ------- | --------- | ----------------------------------------- |
| Isis    | `isis`    | Generation jobs, GPU execution, workflows |
| Hathor  | `hathor`  | Worldbuilding, narrative, scheduling      |
| Sophia  | `sophia`  | Research, knowledge, documents            |
| Bellona | `bellona` | Engine integration, build pipelines       |

---

## Cross-Domain Integration

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

- **Isis** -- AI generation jobs (3D models, images, text)
- **Hathor** -- Worldbuilding and narrative pre-production
- **Sophia** -- Research materials and knowledge bases
- **Bellona** -- Engine build pipelines and optimization

Cross-references are stored as lightweight IDs on Yemaya records
(`hathorWorldId`, `isisWorkflowIds`, `sophiaPackIds`, `bellonaAssetId`) rather
than foreign keys, maintaining database independence.

---

## Architecture

See [architecture.md](./architecture.md) for the complete technical architecture
document covering:

- Service topology and ports
- All 44 API route groups
- Database schema (Prisma models)
- Worker architecture (BullMQ)
- Cross-domain event bus integration
- Real-time collaboration protocol
- AI agent orchestration
- Deployment architecture
- Technology stack

---

## Legacy Documentation

Yemaya has extensive legacy documentation from its pre-monorepo codebase at
[`docs/domains/yemaya/extras/`](../../yemaya/) (58 files):

| Category             | Location                                                          |
| -------------------- | ----------------------------------------------------------------- |
| Product Requirements | [PRD.md](../../yemaya/PRD.md)                                     |
| Architecture         | [architecture/](../../yemaya/architecture/)                       |
| Getting Started      | [getting-started/](../../yemaya/getting-started/)                 |
| API Docs             | [api/](../../yemaya/api/)                                         |
| Features             | [features/](../../yemaya/features/)                               |
| Deployment           | [deployment/](../../yemaya/deployment/)                           |
| Security             | [security/](../../yemaya/security/)                               |
| GPU Jobs             | [gpu-jobs/](../../yemaya/gpu-jobs/)                               |
| Debugging            | [debugging/](../../yemaya/debugging/)                             |
| Configuration        | [CONFIGURATION.md](../../yemaya/CONFIGURATION.md)                 |
| Environment Vars     | [ENVIRONMENT_VARIABLES.md](../../yemaya/ENVIRONMENT_VARIABLES.md) |
| Accessibility        | [ACCESSIBILITY.md](../../yemaya/ACCESSIBILITY.md)                 |
| Logging              | [LOGGING.md](../../yemaya/LOGGING.md)                             |
| Known Limitations    | [KNOWN_LIMITATIONS.md](../../yemaya/KNOWN_LIMITATIONS.md)         |
| Troubleshooting      | [TROUBLESHOOTING.md](../../yemaya/TROUBLESHOOTING.md)             |

> **Note:** Legacy docs reference `npm` and standalone tooling from the old
> project. For current development instructions, use the setup described above.

---

## Related Documentation

- [Architecture](./architecture.md) -- Complete system architecture
- [Oshun Getting Started](../../getting-started.md) -- Monorepo setup guide
- [CLAUDE.md](../../../CLAUDE.md) -- Development guidelines
