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#
- Overview
- Key Features
- Applications
- Library Ecosystem
- Getting Started
- Development Setup
- API Overview
- Database
- Cross-Domain Integration
- Architecture
- Legacy 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#
- Human-driven -- Traditional manual workflows with professional tools
- AI-assisted -- AI suggestions with human-in-the-loop approval
- 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#
# 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#
# Build all Yemaya projects
pnpm nx run-many -t build --projects=tag:scope:yemaya
# Build a specific library
pnpm nx build @yemaya/core
Testing#
# Run all Yemaya tests
pnpm nx run-many -t test --projects=tag:scope:yemaya
# Test a specific library
pnpm nx test @yemaya/auth
Linting#
# 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 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 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/ (58 files):
| Category | Location |
|---|---|
| Product Requirements | PRD.md |
| Architecture | architecture/ |
| Getting Started | getting-started/ |
| API Docs | api/ |
| Features | features/ |
| Deployment | deployment/ |
| Security | security/ |
| GPU Jobs | gpu-jobs/ |
| Debugging | debugging/ |
| Configuration | CONFIGURATION.md |
| Environment Vars | ENVIRONMENT_VARIABLES.md |
| Accessibility | ACCESSIBILITY.md |
| Logging | LOGGING.md |
| Known Limitations | KNOWN_LIMITATIONS.md |
| Troubleshooting | TROUBLESHOOTING.md |
Note: Legacy docs reference
npmand standalone tooling from the old project. For current development instructions, use the setup described above.
Related Documentation#
- Architecture -- Complete system architecture
- Oshun Getting Started -- Monorepo setup guide
- CLAUDE.md -- Development guidelines