# mahakagarwal7/bharatvidya architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/bharatvidya
- Repository: https://github.com/mahakagarwal7/bharatvidya

## Overview

#### Purpose and entry points
BharatVidya converts a concept prompt into a narrated, animated MP4 in selected languages. It has three entry surfaces: React SPA (`frontend/src/main.jsx`, `frontend/src/App.jsx`), FastAPI service (`web_app/api.py`, launched by `run.py`), and direct CLI pipeline (`src/main.py`).

#### Client application
The Vite/React frontend collects concept, language, and animation preferences; submits generation requests; polls job state; and presents generated videos/gallery. Its integration boundary is the backend `/api` contract, configured separately for frontend deployment.
Paths: `frontend/src/App.jsx`, `frontend/src/main.jsx`, `frontend/vercel.json`.

#### API, job lifecycle, and delivery
FastAPI owns public HTTP endpoints for generation, status, video listing/retrieval, supported topics, and health. Requests are validated by Pydantic models, converted into asynchronous job work, and expose progress/error/final URL through job status. The job subsystem is described as Redis-backed; video persistence/delivery is abstracted through S3 service code.
Paths: `web_app/api.py`, `web_app/models.py`, `web_app/jobs.py`, `web_app/video_service.py`, `web_app/s3_service.py`.

#### Content-planning boundary
The core engine first translates an input concept into a structured educational plan: title, summary, sections, facts, and narration-oriented content. `planner.py` delegates model calls to a local Ollama client; plans are materialized under `outputs/plans/`. This structured plan is the key handoff between generative AI and deterministic media stages.
Paths: `src/planner.py`, `src/local_llm_client.py`, `outputs/plans/plan_00157e08.json`.

#### Media-generation pipeline
`Animator` orchestrates plan consumption, narration, visuals, and final composition. The narrator uses Edge-TTS and audio processing to create per-intro/step assets; the renderer uses MoviePy/OpenCV and FFmpeg to combine timed audio, generated cards, images, transitions, and optional animation clips into MP4. Runtime artifacts are filesystem-backed before cloud upload.
Paths: `src/animator.py`, `src/narrator.py`, `src/renderer.py`, `src/card_generator.py`, `outputs/audio/00afbd0b_combined.mp3`.

#### Topic-specific visualization
A router selects specialized visual engines for recognized concepts, while generic rendering remains available for other topics. Existing domain engines cover algorithms and STEM concepts such as binary search, bubble sort, projectile motion, quadratic equations, and sine waves. LaTeX rendering supports formula/image assets within visual scenes.
Paths: `src/topic_router.py`, `src/domain_engines/binary_search.py`, `src/domain_engines/quadratic.py`, `src/latex_renderer.py`.

#### Runtime and infrastructure boundaries
Python 3.9+ runs FastAPI and the media pipeline; Node 18+ builds/serves the frontend. External dependencies are Ollama (local LLM), Edge-TTS, FFmpeg/MoviePy/OpenCV, Redis job management, and AWS S3 storage. Production topology places the frontend on Vercel and backend on AWS EC2, with Docker/Compose and CloudFormation deployment options.
Paths: `requirements.txt`, `deploy/Dockerfile`, `deploy/docker-compose.yml`, `deploy/aws/cloudformation.yaml`.

Main entry points: [`src/renderer.py`](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/renderer.py) (MP4 renderer), [`web_app/api.py`](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/api.py) (FastAPI service), [`src/animator.py`](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/animator.py) (Animator), [`web_app/jobs.py`](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/jobs.py) (Async jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_spa_entry["SPA entry<br/>React entry<br/>[main.jsx]"]
  node_spa["Generation UI<br/>React SPA<br/>[App.jsx]"]
  node_vercel_config["Vercel deployment<br/>frontend deployment<br/>[vercel.json]"]
end

subgraph group_api["API and jobs"]
  node_api_entry["FastAPI service<br/>HTTP API<br/>[api.py]"]
  node_api_models["Request models<br/>Pydantic models<br/>[models.py]"]
  node_jobs["Async jobs<br/>job lifecycle<br/>[jobs.py]"]
  node_video_service["Video delivery<br/>video service<br/>[video_service.py]"]
  node_s3_service["S3 persistence<br/>storage adapter<br/>[s3_service.py]"]
end

subgraph group_pipeline["Media pipeline"]
  node_cli["CLI pipeline<br/>CLI entry<br/>[main.py]"]
  node_planner["Educational planner<br/>plan generator<br/>[planner.py]"]
  node_ollama_client["Local LLM client<br/>Ollama adapter"]
  node_plan_artifact["Structured plan<br/>JSON artifact<br/>[plan_00157e08.json]"]
  node_animator["Animator<br/>pipeline orchestrator<br/>[animator.py]"]
  node_narrator["Narration builder<br/>TTS and audio<br/>[narrator.py]"]
  node_topic_router["Topic visual router<br/>visual routing<br/>[topic_router.py]"]
  node_domain_engines["Domain visual engines<br/>specialized scenes<br/>[binary_search.py]"]
  node_latex["LaTeX renderer<br/>formula assets<br/>[latex_renderer.py]"]
  node_renderer["MP4 renderer<br/>media compositor<br/>[renderer.py]"]
  node_audio_artifact["Audio assets<br/>filesystem artifact"]
end

subgraph group_external["External services"]
  node_ollama{{"Ollama<br/>local LLM"}}
  node_edge_tts{{"Edge-TTS<br/>speech service"}}
  node_media_stack{{"FFmpeg / MoviePy / OpenCV<br/>media runtime"}}
  node_redis[("Redis<br/>job store")]
  node_s3[("AWS S3<br/>object storage")]
end

node_spa_entry -->|"mounts"| node_spa
node_vercel_config -.->|"deploys"| node_spa
node_spa -->|"/api requests and polling"| node_api_entry
node_api_entry -->|"validates"| node_api_models
node_api_entry -->|"queues generation"| node_jobs
node_api_entry -->|"serves videos"| node_video_service
node_jobs -->|"stores state"| node_redis
node_jobs -->|"runs pipeline"| node_planner
node_cli -->|"starts"| node_planner
node_planner -->|"requests content"| node_ollama_client
node_ollama_client -->|"model calls"| node_ollama
node_planner -->|"writes"| node_plan_artifact
node_plan_artifact -->|"drives"| node_animator
node_animator -->|"generates narration"| node_narrator
node_narrator -->|"synthesizes speech"| node_edge_tts
node_narrator -->|"writes"| node_audio_artifact
node_animator -->|"selects visuals"| node_topic_router
node_topic_router -->|"recognized topics"| node_domain_engines
node_domain_engines -->|"formula assets"| node_latex
node_animator -->|"composes video"| node_renderer
node_audio_artifact -->|"timed audio"| node_renderer
node_topic_router -->|"visual scenes"| node_renderer
node_renderer -->|"encodes MP4"| node_media_stack
node_renderer -->|"completed video"| node_video_service
node_video_service -->|"persists through"| node_s3_service
node_s3_service -->|"uploads"| node_s3
node_video_service -->|"final URL"| node_jobs

click node_spa_entry "https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/src/main.jsx"
click node_spa "https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/src/App.jsx"
click node_vercel_config "https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/vercel.json"
click node_api_entry "https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/api.py"
click node_api_models "https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/models.py"
click node_jobs "https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/jobs.py"
click node_video_service "https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/video_service.py"
click node_s3_service "https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/s3_service.py"
click node_cli "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/main.py"
click node_planner "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/planner.py"
click node_ollama_client "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/local_llm_client.py"
click node_plan_artifact "https://github.com/mahakagarwal7/bharatvidya/blob/main/outputs/plans/plan_00157e08.json"
click node_animator "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/animator.py"
click node_narrator "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/narrator.py"
click node_topic_router "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/topic_router.py"
click node_domain_engines "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/domain_engines/binary_search.py"
click node_latex "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/latex_renderer.py"
click node_renderer "https://github.com/mahakagarwal7/bharatvidya/blob/main/src/renderer.py"
click node_audio_artifact "https://github.com/mahakagarwal7/bharatvidya/blob/main/outputs/audio/00afbd0b_combined.mp3"

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_spa_entry,node_spa,node_vercel_config toneBlue
class node_api_entry,node_api_models,node_jobs,node_video_service,node_s3_service toneAmber
class node_cli,node_planner,node_ollama_client,node_plan_artifact,node_animator,node_narrator,node_topic_router,node_domain_engines,node_latex,node_renderer,node_audio_artifact toneMint
class node_ollama,node_edge_tts,node_media_stack,node_redis,node_s3 toneRose
```

## Components

### React client

- [SPA entry](https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/src/main.jsx): React entry · `frontend/src/main.jsx`
- [Generation UI](https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/src/App.jsx): React SPA · Collects requests, polls jobs, and displays videos. · `frontend/src/App.jsx`
- [Vercel deployment](https://github.com/mahakagarwal7/bharatvidya/blob/main/frontend/vercel.json): frontend deployment · Configures deployed frontend integration. · `frontend/vercel.json`

### API and jobs

- [FastAPI service](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/api.py): HTTP API · Public generation, status, video, topic, and health endpoints. · `web_app/api.py`
- [Request models](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/models.py): Pydantic models · `web_app/models.py`
- [Async jobs](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/jobs.py): job lifecycle · Tracks progress, errors, and final video URLs. · `web_app/jobs.py`
- [Video delivery](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/video_service.py): video service · `web_app/video_service.py`
- [S3 persistence](https://github.com/mahakagarwal7/bharatvidya/blob/main/web_app/s3_service.py): storage adapter · `web_app/s3_service.py`

### Media pipeline

- [CLI pipeline](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/main.py): CLI entry · `src/main.py`
- [Educational planner](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/planner.py): plan generator · Produces structured title, sections, facts, and narration content. · `src/planner.py`
- [Local LLM client](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/local_llm_client.py): Ollama adapter · `src/local_llm_client.py`
- [Structured plan](https://github.com/mahakagarwal7/bharatvidya/blob/main/outputs/plans/plan_00157e08.json): JSON artifact · Key handoff from generative planning to media production. · `outputs/plans/plan_00157e08.json`
- [Animator](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/animator.py): pipeline orchestrator · Coordinates narration, visuals, and final composition. · `src/animator.py`
- [Narration builder](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/narrator.py): TTS and audio · Creates timed narration assets. · `src/narrator.py`
- [Topic visual router](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/topic_router.py): visual routing · Chooses domain-specific or generic visual generation. · `src/topic_router.py`
- [Domain visual engines](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/domain_engines/binary_search.py): specialized scenes · Includes algorithm and STEM visualizations. · `src/domain_engines/binary_search.py`
- [LaTeX renderer](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/latex_renderer.py): formula assets · `src/latex_renderer.py`
- [MP4 renderer](https://github.com/mahakagarwal7/bharatvidya/blob/main/src/renderer.py): media compositor · Combines audio, cards, visuals, transitions, and clips. · `src/renderer.py`
- [Audio assets](https://github.com/mahakagarwal7/bharatvidya/blob/main/outputs/audio/00afbd0b_combined.mp3): filesystem artifact · `outputs/audio/00afbd0b_combined.mp3`

### External services

- **Ollama**: local LLM
- **Edge-TTS**: speech service
- **FFmpeg / MoviePy / OpenCV**: media runtime
- **Redis**: job store
- **AWS S3**: object storage

## Connections

- SPA entry → Generation UI: mounts
- Vercel deployment → Generation UI: deploys
- Generation UI → FastAPI service: /api requests and polling
- FastAPI service → Request models: validates
- FastAPI service → Async jobs: queues generation
- FastAPI service → Video delivery: serves videos
- Async jobs → Redis: stores state
- Async jobs → Educational planner: runs pipeline
- CLI pipeline → Educational planner: starts
- Educational planner → Local LLM client: requests content
- Local LLM client → Ollama: model calls
- Educational planner → Structured plan: writes
- Structured plan → Animator: drives
- Animator → Narration builder: generates narration
- Narration builder → Edge-TTS: synthesizes speech
- Narration builder → Audio assets: writes
- Animator → Topic visual router: selects visuals
- Topic visual router → Domain visual engines: recognized topics
- Domain visual engines → LaTeX renderer: formula assets
- Animator → MP4 renderer: composes video
- Audio assets → MP4 renderer: timed audio
- Topic visual router → MP4 renderer: visual scenes
- MP4 renderer → FFmpeg / MoviePy / OpenCV: encodes MP4
- MP4 renderer → Video delivery: completed video
- Video delivery → S3 persistence: persists through
- S3 persistence → AWS S3: uploads
- Video delivery → Async jobs: final URL