# mawoka-myblock/classquiz architecture

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

- Interactive diagram: https://gitdiagram.com/mawoka-myblock/classquiz
- Repository: https://github.com/mawoka-myblock/classquiz

## Overview

##### Project type and purpose
- This is a full-stack, monorepo quiz platform called ClassQuiz.
- Frontend: SvelteKit + TailwindCSS
- Backend: FastAPI + ormar ORM + python-socketio for real-time.
- Self-hostable with Postgres (DB), Redis (cache), Meilisearch (search), Caddy (reverse proxy).
- Students join live quizzes; teachers create and manage quizzes; real-time answer collection and scoring.

##### File structure
- Top level
– Dockerfile, docker-compose.yml, Caddyfile: containerization and proxy.
– Pipfile, pyproject.toml, alembic.ini, migrations/: Python backend and DB migrations.
– classquiz/: core backend code, divided into subpackages (auth, db, oauth, routers, storage, socket_server, worker).
– frontend/: SvelteKit code, with src/routes (all pages), src/lib (UI components, stores, sockets), assets, config files.
– scripts (import_to_meili.py, image_cleanup.py, simulate_players.py, start.sh): utility and start-up scripts.

- Backend structure
– classquiz/routers: HTTP endpoints organized by domain (login, quiz, results, admin, socket-controller).
– classquiz/socket_server: standalone Socket.IO server code for embedded controllers.
– classquiz/worker: background tasks (e.g., storage).
– classquiz/storage: abstraction over local and S3.
– classquiz/db: ormar models and DB initialization.
– alembic migrations track schema evolution.

- Frontend structure
– src/routes: SvelteKit page routes mirroring site map (account, dashboard, play, quiztivity, docs).
– src/lib: reusable components (editor, play UI, modals, stores, sockets), utils, assets, i18n.
– src/lib/socket.ts: client socket-io integration.

##### README for additional insights
- Monorepo with clearly separated frontend and backend.
- External dependencies: Meilisearch (search), Caddy (proxy), Postgres, Redis.
- 3rd-party closed services: Mapbox (maps), hCaptcha (captcha).
- Live mode uses websockets via python-socketio.

##### Detail & scope
- Break backend into HTTP API and real-time socket server.
- Caddy reverse proxy routing to either frontend or backend.
- Migration tooling (Alembic) under backend for completeness if desired.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    ClientBrowser["Client Browser"]:::ui

    %% Reverse Proxy
    Caddy["Caddy Reverse Proxy"]:::service

    %% Frontend Layer
    subgraph "Frontend Layer"
        SvelteKit["SvelteKit App"]:::ui
        Routes["Frontend Routes"]:::ui
        UIComponents["UI Components & Stores"]:::ui
        SocketClient["Socket.IO Client"]:::ui
    end

    %% Backend Layer
    subgraph "Monorepo Backend"
        FastAPI["FastAPI API"]:::service
        Routers["HTTP Routers"]:::service
        AuthOAuth["Authentication & OAuth"]:::service
        SocketServer["Socket.IO Server"]:::service
        Config["App Settings & Init"]:::service
        ORM["ORM Models & DB Init"]:::service
        CacheLogic["Redis Cache & Session"]:::service
        Worker["Background Worker"]:::worker
        Storage["Storage Abstraction"]:::service
        Migrations["Alembic Migrations"]:::service
        ImportScript["MeiliSearch Import Script"]:::service
    end

    %% Infrastructure
    subgraph "Infrastructure Services"
        Postgres["PostgreSQL"]:::datastore
        Redis["Redis"]:::datastore
        Meili["Meilisearch"]:::datastore
        StorageFS["Local FS / S3"]:::datastore
        ExternalMapbox["Mapbox"]:::external
        ExternalHCaptcha["hCaptcha"]:::external
    end

    %% Connections
    ClientBrowser --> Caddy
    Caddy --> SvelteKit
    Caddy --> FastAPI
    Caddy --> SocketServer
    SvelteKit --> Routes
    SvelteKit --> UIComponents
    SvelteKit --> SocketClient
    SocketClient --> Caddy
    SocketClient -.-> SocketServer

    FastAPI --> Routers
    FastAPI --> AuthOAuth
    FastAPI --> Config
    FastAPI --> ORM
    FastAPI --> CacheLogic
    FastAPI --> Meili
    FastAPI --> Storage
    FastAPI --> ExternalMapbox
    FastAPI --> ExternalHCaptcha

    SocketServer --> CacheLogic
    SocketServer --> Redis
    Worker --> Storage
    Worker --> StorageFS
    ImportScript --> Meili

    Migrations --> ORM
    ORM --> Postgres
    CacheLogic --> Redis

    %% Click Events
    click SvelteKit "https://github.com/mawoka-myblock/classquiz/tree/master/frontend/"
    click Routes "https://github.com/mawoka-myblock/classquiz/tree/master/frontend/src/routes/"
    click UIComponents "https://github.com/mawoka-myblock/classquiz/tree/master/frontend/src/lib/"
    click SocketClient "https://github.com/mawoka-myblock/classquiz/blob/master/frontend/src/lib/socket.ts"
    click Caddy "https://github.com/mawoka-myblock/classquiz/tree/master/Caddyfile"
    click Routers "https://github.com/mawoka-myblock/classquiz/tree/master/classquiz/routers/"
    click AuthOAuth "https://github.com/mawoka-myblock/classquiz/blob/master/classquiz/auth.py"
    click AuthOAuth "https://github.com/mawoka-myblock/classquiz/tree/master/classquiz/oauth/"
    click SocketServer "https://github.com/mawoka-myblock/classquiz/tree/master/classquiz/socket_server/"
    click Config "https://github.com/mawoka-myblock/classquiz/blob/master/classquiz/config.py"
    click ORM "https://github.com/mawoka-myblock/classquiz/blob/master/classquiz/db/models.py"
    click ORM "https://github.com/mawoka-myblock/classquiz/blob/master/classquiz/db/__init__.py"
    click Migrations "https://github.com/mawoka-myblock/classquiz/blob/master/alembic.ini"
    click Migrations "https://github.com/mawoka-myblock/classquiz/tree/master/migrations/"
    click CacheLogic "https://github.com/mawoka-myblock/classquiz/blob/master/classquiz/cache.py"
    click ImportScript "https://github.com/mawoka-myblock/classquiz/blob/master/import_to_meili.py"
    click Worker "https://github.com/mawoka-myblock/classquiz/tree/master/classquiz/worker/"
    click Storage "https://github.com/mawoka-myblock/classquiz/tree/master/classquiz/storage/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000;
    classDef service fill:#90EE90,stroke:#000;
    classDef datastore fill:#FFD580,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
    classDef worker fill:#E6E6FA,stroke:#000,stroke-dasharray:5 5;
```
