How chrisroyse/codegraph works
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.