# langtalks/swe-agent architecture

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

- Interactive diagram: https://gitdiagram.com/langtalks/swe-agent
- Repository: https://github.com/langtalks/swe-agent

## Overview

##### Project Type and Purpose
- This is an AI-powered multi-agent orchestration framework (not a web or mobile app).
- It automates software engineering tasks by splitting them into two distinct agents: the **Architect Agent** (research & planning) and the **Developer Agent** (implementation).
- It uses LangGraph to define and run the agent workflows, Anthropic Claude as the LLM, and a set of file- and code-analysis tools (tree-sitter, semantic search).

##### Key Architectural Components
- **User Interface / Entry Point**
- A CLI or API call that feeds the user’s request into LangGraph.
- LangGraph server (`langgraph dev`), configured by `langgraph.json`/`langgraph_debug.py`.
- **LangGraph Orchestrator**
- Defines two graphs (architect and developer) in `langgraph.json`.
- Routes messages/state between agents and manages sequencing.
- **Main Agent Logic**
- `agent/graph.py` – top-level orchestration of the two-stage workflow.
- Maintains `AgentState` with research scratchpad and eventual `ImplementationPlan`.
- **Architect Agent**
- Code in `agent/architect/graph.py`
- State model: `SoftwareArchitectState` (`agent/architect/state.py`).
- Uses prompt templates under `agent/architect/prompts/` for hypothesis generation, research, and plan extraction.
- Invokes tools: `search.py` and `codemap.py` for codebase analysis.
- **Developer Agent**
- Code in `agent/developer/graph.py`
- State model: `SoftwareDeveloperState` (`agent/developer/state.py`).
- Uses prompt templates under `agent/developer/prompts/` for diff generation and file writes.
- Invokes `write.py` to apply diffs to the file system.
- **Shared Entities & State Models**
- `agent/common/entities.py` – Pydantic models (`ImplementationPlan`, `ImplementationTask`, `AtomicTask`, `DiffTask`).
- Ensures type safety, validation, and clear data contracts between agents.
- **Tools Layer**
- File system operations (`write.py`)
- Code search (`search.py`)
- Code parsing/analysis (`codemap.py` leveraging tree-sitter)
- **External Services**
- Anthropic Claude Sonnet 4 LLM via LangChain
- Underlying Python environment with dependencies in `pyproject.toml` and locked by `uv.lock`
- `.env` file for API keys and configuration

##### Relationships and Data Flow
- User → LangGraph Orchestrator → Main Agent →
→ Architect Agent (LLM + search/codemap tools) → updates `SoftwareArchitectState` → outputs `ImplementationPlan` →
→ LangGraph routes `ImplementationPlan` to Developer Agent →
→ Developer Agent (LLM + write tool) → applies diffs to codebase → final results.
- All state transitions and messages are persisted in Pydantic models for traceability and resumability.

##### Architectural Patterns and Principles
- **Separation of Concerns**: Planning (Architect) vs. Execution (Developer).
- **Atomic Tasks**: Every change is broken into smallest diffable units.
- **Stateful Workflows**: Each agent holds its own state; orchestrator holds global state.
- **Tool Integration**: Agents never manipulate raw files directly—they call well-defined tools.
- **Resumability & Traceability**: Full scratchpad of messages and diffs persists between runs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User / CLI / API"]:::external

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        LG["LangGraph Server"]:::orchestrator
        config1["langgraph.json"]:::config
        config2["langgraph_debug.py"]:::config
        subgraph "Main Agent Logic"
            MG["agent/graph.py"]:::logic
            MS["agent/state.py"]:::logic
            MP["agent/prompts.py"]:::logic
            APrompt["act_step_prompt.md"]:::md
            TPrompt["think_step_prompt.md"]:::md
        end
    end

    %% Agents Layer
    subgraph "Agents Layer"
        subgraph "Architect Agent"
            Arch["Architect Agent"]:::agent
            ArchState["SoftwareArchitectState"]:::state
            ArchPrompts["agent/architect/prompts"]:::prompt
        end
        subgraph "Developer Agent"
            Dev["Developer Agent"]:::agent
            DevState["SoftwareDeveloperState"]:::state
            DevPrompts["agent/developer/prompts"]:::prompt
        end
    end

    %% Tools and Codebase Layer
    subgraph "Tools & Codebase"
        search["search.py"]:::tool
        codemap["codemap.py"]:::tool
        write["write.py"]:::tool
        codebase["workspace_repo"]:::db
    end

    %% External Services
    LLM["Anthropic Claude LLM"]:::external
    configEnv[".env.example"]:::config
    pyproj["pyproject.toml"]:::config
    uvlock["uv.lock"]:::config

    %% Connections
    User -->|"request"| LG
    LG -->|"loads workflow"| config1
    LG -->|"loads workflow"| config2
    LG -->|"orchestrates"| MG
    MG -->|"routes to"| Arch
    MG -->|"routes to"| Dev

    Arch -->|"calls LLM"| LLM
    Dev -->|"calls LLM"| LLM

    Arch -->|"research & analysis"| search
    Arch -->|"research & analysis"| codemap
    search -->|"reads code"| codebase
    codemap -->|"reads code"| codebase

    Dev -->|"apply diffs"| write
    write -->|"writes to"| codebase

    %% State and Prompt Flows
    Arch -->|"updates state"| ArchState
    Arch -->|"uses prompts"| ArchPrompts
    Dev -->|"updates state"| DevState
    Dev -->|"uses prompts"| DevPrompts

    %% Common Prompts & State
    MG -->|"uses state"| MS
    MG -->|"uses prompts"| MP
    MG -->|"uses prompts"| APrompt
    MG -->|"uses prompts"| TPrompt

    %% External Configs
    LG -->|"env config"| configEnv
    LG -->|"dependencies"| pyproj
    LG -->|"lockfile"| uvlock

    %% Click Events
    click config1 "https://github.com/langtalks/swe-agent/blob/main/langgraph.json"
    click config2 "https://github.com/langtalks/swe-agent/blob/main/langgraph_debug.py"
    click MG "https://github.com/langtalks/swe-agent/blob/main/agent/graph.py"
    click MS "https://github.com/langtalks/swe-agent/blob/main/agent/state.py"
    click MP "https://github.com/langtalks/swe-agent/blob/main/agent/prompts.py"
    click APrompt "https://github.com/langtalks/swe-agent/blob/main/agent/prompts/act_step_prompt.md"
    click TPrompt "https://github.com/langtalks/swe-agent/blob/main/agent/prompts/think_step_prompt.md"
    click Arch "https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py"
    click ArchState "https://github.com/langtalks/swe-agent/blob/main/agent/architect/state.py"
    click ArchPrompts "https://github.com/langtalks/swe-agent/tree/main/agent/architect/prompts"
    click Dev "https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py"
    click DevState "https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py"
    click DevPrompts "https://github.com/langtalks/swe-agent/tree/main/agent/developer/prompts"
    click search "https://github.com/langtalks/swe-agent/blob/main/agent/tools/search.py"
    click codemap "https://github.com/langtalks/swe-agent/blob/main/agent/tools/codemap.py"
    click write "https://github.com/langtalks/swe-agent/blob/main/agent/tools/write.py"

    %% Styles
    classDef external fill:#fdd0a2,stroke:#e6550d,color:#000
    classDef orchestrator fill:#cbc9e2,stroke:#6a51a3,color:#000
    classDef logic fill:#e0f3db,stroke:#41ab5d,color:#000
    classDef agent fill:#9ecae1,stroke:#3182bd,color:#000
    classDef state fill:#deebf7,stroke:#3182bd,color:#000
    classDef prompt fill:#fee6ce,stroke:#e6550d,color:#000
    classDef tool fill:#c7e9c0,stroke:#238b45,color:#000
    classDef db fill:#edf8fb,stroke:#006d2c,color:#000
    classDef config fill:#f0f0f0,stroke:#636363,color:#000
    classDef md fill:#fde0dd,stroke:#de2d26,color:#000
```
