The
apps/yemaya/area: the five deployable surfaces of the Yemaya creative production platform — the HTTP API gateway, the BullMQ worker fleet, the CLI, and the web and Electron studio clients — that together front the Oshun capability domains for end-to-end film and game creation.
What this area is#
Yemaya is the "creative studio" product: a platform for managing projects,
assets, scripts, storyboards, schedules, budgets, crew, and locations, and for
driving autonomous production pipelines across the Oshun capability domains. The
apps/yemaya/ directory is not one application but five separate Nx
applications — each a distinct runtime surface of that one product. They share
a brand and a domain model but ship and scale independently: a server-side API
gateway (@yemaya/api), a background worker service (@yemaya/workers), a
headless CLI (@yemaya/cli), a browser PWA (@yemaya/studio-web), and an
Electron desktop suite (@yemaya/studio-desktop).
The center of gravity is @yemaya/api, a Hono OpenAPIHono application
(apps/yemaya/api/src/app.ts) that mounts roughly thirty routers under /v1
and acts as the BFF for the studio. The two client apps (studio-web,
studio-desktop) are read/write front-ends against that API; the CLI is a
scripting front-end against the same surface; and @yemaya/workers is the
asynchronous arm that runs the long pipelines the API kicks off. All five carry
the scope:yemaya Nx tag and type:app, distinguished by their platform: tag
(server, cli, desktop, web).
A recurring theme across every surface is integration with the Oshun
capability domains — Isis (generation), Sophia (research/knowledge), Hathor
(worldbuilding), and Bellona (engine/build). The API reverse-proxies to them
(/v1/capabilities/{domain}), the workers dispatch pipeline stages to them by
name, and both clients carry per-domain client stores. Yemaya owns the
studio/production model; it coordinates rather than re-implements the capability
work, which lives in those domains' own queues and services.
How it fits the wider system#
These apps sit at the top of the stack — they are the product front-door, not a
reusable library. They depend downward on Oshun libraries (for example
@yemaya/api imports checkDatabaseHealth from @yemaya/database, and
@yemaya/studio-web consumes @yemaya/ui/interactive-guide) and outward on the
capability domains, but nothing depends on them. The API is the canonical
boundary: it owns authentication (JWT/OAuth/API keys), RFC 7807 problem-details
errors, rate limiting, API versioning, and the OpenAPI 3.1 contract that the CLI
and clients are written against. The workers consume Redis/BullMQ queues and
coordinate domain execution; the clients consume the API over HTTP/WebSocket.
Walk the dependency edges on any node below to see exactly what it pulls in.
Entity catalog (6)#
The 6 tracked Nx projects in yemaya, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 5 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
unclassified (6)#
Yemaya API Gateway - RESTful and gRPC services for the creative studio
The platform's HTTP API gateway and BFF (apps/yemaya/api), built on Hono's
OpenAPIHono. src/app.ts wires a deep SOTA middleware stack — request-id and
async-local request context, performance metrics (100ms p95 target),
secureHeaders/CSP, CORS with origin whitelisting, gzip compression, server
timing, input sanitization, rate limiting, RFC 7807 problem-details errors, and
path/header API versioning — then mounts ~30 routers under /v1 (auth, users,
projects, organizations, project-scoped assets, scripts, storyboards, schedules
plus optimization/sharing, crew, call-sheets, locations, budgets plus
line-items/templates/cost-prediction/variance/multi-currency, collaboration, a
/ws WebSocket surface, agents, plugins, webhooks, search, analytics,
score-editor, admin, versions, and a /v1/capabilities reverse proxy to Isis,
Sophia, Hathor, and Bellona). It self-documents via a generated OpenAPI 3.1 spec
with deterministic operation-id generation (withGeneratedOperationIds), served
through Swagger UI (/docs) and Scalar (/reference, /playground), and
exposes /health, /health/ready (database/cache/storage), /health/live, and
/metrics. This is the largest and most fully-implemented node in the area —
its src/ carries parallel routes/, services/, schemas/, middleware/,
and versioning/ trees plus extensive integration tests (auth, GDPR, SOC2,
projects, scripts, storyboards) and a generated openapi/ bundle.
Yemaya CLI - Command-line interface for automation and headless operations
The headless command-line surface (apps/yemaya/cli), a commander-based
binary named yemaya (src/index.ts, VERSION 0.1.0). It registers seven
command groups — project, asset, pipeline, collaboration (collab),
organization (org), config, and health — plus quick aliases ls (project
list) and whoami, with global flags for --api-url (default
http://localhost:3010), --api-key, --project, --organization, --json,
and --quiet. Commands talk to the API through src/utils/client.ts and render
through src/utils/output.ts and src/utils/progress.ts (chalk + spinners). It
is a real automation front-end against the same @yemaya/api surface the GUIs
use — for headless project/asset management, pipeline runs (with --dry-run and
--watch), and collaboration scripting.
Yemaya Desktop Application - Electron-based creative suite for film and game production
The Electron desktop suite (apps/yemaya/studio-desktop). src/main.ts is a
thin re-export of the real main process at src/main/index.ts, which composes a
large set of main-process modules: a WindowManager, type-safe IPC (ipc.ts
with logging, performance monitoring, and batching), V8-cache performance
optimization, native integrations, an enhanced auto-updater with
channels/rollback, protocol/deep-link handling, file lock/permissions/cache/temp
management, connectivity tracking, and extensive window management
(state/positioning/layouts/snapping/multi-monitor/fullscreen/picture-in-picture),
plus a bellona-bridge to the Bellona domain. The renderer is React
(src/renderer/, with Project/ScoreEditor/Settings/Welcome pages and a Zustand
project store), built by Vite while the main/preload bundles build with tsup.
src/score-editor/core.ts holds the entitlement-tiered Scene Score Editor logic
(with core.test.ts). Packaging is electron-forge: the makers/ directory
carries dmg/nsis/wix/pkg/appimage/flatpak/snap makers and scripts/ carries
per-OS code-signing, certificate rotation, and silent-install/upgrade tooling. A
real, deeply built desktop app.
Yemaya Studio Web Application - Browser-based creative studio for film and game production
The browser PWA client (apps/yemaya/studio-web), a React + Vite + react-router
single-page app served as a static bundle (it ships a Dockerfile and
nginx.conf). src/App.tsx defines lazy-loaded routes behind auth/role guards
(AuthGuard, GuestGuard, RoleGuard) covering the studio surfaces — Welcome,
Project, Scripts, Storyboards, Dailies Review, Director Dashboard, Render Farm,
and a cluster of AI studios (Relight, Video Edit, Motion/Camera, Portrait, A/V
Narrative, Foley, Object Removal), plus an admin-gated Scene Score Editor,
Settings, and Permissions. State is Zustand (src/stores/: app, auth, asset,
project, collaboration, theme, ai, plus per-domain client stores
isisStore/sophiaStore/hathorStore/bellonaStore initialized on mount). It
is a full PWA — service worker (src/sw.ts), web manifest, offline page, push
notifications, and background/periodic sync — with i18n in
English/Spanish/French, Storybook stories, an accessibility test harness, and
Playwright e2e. A substantial, real client, not a placeholder.
Yemaya Background Workers - Orchestration task processing and job queue handlers
The asynchronous worker fleet (apps/yemaya/workers), a BullMQ + pino service
whose entry point (src/index.ts) starts a configurable set of workers and
handles graceful shutdown on SIGTERM/SIGINT. src/queues.ts defines five
Yemaya-owned queues (yemaya:notification, :rendering, :export,
:pipeline, :event) and is explicit that capability-domain execution queues
live with their owning domains — Yemaya workers only coordinate. The workers/
directory implements five workers: notification, rendering orchestration, export
orchestration, pipeline orchestration, and an event consumer, selectable by
config.worker.type (all / per-type / orchestration). The pipeline worker
(src/workers/pipeline-orchestration-worker.ts) is the substantive one: it runs
DAG-based stage execution with dependency resolution, quality gates
(auto/human-review/skip with criteria), budget tracking, and dispatch of
stages to the capability domains (isis/sophia/hathor/bellona). A real
implementation, not a scaffold.