🧠 ARIA

AI-Powered Repository Intelligence Agent

ARIA is an AI-powered repository intelligence platform built on the Repository Intelligence Architecture (RIA) — a modular, layered architecture designed for AI-native repository understanding. ARIA combines AST analysis, dependency graphs, call graphs, semantic search, AI repository chat, PR intelligence, and a VS Code extension to help developers understand unfamiliar repositories faster. v1.5.0 introduces production-ready Model Context Protocol (MCP) servers, enabling AI coding assistants such as Cursor, Claude Desktop, VS Code MCP clients, and MCP Inspector to interact with repository intelligence directly over JSON-RPC 2.0.

🎥 Live Demo · ⚡ Quick Start · 🚀 Capabilities · 🏗️ Architecture · 📡 API Reference · 🗺️ Roadmap

---

🚀 What's New in v1.5.0

Version v1.5.0 represents the largest architectural evolution of the project to date.

Highlights

• 🏗️ Repository Intelligence Architecture (RIA v1)
• 🌌 Interactive Repository Topology & Scene-Based Product Experience
• 🤖 Production Model Context Protocol (MCP) Integration Layer
• ⚡ Dual MCP Server Architecture (Legacy JSON-RPC + FastMCP)
• 🔍 Graph-Based Repository Intelligence (Directed Dependency Graph, AST Call Graph, Impact Analysis)
• 🧠 AI Repository Chat v2 & Grounded Semantic Retrieval
• 📊 Intelligence Reports & Multi-Axis Health Scorecards
• 🗺️ Centrality-Ranked Onboarding Reading Paths & Executive Insights
• 🛡️ Resilient Dual LLM Provider Architecture with Deterministic Error Classification
• 💻 Enhanced VS Code Extension Integration
• 🧪 Comprehensive Test Suite (2,780+ Passing Automated Tests across Python and Frontend)
• 🌐 Cross-Platform Production Validation (Windows, Linux, macOS)

---

🎥 Live Demo

▶ Click the GIF to watch the complete demo on YouTube

---

🚀 Why ARIA?

Most AI code assistants treat repositories as collections of text chunks. They retrieve similar snippets using embeddings but lack an understanding of the repository's structure.

ARIA takes a different approach.

Before any AI reasoning happens, it builds a structural understanding of the repository using AST parsing, dependency graphs, call graphs, and symbol indexing. This enables the AI to reason about relationships between modules, identify architectural patterns, estimate change impact, and answer questions with structural context rather than semantic similarity alone.

The result is more reliable repository understanding, better developer workflows, and insights that traditional RAG-based systems cannot provide.

As of v1.5.0, the platform is organized around the Repository Intelligence Architecture (RIA v1) — a layered architecture that separates the Agent Layer, Application Layer, Domain Layer, Infrastructure Layer, Repository Intelligence Services, Production MCP Integration Layer, API Layer, VS Code Extension, and Dashboard into well-defined boundaries. Every capability — from graph intelligence and semantic search to MCP tool serving and intelligence reports — operates within RIA.

Repository Intelligence Architecture (RIA v1) serves as the architectural foundation of the platform. Every subsystem—including repository analysis, graph intelligence, semantic search, AI reasoning, the Production MCP Integration Layer, REST APIs, the VS Code extension, and future multi-agent workflows—operates within RIA, providing clear boundaries, maintainability, extensibility, and production scalability.

🏛️ Architecture Principles

ARIA is built around five engineering principles:

• Structure Before Semantics — structural understanding precedes AI reasoning.
• Graph-First Intelligence — dependency graphs and call graphs are first-class knowledge sources.
• AI-Native Architecture — every subsystem is designed for intelligent developer tooling.
• Incremental Computation — recompute only what changes via content-hash detection.
• Production-Ready Interfaces — every capability is exposed consistently through APIs, MCP, and IDE integrations.

---

🎯 Who Is This For?

ARIA is designed for developers and teams who need to understand complex codebases quickly.

User	How It Helps
👨‍💻 Software Engineers	Understand unfamiliar repositories without reading hundreds of files.
🔓 Open Source Contributors	Navigate large projects, trace dependencies, and estimate change impact before submitting pull requests.
🏗️ Tech Leads & Architects	Analyze architecture, module coupling, dependency graphs, and code quality.
🤖 AI Engineering Teams	Build AI-powered developer tools on top of structured repository intelligence instead of plain vector search.
🛠️ Maintainers	Detect dead code, architectural drift, hotspot files, and repository health issues.

---

🖼️ Preview Images

Codebase Dashboard	Interactive Dependency Graph
Streaming Repository Chat	Intelligence Report

🔴 The Problem

Most codebase AI assistants run the same playbook: split source files into chunks, embed them, and retrieve by similarity. For prose, that works well. For code, it is structurally blind.

Code is not a collection of text fragments. It is a directed graph of modules, symbols, and call sites. What matters — and what vector similarity cannot surface — is:

Structural Dimension	What's Missing
📦 Import topology	Which modules depend on which, and in what direction
🔗 Call hierarchies	What a function transitively invokes across files
🎯 Reachability	Which files are actually reached from any entry point
💥 Coupling	Which files will be affected by a given change

Traditional RAG pipeline:

  Repository  →  chunk  →  embed  →  similarity search  →  LLM  →  answer
                                             ↑
                              ┌──────────────────────────┐
                              │   no import graph        │
                              │   no call graph          │
                              │   no symbol index        │
                              │   no reachability        │
                              │   no change impact       │
                              └──────────────────────────┘

Caution

The result: hallucinated import paths, missed transitive side effects, and zero blast-radius awareness. Semantic similarity is not a substitute for structural knowledge.

---

✅ The Solution

ARIA runs a structural analysis pass before any retrieval. The dependency graph, call graph, and symbol index are built first — from the AST. Retrieval is grounded in that structure, not in raw text similarity.

Repository
 ├── Tree-sitter AST ──────────→  imports · exports · symbols · call sites
 │                                               │
 │                                    NetworkX DiGraph
 │                                     ├── BFS reachability traces
 │                                     ├── centrality-ordered reading
 │                                     ├── blast-radius estimation
 │                                     └── architecture drift delta
 │
 ├── BGE-small-en-v1.5 ────────→  ChromaDB (semantic search)
 └── Git history mining ───────→  churn scores · hotspot files
                                               │
                                Gemini 2.5 Flash / DeepSeek V4 Flash
                                               │
                                   Structurally grounded answers

Important

Every LLM call receives retrieved chunks plus the structural context that makes those chunks meaningful: which modules import the file, which functions call the symbol, and which other files would be affected by a change.

---

⚡ How We Compare

Traditional RAG tools index text. This tool indexes your codebase's structure.

Capability	Traditional RAG	ARIA
🔍 Semantic code search	✅	✅
📦 Dependency graph (import topology)	❌	✅
🔗 Call graph (function-level)	❌	✅
🏷️ AST symbol index	❌	✅
🎯 Reachability traces (BFS)	❌	✅
💀 Dead code detection	❌	✅
🏗️ Architecture drift detection	❌	✅
💥 PR blast-radius scoring	❌	✅
🔥 Churn × coupling hotspot analysis	❌	✅
🔌 API surface with stability coefficients	❌	✅
⚡ Incremental analysis (hash-based)	❌	✅
📚 Onboarding reading order	❌	✅
🐛 Issue → implementation plan mapping	❌	✅
📊 Intelligence Report (HTML / PDF / MD)	❌	✅
🧠 Rule-based intent routing (zero LLM overhead)	❌	✅
🔄 Circuit-breaker LLM failover	❌	✅
📈 Prometheus observability	❌	✅
🧠 Model Context Protocol (MCP)	❌	✅
🔌 JSON-RPC 2.0 Tool Server	❌	✅
🤖 AI Agent Integration (Cursor, Claude Desktop)	❌	✅
🖥️ VS Code MCP Client Compatibility	❌	✅

---

🚀 Capabilities

🔬 Repository Analysis

Full structural pipeline — Clone any public GitHub repository and run AST parsing, embedding, graph construction, and analysis in one command. Pipeline stages run as a DAG — tasks are parallelized where dependencies allow.

Incremental rebuilds — Changed files are detected by content hash. On subsequent runs, only modified files are re-parsed, re-embedded, and re-indexed. Small change sets rebuild in under 2 seconds (typical development-machine measurements).

Tech stack detection — Automatically identifies languages, frameworks, and build tooling from file extensions and configuration files before analysis begins.

🧠 Code Intelligence

Feature	What It Does
Symbol Index	AST-extracted index of every class, function, and method across the repository. Definition lookup and cross-file reference search — no language server required.
Dead Code Detection	Reachability sweep from detected entry points across the full dependency graph. Identifies unused files, orphaned modules, and dead dependency chains. Each finding carries a cleanup score (0–100) to prioritize remediation.
API Surface Intelligence	Classifies every exported symbol as public, internal, or deprecated. Computes Martin's instability coefficients per module. Detects breaking changes between repository versions.
Churn Analysis	Mines git commit history to produce per-file churn scores. Identifies hotspot files — those with high churn combined with high coupling — with weekly activity timelines.

🌐 Graph Intelligence

Architecture Graph — Interactive React Flow dependency graph with search filtering, node neighborhood inspection, forward/backward BFS reachability traces, and DAG/hierarchical layout options. Visualizes the full import topology of the repository.

Call Graph — Function-level call graph built from AST analysis. Distinguishes callers from callees with explicit edge directionality, supports call hierarchy walks, and computes blast-radius estimation per function.

Impact Analysis Graph — Change-propagation graph tracing how modifications in a specific file or symbol ripple outward to downstream components and automated test suites.

Shared Edge Semantics — Cohesive visual and directional edge language distinguishing composition, imports, dependencies, function invocations, and change propagation.

💬 Developer Workflows

Workflow	What It Does
Repository Chat	Streaming chat over any indexed repository via Server-Sent Events. Nine intent types are detected by a rule-based classifier — no LLM call is made for routing. Each response includes source citations and a confidence score.
PR Intelligence	Risk-scores pull requests by size (XS → XL) and blast radius (LOW → EXTREME). Detects architectural drift by delta-patching the dependency graph against the PR's changed files.
Issue Mapper	Maps GitHub issues to source files using embedding retrieval and two targeted LLM calls — one to rank candidate files, one to generate an implementation plan. Results are cached to avoid redundant API calls.
Executive Insights	Derives plain-language architectural findings directly from repository metrics — highlighting circular dependencies, density, onboarding effort, test presence, and documentation depth.
Reading Order Timeline	Generates a centrality-ranked, step-by-step reading sequence optimized for rapid onboarding to an unfamiliar codebase.

📊 Intelligence Report — The Flagship Output

Aggregates every analysis dimension into a unified health report scored across five axes:

Dimension	What Is Measured
🏗️ Architecture Stability	Module coupling · circular dependency depth · instability coefficients
🔌 API Quality	Public / internal / deprecated symbol ratios · breaking change count
🧹 Code Hygiene	Dead code ratio · orphaned module count
🔥 Hotspot Risk	Churn × coupling composite score per file
📚 Onboarding Clarity	Reading-order quality · entry-point coverage

Export formats: Interactive HTML · Print-optimized PDF · Collapsible Markdown (suitable for GitHub PR comments)

🔌 VS Code Extension Integration

Brings the full power of codebase intelligence directly into your editor:

Capability	What It Provides
Engineering Findings	Inline list of code smells, coupling issues, and quality recommendations.
Advisor Dashboard	Phased refactoring roadmaps and priority recommendations visible inside VS Code.
Execution Planner	Interactively trace the generated execution batches, critical paths, and safety checkpoints.
Hover Intelligence	Hover over functions, classes, or imports to see AST symbols, definitions, and docstrings.
CodeLens Triggers	Actions directly above functions to "Show Callers", "Show Blast Radius", or "Ask Agent".
Code Actions	Highlight code and press Ctrl+. / Cmd+. to request refactoring suggestions.
Interactive Graph Navigation	Open Dependency or Call Graphs on a visual canvas within the editor.
Repository Search & Switching	Set active repository, search symbols, and switch between codebases instantly.
Diagnostics & Settings	Built-in diagnostics view monitoring backend connection status, LLM health, and configurations.
Recommendation Persistence	Persistently ignore specific recommendations, which will be cached across indexing cycles.

---

🧠 Model Context Protocol (MCP)

The Production MCP Integration Layer is a first-class subsystem within the Repository Intelligence Architecture (RIA v1), exposing repository intelligence capabilities to AI coding assistants through the Model Context Protocol (MCP). Any MCP-compatible client can connect over stdio and invoke tools, query resources, and use prompt templates — without needing the REST API or dashboard.

Dual MCP Architecture

The project ships two complementary MCP server implementations:

Server	Entry Point	Transport	Purpose
Legacy MCP Server	backend/mcp_server.py	stdio (JSON-RPC 2.0)	Production stdio server — lightweight, zero SDK dependencies, direct JSON-RPC over stdin/stdout
FastMCP Server	mcp/server.py	stdio · SSE	FastMCP SDK integration — automatic tool discovery, resource templates, prompt templates, and Server-Sent Events support

Supported MCP Clients

Client	Status
🖱️ Cursor	✅ Verified
🤖 Claude Desktop	✅ Verified
🔌 VS Code MCP	✅ Verified
🔍 MCP Inspector	✅ Verified
🛠️ Custom JSON-RPC Clients	✅ Compatible

Production Validation Status (v1.5.0): JSON-RPC 2.0 compliant · Legacy stdio server verified · FastMCP server verified · Cursor verified · Claude Desktop verified · VS Code MCP verified · MCP Inspector verified · Cross-platform transport validated (Windows, Linux, macOS)

Transport Support

Transport	Server	Status
stdio	Legacy MCP + FastMCP	✅
Server-Sent Events (SSE)	FastMCP	✅

Production Features

• JSON-RPC 2.0 compliant — full protocol conformance with proper error codes
• Automatic Tool Discovery — tools are registered from decorated handler functions
• Resource Templates — repository-scoped resources for structured data access
• Prompt Templates — pre-built prompts for common analysis workflows
• Structured Error Responses — client-safe error messages with traceback sanitization
• Windows / Linux / macOS validated — cross-platform stdio transport verified
• Production-ready transport — unbuffered I/O, graceful shutdown, pipe safety guards
• Manual MCP Inspector verification — every tool validated through interactive Inspector sessions

🔧 MCP Tool Inventory

Repository Tools

Tool	Description
list_repositories	List all indexed repositories
get_repository_summary	Full structural summary for a repository
query_codebase	Natural language query over indexed code

Navigation Tools

Tool	Description
get_file_symbols	AST-extracted symbols for a file
get_symbol_definition	Definition lookup across the repository
get_symbol_references	Cross-file reference search

Architecture Tools

Tool	Description
get_call_graph	Function-level call graph
get_dead_code	Reachability sweep for unused code
get_impact_analysis	Change impact prediction

Extended FastMCP Tools

Tool	Description
semantic_search	Embedding-based code search
architecture_overview	High-level architecture summary
dependency_analysis	Module dependency analysis
api_surface	Public/internal API classification
workspace_snapshot	Consolidated workspace metrics
health_report	Repository health scorecard
execution_trace	Execution plan trace
report_generation	Intelligence report generation

🚀 MCP Quick Start

# Start the MCP server (communicates over stdio using JSON-RPC 2.0)
python -m backend.cli mcp

The server reads JSON-RPC requests from stdin and writes responses to stdout. Connect directly from any MCP-compatible client:

• Cursor — Add to your MCP configuration
• Claude Desktop — Register in claude_desktop_config.json
• VS Code MCP — Configure as an MCP server in settings
• MCP Inspector — Connect via npx @modelcontextprotocol/inspector

MCP Architecture

flowchart TD
    A["AI Client\nCursor · Claude Desktop · VS Code MCP · Inspector"] -->|"JSON-RPC 2.0\nstdio"| B["Legacy MCP Server\nbackend/mcp_server.py"]
    A -->|"JSON-RPC 2.0\nstdio · SSE"| C["FastMCP Server\nmcp/server.py"]

    B --> D["Repository Intelligence Services"]
    C --> D

    subgraph services["Intelligence Layer"]
        D --> D1["Symbol Service"]
        D --> D2["Call Graph Service"]
        D --> D3["Dead Code Service"]
        D --> D4["Retrieval Engine"]
        D --> D5["Architecture Service"]
    end

    subgraph data["Data Layer"]
        D1 --> S1[("Analysis Store")]
        D2 --> S1
        D3 --> S1
        D4 --> S2[("ChromaDB")]
        D5 --> S3[("NetworkX DiGraph")]
    end

Loading

💡 Why RIA?

Traditional RAG

Repository
      │
      ▼
Chunks
      │
      ▼
Embeddings
      │
      ▼
LLM

────────────────────────────

Repository Intelligence Architecture (RIA)

Repository
      │
      ▼
AST
      │
      ▼
Knowledge Graph
      │
      ▼
Dependency Graph
      │
      ▼
Call Graph
      │
      ▼
Symbol Index
      │
      ▼
Semantic Search
      │
      ▼
LLM

---

🏗️ Architecture — Repository Intelligence Architecture (RIA)

flowchart TD
    A["Astro 4 + React\n:4321"] -->|"HTTP · SSE"| B["FastAPI Gateway\n:8001\n\nRateLimit · GZip · CORS\nRequestId · Prometheus"]

    B --> C["Analysis Pipeline"]
    B --> D["Chat Pipeline v2"]

    subgraph ingestion["Ingestion & Indexing"]
        C --> C1["GitHub Clone"]
        C1 --> C2["Tree-sitter AST\nimports · exports · symbols"]
        C2 --> C3["BGE Embeddings\nbge-small-en-v1.5"]
        C3 --> C4[("ChromaDB\nvector store")]
        C2 --> C5[("NetworkX DiGraph\ndependency + call graph")]
        C2 --> C6["Symbol Index\ncross-file references"]
    end

    subgraph chat["Chat Pipeline"]
        D --> D1["Intent Detector\n9 types · rule-based\nzero LLM overhead"]
        D1 --> D2["Intent Router"]
        D2 --> D3["Retrieval + Rerank\ntop-15 → top-5"]
        D3 --> D4["Context Builder\ntoken budget management"]
        D4 --> D5["ProviderManager\ncircuit breaker · failover"]
    end

    subgraph llm["LLM Layer"]
        D5 -->|"primary"| L1["Gemini 2.5 Flash"]
        D5 -->|"fallback"| L2["DeepSeek V4 Flash\nNVIDIA NIM"]
        D5 -->|"no-LLM mode"| L3["Fallback Renderer\nstructured response"]
    end

    subgraph storage["Data Layer"]
        C4
        C5
        DB1[("SQLite\nreports · state")]
        DB2["JSON Snapshots\nanalysis cache"]
        CA["In-memory Cache\nschema-versioned"]
    end

    C4 --> D3
    C5 --> D3

Loading

The platform is organized around the Repository Intelligence Architecture (RIA), which separates concerns across well-defined layers: the API Layer (FastAPI gateway), the Application Layer (analysis and chat pipelines), the Domain Layer (graph, symbol, and retrieval services), the Infrastructure Layer (ChromaDB, NetworkX, SQLite), and the MCP Integration Layer (Legacy + FastMCP servers). The Dashboard (Astro 4 + React) and VS Code Extension consume these layers through REST APIs and Workspace snapshots.

🗂️ Full component diagrams, sequence diagrams, and mathematical models are documented in ARCHITECTURE.md.

🧬 Codebase Intelligence Pipeline

The Repository Intelligence Architecture processes repository structures through an end-to-end multi-tier pipeline:

1. Repository Ingestion: Clones files and identifies program stacks.
2. Digital Twin: Generates a local AST representation of all code symbols, imports, and exports.
3. Knowledge Graph: Builds a directed import graph and function call graph via NetworkX.
4. Inspection Pipeline: Automatically sweeps the graph to detect circular dependencies, code smells, and dead code.
5. AI Advisor: Evaluates findings and generates prioritized recommendations and phased engineering roadmaps.
6. Execution Planner: Formulates concrete, conflict-free execution plans with rollback safety checkpoints.
7. Workspace APIs: Consolidates all metrics, findings, and plan states into a unified snapshot endpoint.
8. VS Code Extension: Consumes the Workspace APIs to power hovers, tree views, and graph webviews.

---

⚙️ How It Works

Each repository analysis runs through eight sequential stages. Incremental mode re-runs only stages 2–6 for files that have changed since the last run.

View the 8-stage analysis pipeline

Stage	Name	Input → Output	Why It Matters
1	Clone	GitHub URL → local working copy	Provides the file tree and git history for all downstream stages
2	Parse	Source files → AST nodes	Extracts structural information that text chunking cannot recover
3	Embed	Code chunks → BGE-small-en-v1.5 vectors	Enables semantic search over code semantics
4	Index	Vectors + metadata → ChromaDB	Persists embeddings for retrieval without re-encoding on each query
5	Graph	AST import/call nodes → NetworkX DiGraph	Enables reachability traces, centrality ranking, and blast-radius estimation
6	Analyze	Graph + git history → scores + findings	Produces the structural intelligence that grounds LLM responses
7	Reason	Query + chunks + structural context → answer	LLM operates on structurally filtered context, not raw similarity results
8	Deliver	All outputs → Dashboard · Chat · Report · REST API	Multiple consumption surfaces for different developer workflows

Tip

Why incremental is fast: Subsequent runs skip re-embedding and re-indexing for unchanged files. Only files whose content hash has changed are re-processed through the pipeline. Graph nodes for unchanged files are read from the schema-versioned in-memory cache rather than recomputed (typical development-machine measurements).

📈 Repository Statistics

Category	Details
Architecture	Repository Intelligence Architecture (RIA v1)
Languages	Python, TypeScript, JavaScript
AI Providers	Google Gemini, DeepSeek (via NVIDIA NIM)
Knowledge Layer	AST + Dependency Graph + Call Graph + Symbol Index
Retrieval	ChromaDB + Local Semantic Search (BGE-small)
AI Interfaces	REST API + Production MCP Integration Layer
IDE Integration	VS Code Extension
Dashboard	Astro 4 + React 18 (with Interactive Software Topology)
Automated Tests	2,780+ Passing Tests (2,531 Python + 248 Frontend)

---

🛠️ Technology Stack

Layer	Technology	Purpose
Frontend	Astro 4 + React 18	Dashboard, interactive topology, chat UI, report viewer
Graph UI	React Flow + Dagre	Architecture, call graph, and impact graph visualization
Backend	FastAPI	Async API gateway, middleware stack, Server-Sent Events
AST Parsing	Tree-sitter	Language-agnostic symbol, import, and call site extraction
Embeddings	BAAI/bge-small-en-v1.5	Local code chunk vector encoding — no external API cost
Vector Store	ChromaDB	Persistent local vector search and similarity retrieval
Graph Engine	NetworkX	Directed graphs, BFS traversal, centrality ranking, cycle detection
Primary LLM	Gemini 2.5 Flash	Structured reasoning, explanation, and grounded answers
Fallback LLM	DeepSeek V4 Flash (NVIDIA NIM)	Secondary provider managed via circuit-breaker failover
Error Classification	Deterministic ProviderErrorType	Classifies SDK errors into 9 actionable categories with remediation guidance
Persistence	SQLite + JSON snapshots	Reports, workspace caches, and analysis snapshots
Metrics	Prometheus	HTTP request metrics and build pipeline histograms
MCP	Model Context Protocol	JSON-RPC 2.0 tool server for AI coding assistants (Cursor, Claude Desktop, VS Code)
Testing & Quality	pytest + Node Test Runner	2,780+ automated tests across backend, frontend, and MCP suites

View directory layout

Repo-Intelligence-Agent/
├── backend/
│   ├── api.py                     # App factory, middleware stack, router registration
│   ├── main.py                    # Uvicorn entry point with watch-dir filtering
│   ├── settings.py                # Pydantic Settings — all configuration via env vars
│   ├── dependencies.py            # Service singletons and analysis store
│   ├── security_middleware.py     # Sliding-window rate limiter (per IP)
│   ├── metrics_middleware.py      # Prometheus HTTP metrics
│   └── routers/                   # One router module per feature domain
│
├── services/
│   ├── chat/                      # Chat v2 pipeline
│   │   ├── retrieval_pipeline.py  # Authoritative pipeline entry point
│   │   ├── intent_detector.py     # Rule-based classifier, 9 intent types
│   │   ├── intent_router.py       # Routes intents to structured services
│   │   ├── conversation_memory.py # Session memory and pronoun resolution
│   │   ├── retrieval.py           # Tier-weighted chunk reranking
│   │   ├── context_builder.py     # Token budget management
│   │   ├── provider_manager.py    # Circuit breaker and provider failover
│   │   └── fallback_renderer.py   # Structured response without LLM
│   ├── llm/
│   │   ├── gemini_provider.py     # Gemini 2.5 Flash integration
│   │   ├── deepseek_provider.py   # DeepSeek V4 Flash via NVIDIA NIM
│   │   ├── provider_errors.py     # Deterministic ProviderError classification
│   │   └── provider_factory.py    # Singleton, hot-reload, startup validation
│   ├── report/
│   │   ├── composer.py            # Assembles ReportDataModel from all services
│   │   └── renderer.py            # HTML, Markdown, and PDF renderers
│   └── *.py                       # Architecture, graph, symbol, PR, drift, churn services
│
├── agents/                        # IssueMapper, EvaluationAgent
├── core/
│   ├── cache.py                   # Schema-versioned in-memory cache
│   ├── change_detector.py         # File hash-based incremental detection
│   ├── analysis_registry.py       # DAG task registry
│   └── build_pipeline.py          # DAG orchestration
├── ria/                           # Repository Intelligence Architecture (RIA) — v1.5.0
│   ├── agent/                     # Agent Layer
│   ├── application/               # Application Layer
│   ├── domain/                    # Domain Layer
│   ├── infrastructure/            # Infrastructure Layer
│   ├── plugins/                   # Language plugins and extensions
│   ├── search/                    # Semantic search services
│   ├── query/                     # Query engine and ports
│   ├── knowledge/                 # Knowledge graph services
│   ├── ports/                     # Hexagonal port interfaces
│   └── container.py               # Dependency injection container
├── mcp/
│   ├── server.py                  # FastMCP server — automatic tool discovery, resources, prompts
│   ├── tools/                     # MCP tool handlers (repository, symbol, architecture, search, analysis, report, workspace)
│   └── resources/                 # MCP resource providers
│
├── memory/                        # ChromaStore adapter
├── models/                        # Pydantic domain models
├── storage/                       # JsonSnapshotStore, SQLite migrations
├── frontend/                      # Astro 4 + React dashboard & interactive topology
├── tests/                         # 2,780+ passing tests (backend + frontend + extension + MCP)
└── docs/                          # Extended documentation

---

⚡ Quick Start

Prerequisites

Requirement	Version / Notes
Python	≥ 3.11 (Docker 3.11, CI 3.12)
Node.js	≥ 18
Git	Any recent version
LLM API key	Google Gemini or NVIDIA NIM
Disk space	~2 GB (BGE model cache on first run)

1 — Backend

git clone https://github.com/VarshithReddy2006/Repo-Intelligence-Agent.git
cd Repo-Intelligence-Agent

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .

cp .env.example .env
# Open .env and set GEMINI_API_KEY or DEEPSEEK_API_KEY

python backend/main.py           # API starts at http://localhost:8001

2 — Frontend

cd frontend
npm install
npm run dev                      # Dashboard at http://localhost:4321

3 — Docker (recommended for production)

# Production
docker compose -f docker-compose.prod.yml up -d --build

# Development with hot reload
docker compose -f docker-compose.dev.yml up -d --build

Note

Named volumes mount data/ (ChromaDB, graphs, SQLite) and the cloned repository cache independently of the container lifecycle. Data persists across container restarts.

4 — VS Code Extension

cd vscode-extension
npm install
npm run compile
npx @vscode/vsce package --allow-missing-repository

Brief Setup:

1. In VS Code, install the generated repo-intelligence-agent-0.1.0.vsix file using the Install from VSIX... command.
2. Start the local backend server (running on port 8001).
3. Open your target codebase repository folder in VS Code.
4. Open the Command Palette (Ctrl+Shift+P), select Set Active Repository, and enter the owner/repo details.
5. Click Analyze Repository in the sidebar.
6. Verify your findings, advisor recommendations, and execution planner routes inside the custom views.

5 — Verify

curl http://localhost:8001/health

{
  "backend": "online",
  "llm_provider": "gemini",
  "llm_model": "gemini-2.5-flash",
  "embedding_provider": "BAAI/bge-small-en-v1.5",
  "vector_db": "chromadb",
  "status": "healthy"
}

6 — Start MCP Server

python -m backend.cli mcp

The MCP server communicates over JSON-RPC 2.0 using stdio. It is compatible with Cursor, Claude Desktop, VS Code MCP, and MCP Inspector. No additional configuration is required beyond the standard .env setup.

---

🎯 Usage

Analyze a Repository

# CLI
repo-intel analyze https://github.com/fastapi/fastapi

# API — streams SSE progress events, one per pipeline stage
curl -N -X POST http://localhost:8001/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/fastapi/fastapi", "branch": "master"}'

Chat with a Repository

curl -N -X POST http://localhost:8001/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "fastapi/fastapi",
    "message": "How is dependency injection implemented?",
    "history": []
  }'

Note

Responses stream as text/event-stream. Each SSE event carries a token delta. The final event carries "status": "done" along with a sources array and a confidence score.

curl http://localhost:8001/api/chat/health    # Check active provider and circuit breaker state
curl -X POST http://localhost:8001/api/chat/reload  # Hot-reload provider config — no restart required

Generate an Intelligence Report

# CLI
repo-intel report fastapi/fastapi
repo-intel report fastapi/fastapi --markdown
repo-intel report fastapi/fastapi --pdf -o report.html

# API
curl -X POST http://localhost:8001/api/v1/report/fastapi/fastapi/build
curl -o report.html "http://localhost:8001/api/v1/report/fastapi/fastapi/download?format=html"
curl -o report.md   "http://localhost:8001/api/v1/report/fastapi/fastapi/download?format=markdown"

PR Risk Analysis

curl -X POST http://localhost:8001/api/pr/analyze \
  -H "Content-Type: application/json" \
  -d '{"owner": "fastapi", "repo": "fastapi", "pr_number": 1234}'

Returns size classification (XS → XL), blast radius (LOW → EXTREME), symbol diffs, and an architecture drift report.

Dead Code Detection

curl -X POST http://localhost:8001/api/dead-code/analyze \
  -H "Content-Type: application/json" \
  -d '{"owner": "fastapi", "repo": "fastapi"}'

Issue Mapping

curl -X POST http://localhost:8001/api/issues/map \
  -H "Content-Type: application/json" \
  -d '{"owner": "fastapi", "repo": "fastapi", "issue_number": 42}'

---

🔧 Configuration

cp .env.example .env

Required

Variable	Default	Description
LLM_PROVIDER	gemini	Active provider: gemini or deepseek
GEMINI_API_KEY	—	Google AI Studio key — required when LLM_PROVIDER=gemini
DEEPSEEK_API_KEY	—	NVIDIA NIM key — required when LLM_PROVIDER=deepseek

Optional

View all optional environment variables

Variable	Default	Description
GEMINI_MODEL	gemini-2.5-flash	Gemini model variant
DEEPSEEK_BASE_URL	https://integrate.api.nvidia.com/v1	NIM API endpoint
DEEPSEEK_MODEL	deepseek-ai/deepseek-v4-flash	DeepSeek model variant
GITHUB_TOKEN	—	PAT for private repositories or higher rate limits
API_SERVER_HOST	0.0.0.0	Uvicorn bind host
API_SERVER_PORT	8001	Uvicorn bind port
FRONTEND_URL	http://localhost:4321	Allowed CORS origin — set to your production domain before deploying
API_KEY	—	Optional API key authentication to secure resource-intensive endpoints
SQLITE_DB_PATH	data/repo_understanding.db	SQLite database path
CHROMA_DB_PATH	data/chroma_db	ChromaDB persistence directory
CLONED_REPOS_PATH	data/cloned_repos	Clone destination — must be outside the project tree to avoid triggering uvicorn reload loops (defaults to ~/.repo_intelligence/cloned_repos if empty in .env)
APP_ENV	development	development or production — controls fail-fast behavior at startup
LOG_LEVEL	INFO	Logging verbosity
LOG_FORMAT	human	human or json — use json in production
RATE_LIMIT_PER_MINUTE	60	Max requests per IP per minute
ALLOWED_HOSTS	["*"]	TrustedHost middleware allowed hostnames

Important

Production checklist: Set FRONTEND_URL to your domain, APP_ENV=production, and LOG_FORMAT=json. In production mode, invalid LLM credentials fail fast at startup with an actionable error message rather than silently degrading at request time.

---

📡 API Reference

Base URL: http://localhost:8001 · All routes also available under /api/v1/

Core & Repository

Method	Path	Description
GET	/health	System health and active LLM provider
GET	/metrics	Prometheus metrics
POST	/api/analyze	Full analysis pipeline (SSE)
POST	/api/index	Vector-only indexing
GET	/api/analysis/{owner}/{repo_name}	Fetch analysis result
POST	/api/repos/repair	Rebuild missing symbol or graph indexes
GET	/api/repos/recent	Recently analyzed repositories
GET	/api/repos/examples	Pre-configured example repositories

Chat

Method	Path	Description
POST	/api/chat	Streaming repository chat (SSE)
POST	/api/retrieve	Vector search with LLM-generated answer
GET	/api/chat/health	Live provider health diagnostic
POST	/api/chat/reload	Hot-reload LLM provider configuration

Graphs — Dependency & Call

Method	Path	Description
POST	/api/architecture/build	Build dependency graph
GET	/api/architecture/{owner}/{repo_name}/graph	React Flow graph payload
GET	/api/graph/{owner}/{repo}/full	Full file-level dependency graph
GET	/api/graph/{owner}/{repo}/neighbors/{node_path}	Node neighborhood
GET	/api/graph/{owner}/{repo}/trace/{node_path}	BFS reachability trace
GET	/api/graph/{owner}/{repo}/search	Graph node search
POST	/api/call-graph/build	Build call graph (SSE)
GET	/api/call-graph/{owner}/{repo_name}	React Flow call graph payload
GET	/api/call-graph/{owner}/{repo_name}/callers/{function_id}	Callers of a function
GET	/api/call-graph/{owner}/{repo_name}/callees/{function_id}	Callees of a function
GET	/api/call-graph/{owner}/{repo_name}/blast-radius/{function_id}	Function blast radius

Analysis — Symbols, API Surface, Churn, PR

Method	Path	Description
GET	/api/symbols/{owner}/{repo}/file/{file_path}	Symbols in a file
GET	/api/symbols/{owner}/{repo}/definition/{symbol_name}	Symbol definition lookup
GET	/api/symbols/{owner}/{repo}/references/{symbol_name}	Symbol cross-references
POST	/api/api-surface/build	Build API surface index (SSE)
GET	/api/api-surface/{owner}/{repo_name}	Full API surface report
GET	/api/api-surface/{owner}/{repo_name}/public	Public symbols only
GET	/api/api-surface/{owner}/{repo_name}/breaking	Breaking change detection
POST	/api/churn/analyze	Mine git history for churn scores (SSE)
GET	/api/churn/{owner}/{repo_name}/hotspots	Top hotspot files
POST	/api/pr/analyze	PR risk scoring and blast radius
POST	/api/architecture/drift	Architecture drift detection
POST	/api/dead-code/analyze	Dead code reachability sweep
POST	/api/issues/map	Map GitHub issue to implementation plan
POST	/api/reading-order	Onboarding-optimized reading order
POST	/api/impact-analysis	Change impact prediction

Reports

Method	Path	Description
POST	/api/v1/report/{owner}/{repo}/build	Build intelligence report
GET	/api/v1/report/{owner}/{repo}/summary	Health summary
GET	/api/v1/report/{owner}/{repo}/download	Download HTML · PDF · Markdown

Workspace

Method	Path	Description
GET	/api/repositories/{username}/{repository}/workspace	Fetch full consolidated workspace snapshot
GET	/api/repositories/{username}/{repository}/workspace/overview	Overview metrics only
GET	/api/repositories/{username}/{repository}/workspace/findings	Workspace findings panel data
GET	/api/repositories/{username}/{repository}/workspace/advisor	Workspace advisor panel recommendations
GET	/api/repositories/{username}/{repository}/workspace/execution	Workspace execution plan panel batches

Advisor

Method	Path	Description
POST	/api/repositories/{username}/{repository}/advisor	Compile AI Advisor recommendations
GET	/api/repositories/{username}/{repository}/advisor/latest	Fetch latest generated Advisor report
GET	/api/repositories/{username}/{repository}/advisor/recommendations	List Advisor recommendations
GET	/api/repositories/{username}/{repository}/advisor/roadmap	Fetch phased engineering roadmap

Execution Planner

Method	Path	Description
POST	/api/repositories/{username}/{repository}/execution-plan	Formulate AEA² implementation plan
GET	/api/repositories/{username}/{repository}/execution-plan/latest	Fetch latest generated execution plan
GET	/api/repositories/{username}/{repository}/execution-plan/batches	Get planned execution batches
GET	/api/repositories/{username}/{repository}/execution-plan/critical-path	Get critical path of tasks

📄 Full request/response schemas are documented in docs/API_REFERENCE.md.

---

📈 Performance

Typical development-machine measurements (Intel i7 / 16 GB RAM). Repository size, file count, and I/O characteristics will affect results.

Operation	Latency / Duration
Fresh analysis — small repository (~300 files)	25–45 s
Incremental rebuild (small change set)	< 2 s
Backend Health /health latency	~10–15 ms
Overview endpoint /workspace/overview latency	~40–60 ms
Findings /workspace/findings latency	~80–120 ms
Advisor /advisor generation latency	~1.2–2.0 s
Execution Planner /execution-plan latency	~1.5–2.5 s
Chat — first token latency	< 3 s
Chat — streaming throughput	~50–90 ms / token

Tip

Why incremental is fast: Subsequent runs skip re-embedding and re-indexing for unchanged files. Only files whose content hash has changed are re-processed. Graph nodes for unchanged files are served from the schema-versioned in-memory cache — not recomputed (typical development-machine measurements).

Prometheus Metrics

Exposed at /metrics:

Metric	Type	Description
http_requests_total	Counter	Requests by method, path, and status
active_requests_count	Gauge	In-flight requests
build_duration_seconds	Histogram	Per-repository build durations
analysis_task_duration_seconds	Histogram	Per-task durations
cache_hits_total	Counter	Cache hit count
cache_misses_total	Counter	Cache miss count

---

🛡️ Production Readiness

Built to be operated, not just installed. Released in v1.5.0 — production certified.

Concern	Implementation
	Infrastructure
Docker	Production and development Compose files with named volumes for data persistence
Health endpoint	/health reports backend status, active LLM provider, and vector store state
Fail-fast startup	In APP_ENV=production, misconfiguration halts startup with an actionable error
Incremental analysis	Hash-based change detection helps prevent redundant work on re-runs
In-memory cache	Schema-versioned cache helps prevent stale data from surviving configuration changes
Repository Switching	State-clean routines clear active graphs and caches when changing active repos
	Security
Rate limiting	Sliding-window per-IP limiter — configurable via RATE_LIMIT_PER_MINUTE
CORS	Restricted to FRONTEND_URL — set to your production domain before deploying
TrustedHost	ALLOWED_HOSTS middleware for hostname validation
Input validation	Pydantic model validation on every request body
Secret handling	API keys loaded from environment variables only — helps prevent logging or exposure
Traceback Sanitization	Server errors return client-safe messages — internal tracebacks never leak to MCP clients
	Reliability
LLM circuit breaker	ProviderManager tracks LLM health and fails over to DeepSeek on provider errors
Error Classification	ProviderError system with deterministic error categories (Missing, Auth, Rate Limit, Timeout)
Fallback renderer	If both LLM providers are unavailable, structured responses render without LLM
Race-condition Safety	Asynchronous operations are wrapped in thread executors to help prevent ASGI loop blockage
Memory Isolation	Capacity limits and TTL-based evictions protect caches from memory bloat
Self Diagnostics	Startup configuration checks automatically report provider availability and key validations
	Observability
Prometheus metrics	Prometheus metrics at /metrics with histograms for build and task durations
Structured logging	JSON log format via LOG_FORMAT=json, with request IDs on every log line
Structured Logs	OutputChannel logging traces backend connections and workspace states
API Compliance	Built-in Workspace API schema compliance checks help prevent UI rendering crashes
	MCP
MCP Inspector Validation	Every MCP tool manually validated through interactive MCP Inspector sessions
MCP Transport Verification	Cross-platform stdio transport verified with unbuffered I/O and graceful shutdown
FastMCP SDK Compatibility	FastMCP server construction and tool registration validated across pydantic versions
MCP Behavioral Parity	Legacy and FastMCP servers produce equivalent results for all shared tools
JSON-RPC Compliance	Full protocol conformance including error codes, notifications, and method dispatch
	Testing
Quality Gate	2,780+ automated tests (2,531 Python + 248 Frontend + extension + MCP)
Packaging Validation	Automated VSIX packaging validations help prevent publishing failures
Clean Profile Testing	Extension validated against isolated clean VS Code profiles to help prevent activation leaks
Regression Protection	Automated tests help protect against regressions in Digital Twin mapping and AST processing

Warning

No built-in user/session management. The application supports optional API key access control but does not include multi-user session/credential management. For multi-tenant or public deployments, place a reverse proxy with user authentication in front of the backend.

---

🧪 Testing

# Python backend & RIA tests
pytest tests/ -v
pytest tests/ --cov=. --cov-report=term-missing

# Frontend tests
cd frontend
npm test

• 2,780+ passing automated tests across Python backend/RIA suites (2,531 tests) and Frontend suites (248 tests across 46 suites)
• LLM and GitHub API boundaries are isolated with mock adapters — the full suite runs without consuming any API quota
• GitHub Actions runs the full test suite, lint check (ruff check, tsc --noEmit), and format check (ruff format --check) on every pull request
• MCP transport tests — stdio subprocess integration tests validating full JSON-RPC round-trips
• Behavioral parity tests — verify Legacy MCP and FastMCP produce identical results for all shared tools
• SDK compatibility tests — validate FastMCP server construction and tool registration across pydantic versions
• Protocol conformance tests — verify JSON-RPC 2.0 compliance including error codes, notifications, and edge cases
• Manual MCP Inspector validation — every tool verified through interactive Inspector sessions

Caution

Always run pytest tests/ with the explicit path. Running bare pytest from the repository root will traverse data/ and encounter import errors from cloned repositories.

---

🗺️ Roadmap

Completed (v1.5.0)

• Repository Intelligence Architecture (RIA) — layered, modular production architecture
• Full structural analysis pipeline with incremental hash-based rebuilds
• Digital Twin (AST parser) & Knowledge Graph (import topology) representation
• Interactive Repository Topology with scene-based cinematic storytelling
• Repository Chat v2 with 9 intent types and rule-based routing
• Interactive Graph Navigation (React Flow canvas graphs for Dependencies, Call Graphs, and Impact Analysis)
• Engineering Findings (dead code sweeps, circular dependencies, smells)
• Health Scorecards & Intelligence Reports (HTML, PDF, Markdown)
• AI Advisor Dashboard (prioritized roadmaps & recommendations)
• Execution Planner (AEA² task batches & rollback checkpoints)
• Workspace APIs (consolidated snapshot endpoints)
• VS Code Extension Integration (symbol hovers, CodeLenses, sidebar panels)
• LLM Failover Management (Gemini 2.5 Flash to DeepSeek V4 Flash circuit breakers)
• Deterministic Provider Error Classification (ProviderErrorType)
• Self Diagnostics & Startup Health Verifications
• Repository Review Command Actions
• AI Repository Intelligence (graph-based code understanding)
• Production MCP Server (Legacy stdio JSON-RPC)
• FastMCP SDK Integration (automatic tool discovery, resources, prompts)
• MCP Inspector Validation (manual verification of all tools)
• JSON-RPC 2.0 Transport (stdio + SSE)
• Cursor Compatibility
• Claude Desktop Compatibility
• Cross-platform support (Windows, Linux, macOS)
• Production validation (2,780+ passing automated tests)

Planned (v1.6.0)

• Module Stability endpoints router (backend/routers/stability.py)
• Dependency Smells endpoints router (backend/routers/dependency_smells.py)
• Treemap visualizers sizing dead code modules on dashboard canvas
• Persistent cross-session conversation memory
• Webhook-triggered incremental analysis on push events

Planned (v1.7.0)

• Multi-repository workspaces (cross-service link resolution)
• PR Review Assistant (GitHub App webhook integration)
• Incremental indexing (parse only modified files on branch updates)

Future (v2.0)

• Team-scoped SaaS deployments with user access control
• Collaborative multi-user dashboards
• Plugin ecosystem for custom Tree-sitter query modules

---

🤝 Contributing

Contributions are welcome. This project follows the Contributor Covenant. See CONTRIBUTING.md for the development workflow, coding standards, and pull request guidelines.

Good first issues are tagged good-first-issue. Questions and ideas welcome in Discussions.

pip install -e ".[dev]"                                      # Install dev dependencies
ruff check .                                                  # Lint
ruff format --check .                                         # Format check
pytest tests/ -v                                             # Run tests
pytest tests/ --cov=. --cov-report=term-missing             # With coverage

Pull Request Checklist

• ruff check . passes
• ruff format --check . passes
• pytest tests/ -v passes with no new failures
• cd frontend && npm test passes
• New behavior is covered by at least one test
• Public API changes are reflected in docs/API_REFERENCE.md
• Breaking changes are noted in the PR description

---

❓ FAQ

Which programming languages are supported?

The current implementation targets Python repositories. Multi-language AST support is on the roadmap. Tree-sitter grammars exist for most major languages — adding a new language requires implementing an AST visitor for that grammar.

Can it analyze private repositories?

Public repositories work out of the box. For private repositories, set GITHUB_TOKEN to a personal access token with repo scope. Full private repository support via GitHub App is on the roadmap.

Does it require a GPU?

No. BGE-small-en-v1.5 runs on CPU and is fast enough for interactive use on most developer machines. Embedding large repositories (~300 files) takes roughly 20–30 seconds on CPU (typical development-machine measurements).

Does it work on Windows?

Yes. The platform is supported and validated on native Windows (via PowerShell and Command Prompt), Linux, macOS, and WSL2.

Can it run without internet access?

Embedding runs locally with no API calls. Cloning public repositories and LLM calls (Gemini or DeepSeek) require internet access. The fallback renderer can produce structured responses without any LLM call.

Which LLM providers are supported?

Gemini 2.5 Flash (Google AI Studio) and DeepSeek V4 Flash via NVIDIA NIM. The LLM_PROVIDER environment variable selects the active provider. The circuit-breaker fails over to the secondary provider automatically on errors.

How large a repository can it handle?

The system has been tested on repositories up to several hundred files. Larger repositories will work but take longer on the initial analysis run. Incremental rebuilds remain fast regardless of total repository size, as only changed files are reprocessed.

How does incremental analysis work?

Each file's content is hashed after cloning. On subsequent runs, only files whose hash has changed are re-parsed, re-embedded, and re-indexed. Graph nodes and embeddings for unchanged files are read from the schema-versioned in-memory cache. Incremental rebuilds for small change sets complete in under 2 seconds (typical development-machine measurements).

Does the chat have memory across sessions?

Conversation memory is maintained within a session. Persistent cross-session memory is on the roadmap.

Is there built-in authentication?

The platform includes optional API key authentication middleware (via API_KEY configuration), rate limiting, and CORS restrictions. For multi-user credentials or session management, place a reverse proxy (e.g. nginx + OAuth2 proxy, Cloudflare Access) in front of the backend.

How do I install the VS Code Extension?

Compile the code inside the vscode-extension directory and run vsce package to generate a .vsix file. You can then install it directly in VS Code using the Install from VSIX... option.

How do I generate an execution plan?

Once a repository has been indexed and an Advisor report has been generated, trigger POST /api/v1/repositories/{username}/{repository}/execution-plan or expand the Execution Planner sidebar view in VS Code to automatically formulate a phased implementation roadmap.

What does Advisor do?

The AI Engineering Advisor analyzes codebase design smells, circular imports, and dead code, producing prioritized recommendations and structured refactoring roadmaps divided into phased segments.

What is Self Diagnostics?

At startup, the server automatically validates API configurations and validates connection health for the configured LLM providers (Gemini and DeepSeek) using non-quota-consuming API checks, flagging any authentication issues before requests are processed.

Can the extension work without the dashboard?

Yes. The VS Code extension connects directly to the FastAPI backend server (port 8001) via Workspace API snapshots. The Astro dashboard (port 4321) is optional for extension users.

How are ignored recommendations stored?

Ignored recommendations are saved persistently in the VS Code extension's workspaceState (via IgnoredRecommendationService). They survive reloads and panel refreshes, but are automatically reset when a fresh repository analysis is performed (detected via changed analysis timestamps).

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI coding assistants to external tools and data sources. ARIA implements MCP so that clients like Cursor, Claude Desktop, and VS Code MCP extensions can directly invoke repository intelligence tools over JSON-RPC 2.0.

Which AI clients are supported via MCP?

Cursor, Claude Desktop, VS Code MCP clients, MCP Inspector, and any custom JSON-RPC 2.0 client that speaks the MCP protocol. The server communicates over stdio — any client that can spawn a subprocess and read/write JSON-RPC messages is compatible.

How do I start the MCP server?

Run python -m backend.cli mcp from the project root. The server reads JSON-RPC requests from stdin and writes responses to stdout. No additional configuration is required beyond the standard .env setup.

What is the difference between Legacy MCP and FastMCP?

The Legacy MCP server (backend/mcp_server.py) is a lightweight, zero-SDK-dependency JSON-RPC server that runs over stdio. The FastMCP server (mcp/server.py) uses the FastMCP SDK and provides automatic tool discovery, resource templates, prompt templates, and SSE transport support. Both servers expose the same core repository intelligence tools and produce equivalent results.

Why does ARIA use RIA instead of a traditional RAG architecture?

Traditional RAG architectures retrieve text chunks based on embedding similarity, which works well for general knowledge but lacks structural understanding of codebases. The Repository Intelligence Architecture (RIA), introduced in v1.5.0, goes beyond semantic retrieval by building AST-level structural understanding, dependency graphs, call graphs, and symbol indexes before any AI reasoning occurs. This means the LLM reasons over verified structural relationships — not just similar-looking text — enabling accurate dependency tracing, change impact estimation, dead code detection, and architectural analysis that pure embedding-based systems cannot provide.

---

🔧 Troubleshooting

Backend fails to start in production mode

Check that GEMINI_API_KEY or DEEPSEEK_API_KEY is set correctly. In APP_ENV=production, invalid credentials fail fast with an actionable error message.

Uvicorn reload loops when cloning repositories

Set CLONED_REPOS_PATH to a directory outside the project root. The file watcher triggers reloads when it detects new files inside the project tree.

pytest fails with import errors

Always run pytest tests/ with the explicit path. Running bare pytest from the project root traverses data/ and encounters import errors from cloned repositories.

ChromaDB collection not found after restart

Check that CHROMA_DB_PATH points to a persistent directory and that the path is correctly mounted if running in Docker.

---

📚 Documentation

Document	Description
ARCHITECTURE.md	Repository Intelligence Architecture (RIA) — component diagrams, sequence diagrams, and mathematical models
docs/API_REFERENCE.md	Request/response schemas for all endpoints
docs/MCP_RELEASE_READINESS.md	MCP subsystem production release readiness and validation results
docs/MCP_FINAL_AUDIT.md	MCP final audit — production certified in v1.5.0
docs/MCP_SDK_MIGRATION.md	MCP SDK migration guide and pydantic compatibility notes
docs/EXECUTION_GUIDE.md	Step-by-step setup, compilation, and validation sequences
CONTRIBUTING.md	Development workflow, coding standards, and pull request checklist
SECURITY.md	Responsible disclosure policy and security controls

---

📄 License

Distributed under the MIT License. See LICENSE for the full text.

---

🙌 Acknowledgements

Built on excellent open-source foundations:

FastAPI · Astro · React Flow · ChromaDB · sentence-transformers · Tree-sitter · NetworkX · Google Gemini · NVIDIA NIM · Model Context Protocol · FastMCP

---

If ARIA helps you understand a codebase faster, consider giving it a ⭐
It helps other engineers find the project.