How sust-cp-geeks/cp-geeks-backend works
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: routes/mod.rs Routes · services/mod.rs Services · auth_handler.rs Auth · app_state.rs App state
Components 26
API layer
HTTP entrypoints, routing, handlers, and request cross-cutting concerns
- Main · Assembles config, shared state, middleware, routes, and server startup
src/main.rs - Routes · Mounts the domain route modules
src/routes/mod.rs - Auth routes · Public auth and account lifecycle endpoints
src/routes/auth_routes.rs - Admin routes · Privileged admin endpoints
src/routes/admin_routes.rs - Content routes · Contest, announcement, and event endpoints
src/routes/contest_routes.rs - Ranker routes · Ranking analysis and report endpoints
src/routes/ranker_routes.rs - User routes · User-facing profile and account endpoints
src/routes/user_routes.rs - Health · Service health endpoint
src/handlers/health_handler.rs - Auth · Registration, OTP, login, and password reset flows
src/handlers/auth_handler.rs - Admin · Administrative operations and management actions
src/handlers/admin_handler.rs - Content · Contest, announcement, and event CRUD workflows
src/handlers/contest_handler.rs - Ranker · Contest ranking analysis and PDF download
src/handlers/ranker_handler.rs - Users · User profile and account endpoints
src/handlers/user_handler.rs - Auth mw · JWT extraction and authorization for protected routes
src/middleware/auth_middleware.rs
Core domain
Shared state, models, business logic, and request validation
- App state · Shared Postgres pool and ranking cache
src/app_state.rs - Models · Shared data shapes for handlers, DB, and external payloads
src/models/mod.rs - Services · Email, external API access, and ranking computations
src/services/mod.rs - Validation · Request validation rules and constraints
src/validation.rs - Errors · Unified application errors and response conversion
src/errors.rs
Data layer
Database configuration and schema evolution
- Postgres · SQLx pool setup for the Neon-hosted database
src/config/database.rs - Migrations · Initial schema and database evolution scripts
migrations/001_initial_schema.sql
External systems
Third-party services, bundled assets, and API documentation
- API docs · Canonical endpoint and payload documentation
docs/api.md - Fonts · Bundled font assets for PDF report rendering
fonts - Codeforces · Live contest and profile data source
src/services/codeforces.rs - VJudge · Contest standings and ranking data source
src/services/vjudge.rs - Resend · Outbound email delivery for OTP and reset flows
src/services/email.rs
Connections 36
- 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