---
status: active
owner: platform
last_reviewed: 2026-09-29
supersedes: []
---
# Venture Studio — System Architecture
<!-- wiki:featured -->

**Purpose.** This repository is the **venture-studio** monorepo: product code, shared platform, infra references, and in-repo docs.

---

## 1. Documentation (single source of truth)

| Location | Role |
|----------|------|
| **`docs/README.md`** | Master router — 4 tracks |
| **`docs/studio-engine/`** | ANDI / agents / llm_brain stack |
| **`docs/studio-infra/`** | Docker + systemd + Ollama living inventory |
| **`docs/studio-products/`** | Registry products + ports |
| **`docs/studio-design/`** | `@studio/ui` + Next/React baselines |
| **`docs/archive/`** | Retired docs only |
| **`products|utilities/<id>/docs/`** | Colocated PRD / architecture per product |

**Rule:** If narrative and shipped code diverge, **code + API + DB + `products/registry.yaml`** win. Docs never override runtime sources.

---

## 2. Repository map

```
studio/
├── docs/                      # 4-track SSOT + operations + contracts + techpack
│   ├── studio-engine/
│   ├── studio-infra/
│   ├── studio-products/
│   ├── studio-design/
│   ├── archive/
│   ├── operations/
│   ├── products/contracts/
│   └── techpack/              # TechPack v4.1 DOCX
├── products/saas/             # Ship-ready SaaS roots
├── utilities/                 # Blueprint, Athena, Nous, …
├── platform/                  # Shared kit, ANDI, llm_brain, jobs
├── dashboard/                 # Studio launcher UI
├── scripts/                   # Ops + audit-docs-vs-runtime.sh
└── products/registry.yaml     # Product/port machine truth
```

**New SaaS product convention:** `products/saas/<kebab-case>/` with `frontend/`, `backend/`, `.devops/`, and `docs/`.

---

## 3. Current product inventory

Canonical registry: **`products/registry.yaml`**. Human view: **`docs/archive/studio-products/TECH_STACK.md`**.

Do not maintain a second product table here — update the registry, then re-run `scripts/audit-docs-vs-runtime.sh`.

---

## 4. Studio data plane

Living container list: **`docs/archive/studio-infra/TECH_STACK.md`** (from `docker ps`).

Typical shared services: Timescale Postgres `:5432`, Redis `:6379`, Qdrant `:6333`, LiteLLM `:4000`, Ollama `:11434`, n8n `:5678`, OpenHands `:3009`.

---

## 5. Cross-cutting deployment patterns

1. **TLS + nginx** — terminate HTTPS; proxy to registry UI/API ports.
2. **systemd** — frontends and many APIs; Docker for data plane + some backends.
3. **Smoke tests** — `.devops/smoke-test.sh` per product.
4. **Secrets** — never commit; see [operations/SECRETS_MANAGEMENT.md](./operations/SECRETS_MANAGEMENT.md).
5. **Async jobs** — `platform/jobs/` + `studio-job-worker`.
6. **DR** — [operations/DISASTER_RECOVERY.md](./operations/DISASTER_RECOVERY.md).

---

## 6. Checklist — adding another SaaS product

1. Scaffold `products/saas/<product>/` (+ `docs/`).
2. Register in **`products/registry.yaml`**.
3. Add contract under `docs/products/contracts/<id>.md`.
4. Update nginx + smoke tests.
5. Run `bash scripts/audit-docs-vs-runtime.sh` and refresh track `TECH_STACK.md` if needed.
6. Bump `docs/studio-products/VERSION` + `CHANGELOG.md`.

---

## 7. Related

- Platform LLM brain: `platform/shared/llm_brain.py`
- Kit version: `platform/VERSION`
- Master docs router: [README.md](./README.md)