# @yemaya - Creative Production Studio

Yemaya is Oshun's AAA game and movie production platform, providing project
management, asset orchestration, real-time collaboration, and autonomous AI
pipelines.

## Overview

| Aspect              | Description         |
| ------------------- | ------------------- |
| **Domain**          | Creative Production |
| **Scope Tag**       | `scope:yemaya`      |
| **API Port**        | 4000                |
| **Database Schema** | `yemaya`            |

## Capabilities

- **Project Management**: Full production lifecycle management
- **Asset Library**: Centralized asset organization and tagging
- **Real-time Collaboration**: Multi-user editing with CRDT sync
- **AI Pipelines**: Autonomous creative workflows
- **Team Management**: Roles, permissions, and organizations
- **Marketplace**: Creator asset marketplace
- **Multi-SDK**: TypeScript, C++, Python SDKs

## Libraries

```
libs/yemaya/
├── sdk/                 # TypeScript SDK
├── sdk-cpp/             # C++ SDK for engine integration
├── sdk-python/          # Python SDK for pipelines
├── database/            # Prisma schema & utilities
├── projects/            # Project management logic
├── orchestration/       # Workflow orchestration
├── collaboration/       # Real-time collaboration (Yjs/CRDT)
├── autonomous-pipelines/ # Autonomous AI workflows
├── agents/              # AI agent framework
├── asset-library/       # Asset management
├── safety/              # Content moderation
├── marketplace/         # Creator marketplace
├── enterprise/          # Enterprise features
├── community/           # Community features
├── ui/                  # React component library
└── event-handlers/      # Event subscriptions
```

## Quick Start

### Using the SDK

```typescript
import { createYemayaClient } from '@yemaya/sdk';

const yemaya = createYemayaClient({
  baseUrl: process.env.YEMAYA_API_URL || 'http://localhost:4000',
  auth: { type: 'api-key', credentials: process.env.YEMAYA_API_KEY },
});

// Create a project
const project = await yemaya.projects.create({
  name: 'Epic Adventure Game',
  type: 'game',
  description: 'An open-world RPG',
});

// Generate assets via Isis
const job = await yemaya.projects.generateAsset(project.id, {
  type: 'image',
  prompt: 'Fantasy landscape concept art',
});

// Real-time collaboration
const collab = await yemaya.collaboration.connect(project.id);
collab.on('change', (update) => console.log('Project updated'));
```

### Running Locally

```bash
# Start Yemaya API
nx serve yemaya-api

# Start Studio web app
nx serve yemaya-studio-web

# Run tests
nx test @yemaya/sdk

# Build all Yemaya libraries
nx run-many --target=build --projects=tag:scope:yemaya
```

## Applications

```
apps/yemaya/
├── api/                 # API Gateway (Hono + OpenAPI)
├── studio-web/          # React web application
├── studio-desktop/      # Electron desktop app
├── workers/             # Background job processors
└── cli/                 # Command-line interface
```

## API Endpoints

| Method | Endpoint                       | Description         |
| ------ | ------------------------------ | ------------------- |
| POST   | `/v1/projects`                 | Create project      |
| GET    | `/v1/projects/:id`             | Get project details |
| PUT    | `/v1/projects/:id`             | Update project      |
| DELETE | `/v1/projects/:id`             | Delete project      |
| POST   | `/v1/projects/:id/assets`      | Upload asset        |
| POST   | `/v1/projects/:id/generate`    | Generate AI asset   |
| POST   | `/v1/projects/:id/export`      | Export to engine    |
| GET    | `/v1/teams`                    | List teams          |
| POST   | `/v1/teams`                    | Create team         |
| WS     | `/v1/collaboration/:projectId` | Real-time sync      |

## Events

| Event                         | Description              |
| ----------------------------- | ------------------------ |
| `yemaya.project.created`      | New project created      |
| `yemaya.project.updated`      | Project modified         |
| `yemaya.asset.uploaded`       | Asset uploaded           |
| `yemaya.asset.attached`       | Asset attached from Isis |
| `yemaya.generation.started`   | AI generation started    |
| `yemaya.generation.completed` | AI generation finished   |
| `yemaya.collaboration.joined` | User joined project      |

## Configuration

```bash
# Required
YEMAYA_DATABASE_URL=postgresql://...?schema=yemaya
REDIS_URL=redis://localhost:6379

# Storage
ASSET_BUCKET=oshun-yemaya-assets
ASSET_CDN_URL=https://assets.yemaya.io

# Cross-domain
ISIS_API_URL=http://localhost:4001
BELLONA_API_URL=http://localhost:4005
SOPHIA_API_URL=http://localhost:4003
HATHOR_API_URL=http://localhost:4004

# Collaboration
WEBSOCKET_URL=wss://ws.yemaya.io
```

## Project Types

| Type        | Description           |
| ----------- | --------------------- |
| `game`      | Video game project    |
| `film`      | Film/video production |
| `animation` | Animation project     |
| `vfx`       | Visual effects        |
| `xr`        | VR/AR experience      |
| `other`     | Custom project type   |

## Cross-Domain Integration

Yemaya integrates with all other Oshun domains:

- **Isis**: AI-powered asset generation
- **Sophia**: Research and reference management
- **Hathor**: World and narrative design
- **Bellona**: Engine export and builds

```typescript
// Generate with Isis
const asset = await yemaya.projects.generateAsset(projectId, {
  type: 'image',
  prompt: 'Concept art',
});

// Search with Sophia
const refs = await yemaya.research.search({
  query: 'medieval architecture',
});

// Create world with Hathor
const world = await yemaya.worldbuilding.createWorld({
  name: 'Game World',
});

// Export with Bellona
const build = await yemaya.projects.export(projectId, {
  engine: 'godot',
});
```

## Local Development

Start the full development environment:

```bash
# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose -f docker/docker-compose.dev.yml up -d

# Run database migrations
pnpm nx run @yemaya/database:prisma:migrate:dev

# Start the API
pnpm nx serve yemaya-api

# Start Studio web app
pnpm nx serve yemaya-studio-web
```

See [CLAUDE.md](/CLAUDE.md) for detailed local development setup.

## Related Documentation

- [API Reference](/docs/api/yemaya/)
- [SDK Documentation](/docs/sdk/yemaya/)
- [Collaboration Guide](/docs/guides/collaboration.md)
- [Migration Guide](/docs/migration/yemaya-migration-guide.md)
