Skip to content

Commit 1a5959f

Browse files
Shashankss1205Shashankss1205
committed
Docs updated with latest changes
1 parent 9494095 commit 1a5959f

29 files changed

Lines changed: 1211 additions & 942 deletions

‎docs/docs/architecture.md‎

Lines changed: 44 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,60 @@
1-
# Architecture Documentation
1+
# System Architecture
22

3-
This document provides a detailed overview of the architecture of the CodeGraphContext project.
3+
CodeGraphContext (CGC) is a **context-aware code intelligence engine** that bridges the gap between your source code and your AI tools.
44

5-
## High-Level Overview
5+
It operates primarily as a background service (MCP Server) backed by a graph database, with a CLI for management.
66

7-
The project is a client-server application designed to analyze and visualize codebases. It consists of:
7+
## High-Level Diagram
88

9-
* **A Python backend:** This is the core of the application, responsible for parsing and analyzing code, building a graph representation of the codebase, and exposing this data through an API.
10-
* **A web-based frontend:** A user interface for interacting with the backend, visualizing the code graph, and exploring the codebase.
11-
* **A command-line interface (CLI):** For managing the backend and performing analysis from the terminal.
9+
```mermaid
10+
graph TD
11+
Client[AI Client / CLI]
12+
Server[MCP Server]
13+
Graph[Graph Builder]
14+
DB[(Graph Database)]
15+
FS[File System]
1216
13-
## Backend Architecture
17+
Client -- "1. Query (MCP/CLI)" --> Server
18+
Server -- "2. Read Graph" --> DB
19+
Server -- "3. Trigger Index" --> Graph
20+
Graph -- "4. Scan Code" --> FS
21+
Graph -- "5. Store Nodes" --> DB
22+
```
1423

15-
The backend is a Python application located in the `src/codegraphcontext` directory.
24+
## 1. The Core (Backend)
1625

17-
### Core Components
26+
The "brain" of the operation lives in `src/codegraphcontext`. It is a pure Python application.
1827

19-
The `src/codegraphcontext/core` directory contains the fundamental building blocks of the backend:
28+
| Component | Responsibility |
29+
| :--- | :--- |
30+
| **Server (`server.py`)** | Acts as the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) host. It translates JSON requests from Claude/Cursor into database queries. |
31+
| **Graph Builder** | The "indexer". It parses your code using **Tree-sitter**, extracts dependencies, and builds the knowledge graph. |
32+
| **Database Layer** | An abstraction layer that talks to either **FalkorDB** (embedded) or **Neo4j** (production). |
33+
| **Background Jobs** | Handles long-running tasks like "Index the entire repo" or "Watch for file changes" without blocking the AI. |
34+
| **Watcher** | A file system monitor that triggers incremental re-indexing when you save a file. |
2035

21-
* **Database:** A graph database is used to store the code graph. This allows for efficient querying of relationships between code elements (e.g., function calls, class inheritance).
22-
* **Jobs:** Asynchronous jobs are used for long-running tasks like indexing a new codebase. This prevents the application from becoming unresponsive.
23-
* **Watcher:** A file system watcher monitors the codebase for changes and triggers re-indexing, keeping the code graph up-to-date.
36+
## 2. No "Frontend" Application
2437

25-
### Tools
38+
**Important:** CodeGraphContext does **not** have a traditional web application frontend.
39+
The `website/` folder you see in the repository is strictly for **documentation** (this site).
2640

27-
The `src/codegraphcontext/tools` directory contains the logic for code analysis:
41+
Instead of a custom UI, we rely on:
2842

29-
* **Graph Builder:** This component is responsible for parsing the code and building the graph representation that is stored in the database.
30-
* **Code Finder:** Provides functionality to search for specific code elements within the indexed codebase.
31-
* **Import Extractor:** This tool analyzes the import statements in the code to understand dependencies between modules.
43+
1. **AI Chat Interfaces:** Your existing IDE chat (Cursor, VS Code) is the UI.
44+
2. **Neo4j Browser:** For advanced users wanting a raw visual exploration of the graph (available at `localhost:7474` if using Neo4j).
45+
3. **Visualizer Tool:** The CLI can generate standalone HTML files (`cgc visualize`) using Vis.js for quick inspections.
3246

33-
### Server
47+
## 3. Data Flow
3448

35-
The `src/codegraphcontext/server.py` file implements the API server. It exposes the functionality of the backend to the frontend through a JSON-RPC API.
49+
1. **Indexing:**
50+
* `cgc index .` -> Scans files -> Parses AST -> Creates Nodes (Functions, Classes) and Edges (CALLS, INHERITS) -> Saves to DB.
51+
2. **Querying (Natural Language):**
52+
* User asks "Who calls function X?" -> MCP Server receives request -> Runs Cypher Query (`MATCH (n)-[:CALLS]->(m)...`) -> Returns context to LLM.
3653

37-
### CLI
54+
## 4. Key Technologies
3855

39-
The `src/codegraphcontext/cli` directory contains the implementation of the command-line interface. It allows users to:
40-
41-
* Start and stop the backend server.
42-
* Index new projects.
43-
* Run analysis tools from the command line.
44-
45-
## Frontend Architecture
46-
47-
The frontend is a modern web application located in the `website/` directory.
48-
49-
* **Framework:** It is built using React and TypeScript.
50-
* **Build Tool:** Vite is used for fast development and building the application.
51-
* **Component-Based:** The UI is organized into reusable components, located in `website/src/components`. This includes UI elements like buttons and dialogs, as well as higher-level components for different sections of the application.
52-
* **Styling:** Tailwind CSS is used for styling the application.
53-
54-
## Testing
55-
56-
The `tests/` directory contains the test suite for the project.
57-
58-
* **Integration Tests:** `test_cgc_integration.py` contains tests that verify the interaction between different components of the backend.
59-
* **Unit Tests:** Other files in this directory contain unit tests for specific modules and functions.
60-
* **Sample Project:** The `tests/sample_project` directory contains a variety of Python files used as input for testing the code analysis tools.
56+
* **Language:** Python 3.10+
57+
* **Parsing:** Tree-sitter (for robust, multi-language support)
58+
* **Protocol:** Model Context Protocol (MCP)
59+
* **Database:** FalkorDB (via Redis) or Neo4j
60+
* **CLI:** Typer / Click

‎docs/docs/cli.md‎

Lines changed: 0 additions & 166 deletions
This file was deleted.

‎docs/docs/concepts/how_it_works.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# How It Works
2+
3+
Understanding the pipeline helps you write better queries.
4+
5+
## 1. Parsing (Tree-Sitter)
6+
We use **Tree-Sitter** to parse your source code into an Abstract Syntax Tree (AST). This allows us to support many languages (Python, JS, Go, etc.) with high accuracy.
7+
8+
## 2. Graph Construction
9+
We walk the AST and generate **Nodes** and **Edges**.
10+
11+
* **Nodes:** Entities like `Class`, `Function`, `File`, `Module`.
12+
* **Edges:** Relationships like `CALLS`, `IMPORTS`, `INHERITS`.
13+
14+
## 3. Storage
15+
These nodes and edges are written to the Graph Database (FalkorDB or Neo4j).
16+
17+
## 4. Querying
18+
When you ask "Who calls X?", we translate that into a Cypher query:
19+
20+
```cypher
21+
MATCH (caller:Function)-[:CALLS]->(callee:Function {name: 'X'})
22+
RETURN caller
23+
```

‎docs/docs/concepts/modes.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# CLI Mode vs. MCP Mode
2+
3+
CodeGraphContext has a "dual personality".
4+
5+
## 🛠️ Mode 1: The CLI Tool
6+
**"I want to ask questions."**
7+
8+
In this mode, YOU are the intelligent agent. You use terminal commands (`cgc analyze`) to explore the codebase.
9+
* **Best for:** Architecture reviews, refactoring planning, exploring new codebases.
10+
* **Interface:** Terminal.
11+
12+
## 🤖 Mode 2: The MCP Server
13+
**"I want my AI to know the answers."**
14+
15+
In this mode, the AI (Cursor/Claude) is the agent. It asks the questions.
16+
* **Best for:** Coding assistance, "Chat with Codebase", debugging help.
17+
* **Interface:** Natural Language Chat in your IDE.
18+
19+
---
20+
21+
**Crucially: They share the same database.**
22+
You can `cgc index` a repo in your terminal, and then immediately ask your AI about it.

‎docs/docs/concepts/the_graph.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# The Graph Model
2+
3+
What does "Code as a Graph" actually look like?
4+
5+
## Nodes (The Nouns)
6+
7+
The graph contains these primary node types:
8+
9+
* **`File`**: A physical file on disk (e.g., `main.py`).
10+
* **`Function`**: A function definition (e.g., `def process_data()`).
11+
* **`Class`**: A class definition (e.g., `class User`).
12+
* **`Module`**: A logical grouping (e.g., a Python package).
13+
* **`Import`**: Represents an external dependency (e.g., `import requests`).
14+
15+
## Relationships (The Verbs)
16+
17+
Edges connect the nodes to describe interaction:
18+
19+
* `(:Function)-[:CALLS]->(:Function)`: Function A calls Function B.
20+
* `(:Class)-[:INHERITS]->(:Class)`: Class A extends Class B.
21+
* `(:File)-[:CONTAINS]->(:Function)`: Where the code lives.
22+
* `(:File)-[:IMPORTS]->(:Module)`: Dependency usage.
23+
24+
## Example Query
25+
26+
Using Cypher, you can query this structure:
27+
28+
```cypher
29+
// Find all classes that inherit from 'BaseModel'
30+
MATCH (c:Class)-[:INHERITS]->(p:Class {name: 'BaseModel'})
31+
RETURN c.name
32+
```

0 commit comments

Comments
 (0)