// Personal Project
Synergy: Code Intelligence Platform
Building a tool that turns a codebase in any of 8 languages into a graph that developers and AI agents can query.
Synergy reads a codebase and builds a graph of it: every module, class and function, and how they call, import and inherit from each other. You can then ask that graph questions, in a web dashboard or through an AI coding agent. It runs entirely on your own machine.
What it does
- • Parses Python, C#, Java, Go, C++, Rust, JavaScript and TypeScript into one typed graph.
- • Only re-parses files that changed. An incremental run gives exactly the same graph as a full one, and the tests check that.
- • Saves a snapshot every time you analyse, or of any git commit or tag, and shows what changed between two snapshots, with the changes that affect the most code first.
- • Draws call-flow diagrams from any entry point.
- • Runs your tests under a tracer and compares the calls it saw with the graph, which catches dynamic calls that static analysis can't see.
- • Analyses a released PyPI package straight from its wheel, without installing it.
Using it with AI coding agents
Coding agents usually find their way around a codebase by searching text. Synergy gives them an MCP server with 21 tools to ask the graph directly: who calls this, what breaks if I change it, how do these two parts connect, what code is never used.
One command, synergy claude install, sets it up for Claude Code: the server, a skill,
and hooks that remind the agent the graph exists when it starts searching with grep. Other agents get the same guidance in an AGENTS.md file.
Uninstalling puts every file back exactly as it was.
How it works
Files are read and hashed, then parsed: Python with its own syntax tree, the other languages with tree-sitter. A linking step resolves imports across files, so every reference points at a real definition. The result is stored in SQLite, and three things read it: a command-line tool, a web dashboard, and the MCP server.
read→parse→link→SQLite→CLI · dashboard · MCP
The backend is seven Python packages with a strict dependency order, from the core data model up to the API and the MCP server. The dashboard is a React and TypeScript app with a graph explorer, history diffs, UML diagrams and a view of exactly what an agent is shown.
Where it's at
In active development. It runs locally for one user and installs from source (version 0.1.0).
Next
- • Measuring whether an agent that has never been told about Synergy actually uses it
- • Making call flows more complete, including the calls Python makes implicitly
- • Packaging it so it installs with one command
Built with
How it started the original 2025 design
Hybrid C#/.NET and Python platform transforming codebases into queryable graphs with architectural intelligence, featuring ASP.NET Core API, Blazor WASM UI, and active "Architectural Linter" capabilities for AI-assisted development
Project Status & Context
Current Stage: Active Personal Research
This is an independent technical research initiative exploring graph-based code analysis and LLM knowledge enhancement. Originally conceived for academic collaboration, the project has been refocused as a personal research endeavor with potential for future publication and open-source contribution. The work explores innovative approaches to bridging the gap between static code organization and dynamic workflow understanding, with particular emphasis on version-specific package analysis and token-efficient AI assistance.
Development Timeline
- • Conceptualization: October 2025
- • Architecture Design: Ongoing
- • Implementation: Progressive development
- • Approach: Modular, iterative research
Research Focus
- • Open-source package/library analysis
- • LLM knowledge gap mitigation
- • Version-specific code understanding
- • Token-efficient AI assistance
The Problem
Developers and AI assistants struggle with unfamiliar codebases. Existing tools show directory structures ("where code lives") but fail to capture behavior ("how code works").
Current Tool Limitations
- File-centric organization: Shows directory structure, not workflows
- Static documentation: Quickly outdated, missing system-level interactions
- Fragmented relationships: Only immediate connections visible
- Lost architectural context: No project philosophy or team culture captured
AI Assistant Challenges
- Version Mismatch: Hallucinating APIs from wrong package versions
- New Package Blindness: No knowledge of recently released libraries
- Confabulation: Plausible but incorrect code generation
- Missing Architectural Context: Code that works but violates team patterns
Critical Impact
AI assistants lack Architectural Context: they don't know if your team prefers composition over inheritance, whether you use dependency injection patterns, or which design principles guide your codebase. This leads to syntactically correct code that violates team culture and architectural philosophy, requiring extensive manual refactoring.
The Solution: Hybrid C#/.NET + Python Architecture
A hybrid platform that transforms codebases into queryable graphs, combining Python's data science ecosystem for deep analysis with C#/.NET's enterprise-grade infrastructure for robust APIs and UI:
Deep Analysis (Python Microservice)
- • Doxygen + AST Pipeline: Extract entities (classes, functions) and relationships
- • Structural & Behavioral Graphs: UML-inspired dual-level analysis
- • Philosophy Metadata: Tag packages with architectural context
- • Workflow Extraction: Trace execution paths and call sequences
Architectural Intelligence (C# ASP.NET Core)
- • API Gateway: Enterprise-grade REST endpoints for graph queries
- • MCP Host (McpController): JSON-RPC 2.0 protocol for AI agents
- • Refactoring Service: Active detection of God Classes and violations
- • Python Bridge: IGraphProvider service consuming Python output
Core Innovation: The "Architectural Linter"
Moving beyond simple code mapping to Architectural Linter capabilities. The C# RefactoringService doesn't just show the graph, it critiques it based on complexity metrics (Cyclomatic Complexity, Fan-Out) and defined project philosophies, accessible directly by LLMs via MCP. AI agents can ask: "Where are the God Classes?" and receive data-backed RefactoringCandidate objects with specific architectural violations.
System Architecture: Hybrid Microservices
Multi-container architecture separating analysis concerns (Python) from application infrastructure (C#/.NET), communicating via REST APIs and shared Neo4j database:
Frontend: Blazor WebAssembly (C#)
- • Interactive graph visualization (D3.js/Cytoscape interop)
- • "Audit View" displaying RefactoringCandidates
- • GitHub repository submission interface
- • Real-time graph exploration with C# client
Application Layer: ASP.NET Core API (C#)
- • API Gateway: REST endpoints for graph queries
- • McpController: JSON-RPC 2.0 for AI tool calls
- • RefactoringService: God Class detection heuristics
- • PythonBridgeService: IGraphProvider implementation
Analysis Layer: Python Microservice
- • Doxygen + AST: Entity/relationship extraction
- • Hierarchical Sanitization: Multi-level graph construction
- • Philosophy Metadata: Architectural context tagging
- • OpenAI Integration: AI-generated documentation
Data Layer: Neo4j + Redis
- • Neo4j: Graph database with package:version namespacing
- • Redis: Caching layer for heavy queries and AI calls
- • Cypher Queries: Graph traversal and pattern matching
- • Shared Access: Both Python and C# services connect
Architecture Benefits
Separation of Concerns
Python handles data science, C# handles enterprise infrastructure
Language-Specific Strengths
Leverage ecosystems: NumPy/Pandas vs. robust APIs/DI
MCP-First Design
AI agents as first-class citizens with dedicated endpoints
Primary Use Case: Open-Source Package Analysis
For Human Developers
- • Understand package/library APIs before integration
- • Learn capabilities and features
- • Explore class structure for open-source contributions
- • Navigate workflows to understand implementations
For AI Systems (via MCP)
- • Query package capabilities by name and version
- • Retrieve structured API documentation
- • Access class structure for contributions
- • Debug version-specific dependency issues
Package-Centric Workflow
Implementation Phases
Phase 1: The "Market-Ready" Prototype
Goal: A functional system capable of ingesting a repo, detecting architectural flaws (God Classes), and exposing the graph to AI agents via MCP
Stage 1: Python Backend
- • Doxygen + AST pipeline
- • Entity/relationship extraction
- • Philosophy metadata tagging
Stage 2: C# Bridge & MCP
- • IGraphProvider + PythonBridgeService
- • McpController (get_workflow, explain_structure)
- • RefactoringService with God Class detection
Stage 3: Blazor UI
- • Interactive graph rendering (D3.js interop)
- • "Audit View" for RefactoringCandidates
- • Docker deployment
Phase 1 Deliverable: Deployable Docker container where users upload a package (e.g., numpy), visualize the graph in Blazor, and AI agents query "Where are the God Classes?" via MCP for data-backed answers
Phase 2: Individual Research Tracks
Building on the C#/.NET + Python foundation with specialized research directions:
Track 1: Big Data ML + Cross-Language
Train GNNs on graph data, map Python AST to C# structures, predict missing edges
Track 2: Cybersecurity Threat Modeling
SecurityScanner extension, CVE mapping, vulnerability heatmap in Blazor UI
Track 3: Enterprise Scaling + Hierarchical Agents
Scale ASP.NET Core for concurrent MCP, Redis caching, sub-linear latency benchmarks
Track 4: Consultancy + Automated Auditing
ReviewController for PDF reports, user validation studies, "State of OSS Architecture" report
Validation Framework
Primary Evaluation: Three-condition LLM experiment using Manim v0.17.3 as test codebase
Condition A: Baseline
LLM with Manim documentation only, no codebase access
Condition B: Full Codebase
Claude Code / Agentic Tool with entire repository access
Avg Input Tokens: 18,500
Condition C: MCP Tool (Our System)
Access to MCP API for structured queries
Avg Input Tokens: 4,300
⚡ 75-80% Token Reduction
Key Validation Metrics
Error Rate (Primary)
Binary: Does generated code run without errors? Target: Condition C <20% vs. A ~50%
Token Efficiency (Critical)
Context Efficiency Ratio: Target 75-80% reduction vs. full codebase (Cohen's d > 2.0)
Code Quality
Likert scale (1-5): Correctness, idiomatic usage, clarity. Target: >4.0/5
Novel Contributions
Hybrid Architecture
Leveraging Python's data science ecosystem for analysis while using C#/.NET for robust, enterprise-grade API and UI serving, combining the strengths of both ecosystems
The "Architectural Linter"
A novel service that proactively critiques codebase health using graph topology, not just syntax checking, detecting God Classes, complexity violations, and architectural anti-patterns
MCP-First Design
Treating AI Agents as first-class citizens with dedicated API endpoints (McpController), allowing them to "read" architecture without visual processing, direct machine-to-machine understanding
Context-Aware Graphs
Embedding project philosophy directly into the data model, solving the "Cultural Alignment" problem for AI coding tools, teaching AI assistants team preferences and architectural patterns
Future Research Directions
Hierarchical LLM Architecture (Potential Pivot)
Multi-level AI agents for enterprise systems:
- • Deployment-level agents (distributed topology)
- • Component-level agents (subsystem management)
- • Package-level agents (module coherence)
- • Hierarchical delegation following architectural boundaries
Big Data: Large-Scale Analysis
Mass repository analysis and pattern discovery:
- • Thousands of high-quality open-source projects
- • Cross-project architectural pattern discovery
- • Community best practices inference
- • Graph Neural Networks for design pattern recognition
Cross-Language Generalization
Language-agnostic architecture mapping:
- • Canonical UML representations across languages
- • Structural isomorphisms (Python → C# → Java)
- • Capability matrices for construct mapping
- • Rapid prototyping in one language, production in another
Cybersecurity Threat Modeling
Security analysis via graph topology:
- • Attack surface mapping and privilege escalation paths
- • Vulnerability localization using historical CVE data
- • Insecure permission flow detection
- • Common vulnerability pattern recognition
Key Insights
- • Workflow-centric organization prioritizes how code works together
- • Package-version namespacing enables precise LLM knowledge
- • Target 75-80% token reduction for sustainable LLM usage
- • Microservices architecture enables parallel development
- • MCP protocol provides standardized AI-system interface
Technology Stack
Frontend & Application Layer (C#/.NET)
Analysis Layer (Python)
Infrastructure & Data
Independent Research Initiative
This project represents a comprehensive personal exploration of graph-based code analysis, LLM integration, and software architecture understanding. Developed as an independent technical research initiative with potential applications in AI-assisted development, open-source package comprehension, and enterprise codebase navigation. The project demonstrates advanced software engineering principles, research methodology, and technical innovation at the intersection of AI and software development, with aspirations for future publication and open-source contribution to the developer tools ecosystem.