How raunov/voxtory works
Project Type and Purpose
• This is a Python-based, stateless microservice exposing a REST API (built on FastAPI) that “analyzes” YouTube or Google Drive videos by:
1. Fetching/transcribing video content
2. Forwarding prompts to Google’s Gemini API
File Structure Analysis
• Top-Level
• Dockerfile / run_local.py → containerization & local UVicorn launcher
• video_insights.py → core orchestration script
• mermaid_example.md → sample output
• app/
• main.py → FastAPI app + route definitions (/, /health, /analyze)
• auth.py → BYOK Gemini-key header validation
• models.py → Pydantic schemas for requests/responses
• video_service.py → video download/transcription (YouTube URL or Drive file)
• prompts/ → base prompt templates for concept maps & speaker analysis
• utils/ → markdown_generator + mermaid_generator for output formatting
Key Insights from README
• Endpoints: GET /, GET /health, POST /analyze
• Authentication: X-Gemini-API-Key header
• Output formats: JSON, Markdown, or Both
• External dependencies: Google Gemini API, YouTube/Drive public download
Components
1. API Consumers (curl, Python client)
2. API Gateway Layer (Uvicorn + FastAPI in app/main.py)
3. Auth Module (app/auth.py)
4. Validation Layer (app/models.py)
5. Orchestration Layer (video_insights.py)
6. Service Modules:
• Video Fetcher (app/video_service.py)
• Prompt Manager (app/prompts/base.py + variants)
• Formatters (app/utils/markdown_generator.py, mermaid_generator.py)
7. External Services: YouTube/Drive, Google Gemini API
9. Infrastructure: Docker container, Render deployment
1. Client → HTTP POST /analyze → FastAPI router
2. FastAPI → Auth → Models.validate → Orchestrator
3. Orchestrator → Video Fetcher → (YouTube/Drive)
4. Orchestrator → Prompt Manager → Gemini API → returns raw LLM output
6. Orchestrator → FastAPI → HTTP Response → Client
c. Architectural Patterns & Principles
• Layered (API → Auth → Validation → Service → Formatter)
• Separation of concerns: each module has a single responsibility
• Template Method in prompts (base prompt + overrides via additional_instructions)
• Stateless design: no persistent storage
d. Key Technologies & Frameworks
• FastAPI + Uvicorn
• Pydantic (models.py)
• Docker
• Google Gemini API (external LLM service)
• HTTP video fetch (YouTube/Drive)