# amadeusssystem/rl-tutor-project architecture

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

- Interactive diagram: https://gitdiagram.com/amadeusssystem/rl-tutor-project
- Repository: https://github.com/amadeusssystem/rl-tutor-project

## Overview

##### Project type and purpose
- This is a full-stack intelligent tutoring system combining a Next.js (React/TypeScript/Tailwind) frontend with a FastAPI (Python) backend.
- Purpose: deliver personalized learning content via a Q-Learning RL agent, track progress and analytics, support secure authentication, and provide a demo/visualization of the RL process.

##### File structure
- Top-level:
- app/ (Next.js “app” router) – pages, layouts, UI components, API client, contexts
- components/ui/ – reusable Tailwind/Framer Motion UI widgets
- backend/ – FastAPI service with subdirs:
– api/ (route handlers: auth, session, analytics, RL stats, recommendations)
– core/ (config, database connection, security)
– models/ (SQLAlchemy ORM, Pydantic schemas)
– services/ (RL agent, collaborative filtering, student model)
- lib/utils.ts – frontend helpers
- config files: Dockerfile, docker-compose.yml, render.yaml, tsconfig.json, ESLint, PostCSS
- docs & scripts for deployment, CI, testing, seeding DB

##### README insights
- Stack: Next.js 16+React 19, Tailwind v4, Aceternity UI, Framer Motion; FastAPI, SQLAlchemy, Pydantic, JWT auth, NumPy/Pandas/Scikit-learn; SQLite/ PostgreSQL
- RL agent: Q-Learning with 4D state, epsilon-greedy, custom reward
- API endpoints grouped by feature (auth, session, analytics)
- Comprehensive testing strategy: unit, integration, end-to-end

a. Frontend (Next.js)
- UI layers (pages under app/)
- Components (Navigation, Sidebar, bespoke UI in components/ui)
- Contexts (AuthContext)
- API client (app/api/client.ts)
b. Backend (FastAPI)
- HTTP API endpoints (routers in backend/app/api)
- Core services: auth & security, DB session management
- Business logic: RL agent, recommendations, learning-pace/style services
- Data layer: SQLAlchemy models and database
c. Database
- Dev: SQLite file
- Prod: PostgreSQL
- Schema (see DATABASE_SCHEMA.md)
d. External & supporting services
- JWT authentication (token issuance & refresh)
- Q-Learning in-process (no external RL engine)
- Optional: deployment environments (Docker, Vercel, Render)
- Testing harnesses (pytest, Python scripts, quick_integration_test.py)

##### Relationships & data flow
- User → Next.js frontend (browser)
- Frontend calls → FastAPI (HTTP/HTTPS) via client.ts
- FastAPI → Database (SQLAlchemy ORM)
- FastAPI invokes → RL services (in-memory Python modules)
- FastAPI returns → JSON (session recommendations, analytics)
- Frontend renders → UI, updates Context & state

##### Architectural patterns & principles
- Clear separation: presentation (frontend) vs. business logic & data (backend)
- Modular routers in FastAPI for each feature domain
- Layered architecture: API → services → data
- Stateless JWT auth with refresh tokens
- Component-based UI with Tailwind and design systems
- Single monolith for backend; monorepo structure

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        direction TB
        FE["Next.js Frontend"]:::frontend
        Pages["Pages (app/)"]:::frontend
        Nav["Navigation Component"]:::frontend
        Sidebar["Sidebar Component"]:::frontend
        UIWidgets["Reusable UI Widgets"]:::frontend
        AuthCtx["Auth Context"]:::frontend
        APIClient["API Client"]:::frontend
        Globals["Global Stylesheet"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        direction TB
        Entry["main.py"]:::backend

        subgraph "API Routers"
            direction TB
            AuthRouter["auth.py"]:::backend
            SessionRouter["session.py"]:::backend
            AnalyticsRouter["analytics.py"]:::backend
            PaceRouter["learning_pace.py"]:::backend
            StyleRouter["learning_style.py"]:::backend
            MasteryRouter["mastery.py"]:::backend
            GapsRouter["skill_gaps.py"]:::backend
            RecsRouter["recommendations.py"]:::backend
            SmartRecsRouter["smart_recommendations.py"]:::backend
            StudentsRouter["students.py"]:::backend
        end

        subgraph "Core"
            direction TB
            Config["config.py"]:::backend
            DatabaseCore["database.py"]:::backend
            Security["security.py"]:::backend
        end

        subgraph "Services"
            direction TB
            RLAgent["rl_agent.py"]:::backend
            CF["collaborative_filtering.py"]:::backend
            Bandit["content_bandit.py"]:::backend
            MasterySvc["mastery_service.py"]:::backend
            StudentModel["student_model.py"]:::backend
        end

        subgraph "Models"
            direction TB
            ORMModels["models.py"]:::backend
            Schemas["schemas.py"]:::backend
            PaceModel["learning_pace.py"]:::backend
            StyleModel["learning_style.py"]:::backend
            MasteryModel["mastery.py"]:::backend
            GapsModel["skill_gap.py"]:::backend
            SmartRecsModel["smart_recommendations.py"]:::backend
        end
    end

    %% Database
    DB[(PostgreSQL / SQLite)]:::database

    %% External & Deployment
    subgraph "External / Deployment"
        direction TB
        Docker["Docker / Kubernetes / Vercel"]:::external
        Testing["Testing Harnesses"]:::external
    end

    %% Connections
    User -->|"HTTP 3000"| FE
    FE -->|"HTTP/HTTPS 8000"| Entry
    Entry --> AuthRouter
    Entry --> SessionRouter
    Entry --> AnalyticsRouter
    Entry --> PaceRouter
    Entry --> StyleRouter
    Entry --> MasteryRouter
    Entry --> GapsRouter
    Entry --> RecsRouter
    Entry --> SmartRecsRouter
    Entry --> StudentsRouter

    AuthRouter --> Config
    SessionRouter --> RLAgent
    SessionRouter --> DatabaseCore
    AnalyticsRouter --> MasterySvc
    AnalyticsRouter --> StudentModel
    PaceRouter --> PaceModel
    StyleRouter --> StyleModel
    MasteryRouter --> MasteryModel
    GapsRouter --> GapsModel
    RecsRouter --> SmartRecsModel
    SmartRecsRouter --> SmartRecsModel
    StudentsRouter --> ORMModels

    Config --> DatabaseCore
    DatabaseCore --> DB
    Security --> AuthRouter

    RLAgent -->|Q-Learning update| DatabaseCore
    CF --> DatabaseCore
    Bandit --> DatabaseCore
    MasterySvc --> DatabaseCore
    StudentModel --> DatabaseCore

    Docker -.-> Entry
    Docker -.-> FE
    Testing -.-> Entry
    Testing -.-> FE

    %% Frontend internals
    FE --> Pages
    FE --> Nav
    FE --> Sidebar
    FE --> UIWidgets
    FE --> AuthCtx
    FE --> APIClient
    FE --> Globals

    APIClient --> Entry

    %% Click Events
    click FE "https://github.com/amadeusssystem/rl-tutor-project/tree/main/app/"
    click Pages "https://github.com/amadeusssystem/rl-tutor-project/tree/main/app/"
    click Nav "https://github.com/amadeusssystem/rl-tutor-project/blob/main/app/components/Navigation.tsx"
    click Sidebar "https://github.com/amadeusssystem/rl-tutor-project/blob/main/app/components/Sidebar.tsx"
    click UIWidgets "https://github.com/amadeusssystem/rl-tutor-project/tree/main/components/ui/"
    click AuthCtx "https://github.com/amadeusssystem/rl-tutor-project/blob/main/app/contexts/AuthContext.tsx"
    click APIClient "https://github.com/amadeusssystem/rl-tutor-project/blob/main/app/api/client.ts"
    click Globals "https://github.com/amadeusssystem/rl-tutor-project/blob/main/app/globals.css"

    click Entry "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/main.py"
    click AuthRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/auth.py"
    click SessionRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/session.py"
    click AnalyticsRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/analytics.py"
    click PaceRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/learning_pace.py"
    click StyleRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/learning_style.py"
    click MasteryRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/mastery.py"
    click GapsRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/skill_gaps.py"
    click RecsRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/recommendations.py"
    click SmartRecsRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/smart_recommendations.py"
    click StudentsRouter "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/api/students.py"

    click Config "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/core/config.py"
    click DatabaseCore "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/core/database.py"
    click Security "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/core/security.py"

    click ORMModels "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/models.py"
    click Schemas "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/schemas.py"
    click PaceModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/learning_pace.py"
    click StyleModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/learning_style.py"
    click MasteryModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/mastery.py"
    click GapsModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/skill_gap.py"
    click SmartRecsModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/models/smart_recommendations.py"

    click RLAgent "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/services/rl_agent.py"
    click CF "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/services/collaborative_filtering.py"
    click Bandit "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/services/content_bandit.py"
    click MasterySvc "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/services/mastery_service.py"
    click StudentModel "https://github.com/amadeusssystem/rl-tutor-project/blob/main/backend/app/services/student_model.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef backend fill:#D0FFD6,stroke:#333,stroke-width:1px;
    classDef database fill:#FFEDB5,stroke:#333,stroke-width:1px;
    classDef external fill:#E2E2E2,stroke:#333,stroke-width:1px;
```
