# fawmeen/manimai architecture

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

- Interactive diagram: https://gitdiagram.com/fawmeen/manimai
- Repository: https://github.com/fawmeen/manimai

## Overview

AI-Math-Tutor accepts a topic, routes it through a FastAPI/LangGraph workflow, reuses cached animations when possible, and otherwise generates and renders Manim or Matplotlib video. The Manim path can add a transcript and audio before merging them; results are returned as media URLs. The README also describes planning and self-healing capabilities, though the sampled workflow does not show a planner stage or its retry loop. Frontend source is present, but its connection to the API is not evidenced in the excerpts.

Main entry points: [`backend/graph/workflow.py`](https://github.com/fawmeen/manimai/blob/main/backend/graph/workflow.py) (LangGraph workflow), [`backend/agents/tools.py`](https://github.com/fawmeen/manimai/blob/main/backend/agents/tools.py) (Agent tools), [`backend/agents/code_generator.py`](https://github.com/fawmeen/manimai/blob/main/backend/agents/code_generator.py) (Manim generator), [`Frontend/src/app/page.tsx`](https://github.com/fawmeen/manimai/blob/main/Frontend/src/app/page.tsx) (Web page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_web_app["Web page<br/>[page.tsx]"]
  node_hero["Hero section<br/>[Hero.tsx]"]
  node_video_explanation["Video explanation"]
end

subgraph group_api_workflow["API and orchestration"]
  node_api["FastAPI endpoint<br/>[main.py]"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
  node_toolkit["Agent tools<br/>[tools.py]"]
  node_model_config["Gemini client<br/>[config.py]"]
end

subgraph group_generation["Generation and rendering"]
  node_planner["Animation planner<br/>[planner_agent.py]"]
  node_manim_generator["Manim generator<br/>[code_generator.py]"]
  node_code_reviewer["Code reviewer<br/>[code_reviewer.py]"]
  node_manim_executor["Manim executor<br/>[execution_agent.py]"]
  node_mpl_generator["Matplotlib generator"]
  node_mpl_executor["Matplotlib executor"]
  node_extractor["Code extractor<br/>[code_extractor.py]"]
end

subgraph group_media_knowledge["Media and knowledge"]
  node_transcript["Transcript agent"]
  node_audio_agent["Audio agent<br/>[audio_agent.py]"]
  node_audio_generator["Speech generation<br/>[gen_audio.py]"]
  node_video_merge["Video merger<br/>[video_merge.py]"]
  node_retriever["Animation retrieval<br/>[retriever.py]"]
  node_vector_store[("Vector collection<br/>[vector_store.py]")]
  node_memory[("Persistent memory")]
end

node_user(("User"))
node_gemini(("Gemini service"))

node_user -->|"submits prompt"| node_api
node_api -->|"invokes graph"| node_workflow
node_workflow -->|"decides route"| node_orchestrator
node_orchestrator -->|"asks model"| node_model_config
node_model_config -->|"generates content"| node_gemini
node_workflow -->|"checks and stores"| node_retriever
node_retriever -->|"queries and adds"| node_vector_store
node_workflow -->|"generates code"| node_manim_generator
node_manim_generator -->|"reads similar cases"| node_memory
node_manim_generator -->|"extracts code"| node_extractor
node_workflow -->|"executes code"| node_manim_executor
node_manim_executor -->|"uses for review"| node_code_reviewer
node_code_reviewer -->|"extracts revised code"| node_extractor
node_workflow -->|"generates plot code"| node_mpl_generator
node_workflow -->|"renders plot video"| node_mpl_executor
node_workflow -->|"generates transcript"| node_transcript
node_workflow -->|"generates audio"| node_audio_agent
node_audio_agent -->|"creates speech"| node_audio_generator
node_workflow -->|"merges media"| node_video_merge
node_toolkit -->|"creates plan"| node_planner
node_toolkit -->|"generates code"| node_manim_generator
node_toolkit -->|"reviews code"| node_code_reviewer
node_toolkit -->|"executes code"| node_manim_executor
node_api -->|"returns media links"| node_user
node_user -.->|"uses interface"| node_web_app
node_web_app -.->|"presents section"| node_hero
node_web_app -.->|"presents section"| node_video_explanation

click node_web_app "https://github.com/fawmeen/manimai/blob/main/Frontend/src/app/page.tsx"
click node_hero "https://github.com/fawmeen/manimai/blob/main/Frontend/src/components/Hero.tsx"
click node_video_explanation "https://github.com/fawmeen/manimai/blob/main/Frontend/src/components/VideoExplanation.tsx"
click node_api "https://github.com/fawmeen/manimai/blob/main/backend/api/main.py"
click node_workflow "https://github.com/fawmeen/manimai/blob/main/backend/graph/workflow.py"
click node_orchestrator "https://github.com/fawmeen/manimai/blob/main/backend/agents/orchestrator.py"
click node_toolkit "https://github.com/fawmeen/manimai/blob/main/backend/agents/tools.py"
click node_planner "https://github.com/fawmeen/manimai/blob/main/backend/agents/planner_agent.py"
click node_manim_generator "https://github.com/fawmeen/manimai/blob/main/backend/agents/code_generator.py"
click node_code_reviewer "https://github.com/fawmeen/manimai/blob/main/backend/agents/code_reviewer.py"
click node_manim_executor "https://github.com/fawmeen/manimai/blob/main/backend/agents/execution_agent.py"
click node_mpl_generator "https://github.com/fawmeen/manimai/blob/main/backend/agents/matplotlib_agent.py"
click node_mpl_executor "https://github.com/fawmeen/manimai/blob/main/backend/agents/matplotlib_execution_agent.py"
click node_extractor "https://github.com/fawmeen/manimai/blob/main/backend/utils/code_extractor.py"
click node_transcript "https://github.com/fawmeen/manimai/blob/main/backend/agents/transcript_agent.py"
click node_audio_agent "https://github.com/fawmeen/manimai/blob/main/backend/agents/audio_agent.py"
click node_audio_generator "https://github.com/fawmeen/manimai/blob/main/backend/gen_audio.py"
click node_video_merge "https://github.com/fawmeen/manimai/blob/main/backend/utils/video_merge.py"
click node_retriever "https://github.com/fawmeen/manimai/blob/main/backend/rag/retriever.py"
click node_vector_store "https://github.com/fawmeen/manimai/blob/main/backend/rag/vector_store.py"
click node_memory "https://github.com/fawmeen/manimai/blob/main/backend/memory/persistent_memory.py"
click node_model_config "https://github.com/fawmeen/manimai/blob/main/backend/config.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_web_app,node_hero,node_video_explanation,node_user toneBlue
class node_api,node_workflow,node_orchestrator,node_toolkit,node_model_config toneAmber
class node_planner,node_manim_generator,node_code_reviewer,node_manim_executor,node_mpl_generator,node_mpl_executor,node_extractor toneMint
class node_transcript,node_audio_agent,node_audio_generator,node_video_merge,node_retriever,node_vector_store,node_memory toneRose
class node_gemini toneIndigo
```

## Components

### Web experience

- [Web page](https://github.com/fawmeen/manimai/blob/main/Frontend/src/app/page.tsx): `Frontend/src/app/page.tsx`
- [Hero section](https://github.com/fawmeen/manimai/blob/main/Frontend/src/components/Hero.tsx): `Frontend/src/components/Hero.tsx`
- [Video explanation](https://github.com/fawmeen/manimai/blob/main/Frontend/src/components/VideoExplanation.tsx): `Frontend/src/components/VideoExplanation.tsx`

### API and orchestration

- [FastAPI endpoint](https://github.com/fawmeen/manimai/blob/main/backend/api/main.py): `backend/api/main.py`
- [LangGraph workflow](https://github.com/fawmeen/manimai/blob/main/backend/graph/workflow.py): `backend/graph/workflow.py`
- [Orchestrator](https://github.com/fawmeen/manimai/blob/main/backend/agents/orchestrator.py): `backend/agents/orchestrator.py`
- [Agent tools](https://github.com/fawmeen/manimai/blob/main/backend/agents/tools.py): `backend/agents/tools.py`
- [Gemini client](https://github.com/fawmeen/manimai/blob/main/backend/config.py): `backend/config.py`

### Generation and rendering

- [Animation planner](https://github.com/fawmeen/manimai/blob/main/backend/agents/planner_agent.py): `backend/agents/planner_agent.py`
- [Manim generator](https://github.com/fawmeen/manimai/blob/main/backend/agents/code_generator.py): `backend/agents/code_generator.py`
- [Code reviewer](https://github.com/fawmeen/manimai/blob/main/backend/agents/code_reviewer.py): `backend/agents/code_reviewer.py`
- [Manim executor](https://github.com/fawmeen/manimai/blob/main/backend/agents/execution_agent.py): `backend/agents/execution_agent.py`
- [Matplotlib generator](https://github.com/fawmeen/manimai/blob/main/backend/agents/matplotlib_agent.py): `backend/agents/matplotlib_agent.py`
- [Matplotlib executor](https://github.com/fawmeen/manimai/blob/main/backend/agents/matplotlib_execution_agent.py): `backend/agents/matplotlib_execution_agent.py`
- [Code extractor](https://github.com/fawmeen/manimai/blob/main/backend/utils/code_extractor.py): `backend/utils/code_extractor.py`

### Media and knowledge

- [Transcript agent](https://github.com/fawmeen/manimai/blob/main/backend/agents/transcript_agent.py): `backend/agents/transcript_agent.py`
- [Audio agent](https://github.com/fawmeen/manimai/blob/main/backend/agents/audio_agent.py): `backend/agents/audio_agent.py`
- [Speech generation](https://github.com/fawmeen/manimai/blob/main/backend/gen_audio.py): `backend/gen_audio.py`
- [Video merger](https://github.com/fawmeen/manimai/blob/main/backend/utils/video_merge.py): `backend/utils/video_merge.py`
- [Animation retrieval](https://github.com/fawmeen/manimai/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Vector collection](https://github.com/fawmeen/manimai/blob/main/backend/rag/vector_store.py): `backend/rag/vector_store.py`
- [Persistent memory](https://github.com/fawmeen/manimai/blob/main/backend/memory/persistent_memory.py): `backend/memory/persistent_memory.py`

### Other components

- **User**
- **Gemini service**

## Connections

- User → FastAPI endpoint: submits prompt (evidence: `README.md`)
- FastAPI endpoint → LangGraph workflow: invokes graph (evidence: `backend/api/main.py`)
- LangGraph workflow → Orchestrator: decides route (evidence: `backend/graph/workflow.py`)
- Orchestrator → Gemini client: asks model (evidence: `backend/agents/orchestrator.py`)
- Gemini client → Gemini service: generates content (evidence: `backend/config.py`)
- LangGraph workflow → Animation retrieval: checks and stores (evidence: `backend/graph/workflow.py`)
- Animation retrieval → Vector collection: queries and adds (evidence: `backend/rag/retriever.py`)
- LangGraph workflow → Manim generator: generates code (evidence: `backend/graph/workflow.py`)
- Manim generator → Persistent memory: reads similar cases (evidence: `backend/agents/code_generator.py`)
- Manim generator → Code extractor: extracts code (evidence: `backend/agents/code_generator.py`)
- LangGraph workflow → Manim executor: executes code (evidence: `backend/graph/workflow.py`)
- Manim executor → Code reviewer: uses for review (evidence: `backend/agents/execution_agent.py`)
- Code reviewer → Code extractor: extracts revised code (evidence: `backend/agents/code_reviewer.py`)
- LangGraph workflow → Matplotlib generator: generates plot code (evidence: `backend/graph/workflow.py`)
- LangGraph workflow → Matplotlib executor: renders plot video (evidence: `backend/graph/workflow.py`)
- LangGraph workflow → Transcript agent: generates transcript (evidence: `backend/graph/workflow.py`)
- LangGraph workflow → Audio agent: generates audio (evidence: `backend/graph/workflow.py`)
- Audio agent → Speech generation: creates speech (evidence: `backend/agents/audio_agent.py`)
- LangGraph workflow → Video merger: merges media (evidence: `backend/graph/workflow.py`)
- Agent tools → Animation planner: creates plan (evidence: `backend/agents/tools.py`)
- Agent tools → Manim generator: generates code (evidence: `backend/agents/tools.py`)
- Agent tools → Code reviewer: reviews code (evidence: `backend/agents/tools.py`)
- Agent tools → Manim executor: executes code (evidence: `backend/agents/tools.py`)
- FastAPI endpoint → User: returns media links (evidence: `backend/api/main.py`)
- User → Web page: uses interface
- Web page → Hero section: presents section
- Web page → Video explanation: presents section
