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