Mathtube Ai

Core System Architecture The service boots a FastAPI application (api_server.py) that defines endpoints for job creation (POST /api/generate), status polling (GET /api/jobs/{job_id}/status), live log streaming (GET /api/jobs/{job_id}/stream), and video assets (GET /api/videos*). Incoming GenerateRequest payloads are validated with pydantic.BaseModel and materialized into a Job object stored in _jobs and persisted to data/jobs.json. A background asyncio task invokes the pipeline via _build_cmd, which launches the main.py script inside the project's virtual environment.

Data Ingestion & Persistence The system uses a SQLite database (data/chroma/chroma.sqlite3) to back the Chroma vector store. Schema tables include tenants, databases, and collections, enforcing multi‑tenant isolation and unique constraints on collection names per database. Default tenant and database rows are seeded on startup, ensuring a ready‑to‑use environment for vector‑based retrieval.

Execution Flow

1. Job Submission – Client POSTs a GenerateRequest; a short UUID is generated and a Job entry is created.
2. Pipeline Launch – _run_job builds a command list (_build_cmd) and spawns a subprocess (subprocess.Popen) that runs main.py with all user‑specified parameters (topic, level, model, etc.).
3. Log Capture – Subprocess stdout/stderr are streamed into job.logs; the /stream endpoint yields new lines as SSE events.
4. Result Harvesting – Upon completion, the job directory under output/<job_id> contains lesson_blueprint.json, qa_report.json, and generated MP4 files. The /videos endpoint walks these directories, aggregates metadata, and returns a catalog.

Security Guardrails

• Tenant Isolation is enforced at the DB layer via foreign keys (tenant_id) and unique constraints.
• Input Sanitization relies on pydantic type enforcement and explicit default values, reducing injection risk.
• File Access is confined to the output subtree; all path constructions use Path objects to avoid directory traversal.

Build & Deployment Topology The codebase is structured for containerization: a Dockerfile can copy the repository, install dependencies into .venv, and expose port 8000. The SQLite file is mounted as a volume for persistence, while the output directory is also a volume to retain generated media across restarts.