# dev-sri67/upgrade-chamber architecture

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

- Interactive diagram: https://gitdiagram.com/dev-sri67/upgrade-chamber
- Repository: https://github.com/dev-sri67/upgrade-chamber

## Overview

Upgrade Chamber accepts a profile-based dependency-upgrade run, checks that the unmodified repository passes its baseline, tries the upgrade, optionally repairs failures with a bounded agent, then independently verifies and publishes evidence. The README documents the service boundaries and major capabilities; sampled source confirms the worker lifecycle, inference transport, persistence, execution attempt, and browser views. Some subsystem wiring is documented but its implementation was not sampled, so uncertain call edges are omitted.

Main entry points: [`src/upgrade_chamber/worker.py`](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/worker.py) (Run worker), [`web/src/App.tsx`](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/App.tsx) (App shell), [`src/upgrade_chamber/api.py`](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/api.py) (FastAPI service), [`web/src/api.ts`](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/api.ts) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_start["Start view<br/>[StartView.tsx]"]
  node_live["Live run view<br/>[RunView.tsx]"]
  node_result["Result view<br/>[ResultView.tsx]"]
  node_webapi["Browser API client<br/>[api.ts]"]
  node_session["Session identity<br/>[session.ts]"]
end

subgraph group_control["Run control"]
  node_api["FastAPI service<br/>[api.py]"]
  node_worker["Run worker<br/>[worker.py]"]
  node_inference["Inference transport<br/>[inference.py]"]
end

subgraph group_workflow["Upgrade workflow"]
  node_profiles["Profile catalog<br/>[profiles.py]"]
  node_baseline["Baseline preparation<br/>[baseline.py]"]
  node_agent["Repair agent<br/>[agent.py]"]
  node_edits["Edit validation<br/>[edits.py]"]
  node_osv["Advisory lookup<br/>[osv.py]"]
end

subgraph group_execution["Isolated execution"]
  node_runner["Container controller<br/>[runner.py]"]
  node_attempt["Test attempt<br/>[attempt.py]"]
end

subgraph group_state["Evidence and state"]
  node_store[("Run persistence<br/>[storage.py]")]
end

node_visitor(("Demo user"))
node_browser(("Browser session"))
node_docker["Docker engine"]
node_model["Vultr inference"]
node_advisories["OSV service"]

node_visitor -->|"uses"| node_app
node_app -->|"renders"| node_start
node_app -->|"renders"| node_live
node_app -->|"renders"| node_result
node_app -->|"persists identity"| node_session
node_start -->|"submits run"| node_webapi
node_live -->|"polls, cancels"| node_webapi
node_result -->|"loads evidence"| node_webapi
node_webapi -->|"HTTP requests"| node_api
node_browser -->|"stores token"| node_session
node_api -->|"reads, writes runs"| node_store
node_worker -->|"leases, records"| node_store
node_worker -->|"uses profile"| node_profiles
node_worker -->|"prepares source"| node_baseline
node_worker -->|"runs phases"| node_runner
node_worker -->|"starts repair"| node_agent
node_agent -->|"validates edits"| node_edits
node_worker -->|"requests inference"| node_api
node_api -->|"dispatches calls"| node_inference
node_inference -->|"sends prompts"| node_model
node_worker -->|"queries advisories"| node_osv
node_osv -->|"fetches snapshots"| node_advisories
node_runner -->|"controls containers"| node_docker
node_docker -->|"runs attempt"| node_attempt
node_worker -->|"stores artifacts"| node_store

click node_app "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/App.tsx"
click node_start "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/StartView.tsx"
click node_live "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/RunView.tsx"
click node_result "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/ResultView.tsx"
click node_webapi "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/api.ts"
click node_session "https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/session.ts"
click node_api "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/api.py"
click node_worker "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/worker.py"
click node_profiles "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/profiles.py"
click node_baseline "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/baseline.py"
click node_agent "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/agent.py"
click node_edits "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/edits.py"
click node_osv "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/osv.py"
click node_runner "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/runner.py"
click node_attempt "https://github.com/dev-sri67/upgrade-chamber/blob/main/execution/attempt.py"
click node_inference "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/inference.py"
click node_store "https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/storage.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_app,node_start,node_live,node_result,node_webapi,node_session,node_visitor,node_browser toneBlue
class node_api,node_worker,node_inference toneAmber
class node_profiles,node_baseline,node_agent,node_edits,node_osv toneMint
class node_runner,node_attempt toneRose
class node_store,node_docker,node_model,node_advisories toneIndigo
```

## Components

### Web interface

- [App shell](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Start view](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/StartView.tsx): `web/src/components/StartView.tsx`
- [Live run view](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/RunView.tsx): `web/src/components/RunView.tsx`
- [Result view](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/components/ResultView.tsx): `web/src/components/ResultView.tsx`
- [Browser API client](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/api.ts): `web/src/api.ts`
- [Session identity](https://github.com/dev-sri67/upgrade-chamber/blob/main/web/src/session.ts): `web/src/session.ts`

### Run control

- [FastAPI service](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/api.py): `src/upgrade_chamber/api.py`
- [Run worker](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/worker.py): `src/upgrade_chamber/worker.py`
- [Inference transport](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/inference.py): `src/upgrade_chamber/inference.py`

### Upgrade workflow

- [Profile catalog](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/profiles.py): `src/upgrade_chamber/profiles.py`
- [Baseline preparation](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/baseline.py): `src/upgrade_chamber/baseline.py`
- [Repair agent](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/agent.py): `src/upgrade_chamber/agent.py`
- [Edit validation](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/edits.py): `src/upgrade_chamber/edits.py`
- [Advisory lookup](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/osv.py): `src/upgrade_chamber/osv.py`

### Isolated execution

- [Container controller](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/runner.py): `src/upgrade_chamber/runner.py`
- [Test attempt](https://github.com/dev-sri67/upgrade-chamber/blob/main/execution/attempt.py): `execution/attempt.py`

### Evidence and state

- [Run persistence](https://github.com/dev-sri67/upgrade-chamber/blob/main/src/upgrade_chamber/storage.py): `src/upgrade_chamber/storage.py`

### Other components

- **Demo user**
- **Browser session**
- **Docker engine**
- **Vultr inference**
- **OSV service**

## Connections

- Demo user → App shell: uses
- App shell → Start view: renders
- App shell → Live run view: renders
- App shell → Result view: renders
- App shell → Session identity: persists identity
- Start view → Browser API client: submits run
- Live run view → Browser API client: polls, cancels
- Result view → Browser API client: loads evidence
- Browser API client → FastAPI service: HTTP requests
- Browser session → Session identity: stores token
- FastAPI service → Run persistence: reads, writes runs
- Run worker → Run persistence: leases, records
- Run worker → Profile catalog: uses profile
- Run worker → Baseline preparation: prepares source
- Run worker → Container controller: runs phases
- Run worker → Repair agent: starts repair
- Repair agent → Edit validation: validates edits
- Run worker → FastAPI service: requests inference
- FastAPI service → Inference transport: dispatches calls
- Inference transport → Vultr inference: sends prompts
- Run worker → Advisory lookup: queries advisories
- Advisory lookup → OSV service: fetches snapshots
- Container controller → Docker engine: controls containers
- Docker engine → Test attempt: runs attempt
- Run worker → Run persistence: stores artifacts