How manisaiteja2007/code-visualizer works
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: App.tsx App shell · Playground.tsx Playground · main.py API app · python_tracer.py Python tracer
Components 19
Backend
FastAPI analysis and payload generation service
- API app · Main HTTP boundary for code submission and trace payload delivery
backend/main.py - Language detect · Chooses the analysis path for incoming snippets
backend/engines/language_detector.py - Python tracer · Builds stepwise runtime traces and execution state
backend/engines/python_tracer.py - Snippet analysis · Extracts snippet metadata and enriches trace output
backend/engines/snippet_analyzer.py - Flow render · Converts analysis output into control-flow visualization data
backend/components/flow_renderer.py - Memory render · Converts analysis output into stack and memory visualization data
backend/components/memory_renderer.py - SQL render · Converts analysis output into SQL execution visualization data
backend/components/sql_renderer.py - Cache DB · Persistent cache for trace results and deduplication
backend/database.db
Frontend
React app for interactive playback and visualization
- App shell · Top-level UI composition and client startup
frontend/src/App.tsx - Client entry · Bootstraps the React application in the browser
frontend/src/main.tsx - Playground · General code execution and visualization workspace
frontend/src/modules/Playground.tsx - CMemory · Memory-focused exploration module
frontend/src/modules/CMemory.tsx - SQL exec · SQL pipeline visualization module
frontend/src/modules/SQLExecution.tsx - Search perf · Algorithm comparison and performance module
frontend/src/modules/SearchPerformance.tsx - Code viewer · Displays source code alongside playback
frontend/src/components/CodeViewer.tsx - Flow graph · Renders control-flow visualization in the browser
frontend/src/components/ControlFlowGraph.tsx - Memory view · Renders stack and memory state
frontend/src/components/MemoryVisualizer.tsx - Playback · Steps through precomputed execution frames locally
frontend/src/components/PlaybackControls.tsx - Search utils · Client-side algorithm helpers used by the search module
frontend/src/utils/search.ts
Connections 23
- 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