# ocanphys/launchpad architecture

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

- Interactive diagram: https://gitdiagram.com/ocanphys/launchpad
- Repository: https://github.com/ocanphys/launchpad
- Video tour (about a minute): https://gitdiagram.com/ocanphys/launchpad/video

## Overview

Launchpad is a Modal-backed run and job orchestrator. Users seed run configuration, inspect readiness in the dashboard or launch a job, and the launcher checks dependencies and grants a per-run lease before dispatching a worker. Jobs execute, record logs and completion artifacts, and publish volume writes on commit; the dashboard reads run state and lease/heartbeat status. The volume is the durable source of truth, with Modal Dicts tracking leases and heartbeats. The README documents ETL and job behavior; some main.py wiring is unsampled, so uncertain call links are omitted.

Main entry points: [`main.py`](https://github.com/ocanphys/launchpad/blob/main/main.py) (Modal app and routes), [`jobs.py`](https://github.com/ocanphys/launchpad/blob/main/jobs.py) (Job classes), [`runtime.py`](https://github.com/ocanphys/launchpad/blob/main/runtime.py) (Worker lifecycle), [`web/app.js`](https://github.com/ocanphys/launchpad/blob/main/web/app.js) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Run setup"]
  node_config_schema["Run config schema<br/>[run_config.py]"]
  node_config_push["Config seeding<br/>[push_config.py]"]
end

subgraph group_control["Launch and state"]
  node_web_ui["Dashboard UI<br/>[app.js]"]
  node_web_render["Dashboard rendering<br/>[render.js]"]
  node_web_dom["DOM builder<br/>[el.js]"]
  node_orchestrator["Modal app and routes<br/>[main.py]"]
end

subgraph group_execution["Job execution"]
  node_job_registry["Job classes<br/>[jobs.py]"]
  node_etl_workflow["ETL workflow"]
  node_worker_scope["Worker lifecycle<br/>[runtime.py]"]
  node_lease_protocol["Lease checks<br/>[lease_protocol.py]"]
  node_call_logs["Call logging<br/>[logs.py]"]
end

subgraph group_persistence["Runtime state"]
  node_run_volume[("Runs volume")]
  node_lease_dict[("Lease Dict")]
  node_heartbeat_dict[("Heartbeat Dict")]
end

node_user(("Run operator"))
node_modal_platform["Modal platform"]

node_user -->|"seed config"| node_config_push
node_config_push -->|"validate"| node_config_schema
node_config_push -->|"write config"| node_run_volume
node_user -->|"open dashboard"| node_web_ui
node_web_ui -->|"poll state"| node_orchestrator
node_web_ui -->|"render state"| node_web_render
node_web_render -->|"build elements"| node_web_dom
node_web_ui -->|"request launch"| node_orchestrator
node_orchestrator -->|"read run data"| node_run_volume
node_orchestrator -->|"read or grant"| node_lease_dict
node_orchestrator -->|"read beats"| node_heartbeat_dict
node_orchestrator -->|"check readiness"| node_job_registry
node_orchestrator -->|"spawn worker"| node_modal_platform
node_modal_platform -->|"invoke job"| node_job_registry
node_job_registry -->|"read config and artifacts"| node_run_volume
node_job_registry -->|"use worker context"| node_worker_scope
node_job_registry -.->|"run ETL"| node_etl_workflow
node_worker_scope -->|"confirm ownership"| node_lease_protocol
node_lease_protocol -->|"check grant"| node_lease_dict
node_worker_scope -->|"publish heartbeat"| node_heartbeat_dict
node_worker_scope -->|"create call log"| node_call_logs
node_worker_scope -->|"reload and commit"| node_run_volume
node_job_registry -->|"write artifact and logs"| node_run_volume

click node_config_schema "https://github.com/ocanphys/launchpad/blob/main/run_config.py"
click node_config_push "https://github.com/ocanphys/launchpad/blob/main/push_config.py"
click node_web_ui "https://github.com/ocanphys/launchpad/blob/main/web/app.js"
click node_web_render "https://github.com/ocanphys/launchpad/blob/main/web/render.js"
click node_web_dom "https://github.com/ocanphys/launchpad/blob/main/web/el.js"
click node_orchestrator "https://github.com/ocanphys/launchpad/blob/main/main.py"
click node_job_registry "https://github.com/ocanphys/launchpad/blob/main/jobs.py"
click node_etl_workflow "https://github.com/ocanphys/launchpad/tree/main/etl"
click node_worker_scope "https://github.com/ocanphys/launchpad/blob/main/runtime.py"
click node_lease_protocol "https://github.com/ocanphys/launchpad/blob/main/lease_protocol.py"
click node_call_logs "https://github.com/ocanphys/launchpad/blob/main/logs.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_config_schema,node_config_push toneBlue
class node_web_ui,node_web_render,node_web_dom,node_orchestrator toneAmber
class node_job_registry,node_etl_workflow,node_worker_scope,node_lease_protocol,node_call_logs toneMint
class node_run_volume,node_lease_dict,node_heartbeat_dict toneRose
class node_user,node_modal_platform toneIndigo
```

## Components

### Run setup

- [Run config schema](https://github.com/ocanphys/launchpad/blob/main/run_config.py): `run_config.py`
- [Config seeding](https://github.com/ocanphys/launchpad/blob/main/push_config.py): `push_config.py`

### Launch and state

- [Dashboard UI](https://github.com/ocanphys/launchpad/blob/main/web/app.js): `web/app.js`
- [Dashboard rendering](https://github.com/ocanphys/launchpad/blob/main/web/render.js): `web/render.js`
- [DOM builder](https://github.com/ocanphys/launchpad/blob/main/web/el.js): `web/el.js`
- [Modal app and routes](https://github.com/ocanphys/launchpad/blob/main/main.py): `main.py`

### Job execution

- [Job classes](https://github.com/ocanphys/launchpad/blob/main/jobs.py): `jobs.py`
- [ETL workflow](https://github.com/ocanphys/launchpad/tree/main/etl): `etl`
- [Worker lifecycle](https://github.com/ocanphys/launchpad/blob/main/runtime.py): `runtime.py`
- [Lease checks](https://github.com/ocanphys/launchpad/blob/main/lease_protocol.py): `lease_protocol.py`
- [Call logging](https://github.com/ocanphys/launchpad/blob/main/logs.py): `logs.py`

### Runtime state

- **Runs volume**
- **Lease Dict**
- **Heartbeat Dict**

### Other components

- **Run operator**
- **Modal platform**

## Connections

- Run operator → Config seeding: seed config
- Config seeding → Run config schema: validate
- Config seeding → Runs volume: write config
- Run operator → Dashboard UI: open dashboard
- Dashboard UI → Modal app and routes: poll state
- Dashboard UI → Dashboard rendering: render state
- Dashboard rendering → DOM builder: build elements
- Dashboard UI → Modal app and routes: request launch
- Modal app and routes → Runs volume: read run data
- Modal app and routes → Lease Dict: read or grant
- Modal app and routes → Heartbeat Dict: read beats
- Modal app and routes → Job classes: check readiness
- Modal app and routes → Modal platform: spawn worker
- Modal platform → Job classes: invoke job
- Job classes → Runs volume: read config and artifacts
- Job classes → Worker lifecycle: use worker context
- Job classes → ETL workflow: run ETL
- Worker lifecycle → Lease checks: confirm ownership
- Lease checks → Lease Dict: check grant
- Worker lifecycle → Heartbeat Dict: publish heartbeat
- Worker lifecycle → Call logging: create call log
- Worker lifecycle → Runs volume: reload and commit
- Job classes → Runs volume: write artifact and logs