# aki-008/prepai architecture

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

- Interactive diagram: https://gitdiagram.com/aki-008/prepai
- Repository: https://github.com/aki-008/prepai

## Overview

##### Project type and purpose
- This is a full-stack web application: a React/TypeScript frontend (under Frontend/) and a FastAPI backend (under Backend/) providing a Student Management System with authentication, PostgreSQL storage, and vector-embedding/LLM capabilities.
- README confirms the core functionality: async FastAPI student API with login/registration, CRUD on student records, JWT-based security, plus CLI runner and health checks.

##### File structure
- Top level:
- Backend/ – FastAPI service
- Frontend/ – React app (Vite + Tailwind + TypeScript)
- ai/ – STT notebook for speech-to-text experiments
- chroma_store/ & Backend/chroma_store – persistent vector store files
- Backend/app/api/v1/endpoints – grouped REST endpoints (auth, prompts, quiz, students).
- Backend/app/core, config.py, security.py – central configuration & security logic (JWT, password hashing).
- Backend/app/database.py, vector_db.py, llm.py – data layer: SQLAlchemy async/PostgreSQL + Chroma vector database + LLM orchestration.
- Frontend/src/api – API client, src/components/pages/routes – UI components, protected routes & context for authentication.

##### Extract architecture insights from README
- FastAPI app uses async SQLAlchemy + asyncpg to talk to PostgreSQL
- Pydantic models for validation
- JWT + HTTPBearer for protected endpoints
- CORS middleware opens API to frontend
- On startup, DB tables created; on shutdown, connections closed
- Endpoints are grouped by tags (Authentication, Students, Health)

##### Detail
- Dependency flow: FastAPI startup → create tables → serve requests → shutdown → dispose engine.
- Optionally, show separate environment (development vs. production) with reload vs. gunicorn.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Frontend (React + Vite)"
        Browser["Web Client"]:::frontend
        APIClient["API Client"]:::frontend
        AuthContext["Auth Context"]:::frontend
        ProtectedRoute["ProtectedRoute"]:::frontend
    end

    subgraph "Backend (FastAPI Service)"
        APIGateway["API Gateway / FastAPI"]:::backend
        APIv1["API Router (v1)"]:::backend
        AuthModule["Authentication Module"]:::backend
        StudentEndpoints["Student Endpoints"]:::backend
        PromptEP["Prompts Endpoint"]:::backend
        QuizEP["Quiz Endpoint"]:::backend
        Config["Config & Startup"]:::backend
        DatabaseSession["DB Session Lifecycle"]:::backend
        Models["Models & Schemas"]:::backend
        VectorDB["Vector DB Interface"]:::backend
        LLM["LLM Orchestration"]:::backend
    end

    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::datastore
        Chroma["Chroma Vector Store"]:::datastore
    end

    subgraph "External Services"
        ExternalLLM["External LLM Service"]:::external
    end

    subgraph "Experimental"
        STT["STT Notebook"]:::experimental
    end

    Browser --> APIClient
    Browser --> AuthContext
    AuthContext --> ProtectedRoute
    ProtectedRoute -->|"requires JWT"| APIGateway
    APIClient -->|"HTTPS REST"| APIGateway

    APIGateway --> APIv1
    APIv1 --> AuthModule
    APIv1 --> StudentEndpoints
    APIv1 --> PromptEP
    APIv1 --> QuizEP
    APIGateway --> Config
    AuthModule --> DatabaseSession
    StudentEndpoints --> DatabaseSession
    PromptEP --> VectorDB
    QuizEP --> VectorDB
    PromptEP --> LLM
    QuizEP --> LLM
    DatabaseSession -->|"async SQL"| Postgres
    VectorDB -->|"vector ops"| Chroma
    LLM -->|"LLM API call"| ExternalLLM

    click Browser "https://github.com/aki-008/prepai/blob/main/Frontend/src/main.tsx"
    click APIClient "https://github.com/aki-008/prepai/blob/main/Frontend/src/api/api.ts"
    click AuthContext "https://github.com/aki-008/prepai/blob/main/Frontend/src/components/context/AuthContext.tsx"
    click ProtectedRoute "https://github.com/aki-008/prepai/blob/main/Frontend/src/routes/ProtectedRoute.tsx"
    click APIGateway "https://github.com/aki-008/prepai/blob/main/Backend/app/main.py"
    click Config "https://github.com/aki-008/prepai/blob/main/Backend/app/config.py"
    click DatabaseSession "https://github.com/aki-008/prepai/blob/main/Backend/app/database.py"
    click APIv1 "https://github.com/aki-008/prepai/blob/main/Backend/app/api/v1/api.py"
    click AuthModule "https://github.com/aki-008/prepai/blob/main/Backend/app/api/v1/endpoints/auth.py"
    click StudentEndpoints "https://github.com/aki-008/prepai/blob/main/Backend/app/api/v1/endpoints/students.py"
    click PromptEP "https://github.com/aki-008/prepai/blob/main/Backend/app/api/v1/endpoints/prompts.py"
    click QuizEP "https://github.com/aki-008/prepai/blob/main/Backend/app/api/v1/endpoints/quiz.py"
    click Models "https://github.com/aki-008/prepai/blob/main/Backend/app/models/tables.py"
    click VectorDB "https://github.com/aki-008/prepai/blob/main/Backend/app/vector_db.py"
    click LLM "https://github.com/aki-008/prepai/blob/main/Backend/app/llm.py"
    click Chroma "https://github.com/aki-008/prepai/blob/main/Backend/chroma_store/chroma.sqlite3"
    click STT "https://github.com/aki-008/prepai/blob/main/ai/stt/stt.ipynb"

    classDef frontend fill:#CCE5FF,stroke:#1E70BF,color:#000
    classDef backend fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef datastore fill:#FDEBD0,stroke:#D35400,color:#000
    classDef external fill:#E8DAEF,stroke:#8E44AD,color:#000
    classDef experimental fill:#F2F3F4,stroke:#B3B6B7,color:#000
```
