# manisaiteja2007/code-visualizer architecture

> Architecture diagram of the GitHub repository manisaiteja2007/code-visualizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manisaiteja2007/code-visualizer
- Repository: https://github.com/manisaiteja2007/code-visualizer

## Overview

1. **Overall shape**
   - This repo is a two-tier application: a **Python/FastAPI backend** that analyzes code and builds execution payloads, and a **React/Vite frontend** that renders those payloads as interactive visualizations.
   - The architecture is intentionally split between **analysis/trace generation** on the server and **playback/rendering** in the browser.

2. **Backend entry point and API boundary**
   - `backend/main.py` is the FastAPI entrypoint and the main integration boundary for the system.
   - The backend appears to expose endpoints for submitting code/snippets and returning structured execution data that the UI can animate.
   - The `backend/test_main.py` and `backend/tests/test_main.py` files indicate the API layer is unit/integration tested independently of the UI.

3. **Trace analysis subsystem**
   - `backend/engines/` contains the code-understanding logic:
     - `language_detector.py` likely routes snippets to the right analysis path.
     - `python_tracer.py` is the execution-tracing engine for Python.
     - `snippet_analyzer.py` suggests static analysis or metadata extraction used to enrich traces.
   - Based on the README, this subsystem produces stepwise execution, scope, and complexity metadata rather than only raw syntax parsing.

4. **Visualization payload generation**
   - `backend/components/` contains the render/build layer for different visualization domains:
     - `flow_renderer.py` for control-flow graphs,
     - `memory_renderer.py` for memory/stack visualization,
     - `sql_renderer.py` for SQL execution stages.
   - These modules likely transform trace data into frontend-ready, structured artifacts such as nodes, edges, frames, memory blocks, or SQL pipeline steps.

5. **Persistent caching layer**
   - `backend/database.py` plus the checked-in `backend/database.db` indicate a **local SQLite cache** for trace results.
   - The README calls this a persistent cache registry, so the backend likely deduplicates identical snippets and returns cached payloads instead of recomputing traces.
   - This cache is part of the backend’s performance boundary and reduces recomputation cost for repeated runs.

6. **Backend runtime/dependencies**
   - `backend/requirements.txt` and `backend/Dockerfile` indicate a Python service containerized separately from the UI.
   - The README mentions Graphviz system dependencies, which implies backend rendering or graph generation relies on native tooling, not just pure Python.

7. **Frontend application shell**
   - `frontend/src/App.tsx` is the top-level UI composition layer, with `main.tsx` bootstrapping the React app.
   - The frontend is built with **TypeScript + Vite**, and the project is structured for code splitting/lazy loading of feature modules.

8. **Frontend visualization components**
   - `frontend/src/components/` contains reusable visualization primitives:
     - `CodeViewer.tsx` for source display,
     - `ControlFlowGraph.tsx` for graph rendering,
     - `MemoryVisualizer.tsx` for memory/stack display,
     - `PlaybackControls.tsx` for stepping through execution.
   - These components form the presentation boundary: they consume backend-produced execution frames and turn them into interactive UI states.

9. **Frontend feature modules**
   - `frontend/src/modules/` organizes the app by simulation mode:
     - `Playground.tsx` for general code execution,
     - `CMemory.tsx` for memory-focused exploration,
     - `SQLExecution.tsx` for query pipeline visualization,
     - `SearchPerformance.tsx` for algorithm comparison.
   - This suggests the UI is not a single-purpose editor, but a multi-workspace simulator with distinct workflows sharing common playback infrastructure.

10. **Client-side interaction model**
   - The README emphasizes “zero-latency playback,” which means the browser likely receives a precomputed trace payload and advances through it locally rather than round-tripping to the server per step.
   - That makes the backend an analysis/compiler service and the frontend a deterministic playback engine.
   - `frontend/src/utils/search.ts` and its test file indicate at least some algorithmic behavior is implemented and validated on the client side as well.

11. **Deployment and composition**
   - `docker-compose.yml` ties the backend and frontend together as separate containers.
   - The frontend Docker setup is a production build/serve path, while the backend Dockerfile packages the API service.
   - This clean separation means the main architecture diagram should show two independently built runtimes connected over HTTP.

12. **Testing and quality boundaries**
   - Backend tests cover server/API behavior; frontend tests and `frontend/tests/TESTING.md` indicate the UI has its own verification layer.
   - This is a good sign that the repo treats analysis logic, rendering logic, and interactive playback as separate concerns with different test surfaces.

13. **Key data flow to diagram**
   - A user enters code or selects a demo in the frontend.
   - The frontend sends the snippet/request to the FastAPI backend.
   - The backend detects language, traces or analyzes execution, optionally caches the result in SQLite, and builds renderable payloads for flow/memory/SQL views.
   - The frontend receives that payload and drives local playback through the visualization components and controls.

Main entry points: [`frontend/src/App.tsx`](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/App.tsx) (App shell), [`frontend/src/modules/Playground.tsx`](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/Playground.tsx) (Playground), [`backend/main.py`](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/main.py) (API app), [`backend/engines/python_tracer.py`](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/python_tracer.py) (Python tracer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_detector["Language detect<br/>router"]
  node_backend_tracer["Python tracer<br/>execution trace<br/>[python_tracer.py]"]
  node_backend_snippet["Snippet analysis<br/>static analysis"]
  node_backend_flow["Flow render<br/>payload builder<br/>[flow_renderer.py]"]
  node_backend_memory["Memory render<br/>payload builder<br/>[memory_renderer.py]"]
  node_backend_sql["SQL render<br/>payload builder<br/>[sql_renderer.py]"]
  node_backend_db[("Cache DB<br/>SQLite cache<br/>[database.db]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_boot["App shell<br/>React bootstrap<br/>[App.tsx]"]
  node_frontend_main["Client entry<br/>Vite entrypoint<br/>[main.tsx]"]
  node_frontend_playground["Playground<br/>workspace<br/>[Playground.tsx]"]
  node_frontend_memory_mod["CMemory<br/>workspace<br/>[CMemory.tsx]"]
  node_frontend_sql_mod["SQL exec<br/>workspace<br/>[SQLExecution.tsx]"]
  node_frontend_search_mod["Search perf<br/>workspace"]
  node_frontend_code["Code viewer<br/>[CodeViewer.tsx]"]
  node_frontend_cfg["Flow graph<br/>viewer"]
  node_frontend_mem_vis["Memory view<br/>viewer"]
  node_frontend_controls["Playback<br/>interaction"]
  node_frontend_search_utils["Search utils<br/>client logic<br/>[search.ts]"]
end

node_frontend_main -->|"mounts"| node_frontend_boot
node_frontend_boot -->|"routes"| node_frontend_playground
node_frontend_boot -->|"routes"| node_frontend_memory_mod
node_frontend_boot -->|"routes"| node_frontend_sql_mod
node_frontend_boot -->|"routes"| node_frontend_search_mod
node_frontend_playground -->|"uses"| node_frontend_code
node_frontend_playground -->|"uses"| node_frontend_cfg
node_frontend_playground -->|"uses"| node_frontend_controls
node_frontend_memory_mod -->|"uses"| node_frontend_mem_vis
node_frontend_memory_mod -->|"uses"| node_frontend_controls
node_frontend_sql_mod -->|"uses"| node_frontend_controls
node_frontend_search_mod -->|"uses"| node_frontend_search_utils
node_frontend_search_mod -->|"uses"| node_frontend_controls
node_frontend_playground -->|"requests trace"| node_backend_main
node_backend_main -->|"dispatches"| node_backend_detector
node_backend_detector -->|"selects"| node_backend_tracer
node_backend_detector -->|"selects"| node_backend_snippet
node_backend_tracer -->|"builds"| node_backend_flow
node_backend_tracer -->|"builds"| node_backend_memory
node_backend_tracer -->|"builds"| node_backend_sql
node_backend_snippet -->|"enriches"| node_backend_flow
node_backend_main -->|"caches"| node_backend_db
node_backend_main -.->|"serves payloads"| node_frontend_boot

click node_backend_main "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/main.py"
click node_backend_detector "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/language_detector.py"
click node_backend_tracer "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/python_tracer.py"
click node_backend_snippet "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/snippet_analyzer.py"
click node_backend_flow "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/flow_renderer.py"
click node_backend_memory "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/memory_renderer.py"
click node_backend_sql "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/sql_renderer.py"
click node_backend_db "https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/database.db"
click node_frontend_boot "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/App.tsx"
click node_frontend_main "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/main.tsx"
click node_frontend_playground "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/Playground.tsx"
click node_frontend_memory_mod "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/CMemory.tsx"
click node_frontend_sql_mod "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/SQLExecution.tsx"
click node_frontend_search_mod "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/SearchPerformance.tsx"
click node_frontend_code "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/CodeViewer.tsx"
click node_frontend_cfg "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/ControlFlowGraph.tsx"
click node_frontend_mem_vis "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/MemoryVisualizer.tsx"
click node_frontend_controls "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/PlaybackControls.tsx"
click node_frontend_search_utils "https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/utils/search.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_detector,node_backend_tracer,node_backend_snippet,node_backend_flow,node_backend_memory,node_backend_sql,node_backend_db toneBlue
class node_frontend_boot,node_frontend_main,node_frontend_playground,node_frontend_memory_mod,node_frontend_sql_mod,node_frontend_search_mod,node_frontend_code,node_frontend_cfg,node_frontend_mem_vis,node_frontend_controls,node_frontend_search_utils toneAmber
```

## Components

### Backend

FastAPI analysis and payload generation service

- [API app](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/main.py): FastAPI entrypoint · Main HTTP boundary for code submission and trace payload delivery · `backend/main.py`
- [Language detect](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/language_detector.py): router · Chooses the analysis path for incoming snippets · `backend/engines/language_detector.py`
- [Python tracer](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/python_tracer.py): execution trace · Builds stepwise runtime traces and execution state · `backend/engines/python_tracer.py`
- [Snippet analysis](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/engines/snippet_analyzer.py): static analysis · Extracts snippet metadata and enriches trace output · `backend/engines/snippet_analyzer.py`
- [Flow render](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/flow_renderer.py): payload builder · Converts analysis output into control-flow visualization data · `backend/components/flow_renderer.py`
- [Memory render](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/memory_renderer.py): payload builder · Converts analysis output into stack and memory visualization data · `backend/components/memory_renderer.py`
- [SQL render](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/components/sql_renderer.py): payload builder · Converts analysis output into SQL execution visualization data · `backend/components/sql_renderer.py`
- [Cache DB](https://github.com/manisaiteja2007/code-visualizer/blob/main/backend/database.db): SQLite cache · Persistent cache for trace results and deduplication · `backend/database.db`

### Frontend

React app for interactive playback and visualization

- [App shell](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/App.tsx): React bootstrap · Top-level UI composition and client startup · `frontend/src/App.tsx`
- [Client entry](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/main.tsx): Vite entrypoint · Bootstraps the React application in the browser · `frontend/src/main.tsx`
- [Playground](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/Playground.tsx): workspace · General code execution and visualization workspace · `frontend/src/modules/Playground.tsx`
- [CMemory](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/CMemory.tsx): workspace · Memory-focused exploration module · `frontend/src/modules/CMemory.tsx`
- [SQL exec](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/SQLExecution.tsx): workspace · SQL pipeline visualization module · `frontend/src/modules/SQLExecution.tsx`
- [Search perf](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/modules/SearchPerformance.tsx): workspace · Algorithm comparison and performance module · `frontend/src/modules/SearchPerformance.tsx`
- [Code viewer](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/CodeViewer.tsx): viewer · Displays source code alongside playback · `frontend/src/components/CodeViewer.tsx`
- [Flow graph](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/ControlFlowGraph.tsx): viewer · Renders control-flow visualization in the browser · `frontend/src/components/ControlFlowGraph.tsx`
- [Memory view](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/MemoryVisualizer.tsx): viewer · Renders stack and memory state · `frontend/src/components/MemoryVisualizer.tsx`
- [Playback](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/components/PlaybackControls.tsx): interaction · Steps through precomputed execution frames locally · `frontend/src/components/PlaybackControls.tsx`
- [Search utils](https://github.com/manisaiteja2007/code-visualizer/blob/main/frontend/src/utils/search.ts): client logic · Client-side algorithm helpers used by the search module · `frontend/src/utils/search.ts`

## Connections

- Client entry → App shell: mounts · Browser entry mounts the app shell
- App shell → Playground: routes · App shell composes the main workspaces
- App shell → CMemory: routes · App shell composes the memory workspace
- App shell → SQL exec: routes · App shell composes the SQL workspace
- App shell → Search perf: routes · App shell composes the search workspace
- Playground → Code viewer: uses · Workspace shows source alongside playback
- Playground → Flow graph: uses · Workspace renders control-flow output
- Playground → Playback: uses · Workspace drives stepwise playback
- CMemory → Memory view: uses · Memory module renders execution state
- CMemory → Playback: uses · Memory module shares playback controls
- SQL exec → Playback: uses · SQL module shares playback controls
- Search perf → Search utils: uses · Search module uses local algorithm helpers
- Search perf → Playback: uses · Search module can step through results
- Playground → API app: requests trace · Frontend submits code to the backend API
- API app → Language detect: dispatches · API boundary routes snippets by language
- Language detect → Python tracer: selects · Python snippets flow into execution tracing
- Language detect → Snippet analysis: selects · Static analysis enriches detected snippets
- Python tracer → Flow render: builds · Trace data is shaped into flow payloads
- Python tracer → Memory render: builds · Trace data is shaped into memory payloads
- Python tracer → SQL render: builds · Trace data is shaped into SQL payloads
- Snippet analysis → Flow render: enriches · Snippet metadata informs rendered flow output
- API app → Cache DB: caches · API stores and reuses trace results
- API app → App shell: serves payloads · Backend returns structured data consumed by the UI
