mahakagarwal7/bharatvidya

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.