# raunov/voxtory architecture

> Architecture diagram of the GitHub repository raunov/voxtory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raunov/voxtory
- Repository: https://github.com/raunov/voxtory

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["API Consumers (curl, Python client)"]:::external

    subgraph "Internal Modules"
        API["API Gateway\n(FastAPI + Uvicorn)"]:::internal
        Auth["Auth Module\n(BYOK Gemini-key)"]:::internal
        Validation["Validation Layer\n(Pydantic schemas)"]:::internal
        Orchestrator["Orchestration Layer\n(core workflow)"]:::internal
        VideoService["Video Fetcher Service\n(download/transcribe)"]:::internal
        PromptManager["Prompt Manager\n(base prompt)"]:::internal
        FormatterMD["Markdown Formatter"]:::internal
        FormatterMMD["Mermaid Formatter"]:::internal
        Output["Output\n(JSON / Markdown / Mermaid)"]:::internal
    end

    subgraph "External Services"
        ExternalVideos["YouTube/Drive"]:::external
        Gemini["Google Gemini API"]:::external
    end

    subgraph "Execution Environment"
        InfraContainer["Docker Container\n& Local Runner"]:::infra
        InfraRender["Render Deployment"]:::infra
        Docs["Docs\n(README, samples)"]:::infra
    end

    Client -->|"POST /analyze"| API
    API -->|"X-Gemini-API-Key header"| Auth
    Auth -->|"validated"| Validation
    Validation -->|"validated request"| Orchestrator

    Orchestrator -->|"fetch video bytes"| VideoService
    VideoService -->|"download video"| ExternalVideos
    ExternalVideos -->|"video bytes"| VideoService
    VideoService -->|"video bytes"| Orchestrator

    Orchestrator -->|"prompt template"| PromptManager
    PromptManager -->|"prompt payload"| Gemini
    Gemini -->|"LLM response"| Orchestrator

    Orchestrator -->|"raw output"| FormatterMD
    Orchestrator -->|"raw output"| FormatterMMD
    FormatterMD -->|"Markdown"| Output
    FormatterMMD -->|"Mermaid code"| Output
    Orchestrator -->|"JSON payload"| Output

    Orchestrator -->|"HTTP response"| API
    API -->|"HTTP response"| Client

    InfraContainer -.-> API
    InfraRender -.-> InfraContainer
    Docs -.-> InfraContainer

    classDef internal fill:#ADD8E6,stroke:#000,color:#000;
    classDef external fill:#90EE90,stroke:#000,color:#000;
    classDef infra fill:#D3D3D3,stroke:#000,color:#000;

    click API "https://github.com/raunov/voxtory/blob/master/app/main.py"
    click Auth "https://github.com/raunov/voxtory/blob/master/app/auth.py"
    click Validation "https://github.com/raunov/voxtory/blob/master/app/models.py"
    click Orchestrator "https://github.com/raunov/voxtory/blob/master/video_insights.py"
    click VideoService "https://github.com/raunov/voxtory/blob/master/app/video_service.py"
    click PromptManager "https://github.com/raunov/voxtory/blob/master/app/prompts/base.py"
    click FormatterMD "https://github.com/raunov/voxtory/blob/master/app/utils/markdown_generator.py"
    click FormatterMMD "https://github.com/raunov/voxtory/blob/master/app/utils/mermaid_generator.py"
    click InfraContainer "https://github.com/raunov/voxtory/tree/master/Dockerfile"
    click InfraContainer "https://github.com/raunov/voxtory/blob/master/run_local.py"
    click Docs "https://github.com/raunov/voxtory/blob/master/README.md"
    click Docs "https://github.com/raunov/voxtory/blob/master/mermaid_example.md"
    click Docs "https://github.com/raunov/voxtory/blob/master/requirements.txt"
```
