# arafeytanwir-cloud/ai-visualizer-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/arafeytanwir-cloud/ai-visualizer-v2
- Repository: https://github.com/arafeytanwir-cloud/ai-visualizer-v2

## Overview

AI Visualizer turns a typed topic or uploaded PDF into an interactive 3D lesson. The main flow accepts input, extracts PDF text when needed, asks Gemini for a structured visualization blueprint, validates it, then renders one of four visualization styles alongside explanatory text and code. The shared blueprint types form a useful internal contract between generation, rendering, and the sidebar. The README provides no further product details; unsampled scene implementations are included because the canvas explicitly dispatches to them, but their internal behavior is not inferred.

Main entry points: [`components/visualization/VisualizationCanvas.tsx`](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/VisualizationCanvas.tsx) (Visualization canvas), [`app/page.tsx`](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/page.tsx) (App page), [`hooks/useVisualization.ts`](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/hooks/useVisualization.ts) (Generation hook), [`app/api/visualize/route.ts`](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/api/visualize/route.ts) (Visualization API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and orchestration"]
  node_home["App page<br/>[page.tsx]"]
  node_upload["Upload form<br/>[UploadForm.tsx]"]
  node_visualization_hook["Generation hook"]
  node_selection_hook["Node selection"]
end

subgraph group_generation["Blueprint generation"]
  node_extract_api["PDF extraction API<br/>[route.ts]"]
  node_visualize_api["Visualization API<br/>[route.ts]"]
  node_prompt["Prompt builder<br/>[prompt.ts]"]
  node_validator["Blueprint validator"]
end

subgraph group_presentation["Visualization and lessons"]
  node_canvas["Visualization canvas"]
  node_knowledge["Knowledge graph<br/>[KnowledgeGraph.tsx]"]
  node_timeline["Timeline scene<br/>[TimelineScene.tsx]"]
  node_hierarchy["Hierarchy scene<br/>[HierarchyScene.tsx]"]
  node_flow["Flow scene<br/>[FlowScene.tsx]"]
  node_controls["Scene controls<br/>[SceneControls.tsx]"]
  node_tooltip["Node tooltip<br/>[NodeTooltip.tsx]"]
  node_sidebar["Lesson sidebar<br/>[LessonSidebar.tsx]"]
  node_text_section["Text section<br/>[TextSection.tsx]"]
  node_code_section["Code section<br/>[CodeSection.tsx]"]
end

subgraph group_contracts["Shared data contract"]
  node_types["Blueprint types<br/>[types.ts]"]
end

node_user(("Learner"))
node_gemini["Gemini API"]

node_user -->|"provides input"| node_upload
node_upload -->|"submits input"| node_home
node_home -->|"starts generation"| node_visualization_hook
node_home -->|"tracks selection"| node_selection_hook
node_visualization_hook -->|"uploads PDF"| node_extract_api
node_visualization_hook -->|"requests blueprint"| node_visualize_api
node_visualize_api -->|"builds prompts"| node_prompt
node_visualize_api -->|"requests generation"| node_gemini
node_visualize_api -->|"validates response"| node_validator
node_visualization_hook -->|"sets blueprint"| node_home
node_home -->|"renders blueprint"| node_canvas
node_home -->|"renders lesson"| node_sidebar
node_canvas -->|"dispatches graph"| node_knowledge
node_canvas -->|"dispatches timeline"| node_timeline
node_canvas -->|"dispatches hierarchy"| node_hierarchy
node_canvas -->|"dispatches flow"| node_flow
node_canvas -->|"renders controls"| node_controls
node_canvas -->|"renders selection"| node_tooltip
node_canvas -->|"updates selection"| node_selection_hook
node_sidebar -->|"renders text"| node_text_section
node_sidebar -->|"renders code"| node_code_section

click node_home "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/page.tsx"
click node_upload "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/landing/UploadForm.tsx"
click node_visualization_hook "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/hooks/useVisualization.ts"
click node_selection_hook "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/hooks/useNodeSelection.ts"
click node_extract_api "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/api/extract/route.ts"
click node_visualize_api "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/api/visualize/route.ts"
click node_prompt "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/prompt.ts"
click node_validator "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/validateBlueprint.ts"
click node_types "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/types.ts"
click node_canvas "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/VisualizationCanvas.tsx"
click node_knowledge "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/KnowledgeGraph.tsx"
click node_timeline "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/TimelineScene.tsx"
click node_hierarchy "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/HierarchyScene.tsx"
click node_flow "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/FlowScene.tsx"
click node_controls "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/ui/SceneControls.tsx"
click node_tooltip "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/ui/NodeTooltip.tsx"
click node_sidebar "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/LessonSidebar.tsx"
click node_text_section "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/TextSection.tsx"
click node_code_section "https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/CodeSection.tsx"

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_home,node_upload,node_visualization_hook,node_selection_hook toneBlue
class node_extract_api,node_visualize_api,node_prompt,node_validator toneAmber
class node_canvas,node_knowledge,node_timeline,node_hierarchy,node_flow,node_controls,node_tooltip,node_sidebar,node_text_section,node_code_section,node_gemini toneMint
class node_types toneRose
class node_user toneIndigo
```

## Components

### Input and orchestration

- [App page](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/page.tsx): `app/page.tsx`
- [Upload form](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/landing/UploadForm.tsx): `components/landing/UploadForm.tsx`
- [Generation hook](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/hooks/useVisualization.ts): `hooks/useVisualization.ts`
- [Node selection](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/hooks/useNodeSelection.ts): `hooks/useNodeSelection.ts`

### Blueprint generation

- [PDF extraction API](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/api/extract/route.ts): `app/api/extract/route.ts`
- [Visualization API](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/app/api/visualize/route.ts): `app/api/visualize/route.ts`
- [Prompt builder](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/prompt.ts): `lib/prompt.ts`
- [Blueprint validator](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/validateBlueprint.ts): `lib/validateBlueprint.ts`

### Visualization and lessons

- [Visualization canvas](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/VisualizationCanvas.tsx): `components/visualization/VisualizationCanvas.tsx`
- [Knowledge graph](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/KnowledgeGraph.tsx): `components/visualization/scene/KnowledgeGraph.tsx`
- [Timeline scene](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/TimelineScene.tsx): `components/visualization/scene/TimelineScene.tsx`
- [Hierarchy scene](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/HierarchyScene.tsx): `components/visualization/scene/HierarchyScene.tsx`
- [Flow scene](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/scene/FlowScene.tsx): `components/visualization/scene/FlowScene.tsx`
- [Scene controls](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/ui/SceneControls.tsx): `components/visualization/ui/SceneControls.tsx`
- [Node tooltip](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/visualization/ui/NodeTooltip.tsx): `components/visualization/ui/NodeTooltip.tsx`
- [Lesson sidebar](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/LessonSidebar.tsx): `components/sidebar/LessonSidebar.tsx`
- [Text section](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/TextSection.tsx): `components/sidebar/TextSection.tsx`
- [Code section](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/components/sidebar/CodeSection.tsx): `components/sidebar/CodeSection.tsx`

### Shared data contract

- [Blueprint types](https://github.com/arafeytanwir-cloud/ai-visualizer-v2/blob/main/lib/types.ts): `lib/types.ts`

### Other components

- **Learner**
- **Gemini API**

## Connections

- Learner → Upload form: provides input (evidence: `components/landing/UploadForm.tsx`)
- Upload form → App page: submits input (evidence: `app/page.tsx`)
- App page → Generation hook: starts generation (evidence: `app/page.tsx`)
- App page → Node selection: tracks selection (evidence: `app/page.tsx`)
- Generation hook → PDF extraction API: uploads PDF (evidence: `hooks/useVisualization.ts`)
- Generation hook → Visualization API: requests blueprint (evidence: `hooks/useVisualization.ts`)
- Visualization API → Prompt builder: builds prompts (evidence: `app/api/visualize/route.ts`)
- Visualization API → Gemini API: requests generation (evidence: `app/api/visualize/route.ts`)
- Visualization API → Blueprint validator: validates response (evidence: `app/api/visualize/route.ts`)
- Generation hook → App page: sets blueprint (evidence: `app/page.tsx`)
- App page → Visualization canvas: renders blueprint (evidence: `app/page.tsx`)
- App page → Lesson sidebar: renders lesson (evidence: `app/page.tsx`)
- Visualization canvas → Knowledge graph: dispatches graph (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Timeline scene: dispatches timeline (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Hierarchy scene: dispatches hierarchy (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Flow scene: dispatches flow (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Scene controls: renders controls (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Node tooltip: renders selection (evidence: `components/visualization/VisualizationCanvas.tsx`)
- Visualization canvas → Node selection: updates selection (evidence: `app/page.tsx`)
- Lesson sidebar → Text section: renders text (evidence: `components/sidebar/LessonSidebar.tsx`)
- Lesson sidebar → Code section: renders code (evidence: `components/sidebar/LessonSidebar.tsx`)