# pranavreddygaddam/quizforge architecture

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

- Interactive diagram: https://gitdiagram.com/pranavreddygaddam/quizforge
- Repository: https://github.com/pranavreddygaddam/quizforge

## Overview

##### Project type and purpose
- QuizForge is a full-stack educational web application that uses AI to convert study materials (PDFs or raw text) into interactive quizzes, summaries, and flashcards.
- The frontend is built with Next.js (React + TypeScript + Tailwind CSS). The backend is a FastAPI service (Python) that handles PDF extraction (PyPDF2), AI service calls, and returns structured responses via REST endpoints.

##### File structure
- Top-level:
- backend/ – FastAPI service
– app/main.py (entrypoint)
– app/models.py (Pydantic schemas)
– app/ai_service.py (OpenRouter AI integration)
– requirements.txt, .env for API key
- frontend/ – Next.js app
– src/app/… (page routes, layout)
– src/components/… (UI components & pages)
– src/lib/api.ts (API wrapper), googleDrive.ts (Google Drive integration), utils.ts
– tailwind.config.ts, next.config.ts, package.json
- No internal database is present; all data flows through REST and AI calls.
- Build and lint config files: eslint.config.mjs, tsconfig.json, postcss.config.mjs

##### README for additional insights
- Core features: PDF upload, text paste, quiz/summary/flashcard generation, performance analytics
- Backend dependencies: FastAPI, Uvicorn, PyPDF2, OpenRouter API (Qwen 3-32B)
- Documented endpoints: POST /upload-pdf, /generate-summary, /generate-quiz, /generate-flashcards, /check-answers, GET /health

##### Detail
- Internal folder/module boundaries (e.g., show ai_service.py inside the service layer)
- Data payload types (JSON schemas from Pydantic models)
- Ports/addresses (frontend port 3000, backend port 8000)
- Critical flows: PDF extraction → AI call → response rendering

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend (Next.js)" 
        direction TB
        subgraph "UI & Pages"
            direction TB
            Layout["layout.tsx"]:::frontend
            Globals["globals.css"]:::frontend
            LandingPage["LandingPage.tsx"]:::frontend
            QuizForgeApp["QuizForgeApp.tsx"]:::frontend
            UploadPage["upload/page.tsx"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            UI_Alert["alert.tsx"]:::frontend
            UI_Badge["badge.tsx"]:::frontend
            UI_Button["button.tsx"]:::frontend
            UI_Card["card.tsx"]:::frontend
            UI_Input["input.tsx"]:::frontend
            UI_Label["label.tsx"]:::frontend
            UI_Progress["progress.tsx"]:::frontend
            UI_Select["select.tsx"]:::frontend
            UI_Separator["separator.tsx"]:::frontend
            UI_Tabs["tabs.tsx"]:::frontend
        end
        subgraph "Libraries"
            direction TB
            APIClient["api.ts"]:::frontend
            GoogleDrive["googleDrive.ts"]:::frontend
            Utils["utils.ts"]:::frontend
            Types["index.ts"]:::frontend
        end
        subgraph "Configurations"
            direction TB
            TailwindConfig["tailwind.config.ts"]:::frontend
            NextConfig["next.config.ts"]:::frontend
            PostCSS["postcss.config.mjs"]:::frontend
            ESLint["eslint.config.mjs"]:::frontend
            TSConfig["tsconfig.json"]:::frontend
        end
    end

    %% Backend Zone
    subgraph "Backend (FastAPI)" 
        direction TB
        Main["main.py"]:::backend
        Models["models.py"]:::backend
        AIService["ai_service.py"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenRouter["OpenRouter AI Endpoint"]:::external
        GoogleAPI["Google Drive API"]:::external
    end

    %% User and Browser
    User["User (Browser)"]:::external

    %% Connections
    User -->|"Interacts via UI"| Layout
    Layout -->|"Renders Pages"| LandingPage
    Layout -->|"Renders Pages"| QuizForgeApp
    QuizForgeApp -->|"/upload"| UploadPage
    LandingPage -->|uses| UI_Alert
    QuizForgeApp -->|uses| UI_Card
    UploadPage -->|uses| UI_Button
    UploadPage -->|calls| APIClient
    APIClient -->|"POST /upload-pdf\nPOST /generate-summary\nPOST /generate-quiz\nPOST /generate-flashcards\nPOST /check-answers\nGET /health"| Main
    GoogleDrive -->|"OAuth/REST"| GoogleAPI
    UploadPage -->|imports via| GoogleDrive
    Main -->|"Extract text via PyPDF2"| AIService
    AIService -->|"Invoke OpenRouter model"| OpenRouter
    OpenRouter -->|"Respond JSON"| AIService
    AIService -->|"Return Pydantic models"| Main
    Main -->|"Return JSON responses"| APIClient
    APIClient -->|"Provides data"| QuizForgeApp

    %% Click Events
    click Layout "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/app/layout.tsx"
    click Globals "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/app/globals.css"
    click LandingPage "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/LandingPage.tsx"
    click QuizForgeApp "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/QuizForgeApp.tsx"
    click UploadPage "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/app/upload/page.tsx"
    click UI_Alert "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/alert.tsx"
    click UI_Badge "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/badge.tsx"
    click UI_Button "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/button.tsx"
    click UI_Card "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/card.tsx"
    click UI_Input "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/input.tsx"
    click UI_Label "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/label.tsx"
    click UI_Progress "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/progress.tsx"
    click UI_Select "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/select.tsx"
    click UI_Separator "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/separator.tsx"
    click UI_Tabs "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/components/ui/tabs.tsx"
    click APIClient "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/lib/api.ts"
    click GoogleDrive "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/lib/googleDrive.ts"
    click Utils "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/lib/utils.ts"
    click Types "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/src/types/index.ts"
    click TailwindConfig "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/tailwind.config.ts"
    click NextConfig "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/next.config.ts"
    click PostCSS "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/postcss.config.mjs"
    click ESLint "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/eslint.config.mjs"
    click TSConfig "https://github.com/pranavreddygaddam/quizforge/blob/main/frontend/tsconfig.json"
    click Main "https://github.com/pranavreddygaddam/quizforge/blob/main/backend/app/main.py"
    click Models "https://github.com/pranavreddygaddam/quizforge/blob/main/backend/app/models.py"
    click AIService "https://github.com/pranavreddygaddam/quizforge/blob/main/backend/app/ai_service.py"
    click Requirements "https://github.com/pranavreddygaddam/quizforge/blob/main/backend/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#DFFFE0,stroke:#2c662d,stroke-width:1px;
    classDef external fill:#F3E8FF,stroke:#6f42c1,stroke-width:1px;
```
