# abdullah270602/adaptive-e-learning-platform-bakend architecture

> Architecture diagram of the GitHub repository abdullah270602/adaptive-e-learning-platform-bakend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullah270602/adaptive-e-learning-platform-bakend
- Repository: https://github.com/abdullah270602/adaptive-e-learning-platform-bakend

## Overview

##### Project Type and Purpose
- This is a FastAPI-based backend service for an adaptive learning platform.
- It exposes RESTful endpoints for authentication, document handling, quiz/MCQ generation, search (RAG), study mode, streak tracking, and library search.
- It integrates with PostgreSQL, Redis, MinIO (S3), Qdrant (vector DB), and external LLM providers.

##### File Structure
- Top-level:
- main.py: FastAPI app instantiation, middleware, router registration
- app/routes: API controllers (auth, file, quiz, study_mode, etc.)
- app/services: Business logic (file processing, LLM prompts, RAG, vector search, etc.)
- app/database: Raw SQL queries and connection management
- app/cache: Redis caching wrappers (metadata & learning profile)
- app/schemas: Pydantic models for request/response validation
- scripts/init_db.py & DB_schema_script.sql: DB initialization
- Configuration: .env.example, pyproject.toml, uv.lock

##### README
- Confirms architecture: FastAPI <-> PostgreSQL, Redis, MinIO, Qdrant, LLMs
- Calls out each subsystem: Auth (Google OAuth2 + JWT), Document conversion, Quiz generation, RAG search, Study Mode, Streaks/Leaderboards, Library search, Caching, Storage.

a. Main Components
1. Client/User (Web or Mobile)
2. FastAPI Backend (main.py)
- API Layer (app/routes)
- Service Layer (app/services)
- Data Layer (app/database, app/cache)
3. PostgreSQL Database
4. Redis Cache
5. MinIO (S3-compatible storage)
6. Qdrant Vector DB
7. External LLM Providers (OpenAI, Groq, DeepSeek, etc.)
8. Google OAuth2 (Auth provider)

b. Relationships & Interactions
- Client ↔ FastAPI API Layer
- API Layer → Service Layer for each request
- Service Layer reads/writes:
- PostgreSQL (user data, metadata, quizzes, progress, streaks)
- Redis (model & metadata caching)
- MinIO (upload/download documents, generated files)
- Qdrant (semantic vectors & RAG search)
- Service Layer calls external LLM APIs for quiz generation, profile summaries, MCQs, etc.
- Auth Flow: FastAPI ↔ Google OAuth2 ↔ issue JWT ↔ stored in PostgreSQL

c. Architectural Patterns & Design Principles
- Layered architecture: Controllers → Services → Data Stores
- Separation of concerns: routing, business logic, persistence, caching, storage
- Dependency injection via FastAPI dependencies (e.g., DB connection, auth)
- Stateless services with external state in DB, cache, and object storage
- RAG integration: vector store + full-text chunks

d. Key Technologies & Frameworks
- FastAPI (Python)
- Pydantic schemas
- PostgreSQL (psycopg2)
- Redis (redis-py)
- MinIO (boto3 or S3 SDK)
- Qdrant (qdrant-client)
- LibreOffice (document conversion CLI)
- LLM SDKs (OpenAI, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: Client
    subgraph "Client Layer"
        direction TB
        Client["Web/Mobile Client"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        AuthAPI["Auth Endpoints"]:::api
        FileAPI["File/Document Endpoints"]:::api
        QuizAPI["Quiz/MCQ Endpoints"]:::api
        StudyAPI["Study Mode Endpoints"]:::api
        StreaksAPI["Streaks/Leaderboards Endpoints"]:::api
        LibraryAPI["Library Search Endpoints"]:::api
        TranscribeAPI["Transcription Endpoints"]:::api
        ModelsAPI["Models Listing & Metadata Endpoints"]:::api
        ProfileAPI["Learning Profile Endpoints"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        DocumentServices["Document Conversion & Processing"]:::service
        AudioService["Audio Transcription Service"]:::service
        FileOpsService["File Download/Delete Service"]:::service
        MinIOClient["MinIO Client"]:::service
        EmbeddingService["Embedding & Vector Operations"]:::service
        RAGService["RAG Service"]:::service
        QuizServices["Quiz & Content Generation"]:::service
        PromptUtils["Prompt Management & Utilities"]:::service
    end

    %% Data & External Services Layer
    subgraph "Data & External Services"
        direction TB
        subgraph "Data Stores"
            direction TB
            Postgres[(PostgreSQL)]:::data
            Redis[(Redis Cache)]:::data
        end
        subgraph "External Services"
            direction TB
            MinIO[(MinIO Storage)]:::external
            Qdrant[(Qdrant Vector DB)]:::external
            OAuth2["Google OAuth2"]:::external
            LLMs["External LLM Providers"]:::external
        end
    end

    %% Connections
    Client -->|"HTTPS Requests"| AuthAPI
    Client -->|"HTTPS Requests"| FileAPI
    Client -->|"HTTPS Requests"| QuizAPI
    Client -->|"HTTPS Requests"| StudyAPI
    Client -->|"HTTPS Requests"| StreaksAPI
    Client -->|"HTTPS Requests"| LibraryAPI
    Client -->|"HTTPS Requests"| TranscribeAPI
    Client -->|"HTTPS Requests"| ModelsAPI
    Client -->|"HTTPS Requests"| ProfileAPI

    AuthAPI -->|"calls"| DocumentServices
    FileAPI -->|"calls"| DocumentServices
    QuizAPI -->|"calls"| QuizServices
    StudyAPI -->|"calls"| PromptUtils
    StreaksAPI -->|"calls"| PromptUtils
    LibraryAPI -->|"calls"| RAGService
    TranscribeAPI -->|"calls"| AudioService
    ModelsAPI -->|"calls"| EmbeddingService
    ProfileAPI -->|"calls"| RAGService

    DocumentServices -->|"Store/Process"| Postgres
    DocumentServices -->|"Upload/Download"| MinIO
    AudioService -->|"Temp Storage"| MinIO
    FileOpsService -->|"Read/Delete"| MinIO
    MinIOClient -->|"Client SDK"| MinIO
    EmbeddingService -->|"Store Vectors"| Qdrant
    EmbeddingService -->|"Cache Embeddings"| Redis
    RAGService -->|"Query Vectors"| Qdrant
    RAGService -->|"Query Text"| Postgres
    QuizServices -->|"Fetch Data"| Postgres
    QuizServices -->|"Cache Profiles"| Redis
    PromptUtils -->|"LLM Calls"| LLMs
    AuthAPI -->|"OAuth Flow"| OAuth2
    AuthAPI -->|"Store Tokens"| Postgres

    %% Click Events for API Layer
    click AuthAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/auth.py"
    click FileAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/file.py"
    click QuizAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/quiz_gen.py"
    click StudyAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/study_mode.py"
    click StreaksAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/streaks.py"
    click LibraryAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/library_search.py"
    click TranscribeAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/transcribe.py"
    click ModelsAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/models.py"
    click ProfileAPI "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/routes/learning_profile.py"

    %% Click Events for Service Layer
    click DocumentServices "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/pdf_converter.py"
    click AudioService "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/audio_transcribe.py"
    click FileOpsService "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/download_file.py"
    click MinIOClient "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/minio_client.py"
    click EmbeddingService "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/embeddings.py"
    click RAGService "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/rag_service.py"
    click QuizServices "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/quiz_generator.py"
    click PromptUtils "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/services/prompts.py"

    %% Click Events for Data & External
    click Postgres "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/database/connection.py"
    click Redis "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/cache/redis.py"
    click OAuth2 "https://github.com/abdullah270602/adaptive-e-learning-platform-bakend/blob/main/app/auth/google_auth.py"

    %% Styling
    classDef client fill:#f0f8ff,stroke:#036,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef service fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
