# quangngonz/mini_cs50x_answer_api architecture

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

- Interactive diagram: https://gitdiagram.com/quangngonz/mini_cs50x_answer_api
- Repository: https://github.com/quangngonz/mini_cs50x_answer_api

## Overview

##### Main Components
- API Server (Express Application)
- Entry point: index.js
- Controllers: Handle endpoints for adding hints, getting questions, ranking, team-related actions, and answer submissions.
- Middleware: Authentication (authenticate.js) that intercepts requests requiring a valid JWT.
- Database (Supabase)
- Tables include questions, teams_progress, submissions, hints_given, and team_info.
- Utility Scripts
- Scripts such as pushQuestions.js, pushTeams.js, and randomTeamResults.js for seeding and simulating progress.
- Swagger Documentation
- Publicly available API documentation (swagger.html and swagger.json) to interact with the API.
- Deployment Configuration
- Vercel configuration (vercel.json) indicates a serverless deployment model.

##### Out Relationships and Interactions
- Requests from clients hit index.js which routes them to appropriate controllers based on HTTP methods and endpoints.
- Each controller handles request-specific logic (input validation, answer checking, hint processing) and communicates with Supabase via the supabaseService.js.
- The authentication middleware verifies and parses JWT tokens before protected controllers (e.g., get-team-name) process the request.
- Utility scripts are run externally (or as part of initial seed processes) to populate or simulate data in Supabase.
- Swagger UI (served from the public folder) provides an interactive interface for exploring API endpoints; it references the auto-generated swagger.json.

##### Architectural Patterns / Design Principles
- Separation of concerns: Distinct directories for controllers, middleware, services, and utilities keep business logic, authentication, database access, and support scripts modular.
- RESTful design: Endpoints are clearly defined (GET, POST) with predictable responses.
- Middleware pattern: Authentication middleware intercepts requests for protected endpoints.
- Externalized configuration: Environment variables (via .env) and vercel.json for deployment make the application highly configurable.
- Documentation-first: Integrated Swagger docs for developer accessibility and testing.

##### Relevant Technologies
- Node.js, Express for the server and routing.
- Supabase for cloud database interactions.
- JWT (JSON Web Tokens) for authentication.
- Swagger for API documentation.
- Vercel for serverless deployment.
- Utility libraries (e.g., moment for time handling) for business logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Client/Application"):::client

    subgraph "API Server (Express)"
        E("Entry Point: index.js"):::api
        C("Controllers: addHint, getAllQuestions, getRankings, getTeamName, getTeamQuestions, getTeamStats, submitAnswer, updateTeamName"):::controller
        M("Authentication Middleware: authenticate.js"):::middleware
        S("Supabase Service: supabaseService.js"):::service
    end

    DB("Supabase Database\n(tables: questions, teams_progress, submissions, hints_given, team_info)"):::database

    subgraph "Utility Scripts"
        U1("pushQuestions.js"):::utility
        U2("pushTeams.js"):::utility
        U3("randomTeamResults.js"):::utility
    end

    SW("Swagger Documentation\n(swagger.html & swagger.json)"):::external
    VER("Vercel Deployment\n(vercel.json)"):::deployment

    A -->|"HTTP_Request"| E
    E -->|"Route_to"| C
    E -->|"Auth_Check"| M
    C -->|"DB_operations"| S
    S -->|"Data_RW"| DB

    E -->|"Seeding_Simulation"| U1
    E -->|"Seeding_Simulation"| U2
    E -->|"Seeding_Simulation"| U3

    E -->|"API_Docs"| SW
    VER -->|"Deployed_via"| E
    SW -->|"Docs_accessible_to"| A

    class A client
    class E api
    class C controller
    class M middleware
    class S service
    class DB database
    class U1,U2,U3 utility
    class SW external
    class VER deployment

click E "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/index.js"
click C "https://github.com/quangngonz/mini_cs50x_answer_api/tree/main/controllers/"
click M "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/middleware/authenticate.js"
click S "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/services/supabaseService.js"
click U1 "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/utils/pushQuestions.js"
click U2 "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/utils/pushTeams.js"
click U3 "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/utils/randomTeamResults.js"
click SW "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/public/swagger.html"
click VER "https://github.com/quangngonz/mini_cs50x_answer_api/blob/main/vercel.json"
```
