How mauro-bonilla/algelab-backend works
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