# zeeeepa/graph-sitter architecture

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

- Interactive diagram: https://gitdiagram.com/zeeeepa/graph-sitter
- Repository: https://github.com/zeeeepa/graph-sitter

## Overview

##### Project type and purpose
- This is a full-stack, scriptable code-manipulation platform (“Graph-sitter”) implemented in Python.
- It exposes:
- A core library (src/graph_sitter) for parsing codebases into ASTs and graphs.
- A suite of CLI tools (src/graph_sitter/cli, src/gscli, src/contexten/cli) for codemods, codegen, LSP, notebooks, etc.
- A codemod framework (src/codemods) with canonical and eval modules.
- An agent/extension layer (src/contexten, src/graph_sitter/extensions) for integrating with AI agents, GitHub, Slack, Linear, Modal, SWEbench.
- Build and packaging (Dockerfile, pyproject.toml, GitHub Actions workflows).

##### File structure
- Top-level “src” splits into:
- graph_sitter (core parsing, codebase graph, Cython extensions, configs, types, visitor patterns).
- codemods (framework for writing and evaluating code transforms).
- contexten (AI-agent orchestration, CLI commands, API clients, auth).
- gscli (global CLI wrapper).
- gsbuild (packaging/build entrypoint).
- “docs” and “examples” illustrate API usage and full-stack examples (frontend + backend).
- “tests” covers unit and integration tests for CLI, core, SDK, codemods, agents, extensions.
- CI/CD defined in .github/workflows and scripts for linting, type-checking, testing, releasing.

##### README for additional insights
- Describes primary abstractions: Codebase, Agent, Task.
- Highlights dependencies: Tree-sitter (parsing), rustworkx (graph algorithms).
- Shows usage patterns: instantiate Codebase, traverse functions, perform edits, run an AI agent via REST.

##### Main components
a. Frontend/CLI layer
- gs (global entrypoint)
- graph-sitter CLI commands (init, create, run, lsp, notebook)
- contexten CLI (agent, create, deploy, run, serve)
b. Agent/API layer
- Agent class (src/contexten/agents)
- REST API client (modal.run base_url)
c. Core processing engine
- File discovery & parsing (Tree-sitter bindings in src/graph_sitter/tree_sitter_parser.py)
- AST & graph construction (codebase, multigraph, rustworkx)
- Semantic analyses (type analysis, import/export resolution)
- Transactions & edits (transaction_manager, codemod runner)
- Incremental recomputation sub-system
d. Extensions & plugins
- Language plugins (python, typescript, core/plugins)
- External integrations (GitHub, Slack, Linear, Modal, SWEbench)
- LSP server & protocol handler
e. I/O & external dependencies
- File system I/O
- Cython-compiled modules (src/graph_sitter/compiled)
- Config management (hatch.toml, pyproject.toml, configs models)
- Docker environment & UV toolchain

##### Relationships and interactions
- CLI → Core: invokes parsing, codebase build, codemod runner
- Agent → REST API → Core: submits tasks, polls status
- Core → Tree-sitter & rustworkx: builds ASTs and graphs
- Core → Extensions: dispatches language-specific or third-party plugins
- Codemod framework → Core: uses AST & graph to apply transforms
- Tests & CI → CLI/Core: validate behavior, perform integration scenarios

##### Architectural patterns and design principles
- Layered architecture: CLI/Agent → Core → Extensions → I/O
- Plugin/extension pattern for languages & external services
- Modular separation of concerns (parsing, analysis, edits, API)
- Incremental computation graph for performance
- Cython extension for critical performance paths

##### Technologies, frameworks & libraries
- Python 3.12+
- Tree-sitter (parsing)
- rustworkx (graph algorithms)
- Cython (compiled performance modules)
- Click or Typer (CLI – implied)
- Docker & UV (toolchain)
- GitHub Actions (CI/CD)

##### Final recommendations
- Heavy-weight modules (Cython compiled, rustworkx) to show performance boundaries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI / CLI Layer
    subgraph "UI / CLI Layer"
        CLI_GS["Global CLI Wrapper (gs)"]:::ui
        CLI_GSCLI["Graph-sitter CLI Commands"]:::ui
        CLI_CTXCLI["Contexten CLI Commands"]:::ui
    end

    %% Agent / API Layer
    subgraph "Agent / API Layer"
        AGENTS["Contexten Agents"]:::api
        EXT_INT["External Integrations"]:::api
        RUNNER["Runner Service & Sandbox"]:::api
    end

    %% Core Engine
    subgraph "Core Engine"
        PARSER["Tree-sitter Parser"]:::core
        CODEBASE["Codebase & Transaction Manager"]:::core
        GRAPH["AST & Graph Construction"]:::core
        CODERUN["Codemod Framework"]:::core
        SHARED["Shared Utilities & Networking"]:::core
        CYTHON["Cython-Accelerated Modules"]:::core
    end

    %% Extensions / Plugins
    subgraph "Extensions / Plugins"
        LSP["LSP & Protocol Handler"]:::ext
        GRAPH_EXT["Graph & Visualization Extension"]:::ext
    end

    %% I/O & External Dependencies
    subgraph "I/O & External Dependencies"
        FS["File System I/O"]:::ext2
        GIT["Git Integration"]:::ext2
        CONFIG["Config Management"]:::ext2
        DOCKER["Docker Environment"]:::ext2
        CI["CI/CD Workflows"]:::ext2
    end

    %% Connections
    CLI_GS -->|"invoke"| PARSER
    CLI_GS -->|"invoke"| CODEBASE
    CLI_GS -->|"invoke"| CODERUN
    CLI_GSCLI -->|"invoke parse"| PARSER
    CLI_CTXCLI -->|"orchestrate agents"| AGENTS

    AGENTS -->|"submit tasks"| RUNNER
    RUNNER -->|"run codemod"| CODERUN

    CODERUN -->|"uses parser"| PARSER
    CODERUN -->|"uses graph"| GRAPH
    CODERUN -->|"manages transactions"| CODEBASE

    PARSER -->|"builds AST"| GRAPH
    CODEBASE -->|"uses utils"| SHARED
    GRAPH -->|"uses algorithms"| SHARED

    PARSER -->|"optimized by"| CYTHON
    CODEBASE -->|"optimized by"| CYTHON

    PARSER -->|"dispatch to"| LSP
    GRAPH -->|"dispatch to"| GRAPH_EXT

    CODEBASE -->|"reads/writes"| FS
    CODEBASE -->|"integrates"| GIT

    CONFIG -.-> CODEBASE
    DOCKER -.-> CLI_GS
    CI -.-> CODEBASE

    %% Click Events
    click CLI_GS "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/gscli"
    click CLI_GSCLI "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/cli"
    click CLI_CTXCLI "https://github.com/zeeeepa/graph-sitter/tree/develop/src/contexten/cli"
    click PARSER "https://github.com/zeeeepa/graph-sitter/blob/develop/src/graph_sitter/tree_sitter_parser.py"
    click CODEBASE "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/codebase"
    click CYTHON "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/compiled"
    click CODERUN "https://github.com/zeeeepa/graph-sitter/blob/develop/src/codemods/codemod.py"
    click AGENTS "https://github.com/zeeeepa/graph-sitter/tree/develop/src/contexten/agents"
    click EXT_INT "https://github.com/zeeeepa/graph-sitter/tree/develop/src/contexten/extensions"
    click LSP "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/extensions/lsp"
    click GRAPH_EXT "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/extensions/graph"
    click FS "https://github.com/zeeeepa/graph-sitter/blob/develop/src/graph_sitter/codebase/io/file_io.py"
    click GIT "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/git"
    click RUNNER "https://github.com/zeeeepa/graph-sitter/tree/develop/src/graph_sitter/runner"
    click CONFIG "https://github.com/zeeeepa/graph-sitter/blob/develop/pyproject.toml"
    click DOCKER "https://github.com/zeeeepa/graph-sitter/tree/develop/Dockerfile"
    click CI "https://github.com/zeeeepa/graph-sitter/tree/develop/.github/workflows"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef api fill:#A3E4D7,stroke:#1ABC9C,color:#0E6251
    classDef core fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef ext fill:#F9E79F,stroke:#F1C40F,color:#7D6608
    classDef ext2 fill:#D5DBDB,stroke:#85929E,color:#424949
```
