# madjagstudios/podium architecture

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

- Interactive diagram: https://gitdiagram.com/madjagstudios/podium
- Repository: https://github.com/madjagstudios/podium

## Overview

Podium is a Claude Code mod for dispatching work to local coding agents and reviewing their results in one pane. The usual flow is a user request or pane action, job dispatch, agent execution, then review and delivery; edits run in a separate worktree by default. Pull requests and multi-ticket sprints are major additional workflows. The graph combines README-documented behavior with sampled imports and calls; several engine capabilities are represented at their exact paths, but unsampled implementation details and links are omitted where evidence is limited.

Main entry points: [`engine/dispatch.js`](https://github.com/madjagstudios/podium/blob/main/engine/dispatch.js) (Job dispatch), [`engine/sprint.js`](https://github.com/madjagstudios/podium/blob/main/engine/sprint.js) (Sprint board and runner), [`engine/pr.js`](https://github.com/madjagstudios/podium/blob/main/engine/pr.js) (Pull request workflow), [`hooks/register.tsx`](https://github.com/madjagstudios/podium/blob/main/hooks/register.tsx) (Pane and hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Claude Code interface"]
  node_modtools["Mod tools<br/>[tools.js]"]
  node_hooks["Pane and hooks<br/>[register.tsx]"]
  node_screens["Pane screens<br/>[screens.tsx]"]
  node_view["Job and sprint view<br/>[view.js]"]
  node_client["Pane client state<br/>[client.js]"]
end

subgraph group_jobs["Job execution"]
  node_cli["Engine CLI<br/>[cli.js]"]
  node_dispatch["Job dispatch<br/>[dispatch.js]"]
  node_adapters["Agent adapters<br/>[registry.js]"]
  node_worktree["Worktree isolation<br/>[worktree.js]"]
  node_jobstore[("Job records<br/>[store.js]")]
  node_settings[("Agent and repo settings<br/>[settings.js]")]
end

subgraph group_delivery["Review and delivery"]
  node_review["Keep or discard<br/>[review.js]"]
  node_changes["Change inspection<br/>[changes.js]"]
  node_pr["Pull request workflow<br/>[pr.js]"]
  node_checks["PR check watching<br/>[ci-steps.js]"]
end

subgraph group_sprints["Sprint coordination"]
  node_sprint["Sprint board and runner<br/>[sprint.js]"]
  node_sprinttext["Sprint prompts and text<br/>[sprint-text.js]"]
end

node_user(("User / Claude"))
node_agent{{"Local agent CLI"}}
node_github{{"GitHub"}}

node_user -->|"requests work"| node_modtools
node_user -->|"uses pane"| node_hooks
node_hooks -->|"registers tools"| node_modtools
node_hooks -->|"renders"| node_screens
node_screens -->|"formats status"| node_view
node_screens -->|"uses pane data"| node_client
node_modtools -.->|"invokes engine"| node_cli
node_cli -->|"dispatches jobs"| node_dispatch
node_dispatch -->|"loads agent"| node_adapters
node_dispatch -->|"prepares copy"| node_worktree
node_dispatch -->|"records job"| node_jobstore
node_dispatch -->|"reads settings"| node_settings
node_dispatch -->|"launches process"| node_agent
node_user -->|"installs agent"| node_agent
node_user -->|"keeps or discards"| node_review
node_review -->|"cleans copy"| node_worktree
node_user -->|"inspects diff"| node_changes
node_user -->|"opens PR"| node_pr
node_pr -->|"creates and merges"| node_github
node_pr -->|"watches checks"| node_checks
node_checks -->|"reads check results"| node_github
node_user -->|"plans sprint"| node_sprint
node_sprint -->|"dispatches task steps"| node_dispatch
node_sprint -->|"builds prompts"| node_sprinttext
node_sprint -->|"opens ticket PR"| node_pr

click node_modtools "https://github.com/madjagstudios/podium/blob/main/mod/tools.js"
click node_hooks "https://github.com/madjagstudios/podium/blob/main/hooks/register.tsx"
click node_screens "https://github.com/madjagstudios/podium/blob/main/hooks/screens.tsx"
click node_view "https://github.com/madjagstudios/podium/blob/main/mod/view.js"
click node_client "https://github.com/madjagstudios/podium/blob/main/mod/client.js"
click node_cli "https://github.com/madjagstudios/podium/blob/main/engine/cli.js"
click node_dispatch "https://github.com/madjagstudios/podium/blob/main/engine/dispatch.js"
click node_adapters "https://github.com/madjagstudios/podium/blob/main/engine/adapters/registry.js"
click node_worktree "https://github.com/madjagstudios/podium/blob/main/engine/worktree.js"
click node_jobstore "https://github.com/madjagstudios/podium/blob/main/engine/store.js"
click node_settings "https://github.com/madjagstudios/podium/blob/main/engine/settings.js"
click node_review "https://github.com/madjagstudios/podium/blob/main/engine/review.js"
click node_changes "https://github.com/madjagstudios/podium/blob/main/engine/changes.js"
click node_pr "https://github.com/madjagstudios/podium/blob/main/engine/pr.js"
click node_checks "https://github.com/madjagstudios/podium/blob/main/engine/ci-steps.js"
click node_sprint "https://github.com/madjagstudios/podium/blob/main/engine/sprint.js"
click node_sprinttext "https://github.com/madjagstudios/podium/blob/main/engine/sprint-text.js"

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_modtools,node_hooks,node_screens,node_view,node_client,node_user toneBlue
class node_cli,node_dispatch,node_adapters,node_worktree,node_jobstore,node_settings toneAmber
class node_review,node_changes,node_pr,node_checks toneMint
class node_sprint,node_sprinttext toneRose
class node_agent,node_github toneIndigo
```

## Components

### Claude Code interface

- [Mod tools](https://github.com/madjagstudios/podium/blob/main/mod/tools.js): `mod/tools.js`
- [Pane and hooks](https://github.com/madjagstudios/podium/blob/main/hooks/register.tsx): `hooks/register.tsx`
- [Pane screens](https://github.com/madjagstudios/podium/blob/main/hooks/screens.tsx): `hooks/screens.tsx`
- [Job and sprint view](https://github.com/madjagstudios/podium/blob/main/mod/view.js): `mod/view.js`
- [Pane client state](https://github.com/madjagstudios/podium/blob/main/mod/client.js): `mod/client.js`

### Job execution

- [Engine CLI](https://github.com/madjagstudios/podium/blob/main/engine/cli.js): `engine/cli.js`
- [Job dispatch](https://github.com/madjagstudios/podium/blob/main/engine/dispatch.js): `engine/dispatch.js`
- [Agent adapters](https://github.com/madjagstudios/podium/blob/main/engine/adapters/registry.js): `engine/adapters/registry.js`
- [Worktree isolation](https://github.com/madjagstudios/podium/blob/main/engine/worktree.js): `engine/worktree.js`
- [Job records](https://github.com/madjagstudios/podium/blob/main/engine/store.js): `engine/store.js`
- [Agent and repo settings](https://github.com/madjagstudios/podium/blob/main/engine/settings.js): `engine/settings.js`

### Review and delivery

- [Keep or discard](https://github.com/madjagstudios/podium/blob/main/engine/review.js): `engine/review.js`
- [Change inspection](https://github.com/madjagstudios/podium/blob/main/engine/changes.js): `engine/changes.js`
- [Pull request workflow](https://github.com/madjagstudios/podium/blob/main/engine/pr.js): `engine/pr.js`
- [PR check watching](https://github.com/madjagstudios/podium/blob/main/engine/ci-steps.js): `engine/ci-steps.js`

### Sprint coordination

- [Sprint board and runner](https://github.com/madjagstudios/podium/blob/main/engine/sprint.js): `engine/sprint.js`
- [Sprint prompts and text](https://github.com/madjagstudios/podium/blob/main/engine/sprint-text.js): `engine/sprint-text.js`

### Other components

- **User / Claude**
- **Local agent CLI**
- **GitHub**

## Connections

- User / Claude → Mod tools: requests work (evidence: `README.md`)
- User / Claude → Pane and hooks: uses pane (evidence: `README.md`)
- Pane and hooks → Mod tools: registers tools (evidence: `hooks/register.tsx`)
- Pane and hooks → Pane screens: renders (evidence: `hooks/register.tsx`)
- Pane screens → Job and sprint view: formats status (evidence: `hooks/screens.tsx`)
- Pane screens → Pane client state: uses pane data (evidence: `hooks/screens.tsx`)
- Mod tools → Engine CLI: invokes engine
- Engine CLI → Job dispatch: dispatches jobs (evidence: `engine/cli.js`)
- Job dispatch → Agent adapters: loads agent (evidence: `engine/dispatch.js`)
- Job dispatch → Worktree isolation: prepares copy (evidence: `engine/dispatch.js`)
- Job dispatch → Job records: records job (evidence: `engine/dispatch.js`)
- Job dispatch → Agent and repo settings: reads settings (evidence: `engine/dispatch.js`)
- Job dispatch → Local agent CLI: launches process (evidence: `engine/dispatch.js`)
- User / Claude → Local agent CLI: installs agent (evidence: `README.md`)
- User / Claude → Keep or discard: keeps or discards (evidence: `README.md`)
- Keep or discard → Worktree isolation: cleans copy (evidence: `engine/review.js`)
- User / Claude → Change inspection: inspects diff (evidence: `README.md`)
- User / Claude → Pull request workflow: opens PR (evidence: `README.md`)
- Pull request workflow → GitHub: creates and merges (evidence: `README.md`)
- Pull request workflow → PR check watching: watches checks (evidence: `engine/ci-steps.js`)
- PR check watching → GitHub: reads check results (evidence: `engine/ci-steps.js`)
- User / Claude → Sprint board and runner: plans sprint (evidence: `README.md`)
- Sprint board and runner → Job dispatch: dispatches task steps (evidence: `engine/sprint.js`)
- Sprint board and runner → Sprint prompts and text: builds prompts (evidence: `engine/sprint.js`)
- Sprint board and runner → Pull request workflow: opens ticket PR (evidence: `engine/sprint.js`)
