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:

  1. 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.
  2. 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.
  3. Mode 3: Data Flow View (Execution Tracing): Traces end-to-end request lifecycles from frontend entrypoints through API routes down to database persistence models.
  4. 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".
  5. 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:7b via Ollama), Google Gemini 1.5 Flash, or deterministic AST heuristics if offline.
  6. Integrated Code Viewer & Interactive Inspector: Click any node to view formatted syntax-highlighted source code with line numbers, callers, callees, and exported symbols.
  7. 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 ast module 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/dagre with custom hierarchical coordinate assignment.
    • Dark-mode glassmorphic interface with Lucide icons and JetBrains Mono typography.

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.py serves 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
Share this project:

Updates

Submission history