# venkat2305/learnscribe architecture

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

- Interactive diagram: https://gitdiagram.com/venkat2305/learnscribe
- Repository: https://github.com/venkat2305/learnscribe

## Overview

##### Project type and purpose
- This is a full‑stack, single‑page web application (“Learn‑Scribe”) built with React+TypeScript on the frontend and FastAPI (Python) on the backend.
- Purpose: Let users generate and attempt AI‑powered quizzes and summaries from YouTube videos, articles, PDFs, etc., persisting results in MongoDB, and leveraging external LLM services (Gemini, Groq, etc.).

##### File structure
- Top‑level “frontend” folder: Vite + React app, pages (Auth, Dashboard, Quiz, Summary), Redux Toolkit store, UI components, service clients.
- Top‑level “backend” folder: FastAPI app organized into config, routers (auth, quiz, summary), Pydantic models, service layer (AI integrations, article extraction, YouTube transcript), utils (authentication helpers, quiz & summary generators), and async MongoDB connector.
- Deployment: Dockerfiles in frontend & backend, docker‑compose.yml to orchestrate services. CI via .github/workflows.

##### README for additional insights
- Uses Pydantic BaseSettings for config, Motor AsyncIOMotorClient for non‑blocking MongoDB access, OAuth2PasswordBearer for JWT auth, CORS middleware configured for secure cross‑origin calls.
- External AI services abstracted in a “llm_factory” and per‑provider modules (gemini.py, groq.py).

##### Elements
- Clear labels: “React SPA”, “FastAPI Routers”, “LLM Factory”, “MongoDB”
- User → SPA → API
- API → Services → external AI → Services → DB → API → SPA → User
- Blue rectangle: Frontend
- Green rectangle: Backend components (API, Services, Utils)
- Purple clouds: External AI & data sources

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User to Frontend
    Browser("User Browser"):::user
    Browser -->|interacts with| MainTS

    %% Frontend Layer
    subgraph "Frontend SPA" 
        direction TB
        MainTS["main.tsx"]:::frontend
        AppTS["App.tsx"]:::frontend
        AppRoutes["AppRoutes.tsx"]:::frontend

        subgraph "Redux Store"
            direction TB
            Store["store.ts"]:::frontend
            AuthSlice["authSlice.ts"]:::frontend
            QuizSlice["quizSlice.ts"]:::frontend
            SummarySlice["summarySlice.ts"]:::frontend
        end

        subgraph "UI Components"
            UIComp["frontend/src/components/ui"]:::frontend
        end

        subgraph "Pages & Components"
            direction TB
            subgraph "Auth"
                LoginPage["Login.tsx"]:::frontend
                RegisterPage["Register.tsx"]:::frontend
            end
            subgraph "Dashboard"
                DashboardPage["Dashboard.tsx"]:::frontend
            end
            subgraph "Quiz Features"
                CreateQuiz["CreateQuizPage.tsx"]:::frontend
                MyQuizzes["MyQuizzesPage.tsx"]:::frontend
                QuizAttempt["QuizAttemptPage.tsx"]:::frontend
                QuizResult["QuizResultPage.tsx"]:::frontend
                QuizComps["frontend/src/components/quiz"]:::frontend
            end
            subgraph "Summary Features"
                CreateSummary["CreateSummaryPage.tsx"]:::frontend
                MySummaries["MySummariesPage.tsx"]:::frontend
                SummaryDetail["SummaryDetailPage.tsx"]:::frontend
                SumComps["frontend/src/components/summary"]:::frontend
            end
        end

        subgraph "Service Clients & Hooks"
            direction TB
            AuthSvc["authService.ts"]:::frontend
            QuizSvc["quizService.ts"]:::frontend
            SummarySvc["summaryService.ts"]:::frontend
            UseAuth["useAuth.ts"]:::frontend
            UseQuiz["useQuiz.ts"]:::frontend
            UseSummary["useSummary.ts"]:::frontend
        end
    end

    %% Frontend flow
    MainTS --> AppTS --> AppRoutes
    AppRoutes --> LoginPage & RegisterPage & DashboardPage & CreateQuiz & MyQuizzes & QuizAttempt & QuizResult & CreateSummary & MySummaries & SummaryDetail
    Store --> AuthSlice & QuizSlice & SummarySlice
    LoginPage & RegisterPage --> AuthSvc
    CreateQuiz & MyQuizzes & QuizAttempt & QuizResult --> QuizSvc
    CreateSummary & MySummaries & SummaryDetail --> SummarySvc
    UIComp --> AppRoutes
    AuthSvc & QuizSvc & SummarySvc & UseAuth & UseQuiz & UseSummary -->|HTTP| API

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        direction TB
        Configs["config.py, llm_config.py"]:::backend
        MainPy["main.py"]:::backend

        subgraph "API Routers"
            AuthRouter["auth.py"]:::backend
            QuizRouter["quiz.py"]:::backend
            SummaryRouter["summary.py"]:::backend
        end

        subgraph "Service Layer"
            LLMFactory["llm_factory.py"]:::backend
            Gemini["gemini.py"]:::backend
            Groq["groq.py"]:::backend
            GenerateAI["generate_ai_response.py"]:::backend
            ArticleExtract["article_extraction.py"]:::backend
            YouTube["youtube.py"]:::backend
            Mistakes["mistakes_transcript.py"]:::backend
            QuizConfig["quiz_config.py"]:::backend
        end

        subgraph "Utils"
            AuthHelpers["auth.py"]:::backend
            QuizGenUtil["quiz_generator.py"]:::backend
            QuizUtil["quiz.py"]:::backend
            SummaryUtil["summary.py"]:::backend
        end

        DBConnector["mongodb.py"]:::backend
    end

    %% Backend flow
    API["FastAPI API Gateway"]:::backend
    API --> AuthRouter & QuizRouter & SummaryRouter
    AuthRouter -->|calls| AuthHelpers
    QuizRouter & SummaryRouter -->|calls| ServiceLayer
    ServiceLayer --> LLMFactory
    LLMFactory --> Gemini & Groq
    ServiceLayer --> GenerateAI & ArticleExtract & YouTube & Mistakes & QuizConfig
    ServiceLayer --> DBConnector
    Utils --> DBConnector

    %% Database
    MongoDB["MongoDB (Motor)"]:::db
    DBConnector -->|async| MongoDB

    %% External Services
    subgraph "External Services"
        direction TB
        AIProviders["Gemini/Groq API"]:::external
        DataSources["YouTube API / Web Scraper / OCR"]:::external
    end
    ServiceLayer -->|async| AIProviders
    ServiceLayer -->|async| DataSources

    %% Deploy & CI/CD
    subgraph "DevOps"
        DockerCompose["docker-compose.yml"]:::infra
        FE_Docker["frontend/Dockerfile"]:::infra
        BE_Docker["backend/Dockerfile"]:::infra
        CI[".github/workflows"]:::infra
    end
    DockerCompose --> FE_Docker & BE_Docker & MongoDB

    %% Click Events
    click MainTS "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/main.tsx"
    click AppTS "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/App.tsx"
    click AppRoutes "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/AppRoutes.tsx"
    click Store "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/store/store.ts"
    click AuthSlice "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/store/slices/authSlice.ts"
    click QuizSlice "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/store/slices/quizSlice.ts"
    click SummarySlice "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/store/slices/summarySlice.ts"
    click UIComp "https://github.com/venkat2305/learnscribe/tree/master/frontend/src/components/ui"
    click LoginPage "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/pages/Auth/Login.tsx"
    click RegisterPage "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/pages/Auth/Register.tsx"
    click DashboardPage "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/pages/Dashboard/Dashboard.tsx"
    click QuizComps "https://github.com/venkat2305/learnscribe/tree/master/frontend/src/components/quiz"
    click SumComps "https://github.com/venkat2305/learnscribe/tree/master/frontend/src/components/summary"
    click AuthSvc "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/services/authService.ts"
    click QuizSvc "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/services/quizService.ts"
    click SummarySvc "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/services/summaryService.ts"
    click UseAuth "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/hooks/useAuth.ts"
    click UseQuiz "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/hooks/useQuiz.ts"
    click UseSummary "https://github.com/venkat2305/learnscribe/blob/master/frontend/src/hooks/useSummary.ts"
    click Configs "https://github.com/venkat2305/learnscribe/blob/master/backend/app/config.py"
    click MainPy "https://github.com/venkat2305/learnscribe/blob/master/backend/app/main.py"
    click AuthRouter "https://github.com/venkat2305/learnscribe/blob/master/backend/app/routers/auth.py"
    click QuizRouter "https://github.com/venkat2305/learnscribe/blob/master/backend/app/routers/quiz.py"
    click SummaryRouter "https://github.com/venkat2305/learnscribe/blob/master/backend/app/routers/summary.py"
    click DBConnector "https://github.com/venkat2305/learnscribe/blob/master/backend/app/db/mongodb.py"
    click LLMFactory "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/llm_factory.py"
    click Gemini "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/ai/gemini.py"
    click Groq "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/ai/groq.py"
    click GenerateAI "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/generate_ai_response.py"
    click ArticleExtract "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/article_extraction.py"
    click YouTube "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/youtube.py"
    click Mistakes "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/mistakes_transcript.py"
    click QuizConfig "https://github.com/venkat2305/learnscribe/blob/master/backend/app/services/quiz_config.py"
    click AuthHelpers "https://github.com/venkat2305/learnscribe/blob/master/backend/app/utils/auth.py"
    click QuizGenUtil "https://github.com/venkat2305/learnscribe/blob/master/backend/app/utils/quiz_generator.py"
    click QuizUtil "https://github.com/venkat2305/learnscribe/blob/master/backend/app/utils/quiz.py"
    click SummaryUtil "https://github.com/venkat2305/learnscribe/blob/master/backend/app/utils/summary.py"
    click FE_Docker "https://github.com/venkat2305/learnscribe/tree/master/frontend/Dockerfile"
    click BE_Docker "https://github.com/venkat2305/learnscribe/tree/master/backend/Dockerfile"
    click DockerCompose "https://github.com/venkat2305/learnscribe/blob/master/docker-compose.yml"
    click CI "https://github.com/venkat2305/learnscribe/blob/master/.github/workflows/codeql.yml"

    %% Styles
    classDef user fill:#D3E5FF,stroke:#1E70BF,color:#1E70BF;
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef db fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef infra fill:#ECEFF1,stroke:#37474F,color:#37474F;
```
