# tural199823/ai_quizer architecture

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

- Interactive diagram: https://gitdiagram.com/tural199823/ai_quizer
- Repository: https://github.com/tural199823/ai_quizer

## Overview

##### Project Type and Purpose
- Full-stack web application for generating quizzes from videos/documents.
- Frontend built in Streamlit, backend in Python + FastAPI, AI transcription and LLM-based quiz generation.
- Supports video input (YouTube/local), document upload, audio transcription, quiz creation, caching, download.

##### File Structure
- Top level: README.md, backend/, frontend/
- backend/
- main.py – FastAPI app entry point
- whisper_utils.py, groq_whisper.py, chat_groq.py – AI integration modules (OpenAI Whisper, open-source LLM wrappers)
- supabase_codes.py – database interactions (Supabase for caching or storing metadata)
- requirements.txt – backend dependencies
- frontend/
- streamlit_main.py – Streamlit UI
- .streamlit/config.toml – Streamlit app configuration
- requirements.txt – frontend dependencies

##### README for Additional Insights
- Tech stack confirms frontend (Streamlit), backend (FastAPI), AI models (Whisper, open-source LLMs), optional Docker/GitHub Actions.
- Functional requirements: video/document ingestion, transcription, chunking, quiz generation, caching, multilingual support, export.

##### Main Components
a. Frontend (Streamlit UI)
- Components: File/URL uploader, quiz display, export buttons.
- Communicates with backend via REST calls.
b. Backend (FastAPI)
- Endpoints:
- /transcribe – accepts media, returns transcript
- /generate_quiz – accepts transcript, returns quiz JSON
- /cache – checks/stores cached results
- Internal modules: whisper_utils, groq_whisper, chat_groq, supabase_codes.
c. AI Services
- OpenAI Whisper (audio transcription)
- Open-source LLM wrappers (quiz generation)
d. Database/Cache
- Supabase (or other DB) stores processed transcripts, quizzes for caching.
e. Storage
- Local or cloud storage for uploaded files and video chunks.
f. External Services
- YouTube API (for retrieving video streams)
- Optional PDF/text parsing libraries.

##### Relationships and Data Flows
- User interacts with Streamlit UI → invokes FastAPI endpoints.
- FastAPI → checks cache (Supabase) via supabase_codes.
- If not cached → FastAPI calls whisper_utils/groq_whisper → generates transcript.
- Transcript → chat_groq → generates quiz.
- Results → saved to cache & returned to frontend.
- Frontend displays quiz, offers download (PDF/text).

##### Architectural Patterns and Principles
- Separation of concerns: UI layer (Streamlit) vs. API layer (FastAPI).
- Modular AI integration: each AI service wrapped in its own module.
- Caching layer to optimize repeated processing.
- Stateless backend endpoints for scalability.
- Optional containerization (Docker) for consistent deployment.

##### Final Checklist
- Components: Frontend, Backend (with modules), AI services, DB/Cache, Storage, External APIs.
- Labels: clear names and protocols (HTTP/REST).
- Annotations: core frameworks/libraries and optional DevOps.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Actors
    User["User"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        StreamlitMain["Streamlit UI"]:::ui
        Uploader["File/URL Uploader"]:::ui
        QuizDisplay["Quiz Display"]:::ui
        ExportButtons["Export Buttons"]:::ui
        Config["Streamlit Config"]:::config
        FEReq["Frontend Dependencies"]:::config
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        FastAPIApp["FastAPI App (backend/main.py)"]:::backend
        Endpoints["/transcribe, /generate_quiz, /cache"]:::backend
        subgraph "AI Integration Modules"
            direction TB
            WhisperUtil["OpenAI Whisper Wrapper"]:::ai
            GRoQWhisper["GRoQ Whisper Wrapper"]:::ai
            ChatGRoQ["Quiz Generation Module"]:::ai
        end
        SupabaseCode["Supabase DB Module"]:::data
    end

    %% AI Services
    subgraph "AI Services"
        direction TB
        OpenAIWhisper["OpenAI Whisper"]:::external
        LLMWrapper["Open-source LLM"]:::external
    end

    %% Data & Storage
    SupabaseDB[(Supabase DB)]:::data
    Storage[(File Storage)]:::data

    %% External APIs
    YouTubeAPI["YouTube API"]:::external
    PDFParser["PDF/Text Parser"]:::external

    %% DevOps
    subgraph "DevOps"
        Docker["Docker"]:::ops
        CI["GitHub Actions"]:::ops
    end

    %% Flows
    User -->|uses| StreamlitMain
    StreamlitMain -->|uploads/clicks| Uploader
    Uploader -->|HTTP POST| FastAPIApp
    StreamlitMain -->|displays quiz| QuizDisplay
    StreamlitMain -->|exports| ExportButtons

    FastAPIApp -->|defines| Endpoints
    Endpoints -->|calls| SupabaseCode
    SupabaseCode -->|checks/stores| SupabaseDB
    Endpoints -->|if miss cache| WhisperUtil
    WhisperUtil -->|calls| OpenAIWhisper
    Endpoints -->|if miss cache| GRoQWhisper
    GRoQWhisper -->|calls| LLMWrapper
    Endpoints -->|process transcript| ChatGRoQ
    ChatGRoQ -->|calls| LLMWrapper
    ChatGRoQ -->|stores quiz| SupabaseCode
    Endpoints -->|returns quiz| StreamlitMain

    Uploader -->|saves files| Storage
    FastAPIApp -->|fetches videos| YouTubeAPI
    Uploader -->|parses docs| PDFParser

    Docker -.->|containerizes| FastAPIApp
    Docker -.->|containerizes| StreamlitMain
    CI -.->|runs tests/builds| Docker

    %% Click events
    click StreamlitMain "https://github.com/tural199823/ai_quizer/blob/main/frontend/streamlit_main.py"
    click Config "https://github.com/tural199823/ai_quizer/blob/main/frontend/.streamlit/config.toml"
    click FEReq "https://github.com/tural199823/ai_quizer/blob/main/frontend/requirements.txt"
    click FastAPIApp "https://github.com/tural199823/ai_quizer/blob/main/backend/main.py"
    click SupabaseCode "https://github.com/tural199823/ai_quizer/blob/main/backend/supabase_codes.py"
    click WhisperUtil "https://github.com/tural199823/ai_quizer/blob/main/backend/whisper_utils.py"
    click GRoQWhisper "https://github.com/tural199823/ai_quizer/blob/main/backend/groq_whisper.py"
    click ChatGRoQ "https://github.com/tural199823/ai_quizer/blob/main/backend/chat_groq.py"
    click SupabaseDB "https://github.com/tural199823/ai_quizer/blob/main/backend/supabase_codes.py"
    click FEReq "https://github.com/tural199823/ai_quizer/blob/main/backend/requirements.txt"
    click FastAPIApp "https://github.com/tural199823/ai_quizer/blob/main/backend/.gitignore"
    
    %% Styles
    classDef user fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef ui fill:#ffefd5,stroke:#333,stroke-width:1px
    classDef backend fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef ai fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef data fill:#fafad2,stroke:#333,stroke-width:1px
    classDef external fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef ops fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef config fill:#f0fff0,stroke:#333,stroke-width:1px
```
