# 299710583/autoflow architecture

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

- Interactive diagram: https://gitdiagram.com/299710583/autoflow
- Repository: https://github.com/299710583/autoflow

## Overview

#### Purpose and entry points
AutoFlow is a Python multi-agent framework for authorized security assessments, lab testing, and internal red-team workflows. It transforms target/scope input into recon, evidence-backed validation, and reports. Primary runtime entry points are `autoflow/main.py`, CLI runners `scripts/run_assessment.py` and `scripts/run_stepwise_assessment.py`; an HTTP integration surface exists in `autoflow/api/app.py` with project, task, finding, and approval routes.

#### Workflow orchestration
LangGraph is the primary control plane. The graph builder assembles nodes, conditional edges, state transitions, and checkpoint integration in `autoflow/graph/builder.py`, `autoflow/graph/nodes.py`, and `autoflow/graph/edges.py`. Workflow state is modeled separately in `autoflow/graph/state.py` and business flow state/models in `autoflow/flows/state.py` and `autoflow/flows/models.py`. The key loop is planning → discovery/recon → execution → finding verification → validation; validation reasoning may route back to discovery before reporting.

#### Agent stages and reasoning boundary
Agents separate LLM judgment from deterministic collection and execution. `autoflow/agents/planner.py` establishes assessment direction; `autoflow/agents/recon.py` performs factual target collection; `autoflow/agents/discovery_reasoner.py` converts observations, memory, and tool availability into test plans. `autoflow/agents/executor.py`, `autoflow/agents/verifier.py`, `autoflow/agents/validation.py`, and `autoflow/agents/validation_reasoner.py` execute plans, promote signals into candidate findings, produce validation plans, and make iterative evidence decisions. LLM access is isolated behind `autoflow/llm/client.py`, while shared agent/tool-call iteration is centralized in `autoflow/agents/tool_loop.py`.

#### Controlled tool-execution plane
LLMs receive declared tool schemas rather than host-shell access. `autoflow/tools/catalog.py`, `autoflow/tools/manifest.py`, and `autoflow/tools/dispatcher.py` expose and dispatch approved calls. Execution adapters build commands and run them in Docker/Kali, scripts, bounded shell, or SSH through `autoflow/executor/docker_executor.py`, `autoflow/executor/task_container_executor.py`, `autoflow/executor/script_runner.py`, and `autoflow/executor/shell_runner.py`. Tool output parsers, including `autoflow/executor/parsers/nmap.py` and `autoflow/executor/parsers/nuclei.py`, normalize external results. The material execution environment is the Docker image defined by `docker/autoflow-kali-tools/Dockerfile`; tool availability and installation policy are configuration-driven under `configs/tools.yaml`, `configs/tool_manifest.yaml`, and `configs/tool_installs.yaml`.

#### Evidence, domain, and persistence
The evidence pipeline is raw tool result → observation/signal → candidate finding → validation plan/result → report. Core domain records reside in `autoflow/domain/project.py`, `autoflow/domain/task.py`, `autoflow/domain/finding.py`, and `autoflow/domain/evidence.py`; observation parsing and models are in `autoflow/observations/parser.py` and `autoflow/observations/models.py`. Relational persistence is abstracted through `autoflow/db/models.py`, `autoflow/db/repositories.py`, and `autoflow/db/session.py`. Large raw evidence is stored outside LLM context through `autoflow/artifacts/store.py` and `autoflow/artifacts/paths.py`.

#### Memory, recovery, and safety controls
Redis is the runtime memory and checkpoint backend: agent memory, retrieval, embeddings/vector support, and Redis storage are represented by `autoflow/memory/agent_memory.py`, `autoflow/memory/retrieval.py`, and `autoflow/memory/redis_store.py`; graph checkpoint handling is in `autoflow/graph/checkpoints.py`. This boundary supports multi-turn context, interruption recovery, and future approval-resume flows. Authorization scope, tool risk, approval requirements, and policy rules are enforced through `autoflow/policy/engine.py`, `autoflow/policy/risk.py`, and `autoflow/policy/approval.py`; execution supervision is provided by `autoflow/supervision/limits.py` and `autoflow/supervision/monitor.py`.

#### Reporting and operational infrastructure
`autoflow/agents/reporter.py` aggregates assets, observations, findings, validation evidence, and remediation guidance. `autoflow/reporting/generator.py` emits reports through Markdown, HTML, and PDF exporters, with `autoflow/reporting/exporters/markdown.py` the stated primary output path. Runtime scheduling primitives—queueing, locks, conflict detection, and heartbeats—are isolated in `autoflow/scheduler/dispatcher.py`, `autoflow/scheduler/locks.py`, and `autoflow/scheduler/conflict.py`. Required external services/runtimes are Python 3.11+, Docker, Redis/Redis Stack, and an OpenAI-compatible LLM API.

Main entry points: [`autoflow/graph/builder.py`](https://github.com/299710583/autoflow/blob/master/autoflow/graph/builder.py) (LangGraph workflow), [`autoflow/agents/validation_reasoner.py`](https://github.com/299710583/autoflow/blob/master/autoflow/agents/validation_reasoner.py) (Execution and validation), [`autoflow/executor/docker_executor.py`](https://github.com/299710583/autoflow/blob/master/autoflow/executor/docker_executor.py) (Execution adapters), [`autoflow/agents/discovery_reasoner.py`](https://github.com/299710583/autoflow/blob/master/autoflow/agents/discovery_reasoner.py) (Recon and discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_cli["Assessment CLI<br/>Python runner<br/>[run_assessment.py]"]
  node_api["HTTP API<br/>integration API<br/>[app.py]"]
end

subgraph group_workflow["Workflow control"]
  node_graph{{"LangGraph workflow<br/>orchestrator<br/>[builder.py]"}}
  node_workflow_state["Workflow state<br/>state model<br/>[state.py]"]
  node_checkpoints["Checkpoints<br/>recovery layer<br/>[checkpoints.py]"]
end

subgraph group_agents["Agent pipeline"]
  node_planning["Planning<br/>agent stage<br/>[planner.py]"]
  node_recon["Recon and discovery<br/>agent stage"]
  node_validation["Execution and validation<br/>agent stage"]
  node_llm["LLM client<br/>reasoning boundary<br/>[client.py]"]
  node_tool_loop["Tool-call loop<br/>agent runtime<br/>[tool_loop.py]"]
end

subgraph group_tools["Controlled execution"]
  node_tool_dispatch{{"Tool catalog and dispatch<br/>approved tool gateway<br/>[dispatcher.py]"}}
  node_execution["Execution adapters<br/>command execution<br/>[docker_executor.py]"]
  node_kali["Kali tool image<br/>Docker environment"]
end

subgraph group_data["Evidence and runtime state"]
  node_observations["Observations<br/>normalized evidence<br/>[parser.py]"]
  node_domain["Projects, tasks and findings<br/>domain records<br/>[finding.py]"]
  node_persistence[("Relational persistence<br/>repository layer<br/>[repositories.py]")]
  node_artifacts[("Raw evidence artifacts<br/>artifact store<br/>[store.py]")]
  node_redis[("Redis memory<br/>memory and checkpoint backend<br/>[redis_store.py]")]
end

subgraph group_outputs["Governance and outputs"]
  node_policy{{"Policy and approvals<br/>safety control<br/>[engine.py]"}}
  node_reporting["Report generation<br/>reporting pipeline<br/>[generator.py]"]
  node_scheduler["Scheduler and locks<br/>runtime coordination<br/>[dispatcher.py]"]
end

node_cli -->|"starts assessment"| node_graph
node_api -->|"creates and resumes workflows"| node_graph
node_api -->|"manages records and approvals"| node_domain
node_graph -->|"reads and updates"| node_workflow_state
node_graph -->|"routes to"| node_planning
node_planning -->|"assessment direction"| node_recon
node_recon -->|"test plans and observations"| node_validation
node_validation -.->|"needs more discovery"| node_recon
node_planning -->|"reasoning"| node_llm
node_recon -->|"reasoning"| node_llm
node_validation -->|"evidence decisions"| node_llm
node_validation -->|"tool iterations"| node_tool_loop
node_tool_loop -->|"declared tool calls"| node_tool_dispatch
node_tool_dispatch -->|"authorize call"| node_policy
node_policy -->|"approved execution"| node_execution
node_execution -->|"runs tools in"| node_kali
node_execution -->|"external output"| node_observations
node_observations -->|"signals and candidate findings"| node_domain
node_execution -->|"raw evidence"| node_artifacts
node_domain -->|"stored through"| node_persistence
node_graph -->|"checkpoint lifecycle"| node_checkpoints
node_checkpoints -->|"persists runtime state"| node_redis
node_validation -->|"validated evidence"| node_reporting
node_reporting -->|"reads evidence"| node_artifacts
node_scheduler -->|"dispatches coordinated runs"| node_graph

click node_cli "https://github.com/299710583/autoflow/blob/master/scripts/run_assessment.py"
click node_api "https://github.com/299710583/autoflow/blob/master/autoflow/api/app.py"
click node_graph "https://github.com/299710583/autoflow/blob/master/autoflow/graph/builder.py"
click node_workflow_state "https://github.com/299710583/autoflow/blob/master/autoflow/graph/state.py"
click node_checkpoints "https://github.com/299710583/autoflow/blob/master/autoflow/graph/checkpoints.py"
click node_planning "https://github.com/299710583/autoflow/blob/master/autoflow/agents/planner.py"
click node_recon "https://github.com/299710583/autoflow/blob/master/autoflow/agents/discovery_reasoner.py"
click node_validation "https://github.com/299710583/autoflow/blob/master/autoflow/agents/validation_reasoner.py"
click node_llm "https://github.com/299710583/autoflow/blob/master/autoflow/llm/client.py"
click node_tool_loop "https://github.com/299710583/autoflow/blob/master/autoflow/agents/tool_loop.py"
click node_tool_dispatch "https://github.com/299710583/autoflow/blob/master/autoflow/tools/dispatcher.py"
click node_policy "https://github.com/299710583/autoflow/blob/master/autoflow/policy/engine.py"
click node_execution "https://github.com/299710583/autoflow/blob/master/autoflow/executor/docker_executor.py"
click node_kali "https://github.com/299710583/autoflow/blob/master/docker/autoflow-kali-tools/Dockerfile"
click node_observations "https://github.com/299710583/autoflow/blob/master/autoflow/observations/parser.py"
click node_domain "https://github.com/299710583/autoflow/blob/master/autoflow/domain/finding.py"
click node_persistence "https://github.com/299710583/autoflow/blob/master/autoflow/db/repositories.py"
click node_artifacts "https://github.com/299710583/autoflow/blob/master/autoflow/artifacts/store.py"
click node_redis "https://github.com/299710583/autoflow/blob/master/autoflow/memory/redis_store.py"
click node_reporting "https://github.com/299710583/autoflow/blob/master/autoflow/reporting/generator.py"
click node_scheduler "https://github.com/299710583/autoflow/blob/master/autoflow/scheduler/dispatcher.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_cli,node_api toneBlue
class node_graph,node_workflow_state,node_checkpoints toneAmber
class node_planning,node_recon,node_validation,node_llm,node_tool_loop toneMint
class node_tool_dispatch,node_execution,node_kali toneRose
class node_observations,node_domain,node_persistence,node_artifacts,node_redis toneIndigo
class node_policy,node_reporting,node_scheduler toneTeal
```

## Components

### Entry surfaces

- [Assessment CLI](https://github.com/299710583/autoflow/blob/master/scripts/run_assessment.py): Python runner · `scripts/run_assessment.py`
- [HTTP API](https://github.com/299710583/autoflow/blob/master/autoflow/api/app.py): integration API · Exposes project, task, finding, and approval routes. · `autoflow/api/app.py`

### Workflow control

- [LangGraph workflow](https://github.com/299710583/autoflow/blob/master/autoflow/graph/builder.py): orchestrator · Builds conditional stages and state transitions. · `autoflow/graph/builder.py`
- [Workflow state](https://github.com/299710583/autoflow/blob/master/autoflow/graph/state.py): state model · `autoflow/graph/state.py`
- [Checkpoints](https://github.com/299710583/autoflow/blob/master/autoflow/graph/checkpoints.py): recovery layer · `autoflow/graph/checkpoints.py`

### Agent pipeline

- [Planning](https://github.com/299710583/autoflow/blob/master/autoflow/agents/planner.py): agent stage · Establishes assessment direction. · `autoflow/agents/planner.py`
- [Recon and discovery](https://github.com/299710583/autoflow/blob/master/autoflow/agents/discovery_reasoner.py): agent stage · Collects facts and turns them into test plans. · `autoflow/agents/discovery_reasoner.py`
- [Execution and validation](https://github.com/299710583/autoflow/blob/master/autoflow/agents/validation_reasoner.py): agent stage · Executes plans, verifies signals, and makes iterative evidence decisions. · `autoflow/agents/validation_reasoner.py`
- [LLM client](https://github.com/299710583/autoflow/blob/master/autoflow/llm/client.py): reasoning boundary · OpenAI-compatible LLM access is isolated here. · `autoflow/llm/client.py`
- [Tool-call loop](https://github.com/299710583/autoflow/blob/master/autoflow/agents/tool_loop.py): agent runtime · `autoflow/agents/tool_loop.py`

### Controlled execution

- [Tool catalog and dispatch](https://github.com/299710583/autoflow/blob/master/autoflow/tools/dispatcher.py): approved tool gateway · Provides declared schemas and dispatches approved calls. · `autoflow/tools/dispatcher.py`
- [Execution adapters](https://github.com/299710583/autoflow/blob/master/autoflow/executor/docker_executor.py): command execution · Runs bounded Docker, task-container, script, shell, or SSH work. · `autoflow/executor/docker_executor.py`
- [Kali tool image](https://github.com/299710583/autoflow/blob/master/docker/autoflow-kali-tools/Dockerfile): Docker environment · `docker/autoflow-kali-tools/Dockerfile`

### Evidence and runtime state

- [Observations](https://github.com/299710583/autoflow/blob/master/autoflow/observations/parser.py): normalized evidence · Parses external output into observations and signals. · `autoflow/observations/parser.py`
- [Projects, tasks and findings](https://github.com/299710583/autoflow/blob/master/autoflow/domain/finding.py): domain records · `autoflow/domain/finding.py`
- [Relational persistence](https://github.com/299710583/autoflow/blob/master/autoflow/db/repositories.py): repository layer · `autoflow/db/repositories.py`
- [Raw evidence artifacts](https://github.com/299710583/autoflow/blob/master/autoflow/artifacts/store.py): artifact store · Keeps large raw evidence outside LLM context. · `autoflow/artifacts/store.py`
- [Redis memory](https://github.com/299710583/autoflow/blob/master/autoflow/memory/redis_store.py): memory and checkpoint backend · Supports agent context, retrieval, embeddings, and recovery. · `autoflow/memory/redis_store.py`

### Governance and outputs

- [Policy and approvals](https://github.com/299710583/autoflow/blob/master/autoflow/policy/engine.py): safety control · Enforces scope, risk, and approval requirements. · `autoflow/policy/engine.py`
- [Report generation](https://github.com/299710583/autoflow/blob/master/autoflow/reporting/generator.py): reporting pipeline · Exports Markdown, HTML, and PDF reports. · `autoflow/reporting/generator.py`
- [Scheduler and locks](https://github.com/299710583/autoflow/blob/master/autoflow/scheduler/dispatcher.py): runtime coordination · Provides queueing, locks, conflict detection, and heartbeats. · `autoflow/scheduler/dispatcher.py`

## Connections

- Assessment CLI → LangGraph workflow: starts assessment
- HTTP API → LangGraph workflow: creates and resumes workflows
- HTTP API → Projects, tasks and findings: manages records and approvals
- LangGraph workflow → Workflow state: reads and updates
- LangGraph workflow → Planning: routes to
- Planning → Recon and discovery: assessment direction
- Recon and discovery → Execution and validation: test plans and observations
- Execution and validation → Recon and discovery: needs more discovery
- Planning → LLM client: reasoning
- Recon and discovery → LLM client: reasoning
- Execution and validation → LLM client: evidence decisions
- Execution and validation → Tool-call loop: tool iterations
- Tool-call loop → Tool catalog and dispatch: declared tool calls
- Tool catalog and dispatch → Policy and approvals: authorize call
- Policy and approvals → Execution adapters: approved execution
- Execution adapters → Kali tool image: runs tools in
- Execution adapters → Observations: external output
- Observations → Projects, tasks and findings: signals and candidate findings
- Execution adapters → Raw evidence artifacts: raw evidence
- Projects, tasks and findings → Relational persistence: stored through
- LangGraph workflow → Checkpoints: checkpoint lifecycle
- Checkpoints → Redis memory: persists runtime state
- Execution and validation → Report generation: validated evidence
- Report generation → Raw evidence artifacts: reads evidence
- Scheduler and locks → LangGraph workflow: dispatches coordinated runs