🔬 CodeXray: Interactive Code Execution & Memory Visualizer

A real-time runtime debugger, memory graph explorer, and AI-powered execution tutor for Python and Java programs.

---

🌟 Overview

CodeXray is an interactive full-stack program execution visualizer designed to demystify program execution flow, memory allocation, recursion trees, and variable mutations. Built with a high-performance Go backend, custom runtime AST tracers for Python and Java, and an intuitive web canvas, CodeXray pairs verified dynamic trace events with step-by-step pedagogical explanations powered by the Google Gemini API.

---

🚀 Key Features

• ⚡ Dual Language Runtime Support:
  • Python 3: Dynamic AST analysis and bytecode/sys.settrace execution inspector capturing scopes, stack frames, and object references.
  • Java: Real-time JVM memory tracking and execution event logging.
• 🧠 Memory & Call Stack Visualizer:
  • Visual distinction between Stack frames, Heap allocations, and object pointer references.
  • Recursion visualization with call stack depth and frame popping.
• 🤖 Grounded AI Explanations (Google Gemini):
  • Explanations are strictly grounded in verified runtime trace steps — no hallucinations.
  • Natural-language breakdown of what each line executed, how state mutated, and why.
  • Interactive Q&A chat (/api/ask) allowing students to query program state at any step.
• 🎨 Interactive Canvas:
  • Synchronized line-by-line code highlighting.
  • Execution View, Memory View, and Split View modes with pan, zoom, fit, and focus controls.

---

🏛️ System Architecture

flowchart TD
    User["Student / Developer"] -->|"Types Code"| Frontend["Frontend UI - Web Canvas"]
    Frontend -->|"POST /api/execute"| Server["Go Backend Server (:8080)"]
    
    subgraph Execution_Engine["Execution Engine"]
        Server -->|"Spawn Process"| Tracer["Language Tracer Engine"]
        Tracer -->|"AST Tracing"| PyTracer["python_tracer.py"]
        Tracer -->|"JVM Inspection"| JavaTracer["java_tracer.java"]
        PyTracer -->|"JSON Trace Events"| Server
        JavaTracer -->|"JSON Trace Events"| Server
    end

    subgraph AI_Tutor["AI Tutor Integration"]
        Server -->|"Verified Steps"| Gemini["Google Gemini GenAI SDK"]
        Gemini -->|"Step-by-step Insights"| Server
    end

    Server -->|"Execution Trace & AI Explanations"| Frontend
    Frontend -->|"Interactive Stepping"| User

Loading

---

📂 Project Structure

Code_Visualizer_CodeXray/
├── backend/
│   ├── main.go               # Go HTTP REST API server & router
│   ├── go.mod                # Go module dependencies
│   ├── go.sum                # Checksum hashes
│   ├── .env.example          # Environment variables template
│   └── tracer/
│       ├── python_tracer.py  # Python runtime AST tracer & memory inspector
│       └── java_tracer.java  # Java execution event emitter
├── frontend/
│   ├── index.html            # Main canvas & editor layout
│   ├── style.css             # Dark/Light theme & canvas styling
│   └── app.js                # State management, step player, & graph renderer
├── .gitignore
├── LICENSE                   # MIT License
└── README.md

---

🛠️ Getting Started

Prerequisites

• Go (1.21 or higher)
• Python 3.10+
• Java JDK 17+ (optional, for Java tracing)
• Google Gemini API Key (optional, for AI explanations)

Installation

1. Clone the repository:

   git clone https://github.com/Sankarshan-Mahamuni/Code_Visualizer_CodeXray.git
   cd Code_Visualizer_CodeXray

2. Configure Environment Variables:

   cd backend
   cp .env.example .env

   Add your Gemini API key in .env:

   GEMINI_API_KEY=your_gemini_api_key_here

3. Install Go Dependencies:

   go mod download

4. Run the Server:

   go run main.go

5. Open the Visualizer: Navigate to http://localhost:8080 in your web browser.

---

📡 API Reference

Endpoint	Method	Description
GET /api/health	GET	Health check endpoint returning server status.
POST /api/execute	POST	Executes source code in sandbox, traces execution steps, and returns AI explanations.
POST /api/explain	POST	Generates on-demand Gemini AI tutor explanation from an existing execution trace.
POST /api/ask	POST	Answers specific user questions regarding the code's dynamic state.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check issues page.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.