Eve library

Yemaya Architecture

Guide

Revision 1

On this page

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#

  1. System Overview
  2. Service Architecture
  3. Application Layer
  4. Library Layer
  5. API Architecture
  6. Database Schema
  7. Worker Architecture
  8. Cross-Domain Integration
  9. Real-Time Collaboration
  10. AI Agent Architecture
  11. External Integrations
  12. Data Flow
  13. Deployment Architecture
  14. 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.
text
┌──────────────────────────────────────────────────────────────────┐
│                          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
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#

text
@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#

text
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
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#

text
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:

text
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
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
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
┌──────────────────────────────────────────────────────────────┐
│                      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