# Studio Engine Architecture
<!-- wiki:featured -->
**Package:** `@studio/engine`  
**Version:** v3.0.0  
**Track:** studio-engine  
**Status:** Production — shared API, LLM routing, pipeline, MCP

## Overview

Studio Engine is the shared backend plane: one FastAPI process, registry-driven products, LiteLLM-mediated model calls via `llm_brain`, venture/ANDI pipeline orchestration, and MCP servers for agent tooling. Product UIs stay thin clients — no per-product duplicate stacks.

## Code surfaces

| Surface | Path | Role |
|---------|------|------|
| FastAPI app | `api/main.py` → `fastapi.service` `:8000` | Shared HTTP API |
| Routers | `api/routers/` | Domain route modules |
| Product registry (runtime API) | `api/product_registry.py` + `products/registry.yaml` | Ports, health, systemd SSOT |
| Pipeline | `api/services/pipeline/` | Discovery → definition → blueprint orchestration |
| LLM brain | `studio_platform/shared/llm_brain.py` | Sole product LLM entrypoint |
| LLM policy | `studio_platform/shared/llm_policy.py` | `task_type` → tier / model policy |
| LiteLLM | Docker `studio-litellm` · host `:4000` · `studio_platform/litellm/` | Provider gateway |
| ANDI | `studio_platform/andi/` | Intelligence / agents / Jev client |
| Jobs | `studio_platform/jobs/` | Async worker (`studio-job-worker`) |
| MCP | `studio_platform/mcp/` (+ shared MCP server) | Agent tool servers |

## FastAPI structure

Single app process (`api/main.py`) mounts domain routers. Controllers/models/deps live under `api/`. Product-specific backends may attach under utilities but share the same process and registry discipline.

### Router prefixes

| Prefix | Module | Purpose |
|--------|--------|---------|
| *(root)* | `health` | Liveness / health probes |
| `/api/medcode` | `medcode` | Clinical coding helpers |
| `/api/compliance` | `compliance` | Compliance endpoints |
| `/api/products` | `products` | Registry-backed product list / ops |
| `/api/system` | `system` | Host / console system controls |
| `/api/studio/infra` | `infra` | Infra unit status / control |
| `/api/studio` | `studio_pipeline` | Venture pipeline + studio ops |
| `/cds` (+ CRD router) | `crd` | CDS Hooks / CRD (HealthChain path) |

Ports and systemd units for products are **never** hardcoded — always `products/registry.yaml`.

## LiteLLM routing

```
Product / agent code
        │  llm_brain.complete(..., task_type=…)
        ▼
llm_policy.resolve_policy(task_type)  →  tier/* alias
        ▼
LiteLLM :4000  →  cloud / local providers (budget pools, keys)
```

Rules:

- **Always** call `llm_brain.complete` with a `task_type` — never providers directly.
- Use one of the five product lanes below — never bare `tier/confidential`.
- Budget pools / key selection live in `llm_brain` (`budget_pool_for_task`, LiteLLM key source audit).
- `CLOUD_ONLY_TASKS` and enforce/shadow modes gate sensitive routing.

## LLM Tiers

SSOT: `studio_platform/litellm/config.yaml` (privacy × depth). Dev mirrors: `tier/*-dev`.

| Tier | Thinking | Routing | When to use |
|------|----------|---------|-------------|
| `tier/public-fast` | OFF | Gemini free → OpenRouter → Vast | UI / general / non-PHI latency-sensitive |
| `tier/public-deep` | ON | OpenRouter → Vast (think → off) | Deep reasoning, async analysis (non-PHI) |
| `tier/confidential-fast` | OFF | Vast → Ollama only | PHI / confidential, quick answers (no free APIs) |
| `tier/confidential-deep` | ON | Vast (think) → Vast → Ollama | PHI / confidential, deep reasoning |
| `tier/critical` | ON | Gemini paid — **fail closed** | Must-succeed paid path; no free/Vast fallback |

Bulk sibling (not a product lane): `tier/public-batch` — Mistral free → Gemini free → Vast.

## Product registry

`products/registry.yaml` is the runtime SSOT for:

- Product / utility identity, URLs, icons, hibernate flags  
- `ports.api` / `ports.ui` (prod `:3xxx`, dev `:4xxx`)  
- Health probe URLs  
- systemd unit names  
- Platform adoption metadata (`kit_version`, `kit_target`, shell, llm, auth)

Console and APIs read registry via `api/product_registry.py` / registry fetch helpers — hibernate and fleet actions must not rewrite the git-tracked registry file.

## Pipeline orchestration

`api/services/pipeline/orchestrator.py` runs the venture pipeline (human-gated):

1. **Ingest** — text / audio (`ingest`, Whisper)  
2. **Discovery** — market intent + search (`discovery`, `search_intent`)  
3. **Strategic / quality gates** — viability + constraint checks (Oracle Ampere profile, etc.)  
4. **Definition / documents** — ANDI sections, generated docs  
5. **Arbitrage draft** — feature extraction + draft markdown  
6. **Blueprint compile** — `blueprint.compile_blueprint` after approval  

Supporting pieces: `run_store`, workspace writers, Firecrawl/heuristics, evaluator, gate models. ANDI runtime (`api/services/pipeline/andi/`, `studio_platform/andi/`) keeps heavy science in isolated subprocesses (`andi312` cwd rule — never run from repo root).

## MCP servers

| Server | Location | Tools / use |
|--------|----------|-------------|
| Studio UI MCP | `studio_platform/mcp/studio-ui-server/` · `scripts/studio-ui-mcp.sh` | `list_components`, `get_recipe`, `get_component`, `get_tokens`, `validate_ui` |
| Shared Studio MCP | `studio_platform/shared/mcp/` · `studio-mcp.service` | Platform agent tooling |
| Graphify MCP | graphify tooling | Scoped codebase graph queries before edits |
| Playwright MCP | `@playwright/mcp` | Interactive e2e debugging |

All coding tools (Cursor, OpenCode, Zoo, Codex) wire the **same** Studio UI MCP config pattern — see `AGENTS.md`.

## Design principles (engine)

1. One shared FastAPI + one LiteLLM + one registry — no duplicate stacks per product.  
2. LLM is language only; ANDI / evidence tiers own decisions.  
3. Intelligence (`andi312`) stays isolated from the light API process.  
4. Runtime beats narrative docs when they disagree.

## Related docs

- `docs/studio-engine/` — track VERSION, TECH_STACK, ANDI / foundation charters  
- `docs/operations/PORT_SCHEME.md`, `NEW_PRODUCT_RUNBOOK.md`  
- `platform/andi/ANDI.md`  
- `AGENTS.md` — non-negotiables for LLM + registry