# mauro-bonilla/algelab-backend architecture

> Architecture diagram of the GitHub repository mauro-bonilla/algelab-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mauro-bonilla/algelab-backend
- Repository: https://github.com/mauro-bonilla/algelab-backend

## Overview

##### Project type and purpose
- AlgeLab is a full-stack educational web platform: React.js frontend + FastAPI backend.
- Purpose: deliver interactive linear-algebra labs with multimedia learning and gamification, authenticate via GitHub, track progress, containerized with Docker, deployed on Azure.

##### File structure
- Top-level: Dockerfile, manage.py, pyproject.toml, src/ and docs/
- src/api: HTTP route handlers (auth.py, users.py, routes.py)
- src/auth: OAuth and JWT logic + middleware
- src/db: database client and exception handling
- src/config: environment-specific settings (dev/prod), constants, logging, middleware
- src/schemas: Pydantic models
- src/main.py: application entry point (FastAPI app instantiation)
- docs/: deployment, env var, database, GitHub auth guides

##### README for additional insights
- Backend: FastAPI (migrated from Django REST), endpoints under /api/*
- Auth: GitHub OAuth → callbacks → JWT issuance/refresh
- Database: PostgreSQL hosted on Supabase
- Deployment: Docker Compose for local, Azure Web Apps in production
- Frontend: separate React repository, communicates with backend over REST

a. Main components
– User’s Web Browser running the React.js SPA
– React.js Frontend (hosted on CDN or Azure Static Web App)
– FastAPI Backend (Docker container running uvicorn)
– Authentication Service (GitHub OAuth, external)
– JWT Service (internal FastAPI module issuing tokens)
– PostgreSQL Database (Supabase)
– Docker Compose / Container Runtime
– Azure Web Apps (production hosting)
b. Relationships & data flows
1) Browser ←→ Frontend: user interactions, HTTP/HTTPS
2) Frontend → Backend: REST calls to /api/auth/*, /api/user/*, /health, etc.
3) Backend → GitHub OAuth: redirect or API call for OAuth handshake
4) GitHub → Backend: OAuth callback with code → JWT issuance
5) Backend → PostgreSQL: SQL queries via src/db/client.py
6) Backend → Frontend: JSON payloads (JWT tokens, user data, lab modules)
c. Architectural patterns & design principles
– Layered separation: presentation (React), application/API (FastAPI), domain logic (auth, db, schemas), configuration (env-based)
– MVC-ish: src/api (controllers), src/schemas (models), src/db (data access)
– 12-Factor app: environment config, stateless services, containerization
– Security: JWT tokens, middleware for token validation/refresh
d. Key technologies & libraries
– Frontend: React.js, Axios/fetch
– Backend: FastAPI, uvicorn, Pydantic, python-dotenv (env vars)
– Auth: OAuth2 via GitHub, JWT (pyjwt or similar)
– Database: PostgreSQL (Supabase client)
– Container: Docker, Docker Compose
– CI/CD & Hosting: GitHub Actions (assumed), Azure Web Apps

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser and Frontend
    Browser["User's Web Browser"]:::external
    React["React.js Frontend"]:::frontend

    %% Backend Service
    subgraph "FastAPI Backend" 
        direction TB
        Main["FastAPI App Entry (main.py)"]:::backend
        subgraph "API Controllers"
            direction TB
            AuthCtrl["auth.py"]:::backend
            RoutesCtrl["routes.py"]:::backend
            UsersCtrl["users.py"]:::backend
        end
        subgraph "Authentication Module"
            direction TB
            GitHubOAuth["github.py"]:::backend
            JWTService["jwt.py"]:::backend
            AuthMiddleware["middleware.py"]:::backend
            AuthExceptions["exceptions.py"]:::backend
        end
        subgraph "Database Layer"
            direction TB
            DBClient["client.py"]:::db
            DBExceptions["exceptions.py"]:::db
        end
        subgraph "Configuration"
            direction TB
            BaseConfig["base.py"]:::backend
            DevConfig["dev.py"]:::backend
            ProdConfig["prod.py"]:::backend
            Constants["constants.py"]:::backend
            LoggingCfg["logging.py"]:::backend
            AppMiddlewareCfg["middleware.py"]:::backend
        end
        Schemas["models.py"]:::backend
    end

    %% Database
    DB["Supabase PostgreSQL"]:::database

    %% External Services
    GitHub["GitHub OAuth Service"]:::external

    %% Containers & Hosting
    subgraph "Container & Hosting"
        direction TB
        Docker["Dockerfile & Compose"]:::container
        Manage["manage.py"]:::container
        Azure["Azure Web Apps"]:::container
    end

    %% Documentation
    subgraph "Documentation Guides"
        direction TB
        DocDB["docs/database.md"]:::docs
        DocDeploy["docs/deployment.md"]:::docs
        DocEnv["docs/env_vars.md"]:::docs
        DocAuthGuide["docs/github_auth.md"]:::docs
    end

    %% Connections
    Browser -->|HTTPS| React
    React -->|REST /api/*| Main
    Main -->|imports controllers| AuthCtrl
    Main -->|imports controllers| RoutesCtrl
    Main -->|imports controllers| UsersCtrl
    AuthCtrl -->|uses| GitHubOAuth
    AuthCtrl -->|uses| JWTService
    AuthMiddleware -->|validates| JWTService
    AuthCtrl -->|raises| AuthExceptions
    Main -->|uses| AuthMiddleware
    Main -->|uses| DBClient
    DBClient -->|handles| DBExceptions
    Main -->|loads| BaseConfig
    BaseConfig -->|extends| DevConfig
    BaseConfig -->|extends| ProdConfig
    Main -->|loads| Constants
    Main -->|loads| LoggingCfg
    Main -->|configures| AppMiddlewareCfg
    Main -->|uses| Schemas
    Main -->|SQL/HTTPS| DB
    AuthCtrl -->|OAuth2| GitHub
    GitHub -->|callback code| AuthCtrl
    Main -->|dockerized by| Docker
    Docker -->|scripts| Manage
    Docker -->|deploys to| Azure
    Main -->|referenced in| DocDB
    Main -->|referenced in| DocDeploy
    Main -->|referenced in| DocEnv
    Main -->|referenced in| DocAuthGuide

    React -->|JWT/JSON| Main
    Main -->|JSON responses| React

    %% Click Events
    click Main "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/main.py"
    click AuthCtrl "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/api/auth.py"
    click RoutesCtrl "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/api/routes.py"
    click UsersCtrl "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/api/users.py"
    click GitHubOAuth "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/auth/github.py"
    click JWTService "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/auth/jwt.py"
    click AuthMiddleware "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/auth/middleware.py"
    click AuthExceptions "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/auth/exceptions.py"
    click DBClient "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/db/client.py"
    click DBExceptions "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/db/exceptions.py"
    click BaseConfig "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/base.py"
    click DevConfig "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/dev.py"
    click ProdConfig "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/prod.py"
    click Constants "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/constants.py"
    click LoggingCfg "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/logging.py"
    click AppMiddlewareCfg "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/config/middleware.py"
    click Schemas "https://github.com/mauro-bonilla/algelab-backend/blob/main/src/schemas/models.py"
    click Docker "https://github.com/mauro-bonilla/algelab-backend/tree/main/Dockerfile"
    click Manage "https://github.com/mauro-bonilla/algelab-backend/blob/main/manage.py"
    click DocDB "https://github.com/mauro-bonilla/algelab-backend/blob/main/docs/database.md"
    click DocDeploy "https://github.com/mauro-bonilla/algelab-backend/blob/main/docs/deployment.md"
    click DocEnv "https://github.com/mauro-bonilla/algelab-backend/blob/main/docs/env_vars.md"
    click DocAuthGuide "https://github.com/mauro-bonilla/algelab-backend/blob/main/docs/github_auth.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3399FF
    classDef backend fill:#E0F8E0,stroke:#33CC33
    classDef db fill:#FFE8C0,stroke:#FF9933
    classDef database fill:#FFE8C0,stroke:#FF9933
    classDef external fill:#F0E0FF,stroke:#9933FF
    classDef container fill:#F2F2F2,stroke:#999999
    classDef docs fill:#FFF0E0,stroke:#CC9900
```
