# jakezimconnections/incident-trawlers architecture

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

- Interactive diagram: https://gitdiagram.com/jakezimconnections/incident-trawlers
- Repository: https://github.com/jakezimconnections/incident-trawlers

## Overview

Incident-Trawlers is a FastAPI harness for running named LangGraph workflows through one shared Claude agent loop. A client lists workflows or submits a run; the API resolves the workflow, which builds and streams the graph, returns the final answer, and records a trace. The default workflow provides project-inspection tools; the ZIM workflow defines incident-investigation state and currently uses file and shell tools. The graph shows documented wiring only; Cognito, Stripe, and Kibana integrations are described as future tools, not implemented capabilities.

Main entry points: [`app/workflows/default.py`](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/default.py) (Default workflow), [`app/workflows/zim_incident.py`](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/zim_incident.py) (ZIM incident workflow), [`app/core/langgraph/workflow.py`](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/workflow.py) (Workflow runner), [`app/api/v1/runs.py`](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/runs.py) (Run endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_routes["API router<br/>[api.py]"]
  node_run_route["Run endpoint<br/>[runs.py]"]
  node_workflow_route["Workflow listing<br/>[workflows.py]"]
  node_run_contracts["Run contracts<br/>[run.py]"]
end

subgraph group_workflow["Workflow orchestration"]
  node_registry["Workflow registry<br/>[__init__.py]"]
  node_default_workflow["Default workflow<br/>[default.py]"]
  node_zim_workflow["ZIM incident workflow<br/>[zim_incident.py]"]
  node_workflow_runner["Workflow runner<br/>[workflow.py]"]
  node_agent_state["Agent state<br/>[graph.py]"]
end

subgraph group_agent["Agent runtime"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_file_tool["File tools<br/>[read_file.py]"]
  node_shell_tool["Shell tool<br/>[run_shell.py]"]
  node_write_tool["Write tool<br/>[write_file.py]"]
  node_model_service["Claude model<br/>[llm.py]"]
end

subgraph group_observability["Run observability"]
  node_trace_logger["Trace logger<br/>[trace_logger.py]"]
  node_trace_files["Trace files"]
  node_settings["Application settings<br/>[config.py]"]
end

node_client(("API client"))
node_anthropic(("Anthropic API"))

node_client -->|"sends HTTP"| node_fastapi
node_fastapi -->|"mounts routes"| node_routes
node_routes -->|"registers"| node_run_route
node_routes -->|"registers"| node_workflow_route
node_run_route -->|"looks up"| node_registry
node_workflow_route -->|"lists"| node_registry
node_run_route -->|"validates and returns"| node_run_contracts
node_registry -->|"registers"| node_default_workflow
node_registry -->|"registers"| node_zim_workflow
node_run_route -->|"runs workflow"| node_workflow_runner
node_default_workflow -->|"configures"| node_workflow_runner
node_zim_workflow -->|"configures"| node_workflow_runner
node_default_workflow -->|"selects state"| node_agent_state
node_zim_workflow -->|"selects state"| node_agent_state
node_workflow_runner -->|"builds and streams"| node_graph
node_default_workflow -->|"supplies tools"| node_file_tool
node_default_workflow -->|"supplies tools"| node_shell_tool
node_default_workflow -->|"supplies tools"| node_write_tool
node_zim_workflow -->|"supplies tools"| node_file_tool
node_zim_workflow -->|"supplies tools"| node_shell_tool
node_graph -->|"creates model via"| node_model_service
node_model_service -->|"reads defaults"| node_settings
node_model_service -->|"calls model"| node_anthropic
node_workflow_runner -->|"records run"| node_trace_logger
node_trace_logger -->|"writes traces"| node_trace_files
node_trace_logger -->|"reads trace config"| node_settings

click node_fastapi "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/main.py"
click node_routes "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/api.py"
click node_run_route "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/runs.py"
click node_workflow_route "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/workflows.py"
click node_run_contracts "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/schemas/run.py"
click node_registry "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/__init__.py"
click node_default_workflow "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/default.py"
click node_zim_workflow "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/zim_incident.py"
click node_workflow_runner "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/workflow.py"
click node_agent_state "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/schemas/graph.py"
click node_graph "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/graph.py"
click node_file_tool "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/read_file.py"
click node_shell_tool "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/run_shell.py"
click node_write_tool "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/write_file.py"
click node_model_service "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/services/llm.py"
click node_trace_logger "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/services/trace_logger.py"
click node_settings "https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/config.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_fastapi,node_routes,node_run_route,node_workflow_route,node_run_contracts,node_client toneBlue
class node_registry,node_default_workflow,node_zim_workflow,node_workflow_runner,node_agent_state toneAmber
class node_graph,node_file_tool,node_shell_tool,node_write_tool,node_model_service,node_anthropic toneMint
class node_trace_logger,node_trace_files,node_settings toneRose
```

## Components

### HTTP API

- [FastAPI app](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/main.py): `app/main.py`
- [API router](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/api.py): `app/api/v1/api.py`
- [Run endpoint](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/runs.py): `app/api/v1/runs.py`
- [Workflow listing](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/api/v1/workflows.py): `app/api/v1/workflows.py`
- [Run contracts](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/schemas/run.py): `app/schemas/run.py`

### Workflow orchestration

- [Workflow registry](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/__init__.py): `app/workflows/__init__.py`
- [Default workflow](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/default.py): `app/workflows/default.py`
- [ZIM incident workflow](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/workflows/zim_incident.py): `app/workflows/zim_incident.py`
- [Workflow runner](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/workflow.py): `app/core/langgraph/workflow.py`
- [Agent state](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/schemas/graph.py): `app/schemas/graph.py`

### Agent runtime

- [Agent graph](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/graph.py): `app/core/langgraph/graph.py`
- [File tools](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/read_file.py): `app/core/langgraph/tools/read_file.py`
- [Shell tool](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/run_shell.py): `app/core/langgraph/tools/run_shell.py`
- [Write tool](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/langgraph/tools/write_file.py): `app/core/langgraph/tools/write_file.py`
- [Claude model](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/services/llm.py): `app/services/llm.py`

### Run observability

- [Trace logger](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/services/trace_logger.py): `app/services/trace_logger.py`
- **Trace files**
- [Application settings](https://github.com/jakezimconnections/incident-trawlers/blob/main/app/core/config.py): `app/core/config.py`

### Other components

- **API client**
- **Anthropic API**

## Connections

- API client → FastAPI app: sends HTTP (evidence: `README.md`)
- FastAPI app → API router: mounts routes (evidence: `app/main.py`)
- API router → Run endpoint: registers (evidence: `app/api/v1/api.py`)
- API router → Workflow listing: registers (evidence: `app/api/v1/api.py`)
- Run endpoint → Workflow registry: looks up (evidence: `app/api/v1/runs.py`)
- Workflow listing → Workflow registry: lists (evidence: `app/api/v1/workflows.py`)
- Run endpoint → Run contracts: validates and returns (evidence: `app/api/v1/runs.py`)
- Workflow registry → Default workflow: registers (evidence: `app/workflows/__init__.py`)
- Workflow registry → ZIM incident workflow: registers (evidence: `app/workflows/__init__.py`)
- Run endpoint → Workflow runner: runs workflow (evidence: `app/api/v1/runs.py`)
- Default workflow → Workflow runner: configures (evidence: `app/workflows/default.py`)
- ZIM incident workflow → Workflow runner: configures (evidence: `app/workflows/zim_incident.py`)
- Default workflow → Agent state: selects state (evidence: `app/workflows/default.py`)
- ZIM incident workflow → Agent state: selects state (evidence: `app/workflows/zim_incident.py`)
- Workflow runner → Agent graph: builds and streams (evidence: `app/core/langgraph/workflow.py`)
- Default workflow → File tools: supplies tools (evidence: `app/workflows/default.py`)
- Default workflow → Shell tool: supplies tools (evidence: `app/workflows/default.py`)
- Default workflow → Write tool: supplies tools (evidence: `app/workflows/default.py`)
- ZIM incident workflow → File tools: supplies tools (evidence: `app/workflows/zim_incident.py`)
- ZIM incident workflow → Shell tool: supplies tools (evidence: `app/workflows/zim_incident.py`)
- Agent graph → Claude model: creates model via (evidence: `app/core/langgraph/graph.py`)
- Claude model → Application settings: reads defaults (evidence: `app/services/llm.py`)
- Claude model → Anthropic API: calls model (evidence: `app/services/llm.py`)
- Workflow runner → Trace logger: records run (evidence: `app/core/langgraph/workflow.py`)
- Trace logger → Trace files: writes traces (evidence: `app/services/trace_logger.py`)
- Trace logger → Application settings: reads trace config (evidence: `app/services/trace_logger.py`)
