# 1catai/1cat-studio architecture

> Architecture diagram of the GitHub repository 1catai/1cat-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1catai/1cat-studio
- Repository: https://github.com/1catai/1cat-studio

## Overview

1Cat Studio is a self-hosted browser workbench for deploying local inference and using it for chat, code preview, agent tasks, and visual creation. The main workflow is prepare or import a runtime and model, configure a launch profile and GPUs, start inference, then use the ready service from Studio or an OpenAI-compatible client. Separate branches support sandboxed project work, creative generation and canvas workflows, and GPU/request monitoring. The map follows documented capabilities; unsampled implementation details are represented only at supported directory or module boundaries.

Main entry points: [`studio/backend/onecat/app.py`](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/app.py) (HTTP application), [`studio/backend/onecat/creative/api.py`](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/api.py) (Creative endpoints), [`studio/backend/onecat/engine.py`](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/engine.py) (Model lifecycle), [`studio/backend/onecat/agent/tasks.py`](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/tasks.py) (Durable agent tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Studio interface"]
  node_frontend["Studio application<br/>[main.tsx]"]
  node_chat_ui["Chat and preview<br/>[chat-page.tsx]"]
  node_model_ui["Model setup<br/>[models-page.tsx]"]
  node_agent_ui["Agent workspace<br/>[agent-page.tsx]"]
  node_creative_ui["Creative workbench<br/>[page.tsx]"]
  node_canvas_ui["Creative canvas<br/>[page.tsx]"]
  node_service_ui["Service and GPU<br/>[service-page.tsx]"]
end

subgraph group_inference["Inference management"]
  node_backend["HTTP application<br/>[app.py]"]
  node_engine["Model lifecycle<br/>[engine.py]"]
  node_runtime_models["Runtime and model setup<br/>[runtimes.py]"]
  node_catalog["Model catalog<br/>[catalog.py]"]
  node_proxy["Inference proxy<br/>[proxy.py]"]
  node_state[("Studio state store<br/>[db.py]")]
end

subgraph group_workflows["User workflows"]
  node_agent_api["Agent endpoints<br/>[api.py]"]
  node_agent_tasks["Durable agent tasks<br/>[tasks.py]"]
  node_agent_runtime["Codex runtime bridge<br/>[runtime.py]"]
  node_creative_api["Creative endpoints<br/>[api.py]"]
  node_creative_services["Creative services<br/>[services.py]"]
  node_creative_generation["Creative generation<br/>[generations.py]"]
  node_creative_runs["Creative runs<br/>[runs.py]"]
  node_preview_runtime["Isolated code preview<br/>[preview-runtime.ts]"]
end

subgraph group_operations["Operations and metrics"]
  node_gpu["GPU controls<br/>[gpu_control.py]"]
  node_telemetry["GPU telemetry<br/>[telemetry.py]"]
  node_request_metrics["Request metrics<br/>[request_metrics.py]"]
  node_jobs["Background jobs<br/>[jobs.py]"]
end

node_user(("Browser user"))
node_api_client(("API client"))
node_external_inference["1Cat-vLLM service"]
node_external_gpu["NVIDIA GPUs"]
node_codex["Codex runtime"]
node_creative_service["Configured creative service"]

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_agent_api
node_backend -->|"mounts routes"| node_creative_api
node_model_ui -->|"manages setup"| node_backend
node_backend -->|"schedules setup"| node_runtime_models
node_runtime_models -->|"resolves models"| node_catalog
node_backend -->|"controls lifecycle"| node_engine
node_engine -->|"reads and writes"| node_state
node_engine -->|"launches service"| node_external_inference
node_chat_ui -->|"sends chat"| node_backend
node_backend -->|"routes inference"| node_proxy
node_proxy -->|"forwards requests"| node_external_inference
node_chat_ui -->|"runs artifacts"| node_preview_runtime
node_agent_ui -->|"submits tasks"| node_agent_api
node_agent_api -->|"dispatches tasks"| node_agent_tasks
node_agent_tasks -->|"controls runtime"| node_agent_runtime
node_agent_tasks -->|"uses model"| node_proxy
node_agent_runtime -->|"starts process"| node_codex
node_creative_ui -->|"requests generation"| node_creative_api
node_canvas_ui -->|"manages workflows"| node_creative_api
node_creative_api -->|"manages services"| node_creative_services
node_creative_api -->|"prepares generation"| node_creative_generation
node_creative_api -->|"dispatches runs"| node_creative_runs
node_creative_services -.->|"connects or launches"| node_creative_service
node_creative_runs -->|"uses service"| node_creative_services
node_service_ui -->|"manages service"| node_backend
node_backend -->|"controls GPUs"| node_gpu
node_gpu -->|"sets power modes"| node_external_gpu
node_backend -->|"reads metrics"| node_telemetry
node_telemetry -->|"samples devices"| node_external_gpu
node_backend -->|"serves request history"| node_request_metrics
node_backend -->|"schedules work"| node_jobs

click node_frontend "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/main.tsx"
click node_chat_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/chat-page.tsx"
click node_model_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/models-page.tsx"
click node_agent_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/agent-page.tsx"
click node_creative_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/creative/page.tsx"
click node_canvas_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/canvas/page.tsx"
click node_service_ui "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/service-page.tsx"
click node_backend "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/app.py"
click node_engine "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/engine.py"
click node_runtime_models "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/runtimes.py"
click node_catalog "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/catalog.py"
click node_proxy "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/proxy.py"
click node_state "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/db.py"
click node_agent_api "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/api.py"
click node_agent_tasks "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/tasks.py"
click node_agent_runtime "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/runtime.py"
click node_creative_api "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/api.py"
click node_creative_services "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/services.py"
click node_creative_generation "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/generations.py"
click node_creative_runs "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/runs.py"
click node_preview_runtime "https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/preview-runtime.ts"
click node_gpu "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/gpu_control.py"
click node_telemetry "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/telemetry.py"
click node_request_metrics "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/request_metrics.py"
click node_jobs "https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/jobs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_chat_ui,node_model_ui,node_agent_ui,node_creative_ui,node_canvas_ui,node_service_ui,node_user,node_api_client toneBlue
class node_backend,node_engine,node_runtime_models,node_catalog,node_proxy,node_state toneAmber
class node_agent_api,node_agent_tasks,node_agent_runtime,node_creative_api,node_creative_services,node_creative_generation,node_creative_runs,node_preview_runtime toneMint
class node_gpu,node_telemetry,node_request_metrics,node_jobs toneRose
class node_external_inference,node_external_gpu,node_codex,node_creative_service toneIndigo
```

## Components

### Studio interface

- [Studio application](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/main.tsx): `studio/frontend/src/onecat/main.tsx`
- [Chat and preview](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/chat-page.tsx): `studio/frontend/src/onecat/chat-page.tsx`
- [Model setup](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/models-page.tsx): `studio/frontend/src/onecat/models-page.tsx`
- [Agent workspace](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/agent-page.tsx): `studio/frontend/src/onecat/agent-page.tsx`
- [Creative workbench](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/creative/page.tsx): `studio/frontend/src/onecat/creative/page.tsx`
- [Creative canvas](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/canvas/page.tsx): `studio/frontend/src/onecat/canvas/page.tsx`
- [Service and GPU](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/service-page.tsx): `studio/frontend/src/onecat/service-page.tsx`

### Inference management

- [HTTP application](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/app.py): `studio/backend/onecat/app.py`
- [Model lifecycle](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/engine.py): `studio/backend/onecat/engine.py`
- [Runtime and model setup](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/runtimes.py): `studio/backend/onecat/runtimes.py`
- [Model catalog](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/catalog.py): `studio/backend/onecat/catalog.py`
- [Inference proxy](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/proxy.py): `studio/backend/onecat/proxy.py`
- [Studio state store](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/db.py): `studio/backend/onecat/db.py`

### User workflows

- [Agent endpoints](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/api.py): `studio/backend/onecat/agent/api.py`
- [Durable agent tasks](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/tasks.py): `studio/backend/onecat/agent/tasks.py`
- [Codex runtime bridge](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/agent/runtime.py): `studio/backend/onecat/agent/runtime.py`
- [Creative endpoints](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/api.py): `studio/backend/onecat/creative/api.py`
- [Creative services](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/services.py): `studio/backend/onecat/creative/services.py`
- [Creative generation](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/generations.py): `studio/backend/onecat/creative/generations.py`
- [Creative runs](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/creative/runs.py): `studio/backend/onecat/creative/runs.py`
- [Isolated code preview](https://github.com/1catai/1cat-studio/blob/main/studio/frontend/src/onecat/preview-runtime.ts): `studio/frontend/src/onecat/preview-runtime.ts`

### Operations and metrics

- [GPU controls](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/gpu_control.py): `studio/backend/onecat/gpu_control.py`
- [GPU telemetry](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/telemetry.py): `studio/backend/onecat/telemetry.py`
- [Request metrics](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/request_metrics.py): `studio/backend/onecat/request_metrics.py`
- [Background jobs](https://github.com/1catai/1cat-studio/blob/main/studio/backend/onecat/jobs.py): `studio/backend/onecat/jobs.py`

### Other components

- **Browser user**
- **API client**
- **1Cat-vLLM service**
- **NVIDIA GPUs**
- **Codex runtime**
- **Configured creative service**

## Connections

- Browser user → Studio application: uses
- Studio application → HTTP application: calls API
- HTTP application → Agent endpoints: mounts routes
- HTTP application → Creative endpoints: mounts routes
- Model setup → HTTP application: manages setup
- HTTP application → Runtime and model setup: schedules setup
- Runtime and model setup → Model catalog: resolves models
- HTTP application → Model lifecycle: controls lifecycle
- Model lifecycle → Studio state store: reads and writes
- Model lifecycle → 1Cat-vLLM service: launches service
- Chat and preview → HTTP application: sends chat
- HTTP application → Inference proxy: routes inference
- Inference proxy → 1Cat-vLLM service: forwards requests
- Chat and preview → Isolated code preview: runs artifacts
- Agent workspace → Agent endpoints: submits tasks
- Agent endpoints → Durable agent tasks: dispatches tasks
- Durable agent tasks → Codex runtime bridge: controls runtime
- Durable agent tasks → Inference proxy: uses model
- Codex runtime bridge → Codex runtime: starts process
- Creative workbench → Creative endpoints: requests generation
- Creative canvas → Creative endpoints: manages workflows
- Creative endpoints → Creative services: manages services
- Creative endpoints → Creative generation: prepares generation
- Creative endpoints → Creative runs: dispatches runs
- Creative services → Configured creative service: connects or launches
- Creative runs → Creative services: uses service
- Service and GPU → HTTP application: manages service
- HTTP application → GPU controls: controls GPUs
- GPU controls → NVIDIA GPUs: sets power modes
- HTTP application → GPU telemetry: reads metrics
- GPU telemetry → NVIDIA GPUs: samples devices
- HTTP application → Request metrics: serves request history
- HTTP application → Background jobs: schedules work