# sust-cp-geeks/cp-geeks-backend architecture

> Architecture diagram of the GitHub repository sust-cp-geeks/cp-geeks-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sust-cp-geeks/cp-geeks-backend
- Repository: https://github.com/sust-cp-geeks/cp-geeks-backend

## Overview

1. **Overall shape**
   - This is a single Rust backend service built on **Tokio + Axum**.
   - It exposes a **REST API** for the SUST CP Geeks platform and is centered around a PostgreSQL database plus a handful of external integrations.

2. **Request entrypoint and composition**
   - `src/main.rs` assembles the application: configuration, shared state, CORS, route registration, and server startup.
   - The route tree is split by domain under `src/routes/`, so each resource group is mounted independently rather than via one monolithic router.

3. **Shared application state**
   - `src/app_state.rs` holds cross-cutting runtime state, primarily the **SQLx/Postgres pool** and a **results cache** used by ranking-related features.
   - This state is passed into handlers so most business logic stays stateless at the handler layer.

4. **Layering of responsibilities**
   - `handlers/` contains the HTTP-facing logic: parse inputs, call services, query/update models, and return responses.
   - `services/` contains the non-HTTP business integrations and computations: email delivery, Codeforces API access, VJudge fetching, and ranking calculations.
   - `models/` defines the domain/data shapes used across handlers, database access, and API payloads.

5. **Database boundary**
   - PostgreSQL is the system of record, initialized and evolved through `migrations/`.
   - The schema includes user accounts, OTP codes, contests, announcements, events/teams, and ranker-related records.
   - `src/config/database.rs` encapsulates pool creation for the Neon-hosted Postgres database described in the README.

6. **Authentication and account lifecycle**
   - Auth is handled by `auth_handler` with support for **register, OTP verification, resend OTP, login, forgot-password, and reset-password**.
   - `utils/jwt.rs` manages JWT creation/verification, while `utils/otp.rs` handles one-time code generation and validation.
   - `services/email.rs` sends OTP and reset emails through **Resend**.
   - `middleware/auth_middleware.rs` extracts and validates JWT claims for protected endpoints.

7. **Authorization model**
   - The API distinguishes between public, user, manager, and admin access.
   - Admin-specific operations live in `admin_handler`, while protected user routes are gated by JWT middleware.
   - The architecture is role-aware at the handler/router level rather than via a separate policy engine.

8. **Platform content management**
   - `contest_handler`, `announcement_handler`, and `event_handler` implement CRUD and workflow operations for the community platform.
   - Events include team-related entities, so that subsystem likely spans multiple tables and coordinated writes rather than a single record type.

9. **External API integrations**
   - `services/codeforces.rs` fetches and aggregates live Codeforces data for profile stats and leaderboard endpoints.
   - `services/vjudge.rs` pulls contest/standing data used by the ranker flow.
   - These integrations are isolated behind service modules so the handlers do not directly depend on external API details.

10. **Ranking and report generation**
   - `ranker_handler` exposes analysis and PDF download endpoints for VJudge-based contest ranking.
   - `services/ranker.rs` performs the ICPC-style ranking logic, including multi-contest handle merging and “sum of seconds” style aggregation.
   - The presence of `fonts/` suggests the PDF path uses bundled font assets when rendering downloadable reports.

11. **Error handling and validation**
   - `src/errors.rs` centralizes application errors into a unified response shape via `IntoResponse`.
   - `validation.rs` and the request model types enforce input constraints before the service layer runs.
   - This keeps API behavior consistent across handlers and reduces duplicated error mapping.

12. **API surface and documentation**
   - `docs/api.md` is the canonical reference for request/response shapes.
   - The README’s endpoint grouping matches the code organization, so the repository is designed for easy diagramming: router → handler → service/model/database/external API.

Main entry points: [`src/routes/mod.rs`](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/mod.rs) (Routes), [`src/services/mod.rs`](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/mod.rs) (Services), [`src/handlers/auth_handler.rs`](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/auth_handler.rs) (Auth), [`src/app_state.rs`](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/app_state.rs) (App state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_api["API layer"]
  node_main(("Main<br/>bootstrap<br/>[main.rs]"))
  node_routes["Routes<br/>router tree<br/>[mod.rs]"]
  node_auth_routes["Auth routes<br/>route module<br/>[auth_routes.rs]"]
  node_admin_routes["Admin routes<br/>route module<br/>[admin_routes.rs]"]
  node_content_routes["Content routes<br/>route module<br/>[contest_routes.rs]"]
  node_ranker_routes["Ranker routes<br/>route module<br/>[ranker_routes.rs]"]
  node_user_routes["User routes<br/>route module<br/>[user_routes.rs]"]
  node_health_handler["Health<br/>handler<br/>[health_handler.rs]"]
  node_auth_handler["Auth<br/>handler<br/>[auth_handler.rs]"]
  node_admin_handler["Admin<br/>handler<br/>[admin_handler.rs]"]
  node_content_handler["Content<br/>handler set<br/>[contest_handler.rs]"]
  node_ranker_handler["Ranker<br/>handler<br/>[ranker_handler.rs]"]
  node_user_handler["Users<br/>handler<br/>[user_handler.rs]"]
  node_auth_middleware(("Auth mw<br/>middleware<br/>[auth_middleware.rs]"))
end

subgraph group_g_core["Core domain"]
  node_app_state[("App state<br/>runtime state<br/>[app_state.rs]")]
  node_models["Models<br/>domain types<br/>[mod.rs]"]
  node_services["Services<br/>[mod.rs]"]
  node_validation["Validation<br/>input checks<br/>[validation.rs]"]
  node_errors["Errors<br/>error mapping<br/>[errors.rs]"]
end

subgraph group_g_data["Data layer"]
  node_database[("Postgres<br/>database config<br/>[database.rs]")]
  node_migrations["Migrations<br/>schema"]
end

subgraph group_g_ext["External systems"]
  node_docs["API docs<br/>reference<br/>[api.md]"]
  node_fonts["Fonts<br/>assets"]
  node_codeforces(("Codeforces<br/>external API<br/>[codeforces.rs]"))
  node_vjudge(("VJudge<br/>external API<br/>[vjudge.rs]"))
  node_resend(("Resend<br/>email service<br/>[email.rs]"))
end

node_main -->|"mounts"| node_routes
node_main -->|"uses"| node_auth_middleware
node_main -->|"injects"| node_app_state
node_main -->|"configures"| node_database
node_main -->|"formats"| node_errors
node_routes -->|"includes"| node_auth_routes
node_routes -->|"includes"| node_admin_routes
node_routes -->|"includes"| node_content_routes
node_routes -->|"includes"| node_ranker_routes
node_routes -->|"includes"| node_user_routes
node_routes -->|"includes"| node_health_handler
node_auth_routes -->|"dispatches"| node_auth_handler
node_admin_routes -->|"dispatches"| node_admin_handler
node_content_routes -->|"dispatches"| node_content_handler
node_ranker_routes -->|"dispatches"| node_ranker_handler
node_user_routes -->|"dispatches"| node_user_handler
node_auth_handler -->|"validates"| node_validation
node_auth_handler -->|"uses"| node_models
node_auth_handler -->|"calls"| node_services
node_auth_handler -->|"reads"| node_app_state
node_admin_handler -->|"reads"| node_app_state
node_content_handler -->|"reads"| node_app_state
node_content_handler -->|"uses"| node_models
node_ranker_handler -->|"calls"| node_services
node_ranker_handler -->|"renders with"| node_fonts
node_user_handler -->|"calls"| node_services
node_services -->|"sends mail"| node_resend
node_services -->|"fetches"| node_codeforces
node_services -->|"fetches"| node_vjudge
node_services -->|"produces"| node_models
node_services -->|"uses cache"| node_app_state
node_app_state -->|"contains"| node_database
node_database -->|"schema evolves via"| node_migrations
node_health_handler -.->|"returns"| node_errors
node_auth_handler -.->|"returns"| node_errors
node_docs -.->|"documents"| node_routes

click node_main "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/main.rs"
click node_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/mod.rs"
click node_auth_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/auth_routes.rs"
click node_admin_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/admin_routes.rs"
click node_content_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/contest_routes.rs"
click node_ranker_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/ranker_routes.rs"
click node_user_routes "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/user_routes.rs"
click node_health_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/health_handler.rs"
click node_auth_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/auth_handler.rs"
click node_admin_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/admin_handler.rs"
click node_content_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/contest_handler.rs"
click node_ranker_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/ranker_handler.rs"
click node_user_handler "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/user_handler.rs"
click node_auth_middleware "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/middleware/auth_middleware.rs"
click node_app_state "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/app_state.rs"
click node_models "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/models/mod.rs"
click node_services "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/mod.rs"
click node_validation "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/validation.rs"
click node_errors "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/errors.rs"
click node_database "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/config/database.rs"
click node_migrations "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/migrations/001_initial_schema.sql"
click node_docs "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/docs/api.md"
click node_fonts "https://github.com/sust-cp-geeks/cp-geeks-backend/tree/dev/fonts"
click node_codeforces "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/codeforces.rs"
click node_vjudge "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/vjudge.rs"
click node_resend "https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/email.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_routes,node_auth_routes,node_admin_routes,node_content_routes,node_ranker_routes,node_user_routes,node_health_handler,node_auth_handler,node_admin_handler,node_content_handler,node_ranker_handler,node_user_handler,node_auth_middleware toneBlue
class node_app_state,node_models,node_services,node_validation,node_errors toneAmber
class node_database,node_migrations toneMint
class node_docs,node_fonts,node_codeforces,node_vjudge,node_resend toneRose
```

## Components

### API layer

HTTP entrypoints, routing, handlers, and request cross-cutting concerns

- [Main](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/main.rs): bootstrap · Assembles config, shared state, middleware, routes, and server startup · `src/main.rs`
- [Routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/mod.rs): router tree · Mounts the domain route modules · `src/routes/mod.rs`
- [Auth routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/auth_routes.rs): route module · Public auth and account lifecycle endpoints · `src/routes/auth_routes.rs`
- [Admin routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/admin_routes.rs): route module · Privileged admin endpoints · `src/routes/admin_routes.rs`
- [Content routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/contest_routes.rs): route module · Contest, announcement, and event endpoints · `src/routes/contest_routes.rs`
- [Ranker routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/ranker_routes.rs): route module · Ranking analysis and report endpoints · `src/routes/ranker_routes.rs`
- [User routes](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/routes/user_routes.rs): route module · User-facing profile and account endpoints · `src/routes/user_routes.rs`
- [Health](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/health_handler.rs): handler · Service health endpoint · `src/handlers/health_handler.rs`
- [Auth](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/auth_handler.rs): handler · Registration, OTP, login, and password reset flows · `src/handlers/auth_handler.rs`
- [Admin](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/admin_handler.rs): handler · Administrative operations and management actions · `src/handlers/admin_handler.rs`
- [Content](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/contest_handler.rs): handler set · Contest, announcement, and event CRUD workflows · `src/handlers/contest_handler.rs`
- [Ranker](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/ranker_handler.rs): handler · Contest ranking analysis and PDF download · `src/handlers/ranker_handler.rs`
- [Users](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/handlers/user_handler.rs): handler · User profile and account endpoints · `src/handlers/user_handler.rs`
- [Auth mw](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/middleware/auth_middleware.rs): middleware · JWT extraction and authorization for protected routes · `src/middleware/auth_middleware.rs`

### Core domain

Shared state, models, business logic, and request validation

- [App state](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/app_state.rs): runtime state · Shared Postgres pool and ranking cache · `src/app_state.rs`
- [Models](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/models/mod.rs): domain types · Shared data shapes for handlers, DB, and external payloads · `src/models/mod.rs`
- [Services](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/mod.rs): business services · Email, external API access, and ranking computations · `src/services/mod.rs`
- [Validation](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/validation.rs): input checks · Request validation rules and constraints · `src/validation.rs`
- [Errors](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/errors.rs): error mapping · Unified application errors and response conversion · `src/errors.rs`

### Data layer

Database configuration and schema evolution

- [Postgres](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/config/database.rs): database config · SQLx pool setup for the Neon-hosted database · `src/config/database.rs`
- [Migrations](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/migrations/001_initial_schema.sql): schema · Initial schema and database evolution scripts · `migrations/001_initial_schema.sql`

### External systems

Third-party services, bundled assets, and API documentation

- [API docs](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/docs/api.md): reference · Canonical endpoint and payload documentation · `docs/api.md`
- [Fonts](https://github.com/sust-cp-geeks/cp-geeks-backend/tree/dev/fonts): assets · Bundled font assets for PDF report rendering · `fonts`
- [Codeforces](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/codeforces.rs): external API · Live contest and profile data source · `src/services/codeforces.rs`
- [VJudge](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/vjudge.rs): external API · Contest standings and ranking data source · `src/services/vjudge.rs`
- [Resend](https://github.com/sust-cp-geeks/cp-geeks-backend/blob/dev/src/services/email.rs): email service · Outbound email delivery for OTP and reset flows · `src/services/email.rs`

## Connections

- Main → Routes: mounts · Registers the application route tree
- Main → Auth mw: uses · Installs JWT-based protection on guarded endpoints
- Main → App state: injects · Creates and shares application state
- Main → Postgres: configures · Builds the database pool during startup
- Main → Errors: formats · Uses shared error responses
- Routes → Auth routes: includes · Mounts auth endpoints
- Routes → Admin routes: includes · Mounts admin endpoints
- Routes → Content routes: includes · Mounts content endpoints
- Routes → Ranker routes: includes · Mounts ranking endpoints
- Routes → User routes: includes · Mounts user endpoints
- Routes → Health: includes · Mounts health endpoint
- Auth routes → Auth: dispatches · Routes auth requests to handler logic
- Admin routes → Admin: dispatches · Routes admin requests to handler logic
- Content routes → Content: dispatches · Routes platform content requests
- Ranker routes → Ranker: dispatches · Routes ranking requests
- User routes → Users: dispatches · Routes user requests
- Auth → Validation: validates · Checks incoming auth payloads
- Auth → Models: uses · Consumes request and response shapes
- Auth → Services: calls · Delegates email and credential flows
- Auth → App state: reads · Uses shared database and cache state
- Admin → App state: reads · Accesses shared runtime state
- Content → App state: reads · Uses database-backed state for CRUD workflows
- Content → Models: uses · Uses domain models for platform entities
- Ranker → Services: calls · Invokes ranking computations and data fetches
- Ranker → Fonts: renders with · Uses bundled assets for PDF generation
- Users → Services: calls · Fetches or aggregates external user data
- Services → Resend: sends mail · Delivers OTP and reset emails
- Services → Codeforces: fetches · Pulls Codeforces profile and leaderboard data
- Services → VJudge: fetches · Pulls contest and standing data
- Services → Models: produces · Returns structured domain results
- Services → App state: uses cache · Reads and updates ranking cache when needed
- App state → Postgres: contains · Holds the shared Postgres pool
- Postgres → Migrations: schema evolves via · Database schema is initialized and updated by migrations
- Health → Errors: returns · Uses unified error mapping when health checks fail
- Auth → Errors: returns · Uses unified error mapping for auth failures
- API docs → Routes: documents · Reference API surface mirrors route organization