# suryakrishna999/coidspi architecture

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

- Interactive diagram: https://gitdiagram.com/suryakrishna999/coidspi
- Repository: https://github.com/suryakrishna999/coidspi

## Overview

Code Visualizer lets a learner enter Python, run it as a bounded trace, and inspect execution step by step; it also offers static explanations, trace-based narration, and code Q&A. The React app presents the trace and controls the current step, while the FastAPI service dispatches execution to a subprocess and provides AI-backed endpoints. A sampled Cloudflare Worker implements a parallel AI service path. The README documents the main workflow; some frontend request handlers and Worker routing details were not shown, so those links are limited to documented relationships.

Main entry points: [`frontend/src/App.jsx`](https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx) (Visualizer app), [`backend/main.py`](https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py) (Trace endpoint), [`backend/runner.py`](https://github.com/suryakrishna999/coidspi/blob/main/backend/runner.py) (Sandboxed tracer), [`backend/src/worker.py`](https://github.com/suryakrishna999/coidspi/blob/main/backend/src/worker.py) (Cloudflare API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner_ui["Learner interface"]
  node_visualizer["Visualizer app<br/>[App.jsx]"]
  node_trace_view["Trace playback<br/>[App.jsx]"]
  node_static_view["Line explanations<br/>[App.jsx]"]
  node_chat_ui["Tutor chat<br/>[App.jsx]"]
end

subgraph group_execution["Trace execution"]
  node_runner["Sandboxed tracer<br/>[runner.py]"]
end

subgraph group_api_ai["API and AI"]
  node_api["HTTP API<br/>[main.py]"]
  node_trace_endpoint["Trace endpoint<br/>[main.py]"]
  node_ai_endpoints["Explain and chat<br/>[main.py]"]
  node_explain_page["Standalone explain page<br/>[main.py]"]
end

subgraph group_worker_runtime["Worker runtime"]
  node_cloud_worker["Cloudflare API<br/>[worker.py]"]
end

node_learner(("Learner"))
node_workers_ai{{"Workers AI"}}

node_learner -->|"writes code"| node_visualizer
node_visualizer -->|"requests trace"| node_trace_endpoint
node_trace_endpoint -->|"runs subprocess"| node_runner
node_runner -->|"returns trace"| node_trace_endpoint
node_trace_endpoint -->|"supplies steps"| node_trace_view
node_trace_view -->|"shows playback"| node_learner
node_visualizer -->|"requests narration"| node_ai_endpoints
node_ai_endpoints -->|"returns narration"| node_visualizer
node_learner -->|"asks questions"| node_chat_ui
node_chat_ui -.->|"sends questions"| node_ai_endpoints
node_api -->|"serves page"| node_explain_page
node_explain_page -->|"requests explanation"| node_ai_endpoints
node_cloud_worker -->|"runs model"| node_workers_ai

click node_visualizer "https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx"
click node_trace_view "https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx"
click node_static_view "https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx"
click node_chat_ui "https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py"
click node_trace_endpoint "https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py"
click node_ai_endpoints "https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py"
click node_explain_page "https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py"
click node_runner "https://github.com/suryakrishna999/coidspi/blob/main/backend/runner.py"
click node_cloud_worker "https://github.com/suryakrishna999/coidspi/blob/main/backend/src/worker.py"

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_visualizer,node_trace_view,node_static_view,node_chat_ui toneBlue
class node_runner toneAmber
class node_api,node_trace_endpoint,node_ai_endpoints,node_explain_page toneMint
class node_cloud_worker,node_workers_ai toneRose
class node_learner toneIndigo
```

## Components

### Learner interface

- [Visualizer app](https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Trace playback](https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Line explanations](https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Tutor chat](https://github.com/suryakrishna999/coidspi/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Trace execution

- [Sandboxed tracer](https://github.com/suryakrishna999/coidspi/blob/main/backend/runner.py): `backend/runner.py`

### API and AI

- [HTTP API](https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py): `backend/main.py`
- [Trace endpoint](https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py): `backend/main.py`
- [Explain and chat](https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py): `backend/main.py`
- [Standalone explain page](https://github.com/suryakrishna999/coidspi/blob/main/backend/main.py): `backend/main.py`

### Worker runtime

- [Cloudflare API](https://github.com/suryakrishna999/coidspi/blob/main/backend/src/worker.py): `backend/src/worker.py`

### Other components

- **Learner**
- **Workers AI**

## Connections

- Learner → Visualizer app: writes code (evidence: `README.md`)
- Visualizer app → Trace endpoint: requests trace (evidence: `README.md`)
- Trace endpoint → Sandboxed tracer: runs subprocess (evidence: `backend/main.py`)
- Sandboxed tracer → Trace endpoint: returns trace (evidence: `README.md`)
- Trace endpoint → Trace playback: supplies steps (evidence: `README.md`)
- Trace playback → Learner: shows playback (evidence: `README.md`)
- Visualizer app → Explain and chat: requests narration (evidence: `README.md`)
- Explain and chat → Visualizer app: returns narration (evidence: `README.md`)
- Learner → Tutor chat: asks questions (evidence: `README.md`)
- Tutor chat → Explain and chat: sends questions
- HTTP API → Standalone explain page: serves page (evidence: `backend/main.py`)
- Standalone explain page → Explain and chat: requests explanation (evidence: `backend/main.py`)
- Cloudflare API → Workers AI: runs model (evidence: `backend/src/worker.py`)
