# Yemaya — Systems Deep Dive

> 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 reference

### @yemaya/api

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/workers

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.

### @yemaya/cli

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/studio-web

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/studio-desktop

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.