# suatkocar/codegraph architecture

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

- Interactive diagram: https://gitdiagram.com/suatkocar/codegraph
- Repository: https://github.com/suatkocar/codegraph

## Overview

##### Project type and purpose
- CodeGraph is an open-source code-intelligence engine and MCP (Model Context Protocol) server written in Rust.
- It indexes source code in 32 languages via tree-sitter, builds a semantic graph in SQLite (with FTS5 and vector indexes), exposes 44 “tools” over stdio (rmcp), and provides Git and security hooks for live synchronization.

##### File structure
- Top-level:
- Cargo.toml / Cargo.lock – Rust project metadata
- src/ – core Rust modules
- benches/, tests/ – benchmarks and test suites
- configs/, queries/, rules/ – built-in config and analysis artifacts
- npm/, HomebrewFormula/ – packaging for JS and Homebrew
- scripts/, install.sh / install.ps1 – installation helpers
- .github/, .githooks/ – CI and Git hook definitions
- src/ subdirectories map to major components:
- cli/ & main.rs – CLI entrypoints (clap-based commands: init, index, serve, query…)
- indexer/ – parser, extractor, pipeline (tree-sitter grammars + parallel SHA-256 incremental indexing)
- db/ – SQLite schema, converters, rusqlite integration
- graph/ – graph traversal, ranking, search, complexity, data-flow modules
- mcp/ – MCP server that wraps tools via `#[tool]` macros
- context/ – multi-tier LLM context assembly and token budgeting
- resolution/, security/, git/ – import resolution, security scanning, Git integrations
- config/, observability/, eval/ – configuration loading, structured logging, evaluation harness

##### README for additional insights
Source Files → tree-sitter → Extractor → SQLite DB → Query Engine → MCP Server + Hooks
- Design principles: synchronous core, async boundary at rmcp transport, static linking of grammars, catch_unwind for hook safety, idempotent init, feature-gated embeddings.

- Blue for core engine (parser, extractor, graph)
- Green for storage (SQLite DB)
- Orange for interface (CLI, MCP Server, Hooks)
- Grey for external/optional (ONNX embedder, Git, YAML rules)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Source Files
    SourceFiles["Source Files (32 langs)"]:::external

    %% Core Engine Layer
    subgraph "Core Engine" 
        direction TB
        ParserExtractor["Parser & Extractor\nsrc/indexer/parser.rs"]:::core
        IndexPipeline["Indexing Pipeline\nsrc/indexer/pipeline.rs"]:::core
        ParserExtractor -->|"parses →"| IndexPipeline
    end

    %% Optional Embeddings
    Embeddings["Optional Embeddings Module\nsrc/indexer/embedder.rs"]:::optional

    %% Storage Layer
    subgraph "Persistence Layer" 
        direction TB
        DB["SQLite DB (FTS5 & vec)\nsrc/db/schema.rs"]:::storage
    end

    %% Graph & Query Engine
    subgraph "Query Engine" 
        direction TB
        GraphStore["Graph Store\nsrc/graph/store.rs"]:::core
        Search["Search & Ranking\nsrc/graph/search.rs"]:::core
        Traversal["Graph Traversal\nsrc/graph/traversal.rs"]:::core
        Dataflow["Data-Flow & Complexity\nsrc/graph/dataflow.rs"]:::core
        GraphStore --> Search
        GraphStore --> Traversal
        GraphStore --> Dataflow
    end

    %% Context Assembly
    ContextAssembler["Context Assembler\nsrc/context/assembler.rs"]:::core

    %% Interface Layer
    subgraph "Interface & Tools"
        direction TB
        CLI["CLI\nsrc/main.rs"]:::interface
        MCPServer["MCP Server\nsrc/mcp/server.rs"]:::interface
        Hooks["Hook Framework\nsrc/hooks/mod.rs"]:::interface
    end

    %% Additional Modules
    ConfigLoader["Configuration Loader\nsrc/config/loader.rs"]:::optional
    GitInt["Git Integrations\nsrc/git/mod.rs"]:::optional
    SecurityScan["Security Scanning\nsrc/security/mod.rs"]:::optional
    Resolution["Import Resolution\nsrc/resolution/mod.rs"]:::optional
    Observability["Observability\nsrc/observability/mod.ts"]:::optional
    EvalHarness["Evaluation Harness\nsrc/eval/mod.rs"]:::optional

    %% Data Flows
    SourceFiles -->|"feeds"| ParserExtractor
    IndexPipeline -->|"extracts AST →"| DB
    Embeddings -->|"embeds →"| DB
    DB -->|"queries →"| GraphStore
    CLI -->|"invoke serve"| MCPServer
    MCPServer -->|"executes tools →"| GraphStore
    MCPServer -->|"reads →"| DB
    GraphStore -->|"assemble →"| ContextAssembler
    ContextAssembler -->|"returns JSON →"| MCPServer
    CLI -->|"invoke index"| IndexPipeline
    CLI -->|"invoke query"| GraphStore
    Hooks -->|"subscribe events →"| MCPServer

    ConfigLoader --> CLI
    ConfigLoader --> MCPServer

    GitInt --> Hooks
    SecurityScan --> Hooks
    Resolution --> ParserExtractor

    %% Click events
    click CLI "https://github.com/suatkocar/codegraph/blob/main/src/main.rs"
    click ParserExtractor "https://github.com/suatkocar/codegraph/blob/main/src/indexer/parser.rs"
    click IndexPipeline "https://github.com/suatkocar/codegraph/blob/main/src/indexer/pipeline.rs"
    click Embeddings "https://github.com/suatkocar/codegraph/blob/main/src/indexer/embedder.rs"
    click DB "https://github.com/suatkocar/codegraph/blob/main/src/db/schema.rs"
    click GraphStore "https://github.com/suatkocar/codegraph/blob/main/src/graph/store.rs"
    click Search "https://github.com/suatkocar/codegraph/blob/main/src/graph/search.rs"
    click Traversal "https://github.com/suatkocar/codegraph/blob/main/src/graph/traversal.rs"
    click Dataflow "https://github.com/suatkocar/codegraph/blob/main/src/graph/dataflow.rs"
    click ContextAssembler "https://github.com/suatkocar/codegraph/blob/main/src/context/assembler.rs"
    click MCPServer "https://github.com/suatkocar/codegraph/blob/main/src/mcp/server.rs"
    click Hooks "https://github.com/suatkocar/codegraph/blob/main/src/hooks/mod.rs"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef storage fill:#DFF2D8,stroke:#22863A,color:#22863A
    classDef interface fill:#FFEDD5,stroke:#AD6B00,color:#AD6B00
    classDef optional fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef external fill:#F8F1E4,stroke:#735C0F,color:#735C0F
```
