Canonical source: the canonical architecture document for this domain is
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#
System Overview
Service Architecture
Application Layer
Library Layer
API Architecture
Database Schema
Worker Architecture
Cross-Domain Integration
Real-Time Collaboration
AI Agent Architecture
External Integrations
Data Flow
Deployment Architecture
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:
Modular production pipeline -- Project management, asset management,
scripting, storyboarding, scheduling, and budgeting compose into complete
production workflows.
Multi-engine integration -- Native bridges to Blender, Godot, Unreal
Engine, Houdini, and DaVinci Resolve enable professional-grade rendering and
editing without vendor lock-in.
AI-assisted creation -- Multi-agent orchestration (LangGraph, CrewAI
patterns) with human-in-the-loop for AI-assisted and fully autonomous
production modes.
Real-time collaboration -- WebSocket-based presence, cursors, and
document sync for distributed teams.
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.
text Copy
┌──────────────────────────────────────────────────────────────────┐
│ 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:
text Copy
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#
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#
text Copy
@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)#
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
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#
text Copy
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#
text Copy
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 Copy
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#
text Copy
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:
Human-driven -- Traditional manual workflows
AI-assisted -- AI suggestions with human approval (HITL)
Fully autonomous -- AI agents execute complete production pipelines
Agent Orchestration (@yemaya/agents)#
Built on LangGraph and CrewAI patterns with human-in-the-loop:
text Copy
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#
text Copy
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#
text Copy
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#
text Copy
┌──────────────────────────────────────────────────────────────┐
│ 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