# vinceklw/suture architecture

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

- Interactive diagram: https://gitdiagram.com/vinceklw/suture
- Repository: https://github.com/vinceklw/suture

## Overview

suture is a crash-resilient incident-recovery agent. An incident or operator starts a campaign; its playbook materializes dependent actions, and workers execute, verify, and recover them through a fenced MongoDB ledger. Adapters carry out AWS, GitHub, and notification effects. Separate product branches handle CI-failure fixes and verified-experience recall, field-rename recovery, live progress, proof, and retrospectives. The graph follows README-described behavior and shown source relationships; unsampled subsystems are represented only where documented, so some links are documented rather than verified from implementation excerpts.

Main entry points: [`api/main.py`](https://github.com/vinceklw/suture/blob/main/api/main.py) (API router), [`engine/db.py`](https://github.com/vinceklw/suture/blob/main/engine/db.py) (MongoDB ledger), [`engine/adapter.py`](https://github.com/vinceklw/suture/blob/main/engine/adapter.py) (Adapter registry), [`engine/executor.py`](https://github.com/vinceklw/suture/blob/main/engine/executor.py) (Action executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Incident ingress"]
  node_webhooks["CI webhook<br/>[webhooks.py]"]
  node_chaos["Chaos controls<br/>[chaos.py]"]
  node_api["API router<br/>[main.py]"]
end

subgraph group_runtime["Recovery runtime"]
  node_campaigns["Campaign records<br/>[campaigns.py]"]
  node_playbooks["Playbook runner<br/>[playbook.py]"]
  node_worker["Worker service<br/>[worker.py]"]
  node_executor["Action executor<br/>[executor.py]"]
  node_state["Fenced state<br/>[state.py]"]
  node_reconciler["Crash reconciler<br/>[reconciler.py]"]
  node_ledger[("MongoDB ledger<br/>[db.py]")]
end

subgraph group_integrations["External effects"]
  node_adapter_registry["Adapter registry<br/>[adapter.py]"]
  node_aws["AWS key rotation<br/>[aws_iam.py]"]
  node_github_pr["GitHub PR and CI<br/>[github_pr.py]"]
  node_github_real["GitHub access<br/>[github_real.py]"]
  node_notify["Email notification<br/>[notify.py]"]
end

subgraph group_learning["Recovery learning"]
  node_experience_hooks["Experience hooks<br/>[engine_hooks.py]"]
  node_experience_search["Verified recall<br/>[index.py]"]
  node_experience_embed["Text embeddings<br/>[embed.py]"]
  node_promotion["Experience promotion<br/>[promote.py]"]
  node_mapping["Field mapping<br/>[mapping.py]"]
  node_model_retro["Retro analysis model<br/>[retro.py]"]
end

subgraph group_observability["Run observability"]
  node_dashboard["Live dashboard<br/>[dashboard.py]"]
  node_proof["Run proof view<br/>[proof.py]"]
  node_retro["Incident retrospective<br/>[retro.py]"]
end

node_github_event(("GitHub CI event"))
node_operator(("Operator"))
node_browser(("Dashboard user"))
node_aws_service{{"AWS"}}
node_github_service{{"GitHub"}}
node_smtp{{"Mail service"}}
node_voyage{{"Voyage AI"}}
node_claude{{"Claude"}}

node_github_event -->|"sends event"| node_webhooks
node_webhooks -->|"starts campaign"| node_campaigns
node_operator -->|"triggers controls"| node_chaos
node_chaos -->|"runs campaign"| node_playbooks
node_api -->|"routes requests"| node_webhooks
node_api -->|"routes requests"| node_chaos
node_api -->|"routes requests"| node_dashboard
node_api -->|"routes requests"| node_proof
node_api -->|"routes requests"| node_retro
node_campaigns -->|"stores campaigns"| node_ledger
node_worker -->|"runs campaign"| node_playbooks
node_worker -->|"starts recovery"| node_reconciler
node_playbooks -->|"drives actions"| node_executor
node_executor -->|"gets adapter"| node_adapter_registry
node_executor -->|"transitions actions"| node_state
node_state -->|"fenced writes"| node_ledger
node_reconciler -->|"recovers actions"| node_executor
node_aws -.->|"rotates keys"| node_aws_service
node_github_pr -.->|"opens and checks PRs"| node_github_service
node_github_real -.->|"accesses repositories"| node_github_service
node_notify -.->|"sends email"| node_smtp
node_adapter_registry -.->|"dispatches actions"| node_aws
node_adapter_registry -->|"dispatches actions"| node_github_pr
node_adapter_registry -.->|"dispatches actions"| node_notify
node_experience_hooks -->|"recalls fixes"| node_experience_search
node_experience_search -->|"embeds query"| node_experience_embed
node_experience_embed -.->|"creates embeddings"| node_voyage
node_experience_hooks -->|"handles unknowns"| node_mapping
node_mapping -.->|"proposes mapping"| node_claude
node_experience_hooks -->|"promotes verified fixes"| node_promotion
node_promotion -->|"commits experience"| node_ledger
node_dashboard -->|"streams changes"| node_ledger
node_proof -->|"reads transitions"| node_ledger
node_retro -->|"builds incident facts"| node_ledger
node_retro -->|"requests analysis"| node_model_retro
node_browser -.->|"views progress"| node_dashboard
node_browser -.->|"views proof"| node_proof

click node_webhooks "https://github.com/vinceklw/suture/blob/main/api/webhooks.py"
click node_chaos "https://github.com/vinceklw/suture/blob/main/api/chaos.py"
click node_api "https://github.com/vinceklw/suture/blob/main/api/main.py"
click node_campaigns "https://github.com/vinceklw/suture/blob/main/engine/campaigns.py"
click node_playbooks "https://github.com/vinceklw/suture/blob/main/engine/playbook.py"
click node_worker "https://github.com/vinceklw/suture/blob/main/engine/worker.py"
click node_executor "https://github.com/vinceklw/suture/blob/main/engine/executor.py"
click node_state "https://github.com/vinceklw/suture/blob/main/engine/state.py"
click node_reconciler "https://github.com/vinceklw/suture/blob/main/engine/reconciler.py"
click node_ledger "https://github.com/vinceklw/suture/blob/main/engine/db.py"
click node_adapter_registry "https://github.com/vinceklw/suture/blob/main/engine/adapter.py"
click node_aws "https://github.com/vinceklw/suture/blob/main/adapters/aws_iam.py"
click node_github_pr "https://github.com/vinceklw/suture/blob/main/adapters/github_pr.py"
click node_github_real "https://github.com/vinceklw/suture/blob/main/adapters/github_real.py"
click node_notify "https://github.com/vinceklw/suture/blob/main/adapters/notify.py"
click node_experience_hooks "https://github.com/vinceklw/suture/blob/main/experiences/engine_hooks.py"
click node_experience_search "https://github.com/vinceklw/suture/blob/main/experiences/index.py"
click node_experience_embed "https://github.com/vinceklw/suture/blob/main/experiences/embed.py"
click node_promotion "https://github.com/vinceklw/suture/blob/main/experiences/promote.py"
click node_mapping "https://github.com/vinceklw/suture/blob/main/model/mapping.py"
click node_model_retro "https://github.com/vinceklw/suture/blob/main/model/retro.py"
click node_dashboard "https://github.com/vinceklw/suture/blob/main/api/dashboard.py"
click node_proof "https://github.com/vinceklw/suture/blob/main/api/proof.py"
click node_retro "https://github.com/vinceklw/suture/blob/main/api/retro.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_webhooks,node_chaos,node_api,node_browser toneBlue
class node_campaigns,node_playbooks,node_worker,node_executor,node_state,node_reconciler,node_ledger toneAmber
class node_adapter_registry,node_aws,node_github_pr,node_github_real,node_notify toneMint
class node_experience_hooks,node_experience_search,node_experience_embed,node_promotion,node_mapping,node_model_retro toneRose
class node_dashboard,node_proof,node_retro,node_github_event,node_operator,node_aws_service,node_github_service,node_smtp,node_voyage,node_claude toneIndigo
```

## Components

### Incident ingress

- [CI webhook](https://github.com/vinceklw/suture/blob/main/api/webhooks.py): `api/webhooks.py`
- [Chaos controls](https://github.com/vinceklw/suture/blob/main/api/chaos.py): `api/chaos.py`
- [API router](https://github.com/vinceklw/suture/blob/main/api/main.py): `api/main.py`

### Recovery runtime

- [Campaign records](https://github.com/vinceklw/suture/blob/main/engine/campaigns.py): `engine/campaigns.py`
- [Playbook runner](https://github.com/vinceklw/suture/blob/main/engine/playbook.py): `engine/playbook.py`
- [Worker service](https://github.com/vinceklw/suture/blob/main/engine/worker.py): `engine/worker.py`
- [Action executor](https://github.com/vinceklw/suture/blob/main/engine/executor.py): `engine/executor.py`
- [Fenced state](https://github.com/vinceklw/suture/blob/main/engine/state.py): `engine/state.py`
- [Crash reconciler](https://github.com/vinceklw/suture/blob/main/engine/reconciler.py): `engine/reconciler.py`
- [MongoDB ledger](https://github.com/vinceklw/suture/blob/main/engine/db.py): `engine/db.py`

### External effects

- [Adapter registry](https://github.com/vinceklw/suture/blob/main/engine/adapter.py): `engine/adapter.py`
- [AWS key rotation](https://github.com/vinceklw/suture/blob/main/adapters/aws_iam.py): `adapters/aws_iam.py`
- [GitHub PR and CI](https://github.com/vinceklw/suture/blob/main/adapters/github_pr.py): `adapters/github_pr.py`
- [GitHub access](https://github.com/vinceklw/suture/blob/main/adapters/github_real.py): `adapters/github_real.py`
- [Email notification](https://github.com/vinceklw/suture/blob/main/adapters/notify.py): `adapters/notify.py`

### Recovery learning

- [Experience hooks](https://github.com/vinceklw/suture/blob/main/experiences/engine_hooks.py): `experiences/engine_hooks.py`
- [Verified recall](https://github.com/vinceklw/suture/blob/main/experiences/index.py): `experiences/index.py`
- [Text embeddings](https://github.com/vinceklw/suture/blob/main/experiences/embed.py): `experiences/embed.py`
- [Experience promotion](https://github.com/vinceklw/suture/blob/main/experiences/promote.py): `experiences/promote.py`
- [Field mapping](https://github.com/vinceklw/suture/blob/main/model/mapping.py): `model/mapping.py`
- [Retro analysis model](https://github.com/vinceklw/suture/blob/main/model/retro.py): `model/retro.py`

### Run observability

- [Live dashboard](https://github.com/vinceklw/suture/blob/main/api/dashboard.py): `api/dashboard.py`
- [Run proof view](https://github.com/vinceklw/suture/blob/main/api/proof.py): `api/proof.py`
- [Incident retrospective](https://github.com/vinceklw/suture/blob/main/api/retro.py): `api/retro.py`

### Other components

- **GitHub CI event**
- **Operator**
- **Dashboard user**
- **AWS**
- **GitHub**
- **Mail service**
- **Voyage AI**
- **Claude**

## Connections

- GitHub CI event → CI webhook: sends event (evidence: `api/webhooks.py`)
- CI webhook → Campaign records: starts campaign (evidence: `api/webhooks.py`)
- Operator → Chaos controls: triggers controls (evidence: `api/chaos.py`)
- Chaos controls → Playbook runner: runs campaign (evidence: `api/chaos.py`)
- API router → CI webhook: routes requests (evidence: `api/main.py`)
- API router → Chaos controls: routes requests (evidence: `api/main.py`)
- API router → Live dashboard: routes requests (evidence: `api/main.py`)
- API router → Run proof view: routes requests (evidence: `api/main.py`)
- API router → Incident retrospective: routes requests (evidence: `api/main.py`)
- Campaign records → MongoDB ledger: stores campaigns (evidence: `engine/campaigns.py`)
- Worker service → Playbook runner: runs campaign (evidence: `engine/worker.py`)
- Worker service → Crash reconciler: starts recovery (evidence: `engine/worker.py`)
- Playbook runner → Action executor: drives actions (evidence: `engine/playbook.py`)
- Action executor → Adapter registry: gets adapter (evidence: `engine/executor.py`)
- Action executor → Fenced state: transitions actions (evidence: `engine/executor.py`)
- Fenced state → MongoDB ledger: fenced writes (evidence: `engine/state.py`)
- Crash reconciler → Action executor: recovers actions (evidence: `engine/reconciler.py`)
- AWS key rotation → AWS: rotates keys (evidence: `README.md`)
- GitHub PR and CI → GitHub: opens and checks PRs (evidence: `README.md`)
- GitHub access → GitHub: accesses repositories (evidence: `README.md`)
- Email notification → Mail service: sends email (evidence: `README.md`)
- Adapter registry → AWS key rotation: dispatches actions (evidence: `adapters/aws_iam.py`)
- Adapter registry → GitHub PR and CI: dispatches actions (evidence: `adapters/github_pr.py`)
- Adapter registry → Email notification: dispatches actions (evidence: `adapters/notify.py`)
- Experience hooks → Verified recall: recalls fixes (evidence: `experiences/engine_hooks.py`)
- Verified recall → Text embeddings: embeds query (evidence: `experiences/index.py`)
- Text embeddings → Voyage AI: creates embeddings (evidence: `README.md`)
- Experience hooks → Field mapping: handles unknowns (evidence: `experiences/engine_hooks.py`)
- Field mapping → Claude: proposes mapping (evidence: `README.md`)
- Experience hooks → Experience promotion: promotes verified fixes (evidence: `experiences/engine_hooks.py`)
- Experience promotion → MongoDB ledger: commits experience (evidence: `experiences/promote.py`)
- Live dashboard → MongoDB ledger: streams changes (evidence: `api/dashboard.py`)
- Run proof view → MongoDB ledger: reads transitions (evidence: `api/proof.py`)
- Incident retrospective → MongoDB ledger: builds incident facts (evidence: `api/retro.py`)
- Incident retrospective → Retro analysis model: requests analysis (evidence: `api/retro.py`)
- Dashboard user → Live dashboard: views progress (evidence: `README.md`)
- Dashboard user → Run proof view: views proof (evidence: `README.md`)
