How nayeem10/xoroj works
Project type and purpose
• This is a full-stack online judge system (XorOJ) for coding contests.
• Backend: Spring Boot application exposing REST endpoints, handling authentication (JWT), contest/problem management, code submission/judging, real-time standings.
• Frontend: React/Vite single-page application that interacts with the backend via HTTP and receives live updates.
• Supporting services: PostgreSQL database, file storage for test and submission files, scheduled standings snapshot, code execution engine.
High-level architecture components
• Client (Browser)
– React app (frontend/src)
– AuthContext for login state, API client for HTTP calls
• API Layer (Backend Controllers)
– AuthController, ContestController, ProblemController, SubmissionController, etc.
• Business Logic (Backend Services)
– XUserService, ContestService, SubmissionService, JudgingService, ScoreboardService, StandingsScheduler, FileStorageService, etc.
• Persistence Layer (Repositories & Entities)
– Spring Data JPA repositories, entity classes (Contest, Problem, Submission, XUser, TestFile, GeneratorFile)
• Database
– PostgreSQL (configured in application.yml and .env file)
• File Storage
– Local filesystem under uploads/ for problem test cases and user submissions
• Code Execution Engine
– CppExecutor (isolated process or container) invoked by JudgingService
• Real-time Broadcasting
– StandingsBroadcaster pushes updates to clients (WebSocket or SSE)
• Scheduling
– StandingsScheduler triggers periodic snapshots of standings
• Security
– JWTFilter intercepts requests, SecurityConfig enforces roles and endpoints
Relationships and data flows
• User in browser → HTTP(S) calls → Backend Controllers → Services → Repositories → PostgreSQL
• Submission flow:
1. User uploads solution → SubmissionController
2. SubmissionService stores metadata → FileStorageService saves code file
3. JudgingService calls CppExecutor → compiles/runs against TestFile(s)
4. Results saved to Submission entity → ScoreboardService updates standings
• Live updates: StandingsScheduler writes snapshots → StandingsBroadcaster pushes to frontend
• Authentication: React sends credentials → AuthController → JWTService issues token → JWTFilter validates on each API call
Architectural patterns and principles
• Layered architecture: Controller → Service → Repository → Database
• Configuration by annotation and external yml/env for flexibility
• Dependency injection (Spring) for decoupling
• Event scheduling for periodic tasks (Spring Scheduling)
• Real-time push (WebSocket/SSE) for live standings
• Stateless authentication via JWT
• File listeners (entity listeners) for automatic file cleanup or processing