C Code Visualizer 🚀

A full-stack application that transforms C source code into interactive flowcharts using a hybrid approach of Deterministic AST Parsing and LLM-based Analysis.

🏗️ Architecture & Design Choices

The application follows a modern, containerized client-server architecture designed for scalability and real-time feedback.

Backend (Python/FastAPI)

• Framework: FastAPI for high-performance, async API handling.
• Parsing Engine:
  • ast-grep: Used for precise, deterministic extraction of C functions and structure.
  • Manual AST Traversal: Implements a custom recursive algorithm to generate Mermaid diagrams without AI for instant results.
  • Google Gemini 1.5 Flash: Used for "Deep Analysis" to generate complex, context-aware explanations and diagrams.
• Real-time Communication: WebSockets allow the backend to push live status updates ("Parsing...", "Analyzing Function 2/5", "Done") to the frontend.
• Package Management: Uses uv for extremely fast dependency resolution and installation.

Frontend (React/Vite)

• Framework: React 18 with Vite for lightning-fast builds.
• Styling: TailwindCSS for a responsive, dark-mode UI.
• Visualization: mermaid.js for rendering flowcharts dynamically.
• State Management: React Hooks + WebSocket listeners for event-driven UI updates.

Infrastructure (Docker)

• Multi-stage Builds: The frontend uses a multi-stage Dockerfile (Build -> Nginx) to ensure the final image is lightweight.
• Orchestration: docker-compose manages the entire stack, networking, and volume mounts.

---

✅ Bonus Tasks Completed

This project implements 3 out of 3 suggested bonus tasks to demonstrate engineering depth:

1. Manual AST Traversal:

   • Instead of relying solely on LLMs, I implemented a deterministic parser (backend/services/ast_parser.py) that walks the C Abstract Syntax Tree to build Mermaid diagrams programmatically. This provides an "Instant Preview" feature with zero latency.
   • Demonstrates: Compiler theory, recursion, and graph theory.

2. Real-time Updates with WebSockets:

   • Replaced standard HTTP polling with a WebSocket connection (/ws). The server pushes granular progress updates (e.g., "Processing function 3 of 5") to the client, triggering live Toast notifications and dashboard refreshes.
   • Demonstrates: Asyncio, event-driven architecture, and full-duplex communication.

3. Containerization:

   • Fully dockerized environment with docker-compose. Includes a production-ready Nginx configuration for the frontend to handle React Router correctly.
   • Demonstrates: DevOps, multi-stage builds, and environment configuration.

---

🛠️ Configuration

1. Environment Variables

Create a .env file in the root directory of the project.

# .env
# Google Gemini API Credentials (Required for Deep Analysis)
GEMINI_API_KEY=your_actual_api_key_here
GEMINI_MODEL=gemini-1.5-flash

# Backend Settings
HOST=0.0.0.0
PORT=8000

🚀 How to Run

Option A: Using Docker (Recommended)

This runs the entire stack (Frontend + Backend) with a single command.

1. Build and Start: docker-compose up --build

2. Access the App:

   • Frontend: http://localhost:3000
   • Backend Docs: http://localhost:8000/docs

Option B: Manual Setup (Local Development)

1. Backend Setup

cd backend

# Install dependencies using pip (or uv)
pip install -r requirements.txt

# Run the server
uvicorn main:app --reload --port 8000

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Run the development server
npm run dev

Access frontend at http://localhost:5173

---

📂 Project Structure

.
├── docker-compose.yml       # Orchestrates Frontend & Backend
├── .env                     # Environment config
├── backend/
│   ├── Dockerfile           # Python 3.13 + uv setup
│   ├── main.py              # FastAPI entrypoint & WebSocket route
│   ├── websocket_manager.py # Manages active socket connections
│   ├── models.py            # Pydantic data models
│   ├── services/
│   │   ├── job_manager.py   # Background task logic (LLM + AST)
│   │   └── ast_parser.py    # MANUAL AST TRAVERSAL LOGIC (Bonus Task 1)
│   └── requirements.txt
└── frontend/
    ├── Dockerfile           # Multi-stage Node -> Nginx build
    ├── nginx.conf           # Nginx config for React Router
    ├── src/
    │   ├── api.js           # API & WebSocket handling
    │   ├── pages/
    │   │   ├── Home.jsx     # Main UI with Quick Preview & Deep Analysis
    │   │   └── JobDashboard.jsx # Results view
    │   └── components/
    │       ├── MermaidDiagram.jsx # Diagram renderer
    │       └── MiniDashboard.jsx  # History sidebar

🧪 Features Breakdown

Feature	Description
⚡ Quick Preview	Uses ast-grep and custom Python logic to generate a flowchart instantly. No API costs, zero latency.
🧠 Deep Analysis	Uses Google Gemini to understand complex logic and generate detailed, context-aware flowcharts.
🔴 Live Status	Real-time "Toast" notifications appear in the bottom right corner as the backend processes code.
📜 History	All jobs are saved in-memory and listed in the sidebar.