TraceFlow

See your architecture. Watch your traffic. Understand your system.

What is TraceFlow?

TraceFlow is a VS Code extension that turns your codebase into an interactive, visual architecture map — right inside your editor. It statically analyzes your project (Django + React + React Native) using Python's ast module and renders a live ReactFlow graph with expandable service nodes, grouped endpoints, and optional real-time HTTP telemetry.

Zero config. Zero code changes. Read-only. Just point it at your project root.

✨ Features

🔍 Smart Auto-Discovery

TraceFlow automatically detects your entire stack with a single folder selection:

🎯 Dynamic Granularity

Click any service to drill down. Click again to collapse. The graph smoothly re-layouts.

🏷️ Smart Endpoint Grouping

Backend endpoints aren't just a flat list — they're automatically categorized by business domain:

⚡ Live Telemetry

Watch your architecture come alive. Drop in a lightweight middleware (Django) and interceptor (React), and every HTTP request animates as a glowing pulse on the graph:

• 🟢 Green pulse — 2xx success
• 🔴 Red pulse — 4xx/5xx error
• Edge glows for 2 seconds, then fades

All traffic stays local — ws://localhost:8765. Nothing ever leaves your machine.

🚀 Quick Start

Prerequisites

• VS Code ≥ 1.85
• Python ≥ 3.10 (for the parser)
• Node.js ≥ 18 (for building)

Install

Option 1: Visual Studio Marketplace (Recommended)

1. Open VS Code.
2. Go to the Extensions tab (Ctrl+Shift+X).
3. Search for TraceFlow.
4. Click Install.

Option 2: Manual VSIX Install (For Antigravity IDE / VSCodium)

1. Download the latest traceflow-viz-0.1.0.vsix from the Releases.
2. Open your IDE's Extensions panel.
3. Click ... in the top right → Install from VSIX...
4. Select the downloaded file.

Building from Source

# 1. Clone the repo
git clone https://github.com/xand0dev/TraceFlow.git
cd TraceFlow

# 2. Install dependencies & build
npm install
npm run package

# 3. Launch in VS Code Extension Host
#    Press F5

🏗️ Architecture

graph TB
    subgraph "VS Code Extension Host"
        EXT["extension.ts<br/>Activation · Commands · WebSocket"]
        PARSER["parser.py<br/>AST Analysis · Route Extraction"]
    end

    subgraph "Webview Panel"
        RF["ReactFlow Canvas<br/>Interactive Graph"]
        SN["ServiceNode"]
        EN["EndpointNode"]
        MN["ModelNode"]
        PN["PageNode"]
    end

    subgraph "Optional SDKs"
        DM["Django Middleware<br/>websocket-client"]
        RI["React Interceptor<br/>fetch/axios wrapper"]
    end

    EXT -->|"spawns python"| PARSER
    PARSER -->|"JSON via stdout"| EXT
    EXT -->|"postMessage"| RF
    RF --- SN
    RF --- EN
    RF --- MN
    RF --- PN
    DM -->|"ws://localhost:8765"| EXT
    RI -->|"ws://localhost:8765"| EXT
    EXT -->|"telemetry pulse"| RF

    style EXT fill:#f0883e,stroke:#f0883e,color:#0d1117
    style PARSER fill:#3fb950,stroke:#3fb950,color:#0d1117
    style RF fill:#58a6ff,stroke:#58a6ff,color:#0d1117
    style DM fill:#a371f7,stroke:#a371f7,color:#0d1117
    style RI fill:#a371f7,stroke:#a371f7,color:#0d1117

🔌 Live Telemetry Setup (Optional)

Django Middleware

# Copy sdk/django_middleware.py → your_project/core/middleware.py

# settings.py
MIDDLEWARE = [
    # ... other middleware
    'core.middleware.TraceFlowTelemetryMiddleware',
]

# pip install websocket-client

React Interceptor

// Copy sdk/telemetry_client.js → your src/ folder

// App.js or index.js
import { initTraceFlow } from './telemetry_client';
initTraceFlow(); // connects to ws://localhost:8765

🔒 Security Guarantees

🛠️ Tech Stack

📁 Project Structure

TraceFlow/
├── src/
│   ├── extension.ts          # VS Code activation, commands, WebSocket server
│   ├── parser.py             # Python AST parser (Django + React + RN)
│   └── webview/
│       ├── App.tsx            # Main ReactFlow canvas & layout engine
│       ├── styles.css         # Dark theme styles
│       └── nodes/
│           ├── ServiceNode.tsx    # Expandable service blocks
│           ├── EndpointNode.tsx   # API endpoint pills
│           ├── ModelNode.tsx      # Django model cards
│           └── PageNode.tsx       # Frontend page/screen items
├── sdk/
│   ├── django_middleware.py   # Optional Django telemetry middleware
│   └── telemetry_client.js    # Optional React/RN telemetry interceptor
├── docs/images/               # README assets
├── package.json
└── tsconfig.json

🗺️ Roadmap

• [ ] FastAPI / Express parser support
• [ ] Flutter screen detection
• [ ] Docker Compose service discovery
• [ ] GraphQL schema visualization
• [ ] VS Code Marketplace publishing
• [ ] Export graph as SVG/PNG
• [ ] Search — find endpoint/model by name

_{Built with ❤️ as an MVP for architectural observability}