# reseaxch/podo architecture

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

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

## Overview

Podo detects software incidents from telemetry and CI evidence, builds causal context, supports read-only investigation, then gates tested remediation and delivery on explicit approvals. Operators use the dashboard or terminal clients against the shared Core API. The graph emphasizes the documented vertical workflow and major integrations; several runtime modules are represented by their exact tree paths because their source was not sampled.

Main entry points: [`apps/core/src/app.ts`](https://github.com/reseaxch/podo/blob/main/apps/core/src/app.ts) (Core API), [`apps/core/src/modules/incidents/incident-monitor.ts`](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/incidents/incident-monitor.ts) (Incident monitor), [`packages/client/src/index.ts`](https://github.com/reseaxch/podo/blob/main/packages/client/src/index.ts) (Typed client), [`apps/core/src/modules/remediation/incident-remediation.ts`](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/incident-remediation.ts) (Remediation workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Operator clients"]
  node_dashboard["Dashboard"]
  node_cli["CLI<br/>[index.ts]"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_client["Typed client<br/>[index.ts]"]
end

subgraph group_core["Core workflows"]
  node_coreapi["Core API<br/>[app.ts]"]
  node_monitor["Incident monitor"]
  node_telemetry["Telemetry intake<br/>[index.ts]"]
  node_registry["Incident registry"]
  node_graph[("System graph<br/>[in-memory-graph.ts]")]
  node_causal["Causal analysis"]
  node_investigation["Investigation"]
  node_diagnosis["Evidence diagnosis<br/>[diagnosis.ts]"]
  node_audit["Audit trail<br/>[incident-audit.ts]"]
end

subgraph group_runtime["Execution and delivery"]
  node_remediation["Remediation workflow"]
  node_executor["Worktree executor"]
  node_codex["Codex runtime"]
  node_delivery["PR delivery"]
end

subgraph group_integrations["Evidence integrations"]
  node_github["GitHub adapters<br/>[index.ts]"]
  node_otel["OTel replay<br/>[index.ts]"]
  node_graphify["Graphify adapter<br/>[index.ts]"]
  node_actions["GitHub Actions"]
end

node_operator(("Operator"))
node_signals(("Telemetry signals"))

node_operator -->|"operates"| node_dashboard
node_operator -->|"runs commands"| node_cli
node_operator -->|"operates"| node_tui
node_dashboard -->|"uses"| node_client
node_cli -->|"uses"| node_client
node_tui -->|"uses"| node_client
node_client -->|"calls API"| node_coreapi
node_signals -.->|"provide telemetry"| node_otel
node_otel -.->|"replays events"| node_telemetry
node_telemetry -->|"feeds detection"| node_monitor
node_monitor -->|"reads context"| node_graph
node_monitor -->|"builds causal path"| node_causal
node_actions -->|"registers failures"| node_registry
node_github -.->|"supplies run evidence"| node_actions
node_graphify -.->|"populates graph"| node_graph
node_coreapi -->|"routes incidents"| node_monitor
node_coreapi -->|"starts investigation"| node_investigation
node_investigation -->|"grounds diagnosis"| node_diagnosis
node_coreapi -->|"starts remediation"| node_remediation
node_remediation -->|"requests patch"| node_codex
node_remediation -->|"tests patch"| node_executor
node_coreapi -->|"starts delivery"| node_delivery
node_delivery -.->|"publishes PR"| node_github
node_coreapi -->|"reads audit"| node_audit

click node_dashboard "https://github.com/reseaxch/podo/blob/main/apps/dashboard/app/components/production-incident-workspace.tsx"
click node_cli "https://github.com/reseaxch/podo/blob/main/apps/cli/src/index.ts"
click node_tui "https://github.com/reseaxch/podo/blob/main/apps/tui/src/app.tsx"
click node_client "https://github.com/reseaxch/podo/blob/main/packages/client/src/index.ts"
click node_coreapi "https://github.com/reseaxch/podo/blob/main/apps/core/src/app.ts"
click node_monitor "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/incidents/incident-monitor.ts"
click node_telemetry "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/telemetry/index.ts"
click node_registry "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/incidents/build-incident-registry.ts"
click node_graph "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/graph/in-memory-graph.ts"
click node_causal "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/graph/incident-causal-path.ts"
click node_investigation "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/investigation/incident-investigation.ts"
click node_diagnosis "https://github.com/reseaxch/podo/blob/main/packages/domain/src/diagnosis.ts"
click node_remediation "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/incident-remediation.ts"
click node_executor "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/local-worktree-remediation-executor.ts"
click node_codex "https://github.com/reseaxch/podo/blob/main/apps/core/src/runtime/production-codex-runtime.ts"
click node_delivery "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/incident-delivery.ts"
click node_audit "https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/audit/incident-audit.ts"
click node_github "https://github.com/reseaxch/podo/blob/main/plugins/github/src/index.ts"
click node_otel "https://github.com/reseaxch/podo/blob/main/plugins/otel-replay/src/index.ts"
click node_graphify "https://github.com/reseaxch/podo/blob/main/plugins/graphify/src/index.ts"
click node_actions "https://github.com/reseaxch/podo/blob/main/apps/core/src/runtime/production-github-actions.ts"

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_dashboard,node_cli,node_tui,node_client toneBlue
class node_coreapi,node_monitor,node_telemetry,node_registry,node_graph,node_causal,node_investigation,node_diagnosis,node_audit toneAmber
class node_remediation,node_executor,node_codex,node_delivery toneMint
class node_github,node_otel,node_graphify,node_actions toneRose
class node_operator,node_signals toneIndigo
```

## Components

### Operator clients

- [Dashboard](https://github.com/reseaxch/podo/blob/main/apps/dashboard/app/components/production-incident-workspace.tsx): `apps/dashboard/app/components/production-incident-workspace.tsx`
- [CLI](https://github.com/reseaxch/podo/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [Terminal UI](https://github.com/reseaxch/podo/blob/main/apps/tui/src/app.tsx): `apps/tui/src/app.tsx`
- [Typed client](https://github.com/reseaxch/podo/blob/main/packages/client/src/index.ts): `packages/client/src/index.ts`

### Core workflows

- [Core API](https://github.com/reseaxch/podo/blob/main/apps/core/src/app.ts): `apps/core/src/app.ts`
- [Incident monitor](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/incidents/incident-monitor.ts): `apps/core/src/modules/incidents/incident-monitor.ts`
- [Telemetry intake](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/telemetry/index.ts): `apps/core/src/modules/telemetry/index.ts`
- [Incident registry](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/incidents/build-incident-registry.ts): `apps/core/src/modules/incidents/build-incident-registry.ts`
- [System graph](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/graph/in-memory-graph.ts): `apps/core/src/modules/graph/in-memory-graph.ts`
- [Causal analysis](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/graph/incident-causal-path.ts): `apps/core/src/modules/graph/incident-causal-path.ts`
- [Investigation](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/investigation/incident-investigation.ts): `apps/core/src/modules/investigation/incident-investigation.ts`
- [Evidence diagnosis](https://github.com/reseaxch/podo/blob/main/packages/domain/src/diagnosis.ts): `packages/domain/src/diagnosis.ts`
- [Audit trail](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/audit/incident-audit.ts): `apps/core/src/modules/audit/incident-audit.ts`

### Execution and delivery

- [Remediation workflow](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/incident-remediation.ts): `apps/core/src/modules/remediation/incident-remediation.ts`
- [Worktree executor](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/local-worktree-remediation-executor.ts): `apps/core/src/modules/remediation/local-worktree-remediation-executor.ts`
- [Codex runtime](https://github.com/reseaxch/podo/blob/main/apps/core/src/runtime/production-codex-runtime.ts): `apps/core/src/runtime/production-codex-runtime.ts`
- [PR delivery](https://github.com/reseaxch/podo/blob/main/apps/core/src/modules/remediation/incident-delivery.ts): `apps/core/src/modules/remediation/incident-delivery.ts`

### Evidence integrations

- [GitHub adapters](https://github.com/reseaxch/podo/blob/main/plugins/github/src/index.ts): `plugins/github/src/index.ts`
- [OTel replay](https://github.com/reseaxch/podo/blob/main/plugins/otel-replay/src/index.ts): `plugins/otel-replay/src/index.ts`
- [Graphify adapter](https://github.com/reseaxch/podo/blob/main/plugins/graphify/src/index.ts): `plugins/graphify/src/index.ts`
- [GitHub Actions](https://github.com/reseaxch/podo/blob/main/apps/core/src/runtime/production-github-actions.ts): `apps/core/src/runtime/production-github-actions.ts`

### Other components

- **Operator**
- **Telemetry signals**

## Connections

- Operator → Dashboard: operates
- Operator → CLI: runs commands
- Operator → Terminal UI: operates
- Dashboard → Typed client: uses
- CLI → Typed client: uses
- Terminal UI → Typed client: uses
- Typed client → Core API: calls API
- Telemetry signals → OTel replay: provide telemetry
- OTel replay → Telemetry intake: replays events
- Telemetry intake → Incident monitor: feeds detection
- Incident monitor → System graph: reads context
- Incident monitor → Causal analysis: builds causal path
- GitHub Actions → Incident registry: registers failures
- GitHub adapters → GitHub Actions: supplies run evidence
- Graphify adapter → System graph: populates graph
- Core API → Incident monitor: routes incidents
- Core API → Investigation: starts investigation
- Investigation → Evidence diagnosis: grounds diagnosis
- Core API → Remediation workflow: starts remediation
- Remediation workflow → Codex runtime: requests patch
- Remediation workflow → Worktree executor: tests patch
- Core API → PR delivery: starts delivery
- PR delivery → GitHub adapters: publishes PR
- Core API → Audit trail: reads audit