# chrisroyse/codegraph architecture

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

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

## Overview

##### Project Type & Purpose
- CodeGraph Analyzer is a multi-language static analysis engine that transforms a codebase into a Neo4j graph database. Its purpose is to parse various programming languages (TypeScript, Python, Java, C#, C/C++, Go, SQL, etc.) to build a “digital twin” of your code structure and relationships.
- The project also integrates with MCP (Model Context Protocol) components to bridge natural language queries and the graph database, enabling AI-assisted code comprehension and refactoring.

##### Analyzing the File Structure
- The file tree shows two main sets of directories:
- “src”: This contains the core source code for the analyzer. In particular:
- src/analyzer – responsible for performing code analysis with various sub-components (analysis modules, parsing utilities, multiple language parsers, relationship resolvers, etc.).
- src/database – includes components like neo4j-client and schema definitions to manage the interaction with the Neo4j database.
- src/cli – provides the command line interface for invoking the analysis and monitoring processes.
- Other directories (scanner, config, utils) serve as support modules (file scanning, configuration management, logging, helper functions).
- “mcp”: Contains a separate package that likely handles MCP-related functionalities (integration with Neo4j MCP, specialized configurations, and potentially node-based tooling). It has its own package files and a distinct source structure.
- Additionally, files like python_parser.py and run_neo4j_server.sh indicate direct support for Python parsing and server startup scripts.

##### Key Components
a. Core Analyzer Engine:
- An “Analyzer Service” component (src/analyzer/analyzer-service.ts) that orchestrates the analysis process.
- Multiple analysis modules (assignment-analyzer, call-analyzer, complexity-analyzer, control-flow-analyzer) that work in a “two-pass” approach—first parsing files into ASTs, then resolving cross-file relationships.
- A set of language parsers organized under src/analyzer/parsers (for TypeScript, Python, Java, C#, C/C++, Go, SQL, etc.) along with corresponding test/spec files.
- Relationship resolvers (e.g., relationship-resolver.ts) that map dependencies and interactions between code elements.

b. Database & Graph Integration:
- A “Neo4j Client” (src/database/neo4j-client.ts) and a schema module for mapping the structure into a graph.
- Integration points that take parsed data and transform it into Cypher queries and schema definitions, leveraging Neo4j’s APOC and GDS libraries as per the README.

c. Command Line Interface (CLI):
- The CLI module (src/cli/analyze.ts) that triggers analysis, accepts command-line options (like directory paths, ignored patterns, file extension filters), and initiates the overall process.

d. MCP Integration Components:
- The MCP configuration and integration are embodied by the separate “mcp” directory and the provided JSON configurations in the README.
- Components such as “code-analyzer-mcp” and the connection to the “mcp-neo4j” server, with components for both read and write operations with the code graph.
- These act as bridges between external AI assistants and the internal analysis engine.

e. Utility, Configuration, and Support Modules:
- Utility modules (src/utils) for error handling, logging, and TS helpers.
- Configuration files (tsconfig.json, various package.json files, and scripts like run_neo4j_server.sh) that play a critical role in deployment, build, and runtime behavior.

##### Architectural Patterns & Relationships
- The design follows a modular pattern where each module (language parser, analysis component, database client) is loosely coupled.
- A separation of concerns is evident—parsing, analysis, data storage, and external communication (via CLI/MCP) are distinct.
- The two-pass analysis design (first building ASTs per file, then resolving cross-file relationships) is essential for capturing multi-language dependencies.
- Dependency flows include:
- File scanning (src/scanner) feeding source files to language-specific parser modules.
- Parser outputs being sent to the analyzer, which then applies relationship resolvers and structural analysis.
- Analyzer outputs then are passed to the database management module to create/update the Neo4j graph.
- Optional MCP components (in “mcp”) act as external interfacing modules to allow AI querying and real-time graph updates.

- Drill down into details for critical paths (e.g., how a file goes from being scanned, parsed, analyzed, and finally represented in the Neo4j graph).
- Interactions between the “mcp” integration components and the core analysis engine.
- Relevant technologies (TypeScript, Node.js, Python, Neo4j, MCP configurations) are noted, especially in areas where they influence design choices.
- Remember that clarity is key—organize components logically to support understanding for both new team members and experienced engineers looking for integration details.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Analyzer Engine
    subgraph "Core Analyzer Engine"
        A["File Scanner"]
        B["Language Parsers"]:::core
        C["Analysis Modules"]:::core
        D["Analyzer Service"]:::core
        E["Relationship Resolver"]:::core
    end

    %% Database & Graph Storage
    subgraph "Database & Graph Storage"
        F["Neo4j Client & Schema"]:::db
    end

    %% Command Line Interface
    subgraph "Command Line Interface"
        G["CLI Module"]:::cli
    end

    %% MCP Integration
    subgraph "MCP Integration"
        H["MCP Integration"]:::mcp
    end

    %% Utility & Configuration Modules
    subgraph "Utility & Configuration Modules"
        I["Utilities"]:::support
        J["Configuration Management"]:::support
        K["Python Parser"]:::support
        L["Server Startup Script"]:::support
    end

    %% Flows in Core Analyzer Engine
    A -->|"feeds"| B
    B -->|"translates"| D
    D -->|"orchestrates"| C
    C -->|"invokes"| E

    %% Flow to Database
    D -->|"outputs graph"| F

    %% CLI triggers analysis
    G -->|"triggers"| D

    %% MCP bidirectional communication with Analyzer Service and Database
    H -->|"interfaces"| D
    D -->|"updates"| H
    H -->|"queries/upd"| F
    F -->|"responds to"| H

    %% Support modules providing utility and configuration
    I --- D
    J --- D
    K --- D
    L --- F

    %% Class definitions for colors
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef db fill:#FFCC99,stroke:#000,stroke-width:1px;
    classDef cli fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef mcp fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events for Component Mapping
    click D "https://github.com/chrisroyse/codegraph/blob/main/src/analyzer/analyzer-service.ts"
    click C "https://github.com/chrisroyse/codegraph/tree/main/src/analyzer/analysis"
    click B "https://github.com/chrisroyse/codegraph/tree/main/src/analyzer/parsers"
    click E "https://github.com/chrisroyse/codegraph/blob/main/src/analyzer/relationship-resolver.ts"
    click F "https://github.com/chrisroyse/codegraph/tree/main/src/database"
    click G "https://github.com/chrisroyse/codegraph/blob/main/src/cli/analyze.ts"
    click H "https://github.com/chrisroyse/codegraph/tree/main/mcp"
    click I "https://github.com/chrisroyse/codegraph/tree/main/src/utils"
    click J "https://github.com/chrisroyse/codegraph/tree/main/src/config"
    click K "https://github.com/chrisroyse/codegraph/blob/main/python_parser.py"
    click L "https://github.com/chrisroyse/codegraph/blob/main/run_neo4j_server.sh"
```
