# shashankss1205/codegraphcontext architecture

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

- Interactive diagram: https://gitdiagram.com/shashankss1205/codegraphcontext
- Repository: https://github.com/shashankss1205/codegraphcontext

## Overview

##### Project type and purpose
- This is a full-stack developer tool: an MCP (Meta-Computation Protocol) server and CLI application that indexes Python code into a graph database (Neo4j) and exposes it via a JSON-RPC API for AI assistants and IDEs.
- The README highlights code indexing, relationship analysis, live updates (file watching), an interactive setup wizard, and a JSON-RPC server for queries.

##### File structure
Top-level directories and key files:
- src/codegraphcontext/cli: CLI entry points (main.py, setup_wizard.py)
- src/codegraphcontext/core: Core engine (database.py, jobs.py, watcher.py)
- src/codegraphcontext/tools: Code analysis and graph construction (code_finder.py, graph_builder.py, import_extractor.py, system.py)
- src/codegraphcontext/server.py: MCP/JSON-RPC server implementation
- src/codegraphcontext/prompts.py, utils/debug_log.py: helper modules
- pyproject.toml: build configuration and dependencies
- .github/workflows/test.yml: CI pipeline
- tests/: integration and unit tests

##### README for additional insights
- Architecture hints: MCP client/server, Neo4j backend, Watchdog for file watching, Typer for CLI, Requests for HTTP clients.
- Features: interactive setup (wizard), live updates (file watcher + background jobs), JSON-RPC API.

a. Main components:
1. CLI Layer
- Commands: `cgc setup`, `cgc start`, `cgc watch`, `cgc index`, etc.
- Implements interactive setup wizard, writes `mcp.json`, IDE config.
2. Core Engine
- jobs.py: orchestrates tasks (indexing, watching)
- watcher.py: uses Watchdog to detect FS changes
- tools: code_finder, import_extractor, graph_builder build the AST and graph data
- database.py: Neo4j driver wrapper, sessions, Cypher queries
3. MCP Server (server.py)
- JSON-RPC over HTTP
- Exposes methods: list_imports, add_code_to_graph, check_job_status, etc.
4. External Services
- Neo4j instance (local via Docker or remote)
- IDE/AI clients (VS Code, Claude, Gemini) acting as MCP clients
5. Configuration & State
- mcp.json, `~/.codegraphcontext/.env`
- pyproject.toml, Docker compose (in wizard)
b. Relationships and interactions:
- User invokes CLI → CLI calls core.jobs or server.start
- jobs module uses tools to parse code → pushes nodes/edges to database module → Neo4j
- watcher monitors FS events → signals jobs to re-index changed files
- server listens for client requests → dispatches to tools/database
- clients communicate with server over JSON-RPC (HTTP/WebSocket)
c. Architectural patterns & principles:
- Layered architecture: Presentation (CLI), Application (core), Data (DB)
- Plugin-like tools: code analysis is modularized
- Event-driven updates: file watcher triggers new indexing jobs
- Client-server: MCP JSON-RPC interface
d. Technologies & frameworks:
- Typer for CLI
- Watchdog for file watching
- Neo4j Python driver for database access
- Requests for HTTP calls
- Rich/InquirerPy for wizard UI
- stdlibs for project introspection
- python-dotenv for env config

##### Elements
- Clear labels: “CLI (cgc)”, “Core Engine (jobs, watcher, tools)”, “Neo4j Database”, “MCP Server (JSON-RPC)”, “IDE/AI Clients”
- User → CLI
- CLI ↔ Core Engine
- Core Engine → Neo4j
- Watcher → Core Engine
- IDE Client → MCP Server → Core Engine → Neo4j
- Rectangles for software modules
- Parallelograms or clouds for external clients/services

##### Detailed capture of essential architectural elements
[User & IDE clients]
↓
[CLI layer] ←→ [MCP Server layer]
↓                ↓
[Core Engine: jobs, watcher, tools]
↓
[Database Module]
↓
(Neo4j instance)
- “Setup Wizard” as a sub-flow under CLI that writes config files and provisions Neo4j (Docker or remote).
- Interactions (e.g., “build graph via graph_builder”, “execute Cypher query”, “respond JSON-RPC”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User["User"]:::external
    IDEClients["IDE/AI Clients"]:::external

    %% CLI and Server Layers
    subgraph "CLI Layer"
        direction TB
        Main["main.py"]:::internal
        Wizard["setup_wizard.py"]:::internal
        Prompts["prompts.py"]:::internal
    end

    subgraph "MCP Server Layer"
        direction TB
        Server["server.py"]:::internal
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        direction TB
        Jobs["jobs.py"]:::internal
        Watcher["watcher.py"]:::internal
        subgraph "Tools"
            direction TB
            CodeFinder["code_finder.py"]:::tools
            ImportExtractor["import_extractor.py"]:::tools
            GraphBuilder["graph_builder.py"]:::tools
            SystemIntrospect["system.py"]:::tools
        end
        DatabaseWrapper["database.py"]:::dbclass
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        DebugLog["debug_log.py"]:::utilclass
    end

    %% Configuration & Build
    subgraph "Configuration & Build"
        direction TB
        PyProject["pyproject.toml"]:::configclass
        CI[".github/workflows/test.yml"]:::configclass
    end

    %% Tests
    subgraph "Tests"
        direction TB
        TestRPC["test_jsonrpc.py"]:::testclass
        TestCLI["test_cgc_integration.py"]:::testclass
        TestTools["test_tools.py"]:::testclass
        SampleProj["tests/sample_project/"]:::testclass
    end

    %% Database
    Neo4j[(Neo4j Database)]:::database

    %% Relationships
    User -->|uses| Main
    User -->|uses| Server
    IDEClients -->|MCP JSON-RPC| Server

    Main -->|"orchestrates"| Jobs
    Wizard -->|writes config & provisions DB| PyProject
    Wizard -->|writes config| CI
    Prompts -->|provides UI| Wizard

    Server -->|dispatches jobs| Jobs
    Server -->|queries| DatabaseWrapper

    Watcher -->|FS events| Jobs
    Jobs -->|calls tools| CodeFinder
    Jobs -->|calls tools| ImportExtractor
    Jobs -->|calls tools| GraphBuilder
    Jobs -->|calls tools| SystemIntrospect

    CodeFinder -->|AST nodes| GraphBuilder
    ImportExtractor -->|imports| GraphBuilder
    GraphBuilder -->|builds graph| DatabaseWrapper
    SystemIntrospect -->|env info| Jobs

    DatabaseWrapper -->|executes Cypher| Neo4j
    DebugLog -->|logs| Jobs
    DebugLog -->|logs| Server

    %% Click Events
    click Main "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/cli/main.py"
    click Wizard "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/cli/setup_wizard.py"
    click Prompts "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/prompts.py"
    click Server "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/server.py"
    click Jobs "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/core/jobs.py"
    click Watcher "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/core/watcher.py"
    click DatabaseWrapper "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/core/database.py"
    click CodeFinder "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/tools/code_finder.py"
    click ImportExtractor "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/tools/import_extractor.py"
    click GraphBuilder "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/tools/graph_builder.py"
    click SystemIntrospect "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/tools/system.py"
    click DebugLog "https://github.com/shashankss1205/codegraphcontext/blob/main/src/codegraphcontext/utils/debug_log.py"
    click PyProject "https://github.com/shashankss1205/codegraphcontext/blob/main/pyproject.toml"
    click CI "https://github.com/shashankss1205/codegraphcontext/blob/main/.github/workflows/test.yml"
    click TestRPC "https://github.com/shashankss1205/codegraphcontext/blob/main/tests/test_jsonrpc.py"
    click TestCLI "https://github.com/shashankss1205/codegraphcontext/blob/main/tests/test_cgc_integration.py"
    click TestTools "https://github.com/shashankss1205/codegraphcontext/blob/main/tests/test_tools.py"
    click SampleProj "https://github.com/shashankss1205/codegraphcontext/tree/main/tests/sample_project/"

    %% Styles
    classDef external fill:#D6E9FE,stroke:#1E70BF,color:#1E70BF
    classDef internal fill:#E8F6E4,stroke:#2D7A2F,color:#2D7A2F
    classDef tools fill:#FFF4E5,stroke:#BF7100,color:#BF7100
    classDef dbclass fill:#FFEFEF,stroke:#BF1E1E,color:#BF1E1E
    classDef utilclass fill:#F0EFFF,stroke:#6B1EBF,color:#6B1EBF
    classDef configclass fill:#F7F7F7,stroke:#555555,color:#555555
    classDef testclass fill:#E8E8E8,stroke:#888888,color:#888888
    classDef database fill:#FFF9C4,stroke:#F0AD4E,color:#F0AD4E
```
