# latchkey-dev/gusset architecture

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

- Interactive diagram: https://gitdiagram.com/latchkey-dev/gusset
- Repository: https://github.com/latchkey-dev/gusset
- Video tour (about a minute): https://gitdiagram.com/latchkey-dev/gusset/video

## Overview

Gusset indexes a repository into a dependency graph, then uses that graph to produce verified impact reports, architecture documentation, and documentation-drift findings. In autonomous mode, events pass through invariant guards and workflows; oracle scores govern the autonomy ladder before scoped actions are taken. The local server exposes graph and run information through a browser UI. The README documents optional tracing and self-healing integrations; their internal wiring is only represented where supported by the sampled source.

Main entry points: [`src/gusset/supervisor/runner.py`](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/runner.py) (Custodian runner), [`src/gusset/cli.py`](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/cli.py) (CLI), [`src/gusset/workflows/impact.py`](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/impact.py) (Impact analysis), [`src/gusset/graph/store.py`](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/store.py) (Dependency graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_graph["Repository graph"]
  node_indexer["Graph indexer<br/>[indexer.py]"]
  node_extract["Code extractor<br/>[extract.py]"]
  node_graphdb[("Dependency graph<br/>[store.py]")]
end

subgraph group_workflows["Upkeep workflows"]
  node_impact["Impact analysis<br/>[impact.py]"]
  node_atlas["Architecture atlas<br/>[atlas.py]"]
  node_docsdrift["Docs drift<br/>[docsdrift.py]"]
  node_seeds["Seed resolution<br/>[seeds.py]"]
end

subgraph group_autonomy["Autonomous supervision"]
  node_oracle["Oracle scoring<br/>[scores.py]"]
  node_supervisor["Custodian runner<br/>[runner.py]"]
  node_ladder["Autonomy ladder<br/>[ladder.py]"]
  node_actions["Scoped actions<br/>[actions.py]"]
end

subgraph group_serve["Local interface"]
  node_server["HTTP server<br/>[server.py]"]
  node_api["Serve API state<br/>[api.py]"]
  node_heartbeat["Live events<br/>[heartbeat.py]"]
  node_browser["Browser UI<br/>[app.js]"]
end

subgraph group_optional["Optional observability"]
  node_probe["PandaProbe tracing<br/>[tracing.py]"]
  node_selfheal["Self-healing<br/>[selfheal.py]"]
end

node_maintainer(("Maintainer"))
node_ci(("CI events"))
node_repo[("Target repository")]
node_cli["CLI<br/>[cli.py]"]
node_model["Anthropic model<br/>[llm.py]"]

node_maintainer -->|"runs commands"| node_cli
node_cli -->|"indexes repo"| node_indexer
node_indexer -->|"extracts symbols"| node_extract
node_indexer -->|"reads source"| node_repo
node_indexer -->|"writes graph"| node_graphdb
node_cli -->|"runs analysis"| node_impact
node_cli -->|"generates docs"| node_atlas
node_cli -->|"checks drift"| node_docsdrift
node_impact -->|"resolves seeds"| node_seeds
node_impact -->|"queries dependencies"| node_graphdb
node_impact -.->|"requests explanations"| node_model
node_atlas -->|"uses graph"| node_graphdb
node_docsdrift -->|"checks references"| node_graphdb
node_ci -->|"dispatches event"| node_supervisor
node_supervisor -->|"runs workflow"| node_impact
node_supervisor -->|"runs workflow"| node_atlas
node_supervisor -->|"runs workflow"| node_docsdrift
node_supervisor -->|"scores run"| node_oracle
node_supervisor -->|"records scores"| node_ladder
node_supervisor -->|"applies allowed action"| node_actions
node_actions -->|"writes artifacts"| node_repo
node_actions -->|"posts PR output"| node_ci
node_cli -->|"starts server"| node_server
node_server -->|"routes requests"| node_api
node_api -->|"reads graph"| node_graphdb
node_server -->|"streams events"| node_heartbeat
node_browser -->|"requests data"| node_server
node_supervisor -.->|"emits traces"| node_probe
node_supervisor -.->|"uses repair harness"| node_selfheal

click node_cli "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/cli.py"
click node_indexer "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/indexer.py"
click node_extract "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/extract.py"
click node_graphdb "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/store.py"
click node_impact "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/impact.py"
click node_atlas "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/atlas.py"
click node_docsdrift "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/docsdrift.py"
click node_seeds "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/seeds.py"
click node_oracle "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/oracle/scores.py"
click node_supervisor "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/runner.py"
click node_ladder "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/ladder.py"
click node_actions "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/actions.py"
click node_model "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/llm.py"
click node_server "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/server.py"
click node_api "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/api.py"
click node_heartbeat "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/heartbeat.py"
click node_browser "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/static/app.js"
click node_probe "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/probe/tracing.py"
click node_selfheal "https://github.com/latchkey-dev/gusset/blob/main/src/gusset/probe/selfheal.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_indexer,node_extract,node_graphdb toneBlue
class node_impact,node_atlas,node_docsdrift,node_seeds,node_repo toneAmber
class node_oracle,node_supervisor,node_ladder,node_actions toneMint
class node_server,node_api,node_heartbeat,node_browser toneRose
class node_probe,node_selfheal,node_maintainer,node_ci,node_model toneIndigo
class node_cli toneTeal
```

## Components

### Repository graph

- [Graph indexer](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/indexer.py): `src/gusset/graph/indexer.py`
- [Code extractor](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/extract.py): `src/gusset/graph/extract.py`
- [Dependency graph](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/graph/store.py): `src/gusset/graph/store.py`

### Upkeep workflows

- [Impact analysis](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/impact.py): `src/gusset/workflows/impact.py`
- [Architecture atlas](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/atlas.py): `src/gusset/workflows/atlas.py`
- [Docs drift](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/docsdrift.py): `src/gusset/workflows/docsdrift.py`
- [Seed resolution](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/workflows/seeds.py): `src/gusset/workflows/seeds.py`

### Autonomous supervision

- [Oracle scoring](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/oracle/scores.py): `src/gusset/oracle/scores.py`
- [Custodian runner](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/runner.py): `src/gusset/supervisor/runner.py`
- [Autonomy ladder](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/ladder.py): `src/gusset/supervisor/ladder.py`
- [Scoped actions](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/supervisor/actions.py): `src/gusset/supervisor/actions.py`

### Local interface

- [HTTP server](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/server.py): `src/gusset/serve/server.py`
- [Serve API state](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/api.py): `src/gusset/serve/api.py`
- [Live events](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/heartbeat.py): `src/gusset/serve/heartbeat.py`
- [Browser UI](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/serve/static/app.js): `src/gusset/serve/static/app.js`

### Optional observability

- [PandaProbe tracing](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/probe/tracing.py): `src/gusset/probe/tracing.py`
- [Self-healing](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/probe/selfheal.py): `src/gusset/probe/selfheal.py`

### Other components

- **Maintainer**
- **CI events**
- **Target repository**
- [CLI](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/cli.py): `src/gusset/cli.py`
- [Anthropic model](https://github.com/latchkey-dev/gusset/blob/main/src/gusset/llm.py): `src/gusset/llm.py`

## Connections

- Maintainer → CLI: runs commands
- CLI → Graph indexer: indexes repo
- Graph indexer → Code extractor: extracts symbols
- Graph indexer → Target repository: reads source
- Graph indexer → Dependency graph: writes graph
- CLI → Impact analysis: runs analysis
- CLI → Architecture atlas: generates docs
- CLI → Docs drift: checks drift
- Impact analysis → Seed resolution: resolves seeds
- Impact analysis → Dependency graph: queries dependencies
- Impact analysis → Anthropic model: requests explanations
- Architecture atlas → Dependency graph: uses graph
- Docs drift → Dependency graph: checks references
- CI events → Custodian runner: dispatches event
- Custodian runner → Impact analysis: runs workflow
- Custodian runner → Architecture atlas: runs workflow
- Custodian runner → Docs drift: runs workflow
- Custodian runner → Oracle scoring: scores run
- Custodian runner → Autonomy ladder: records scores
- Custodian runner → Scoped actions: applies allowed action
- Scoped actions → Target repository: writes artifacts
- Scoped actions → CI events: posts PR output
- CLI → HTTP server: starts server
- HTTP server → Serve API state: routes requests
- Serve API state → Dependency graph: reads graph
- HTTP server → Live events: streams events
- Browser UI → HTTP server: requests data
- Custodian runner → PandaProbe tracing: emits traces
- Custodian runner → Self-healing: uses repair harness