# nmakod/codecontext architecture

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

- Interactive diagram: https://gitdiagram.com/nmakod/codecontext
- Repository: https://github.com/nmakod/codecontext

## Overview

##### Project Type and Purpose
- CodeContext is an AI-powered CLI tool (written in Go) plus an embedded “MCP” server.
- Purpose: analyze any codebase (multi-language via Tree-sitter), build a virtual dependency graph, generate token-optimized Markdown context maps, serve real-time context over MCP protocol.
- It’s not a traditional client-server web app; it’s a layered CLI application with an optional long-running server component.

##### File Structure
- Top-level “cmd/codecontext”: the main entry point (Go `main.go`), subcommands (`generate`, `init`, `mcp`, `watch`, etc.).
- `internal/cli`: CLI parsing, command implementations, tests.
- `internal/analyzer`, `internal/parser`, `internal/diff`, `internal/git`, `internal/compact`, `internal/vgraph`: core engine modules.
- **Parser** builds ASTs and extracts symbols.
- **Git** module fetches version/history and change contexts.
- **Diff** layer computes semantic vs structural diffs.
- **Analyzer** and **vgraph** build the dependency/virtual graph.
- **Compact** strategies shrink context payloads.
- `internal/cache`: persistent/in-memory caching to avoid re-parsing.
- `internal/mcp`: MCP server that exposes a persistent gRPC/JSON‐RPC API.
- `pkg/types`: shared data structures (graph nodes, contexts, symbols).

##### Key README/Docs Insights
- Architecture is layered: Parser → Graph Engine → Analyzer → Formatter/Output → MCP Server/CLI.
- Virtual Graph Engine: shadow vs actual graph, incremental updates.
- Caching: LRU + persistent disk.
- Multi-threaded file processing.
- External dependencies: Tree-sitter libraries, Git CLI, Claude (as consumer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        FS["File System"]:::infra
        GitCLI["Git Executable"]:::infra
        TreeSitter["Tree-sitter Parsers"]:::external
    end

    %% Interface Layer
    subgraph "Interface Layer"
        CLI["CLI Front-end\n(cmd/codecontext)"]:::interface
        MCP["MCP Server\n(internal/mcp)"]:::interface
    end

    %% Processing Layer
    subgraph "Processing Layer"
        Parser["Parser Module\n(internal/parser)"]:::core
        GitMod["Git Integration Module\n(internal/git)"]:::core
        Diff["Diff Engine\n(internal/diff)"]:::core
        VGraph["Virtual Graph Engine\n(internal/vgraph)"]:::core
        Analyzer["Analyzer Module\n(internal/analyzer)"]:::core
        Compact["Compaction Module\n(internal/compact)"]:::core
        Cache["Cache Layer\n(internal/cache)"]:::infra
        Types["Shared Types\n(pkg/types)"]:::infra
    end

    %% Output Layer
    subgraph "Output Layer"
        Formatter["Formatter/Output Generator\n(internal/generator/markdown.go)"]:::core
        AIClients["AI Assistant Clients\n(Claude, VSCode)"]:::external
    end

    %% Data Flows
    FS --> Parser
    TreeSitter --> Parser
    GitCLI --> GitMod

    CLI --> Parser
    CLI --> GitMod
    MCP --> Parser
    MCP --> GitMod

    Parser --> Diff
    GitMod --> Diff
    Parser --> VGraph
    Diff --> VGraph

    VGraph --> Analyzer
    Analyzer --> Compact
    Compact --> Formatter

    Formatter --> CLI
    Formatter --> MCP

    MCP --> AIClients
    AIClients --> MCP

    %% Cache cross-cutting
    Cache -.-> Parser
    Cache -.-> Diff
    Cache -.-> VGraph

    Types --> Parser
    Types --> GitMod
    Types --> Diff
    Types --> VGraph
    Types --> Analyzer
    Types --> Compact
    Types --> Formatter

    %% Click Events
    click CLI "https://github.com/nmakod/codecontext/blob/main/cmd/codecontext/main.go"
    click Parser "https://github.com/nmakod/codecontext/tree/main/internal/parser"
    click GitMod "https://github.com/nmakod/codecontext/tree/main/internal/git"
    click Diff "https://github.com/nmakod/codecontext/tree/main/internal/diff"
    click VGraph "https://github.com/nmakod/codecontext/tree/main/internal/vgraph"
    click Analyzer "https://github.com/nmakod/codecontext/tree/main/internal/analyzer"
    click Compact "https://github.com/nmakod/codecontext/tree/main/internal/compact"
    click Cache "https://github.com/nmakod/codecontext/blob/main/internal/cache/persistent.go"
    click Formatter "https://github.com/nmakod/codecontext/blob/main/internal/generator/markdown.go"
    click MCP "https://github.com/nmakod/codecontext/blob/main/internal/mcp/server.go"
    click Types "https://github.com/nmakod/codecontext/tree/main/pkg/types"

    %% Styles
    classDef core fill:#f9d,stroke:#333,stroke-width:1px
    classDef infra fill:#cdf,stroke:#333,stroke-width:1px
    classDef interface fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fcc,stroke:#333,stroke-width:1px
```
