# Isis — Systems Deep Dive

> The `apps/isis/` area: the deployable surface of the Isis "Generative Factory"
> — three Hono API services, a BullMQ GPU worker, a Commander CLI, and a
> Vite/React operations console that together take an AI-generation request from
> submission through GPU processing to a provenance-tracked output.

## What this area is

Isis is Oshun's generative-content domain. The `apps/isis/` directory holds its
**runnable applications** (everything tagged `scope:isis`, `type:app`), as
distinct from the Isis shared libraries (`@isis/job-envelope`,
`@isis/event-publisher`, and friends under `libs/isis/`) that these apps import.
There are six Nx projects here, and they decompose along a clean request
lifecycle: a client submits a generation job, the job is validated and enqueued,
a GPU worker executes it, and the resulting artifact is registered with its
provenance.

The backbone is three independent **Hono** HTTP services that each own one slice
of state. `@isis/generation-api` is the front door: it accepts job-submission
requests, validates them against a large catalog of per-asset-category Zod
schemas, runs budget and quality-gate checks, and enqueues a typed job envelope
onto a BullMQ/Redis queue (`apps/isis/generation-api/src/queue/producer.ts`,
queue `isis:jobs:submit`). `@isis/workflow-registry` owns the workflow and
template definitions — including a dev → staging → prod promotion state machine
for "staging recipes" — that the generation API executes against.
`@isis/output-registry` owns the other end: registering finished outputs, their
retention policies, and a hash-chained provenance/lineage ledger in PostgreSQL.

Between submission and registration sits `@isis/gpu-worker`, a headless BullMQ
consumer. It is not an HTTP service; it pulls jobs off the queue and dispatches
them to one of four real executors (texture upscale, Blender render, mesh
processing, Gaussian splatting), each of which shells out to a Python pipeline
script and ships in its own Docker image (`apps/isis/gpu-worker/src/docker/`,
`apps/isis/gpu-worker/src/assets/scripts/`).

The remaining two projects are the human/operator interfaces. `@isis/cli` is a
Commander-based `isis` command-line tool for generating content, managing jobs,
and operator triage. `@isis/web` is a Vite + React operations console with
RBAC-gated routes for dashboards, jobs, workflows, outputs, models, providers,
and "parity" monitors. Both are clients of the three Hono services rather than
state owners themselves.

## How it fits the wider system

The three services are the state-owning boundary: clients (`@isis/web` over
`browser-http-client`, `@isis/cli` over its `utils/client`, and the platform
BFF) talk to them over HTTP, and the services talk to each other indirectly
through the queue and shared events. The data path is
`generation-api → BullMQ queue → gpu-worker → output-registry`, while the
control path is `generation-api → workflow-registry` for the workflow/template
definitions a job runs against. All four backend projects publish domain events
through the shared `@isis/event-publisher` library (asset-generated,
model-loaded, staging-recipe/promotion changed), which downstream domains such
as Lilith and the audit pipeline consume.

The apps depend downward on platform libraries — `@oshun/logging`,
`@oshun/database` (PostgreSQL), and the Isis contract/envelope libraries — and
never on each other's internals; the queue envelope (`@isis/job-envelope`) and
the event payloads are the only coupling between producer and consumer, which is
what lets the GPU worker scale and deploy independently of the API tier. Each
service ships an `openapi.yaml` and an `openapi.contract.spec.ts` that keeps the
spec honest against the implemented routes.

## Entity reference

### @isis/generation-api

The front-door generation service (`apps/isis/generation-api`), a Hono app
assembled in `src/app.ts` with security headers, CORS, rate limiting, JWT auth
(fail-fast on missing `JWT_SECRET` in production), and `/health` + `/ready`
readiness probes that fan out to job, model, and ComfyUI health checks. Its core
job is to accept generation requests, validate them, and enqueue a typed
envelope onto BullMQ via `src/queue/producer.ts` (queue `isis:jobs:submit`). Its
most distinctive feature is breadth: `src/schemas/` and `src/routes/` carry a
large catalog of asset categories (character concept art, creature concept art,
environment matte painting, material PBR packs, weapon packs, VFX element packs,
voice-line packs, and many more), each with its own `*.schema.ts`,
`*-budget-utils.ts`, `*-quality-gate-utils.ts`, and
`*-regression-golden-dataset.ts` — the quality gates use domain-specific metrics
(e.g. `face_embedding_cosine_similarity`, `facial_landmark_drift_px`,
`wardrobe_palette_delta_e` in `character-concept-art-quality-gate-utils.ts`),
not generic CRUD. It also exposes provider callback webhooks, RunPod budget
guardrails, and a workflow executor that warms a capability cache at boot.

### @isis/gpu-worker

The headless GPU job processor (`apps/isis/gpu-worker`). Unlike its three
siblings it is not an HTTP service — `src/index.ts` boots a `GPUWorker`
(`src/workers/gpu-worker.ts`) that is a real BullMQ `Worker` over Redis (queue
`gpu-jobs`), with heartbeats, graceful SIGTERM/SIGINT shutdown, model-load
tracking, and event emission through `@isis/event-publisher`. Work is dispatched
to one of four registered executors — `TextureUpscaleExecutor`,
`BlenderRenderExecutor`, `MeshProcessingExecutor`, `GaussianSplattingExecutor`
(`src/executors/`) — each of which drives a real Python pipeline under
`src/assets/scripts/` (e.g. `texture_upscale.py`, `gaussian_splat_pipeline.py`)
and has a dedicated Dockerfile under `src/docker/`. The project tags itself
`platform:gpu`; the executor code, throughput benchmark targets
(`executor-throughput.targets.ts`), and Docker images are all present, though
actually running the pipelines requires GPU hardware and the built images.

### @isis/output-registry

The output-and-provenance service (`apps/isis/output-registry`), a Hono app
(`src/app.ts`) mounting `/api/v1/outputs`, `/api/v1/policies`, and
`/api/v1/provenance`. It owns the terminal end of the pipeline: registering
generated output files, their retention/storage-tier policies, and a provenance
and lineage graph persisted in PostgreSQL through `@oshun/database`
(`src/services/output.service.ts`). The service is genuinely substantial —
beyond CRUD it implements a hash-chained provenance ledger (covered by
`output.service.ledger.spec.ts`), lineage nodes/edges, and a paginated
provenance backfill for historical outputs (task marker `WS17-004`). It emits
`IsisAssetGeneratedPayload` events on registration so downstream consumers learn
about new assets.

### @isis/workflow-registry

The workflow/template definition service (`apps/isis/workflow-registry`), a Hono
app (`src/app.ts`) exposing `/workflows`, `/templates`, and `/staging-recipes`,
backed by PostgreSQL with its own migration runner (`src/migrations/`, wired to
the `db:migrate` target via `migrations/cli.ts`). It is the control-plane
counterpart to the generation API: it stores the workflows a job executes
against, plus template governance and enforcement
(`services/template-governance.ts`, `services/template-enforcement.ts`). Its
signature feature is a real **dev → staging → prod promotion state machine** for
named, versioned "staging recipes" (`services/staging-recipe.service.ts`,
`services/environment-promotion.ts`): recipes are validated against a Zod
schema, persisted to `workflow_staging_recipes`, and advanced through an
immutable transition ledger on gate pass/fail/waive/promote/reject, emitting
`isis.workflow.staging-recipe.changed` and `isis.workflow.promotion.changed`
events.

### @isis/cli

The `isis` command-line tool (`apps/isis/cli`), a Commander program assembled in
`src/index.ts`. It is a real, fully-wired CLI: top-level commands for
`generate`, `jobs`, `workflows`, `outputs`, `config`, `health`, and `auth`
(`src/commands/`), plus `t2i`/`i2i` quick-generation aliases and browser-OAuth /
API-key auth (`src/auth.ts`). It talks to the generation API over HTTP through
`src/utils/client.ts`, resolving the endpoint from `--api-url` / `ISIS_API_URL`.
The help text documents operator workflows that map to implemented subcommands —
job triage for stuck jobs and DLQ pressure, dead-letter replay, and several
historical backfills (workflow IDs, unified taxonomy, costs, provenance).

### @isis/web

The Isis operations console (`apps/isis/web`), a Vite + React single-page app.
`src/App.tsx` defines the route table: every operator surface — dashboard, jobs,
workflows (list/details/editor/templates), outputs (plus consistency workspace,
interactive generation, and a mesh-transformer A/B comparison), models,
providers, RunPod, and a set of "API parity" monitor pages — is gated behind
`RequireAuth` and per-route `RequirePermission` checks driven by
`src/auth/rbac.ts`. It is a real implementation with a typed API client
(`src/api/browser-http-client.ts`, `IsisClientProvider`), a design-system
token/theme layer (`src/design-system/`), UI interaction telemetry, and
Playwright e2e specs under `e2e/`. It is a client of the backend services, not a
state owner.