# dub55/learning-platform architecture

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

- Interactive diagram: https://gitdiagram.com/dub55/learning-platform
- Repository: https://github.com/dub55/learning-platform

## Overview

##### Project type and purpose
- This is a full-stack learning platform (“Learning Platform”) with:
- A backend API (Node.js/TypeScript) under apps/api
- A frontend web app (Next.js + React + Supabase) under apps/web
- A PostgreSQL database hosted on Supabase
- AI-powered endpoints wrapping a Python “coder.py” service
- Google OAuth for authentication

##### File structure
- Top-level `apps/` folder contains two sub-apps:
- `apps/api/`: REST API with routes (`src/routes/*.ts`), services (`src/services/*.ts`), and environment config.
- `apps/web/`: Next.js frontend with pages (`src/pages`), lib (`supabaseClient.ts`), styles, and utils.
- `scripts/migrate.sql` defines the database schema (leersets, SRS tables).
- `docs/` contains Google OAuth setup instructions and an OpenAPI spec.
- Monorepo TS config at the root with per-app tsconfig.json files.

##### Key architecture insights from README
- Backend exposes endpoints for:
- Importing learning sets (`POST /api/leersets/import-text`)
- SM-2 spaced repetition review (`GET /api/srs/due`, `POST /api/srs/review`)
- AI wrappers (`POST /api/ai/summarize`, `/generate/flashcards`)
- Supabase handles Auth (email + Google) and stores data.
- The AI service (“coder.py”) is an external streaming endpoint.
- Deployment uses Vercel/GitHub with environment secrets.

##### Main components
A. Frontend (Next.js app)
- Pages: Import UI, Study UI
- Supabase Client (lib/ and utils/)
- Auth flows (Supabase Auth + Google OAuth)
B. Backend API (Express/Koa-style or Fastify)
- API Gateway / HTTP server
- Route handlers (leersets, srs, ai)
- Services layer (business logic: SRS calculations, DB calls)
- AI Proxy service
C. Database
- Supabase/PostgreSQL
- Tables: leersets, cards, reviews, users, subjects, chapters
D. External services
- Supabase Auth provider (Google OAuth)
- AI model endpoint (coder.py)
E. Deployment & CI
- GitHub (repo, CI triggers)
- Vercel (hosting frontend + serverless functions for API)

##### Relationships & interactions
1. User opens Web App → Supabase Auth (sign-in with email/Google)
2. Web App requests data or mutations via REST calls to API
3. API authenticates calls via Supabase service-role key
4. API routes call Services → read/write to Supabase DB
5. For AI endpoints, API forwards requests to coder.py endpoint → streams back response
6. Database triggers or scheduled jobs (future enhancement) for SM-2 queue processing

##### Architectural patterns & principles
- Layered architecture: Presentation (frontend) → API layer → Services → Data layer
- Separation of concerns:
- Next.js handles UI/SSR
- API handles business logic and secures Supabase service-role key
- Monorepo structure with isolated per-app dependencies
- Stateless RESTful services + serverless deployment model
- Externalize identity & data storage to Supabase

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextJS["Next.js Web App"]:::frontend
        subgraph "Pages"
            ImportUI["Import UI"]:::frontend
            StudyUI["Study UI"]:::frontend
        end
        SupabaseLib["Supabase Client (lib)"]:::frontend
        SupabaseUtils["Supabase Client (utils)"]:::frontend
        GlobalsCSS["Global Styles"]:::frontend
        NextJS -->|uses pages| ImportUI
        NextJS -->|uses pages| StudyUI
        NextJS --> SupabaseLib
        NextJS --> SupabaseUtils
        NextJS --> GlobalsCSS
        ImportUI -->|auth| SupabaseAuth
        StudyUI -->|auth| SupabaseAuth
    end

    %% External Auth
    SupabaseAuth["Supabase Auth"]:::external
    SupabaseAuth -->|OAuth redirect| GoogleOAuth["Google OAuth"]:::external

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        APIGateway["API Gateway (apps/api)"]:::backend
        subgraph "Routes"
            AIRoutes["AI Endpoints"]:::backend
            LeersetsRoutes["Leersets Endpoints"]:::backend
            SRSRoutes["SRS Endpoints"]:::backend
        end
        subgraph "Services"
            SRSService["SRS Service"]:::backend
        end
        APIGateway --> AIRoutes
        APIGateway --> LeersetsRoutes
        APIGateway --> SRSRoutes
        AIRoutes --> SRSService
        LeersetsRoutes --> SRSService
        SRSRoutes --> SRSService
    end

    %% Data & External Services
    subgraph "Data & External Services"
        direction TB
        PostgresDB["PostgreSQL DB (Supabase)"]:::database
        AIService["AI Service (coder.py)"]:::external
        PostgresDB -->|read/write| SRSService
        AIService -->|streaming| AIRoutes
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHub["GitHub"]:::ci
        Vercel["Vercel"]:::ci
        GitHub -->|push triggers| Vercel
        Vercel -->|deploys| NextJS
        Vercel -->|deploys| APIGateway
    end

    %% Development Configs & Docs
    subgraph "Configs & Docs"
        direction TB
        Migrations["DB Migrations"]:::database
        RootTS["Root tsconfig.json"]:::ci
        APITS["API tsconfig.json"]:::ci
        WebTS["Web tsconfig.json"]:::ci
        NextConfig["next.config.js"]:::ci
        APIEnv["API .env.example"]:::ci
        WebEnv["Web .env.example"]:::ci
        GoogleOAuthDoc["Google OAuth Setup"]:::external
        OpenAPISpec["OpenAPI Spec"]:::external

        Migrations
        RootTS
        APITS
        WebTS
        NextConfig
        APIEnv
        WebEnv
        GoogleOAuthDoc
        OpenAPISpec
    end

    %% Relationships
    NextJS -->|REST calls| APIGateway
    APIGateway -->|DB calls| PostgresDB

    %% Click Events
    click NextJS "https://github.com/dub55/learning-platform/tree/main/apps/web/src"
    click ImportUI "https://github.com/dub55/learning-platform/blob/main/apps/web/src/pages/leerset/import.tsx"
    click StudyUI "https://github.com/dub55/learning-platform/blob/main/apps/web/src/pages/study/[id].tsx"
    click SupabaseLib "https://github.com/dub55/learning-platform/blob/main/apps/web/src/lib/supabaseClient.ts"
    click SupabaseUtils "https://github.com/dub55/learning-platform/blob/main/apps/web/src/utils/supabaseClient.ts"
    click GlobalsCSS "https://github.com/dub55/learning-platform/blob/main/apps/web/src/styles/globals.css"
    click APIGateway "https://github.com/dub55/learning-platform/blob/main/apps/api/src/index.ts"
    click AIRoutes "https://github.com/dub55/learning-platform/blob/main/apps/api/src/routes/ai.ts"
    click LeersetsRoutes "https://github.com/dub55/learning-platform/blob/main/apps/api/src/routes/leersets.ts"
    click SRSRoutes "https://github.com/dub55/learning-platform/blob/main/apps/api/src/routes/srs.ts"
    click SRSService "https://github.com/dub55/learning-platform/blob/main/apps/api/src/services/srsService.ts"
    click Migrations "https://github.com/dub55/learning-platform/blob/main/scripts/migrate.sql"
    click GoogleOAuthDoc "https://github.com/dub55/learning-platform/blob/main/docs/google-oauth-setup.md"
    click OpenAPISpec "https://github.com/dub55/learning-platform/blob/main/docs/openapi-draft.yaml"
    click RootTS "https://github.com/dub55/learning-platform/blob/main/tsconfig.json"
    click APITS "https://github.com/dub55/learning-platform/blob/main/apps/api/tsconfig.json"
    click WebTS "https://github.com/dub55/learning-platform/blob/main/apps/web/tsconfig.json"
    click NextConfig "https://github.com/dub55/learning-platform/blob/main/next.config.js"
    click APIEnv "https://github.com/dub55/learning-platform/blob/main/apps/api/.env.example"
    click WebEnv "https://github.com/dub55/learning-platform/blob/main/apps/web/.env.example"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#D6FFD6,stroke:#28A745,color:#28A745
    classDef database fill:#FFE2B3,stroke:#DB8E00,color:#DB8E00
    classDef external fill:#E9D0FF,stroke:#6F42C1,color:#6F42C1
    classDef ci fill:#F0F0F0,stroke:#586069,color:#586069
```
