-
-
-
frontend UI with Client and Gateway layer mapping to visualize components and API route listeners.
-
Service Layer overview exposing core business logic, cross-layer bridges, and cyclic issues
-
Deep dive into the Data and Utility layers, mapping out persistence repositories and standalone files
-
Full Client-Server Architecture view automatically detecting and highlighting circular dependencies
-
Data Flow Mode visualizing sequential execution paths across Client, Gateway, and Service tiers
-
Conversational AI Assistant to query your codebase, find dependencies, and trace execution flows
-
Integrated Code Viewer allowing you to inspect source code directly from the architecture map
-
AI Inspector explaining file roles based on selected learning personas (Beginner/Intermediate/Developer
-
Flexible import options allowing you to visualize code directly from a GitHub URL or a local folder
-
switch between Architecture, Dependency, and Data Flow visualization modes
-
Context-aware AI assistant explaining complex data flows and pinpointing structural bottlenecks.
-
Instant repository overview displaying detected tech stack badges and core codebase metrics
-
Sidebar tracking architectural issues like circular dependencies alongside a searchable project file explorer
-
Clear visual legend color-coding edge connections like cross-layer bridges and cyclic dependencies
Inspiration
Every software engineer knows the dread of opening an unfamiliar, multi-thousand-line repository for the first time. Reading through dozens of folders, deciphering undocumented dependencies, and tracing how HTTP requests flow into business services and databases typically takes days of tedious manual inspection.
Static README files and architectural diagrams go stale the moment code changes. We asked ourselves: Why can't understanding a software repository feel as visual, intuitive, and tactile as exploring an Unreal Engine Blueprint or a ComfyUI node graph?
That question led to TraceFlow Map — an automated codebase-to-architecture visualizer that parses any GitHub repository or local directory and turns it into a living, interactive architectural map.
What it does
TraceFlow Map ingests public GitHub repositories or local folders and instantly builds a full architectural digital twin of the codebase with three specialized modes:
- Mode 1: Architecture View (Layer Swimlanes): Organizes files into distinct architectural tiers (Client UI, API Gateway, Service Logic, Data Store, and Utility). It cleanly separates cross-layer bridges, intra-layer pipelines, and standalone files so you can clearly trace how calls transit between layers.
- Mode 2: Dependency View (UE5 Blueprint DAG): Uses a hierarchical Left-to-Right directed acyclic graph (powered by the Dagre layout engine) with cubic bezier splines, input/output sockets, and zero card overlaps. Active connected pipelines stay front-and-center, while standalone docs and utilities sit in an organized gallery below.
- Mode 3: Data Flow View (Execution Tracing): Traces end-to-end request lifecycles from frontend entrypoints through API routes down to database persistence models.
- Architectural Health & Cycle Detection: Runs Tarjan's strongly connected components algorithm to flag dangerous circular import loops (highlighted with pulsing red alerts and animated edges) and detects high-centrality "God files".
- Code-Grounded AI Assistant (Local Ollama & Cloud Gemini): Features a dual-engine AI assistant with three learning personas (Beginner, Intermediate, Developer). It can answer questions about the codebase using local private LLMs (like
qwen2.5-coder:7bvia Ollama), Google Gemini 1.5 Flash, or deterministic AST heuristics if offline. - Integrated Code Viewer & Interactive Inspector: Click any node to view formatted syntax-highlighted source code with line numbers, callers, callees, and exported symbols.
- Expandable / Pop-Out Workspace: The right-hand panel supports smooth drag-to-resize, full popout floating mode, or one-click collapse.
How we built it
We designed TraceFlow Map as a decoupled, high-performance full-stack application:
- Backend & Static Analysis Engine (FastAPI & Python 3):
- Repo Ingestor: Clones remote Git repositories via shallow clone with zipball fallbacks or inspects local directories.
- AST Parsers: Uses Python's native
astmodule and regex/Babel tokenizers to extract classes, functions, imports, decorators, and API route definitions. - Import Resolver & Call Graph: Maps relative and absolute module paths across multi-file directories to resolve true caller-callee relationships.
- Graph Topology: NetworkX algorithms for cycle detection (Tarjan's algorithm) and PageRank centrality scoring.
- Dual-Engine AI: Seamless fallback hierarchy supporting local Ollama (
qwen2.5-coder:7b), Google Gemini API, and deterministic AST-grounded heuristics.
- Frontend & Visual Canvas (React 18, Vite, Tailwind CSS, XYFlow):
- Built with
@xyflow/react(React Flow v12) using custom UE5 Blueprint-styled node cards with glowing sockets and color-coded headers. - Automated rank layout using
@dagrejs/dagrewith custom hierarchical coordinate assignment. - Dark-mode glassmorphic interface with Lucide icons and JetBrains Mono typography.
- Built with
Challenges we ran into
- Preventing Visual Clutter & Spaghetti Graphs: Large real-world repos often have 50+ files in a single service layer. Our early prototype dumped cards into static vertical columns, causing wires to cut through neighboring cards. We solved this by developing a 3-category classification algorithm: Cross-Layer Bridges, Intra-Layer Pipelines (laid out with Dagre
rankdir: 'LR'), and Standalone Files (arranged in a dedicated shelf below). - Import Resolution Ambiguities: Python and TypeScript support relative imports (
../services), absolute package imports, and aliased paths. We engineered an import resolver that normalizes file structures against the scanned project tree. - Local vs. Cloud AI Reliability: To ensure the project always works during live judging without requiring an active internet connection or expensive API keys, we integrated local Ollama support (
qwen2.5-coder:7b) alongside Gemini cloud fallback and deterministic AST heuristics. - React Input Focus Retention: During interactive AI chats, we resolved a subtle React fiber unmounting issue in resizable panels to guarantee smooth, uninterrupted keystroke typing.
Accomplishments that we're proud of
- Zero-Overlap Blueprint Aesthetics: Delivering an interactive canvas that looks and feels like a modern game-engine blueprint or node compositor rather than a generic box-and-arrow diagram.
- Sub-Second Graph Synthesis: Ingesting, parsing, and rendering a full architectural topology of 70+ files in under 2 seconds.
- 100% Offline-Capable AI: Seamlessly running code-intelligence queries completely on-device using local Ollama models.
- Production Build in One Command: Creating a self-contained runtime where
python run.pyserves the compiled frontend and backend API on a single port with zero configuration.
What we learned
- The mathematical nuances of hierarchical graph theory (Sugiyama framework, rank assignment, and minimum feedback arc sets for cycle breaking).
- How to extract meaningful semantic architecture from raw AST syntax trees across multiple programming languages.
- How to balance high visual information density with clean, clutter-free user interface design.
What's next for TraceFlow Map
- Git Diff & PR Architecture Impact: Visualizing architecture changes between two git commits or pull requests to highlight newly introduced circular dependencies or architecture drift before merging.
- Live Runtime Tracing: Attaching OpenTelemetry or eBPF probes to watch live production HTTP requests light up nodes on the map in real time.
- Expanded Language Support: Native AST parsers for Go, Rust, Java, and C# to support enterprise microservices.
- VS Code Extension: Bringing TraceFlow Map directly into the IDE sidebar as a companion visualizer during active coding.
Built With
- ast
- code-intelligence
- dagre
- data-visualization
- developer-tools
- fastapi
- gemini-api
- graph-theory
- httpx
- networkx
- ollama
- pydantic
- python
- react
- react-flow
- rest-api
- tailwindcss
- typescript
- uvicorn
- vite


