# n-avtej/algo-visualizer architecture

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

- Interactive diagram: https://gitdiagram.com/n-avtej/algo-visualizer
- Repository: https://github.com/n-avtej/algo-visualizer

## Overview

AlgoLens Pro is an interactive algorithm-learning suite. Learners explore the curriculum, run algorithms to see stepwise visualizations and telemetry, practice with quizzes, and can ask an AI tutor questions. The graph shows the documented frontend-to-API workflow, curriculum and progress features, and the backend algorithm and AI capabilities. Some backend route-to-implementation links are documented only at a broad level, so those links are marked unverified rather than asserting specific calls.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/App.tsx) (Web app routes), [`frontend/src/components/visualizations`](https://github.com/n-avtej/algo-visualizer/tree/dev/frontend/src/components/visualizations) (Module visualizers), [`backend/app/ai/rag.py`](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/ai/rag.py) (RAG pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning_ui["Learning experience"]
  node_app["Web app routes<br/>[App.tsx]"]
  node_home["Curriculum home<br/>[HomePage.tsx]"]
  node_curriculum["Curriculum content<br/>[curriculumData.ts]"]
  node_practice["Practice quizzes<br/>[PracticePage.tsx]"]
  node_progress["Progress state<br/>[progressStore.ts]"]
  node_module_page["Module learning<br/>[ModulePage.tsx]"]
  node_ai_page["AI tutor page"]
end

subgraph group_visualizers["Algorithm visualizations"]
  node_visualizers["Module visualizers"]
  node_animation["Animation player"]
  node_telemetry["Metrics and code<br/>[MetricsPanel.tsx]"]
end

subgraph group_backend["API and algorithms"]
  node_api_client["API client<br/>[client.ts]"]
  node_api_server["FastAPI entrypoint<br/>[main.py]"]
  node_api_routes["REST route handlers"]
  node_algorithm_runner["Algorithm traces<br/>[algorithms.py]"]
  node_algorithm_impl["Algorithm implementations"]
  node_auth["Authentication<br/>[auth.py]"]
  node_ai_routes["AI endpoint<br/>[ai.py]"]
end

subgraph group_ai_data["AI and persistence"]
  node_rag["RAG pipeline<br/>[rag.py]"]
  node_embeddings["Embedding service<br/>[embeddings.py]"]
  node_knowledge[("Knowledge base<br/>[knowledge_base.py]")]
  node_database[("Application database<br/>[session.py]")]
end

node_learner(("Learner"))
node_gemini{{"Gemini AI"}}

node_learner -->|"navigates"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_module_page
node_app -->|"routes to"| node_practice
node_home -->|"loads content"| node_curriculum
node_home -->|"reads progress"| node_progress
node_module_page -.->|"presents stages"| node_visualizers
node_visualizers -.->|"uses playback"| node_animation
node_visualizers -.->|"shows metrics"| node_telemetry
node_visualizers -->|"requests traces"| node_api_client
node_api_client -->|"sends requests"| node_api_server
node_api_server -->|"mounts routes"| node_api_routes
node_api_routes -.->|"dispatches runs"| node_algorithm_runner
node_algorithm_runner -.->|"generates traces"| node_algorithm_impl
node_api_client -->|"calls auth endpoints"| node_auth
node_ai_page -.->|"submits questions"| node_api_client
node_api_client -->|"calls AI endpoint"| node_ai_routes
node_ai_routes -.->|"uses retrieval"| node_rag
node_rag -->|"retrieves chunks"| node_knowledge
node_rag -->|"requests completion"| node_gemini
node_rag -->|"queries vectors"| node_database
node_embeddings -->|"creates vectors"| node_gemini

click node_app "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/App.tsx"
click node_home "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/HomePage.tsx"
click node_curriculum "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/data/curriculumData.ts"
click node_practice "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/PracticePage.tsx"
click node_progress "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/store/progressStore.ts"
click node_module_page "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/ModulePage.tsx"
click node_visualizers "https://github.com/n-avtej/algo-visualizer/tree/dev/frontend/src/components/visualizations"
click node_animation "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/components/common/AnimationPlayer.tsx"
click node_telemetry "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/components/common/MetricsPanel.tsx"
click node_api_client "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/api/client.ts"
click node_api_server "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/main.py"
click node_api_routes "https://github.com/n-avtej/algo-visualizer/tree/dev/backend/app/api/routes"
click node_algorithm_runner "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/algorithms.py"
click node_algorithm_impl "https://github.com/n-avtej/algo-visualizer/tree/dev/backend/app/algorithms"
click node_auth "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/auth.py"
click node_ai_page "https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/AIAssistantPage.tsx"
click node_ai_routes "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/ai.py"
click node_rag "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/ai/rag.py"
click node_embeddings "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/ai/embeddings.py"
click node_knowledge "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/models/knowledge_base.py"
click node_database "https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/db/session.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_app,node_home,node_curriculum,node_practice,node_progress,node_module_page,node_ai_page toneBlue
class node_visualizers,node_animation,node_telemetry toneAmber
class node_api_client,node_api_server,node_api_routes,node_algorithm_runner,node_algorithm_impl,node_auth,node_ai_routes toneMint
class node_rag,node_embeddings,node_knowledge,node_database toneRose
class node_learner,node_gemini toneIndigo
```

## Components

### Learning experience

- [Web app routes](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Curriculum home](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [Curriculum content](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/data/curriculumData.ts): `frontend/src/data/curriculumData.ts`
- [Practice quizzes](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/PracticePage.tsx): `frontend/src/pages/PracticePage.tsx`
- [Progress state](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/store/progressStore.ts): `frontend/src/store/progressStore.ts`
- [Module learning](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/ModulePage.tsx): `frontend/src/pages/ModulePage.tsx`
- [AI tutor page](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/pages/AIAssistantPage.tsx): `frontend/src/pages/AIAssistantPage.tsx`

### Algorithm visualizations

- [Module visualizers](https://github.com/n-avtej/algo-visualizer/tree/dev/frontend/src/components/visualizations): `frontend/src/components/visualizations`
- [Animation player](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/components/common/AnimationPlayer.tsx): `frontend/src/components/common/AnimationPlayer.tsx`
- [Metrics and code](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/components/common/MetricsPanel.tsx): `frontend/src/components/common/MetricsPanel.tsx`

### API and algorithms

- [API client](https://github.com/n-avtej/algo-visualizer/blob/dev/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [FastAPI entrypoint](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/main.py): `backend/app/main.py`
- [REST route handlers](https://github.com/n-avtej/algo-visualizer/tree/dev/backend/app/api/routes): `backend/app/api/routes`
- [Algorithm traces](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/algorithms.py): `backend/app/api/routes/algorithms.py`
- [Algorithm implementations](https://github.com/n-avtej/algo-visualizer/tree/dev/backend/app/algorithms): `backend/app/algorithms`
- [Authentication](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [AI endpoint](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/api/routes/ai.py): `backend/app/api/routes/ai.py`

### AI and persistence

- [RAG pipeline](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/ai/rag.py): `backend/app/ai/rag.py`
- [Embedding service](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/ai/embeddings.py): `backend/app/ai/embeddings.py`
- [Knowledge base](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/models/knowledge_base.py): `backend/app/models/knowledge_base.py`
- [Application database](https://github.com/n-avtej/algo-visualizer/blob/dev/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Learner**
- **Gemini AI**

## Connections

- Learner → Web app routes: navigates (evidence: `frontend/src/App.tsx`)
- Web app routes → Curriculum home: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Module learning: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Practice quizzes: routes to (evidence: `frontend/src/App.tsx`)
- Curriculum home → Curriculum content: loads content (evidence: `frontend/src/pages/HomePage.tsx`)
- Curriculum home → Progress state: reads progress (evidence: `frontend/src/pages/HomePage.tsx`)
- Module learning → Module visualizers: presents stages (evidence: `README.md`)
- Module visualizers → Animation player: uses playback (evidence: `README.md`)
- Module visualizers → Metrics and code: shows metrics (evidence: `README.md`)
- Module visualizers → API client: requests traces (evidence: `frontend/src/components/visualizations/Module1/ComparisonArena.tsx`)
- API client → FastAPI entrypoint: sends requests (evidence: `frontend/src/api/client.ts`)
- FastAPI entrypoint → REST route handlers: mounts routes (evidence: `backend/app/main.py`)
- REST route handlers → Algorithm traces: dispatches runs
- Algorithm traces → Algorithm implementations: generates traces
- API client → Authentication: calls auth endpoints (evidence: `frontend/src/api/client.ts`)
- AI tutor page → API client: submits questions (evidence: `README.md`)
- API client → AI endpoint: calls AI endpoint (evidence: `frontend/src/api/client.ts`)
- AI endpoint → RAG pipeline: uses retrieval (evidence: `README.md`)
- RAG pipeline → Knowledge base: retrieves chunks (evidence: `backend/app/ai/rag.py`)
- RAG pipeline → Gemini AI: requests completion (evidence: `backend/app/ai/rag.py`)
- RAG pipeline → Application database: queries vectors (evidence: `backend/app/ai/rag.py`)
- Embedding service → Gemini AI: creates vectors (evidence: `backend/app/ai/embeddings.py`)
