# nayeem10/xoroj architecture

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

- Interactive diagram: https://gitdiagram.com/nayeem10/xoroj
- Repository: https://github.com/nayeem10/xoroj

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client (Frontend)"
        React["React App"]:::frontend
        AuthCTX["AuthContext"]:::frontend
        APIClient["API Client"]:::frontend
        StandingsPage["ContestStandingsPage"]:::frontend
    end

    subgraph "API Layer (Backend Controllers)"
        AuthCtrl["AuthController"]:::backend
        ContestCtrl["ContestController"]:::backend
        ProblemCtrl["ProblemController"]:::backend
        SubmissionCtrl["SubmissionController"]:::backend
        StandingsCtrl["StandingsController"]:::backend
    end

    subgraph "Business Logic (Services)"
        JWTService["JWTService"]:::backend
        XUserSvc["XUserService"]:::backend
        ContestSvc["ContestService"]:::backend
        SubmissionSvc["SubmissionService"]:::backend
        JudgingSvc["JudgingService"]:::backend
        ScoreboardSvc["ScoreboardService"]:::backend
        FileStorageSvc["FileStorageService"]:::backend
        StandingsSched["StandingsScheduler"]:::backend
    end

    subgraph "Persistence Layer"
        ContestRepo["ContestRepository"]:::backend
        ProblemRepo["ProblemRepository"]:::backend
        SubmissionRepo["SubmissionRepository"]:::backend
        TestFileRepo["TestFileRepository"]:::backend
        GenFileRepo["GeneratorFileRepository"]:::backend
        StandingsSnapshotRepo["StandingsSnapshotRepository"]:::backend
        XUserRepo["XUserRepository"]:::backend
    end

    Postgres["PostgreSQL DB"]:::db
    FileStorage["File Storage"]:::storage
    CppExec["CppExecutor"]:::external
    Broadcaster["StandingsBroadcaster"]:::external

    React -->|HTTP/HTTPS| AuthCtrl
    React -->|HTTP/HTTPS| ContestCtrl
    React -->|HTTP/HTTPS| ProblemCtrl
    React -->|HTTP/HTTPS| SubmissionCtrl
    StandingsPage -->|WebSocket/SSE| StandingsCtrl

    AuthCtrl -->|calls| JWTService
    AuthCtrl -->|calls| XUserSvc
    ContestCtrl -->|calls| ContestSvc
    ProblemCtrl -->|calls| ContestSvc
    ProblemCtrl -->|calls| ProblemRepo
    SubmissionCtrl -->|calls| SubmissionSvc
    StandingsCtrl -->|calls| ScoreboardSvc

    XUserSvc -->|uses| XUserRepo
    ContestSvc -->|uses| ContestRepo
    SubmissionSvc -->|uses| SubmissionRepo
    SubmissionSvc -->|storesFile| FileStorageSvc
    JudgingSvc -->|executes| CppExec
    JudgingSvc -->|readsTests| TestFileRepo
    FileStorageSvc -->|accesses| FileStorage
    ScoreboardSvc -->|writes| StandingsSnapshotRepo
    StandingsSched -->|writes| StandingsSnapshotRepo
    StandingsSched -->|triggers| Broadcaster
    ScoreboardSvc -->|pushes| Broadcaster

    ContestRepo -->|reads/writes| Postgres
    ProblemRepo -->|reads/writes| Postgres
    SubmissionRepo -->|reads/writes| Postgres
    TestFileRepo -->|reads/writes| Postgres
    GenFileRepo -->|reads/writes| Postgres
    StandingsSnapshotRepo -->|reads/writes| Postgres
    XUserRepo -->|reads/writes| Postgres

    click React "https://github.com/nayeem10/xoroj/tree/main/frontend/src"
    click AuthCTX "https://github.com/nayeem10/xoroj/blob/main/frontend/src/auth/AuthContext.jsx"
    click APIClient "https://github.com/nayeem10/xoroj/blob/main/frontend/src/api/client.js"
    click StandingsPage "https://github.com/nayeem10/xoroj/blob/main/frontend/src/pages/ContestStandingsPage.jsx"
    click AuthCtrl "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/controller/AuthController.java"
    click ContestCtrl "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/controller/ContestController.java"
    click ProblemCtrl "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/controller/ProblemController.java"
    click SubmissionCtrl "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/controller/SubmissionController.java"
    click StandingsCtrl "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/controller/StandingsController.java"
    click ContestSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/ContestService.java"
    click SubmissionSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/SubmissionService.java"
    click JudgingSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/JudgingService.java"
    click ScoreboardSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/ScoreboardService.java"
    click StandingsSched "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/StandingsScheduler.java"
    click FileStorageSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/FileStorageService.java"
    click JWTService "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/JWTService.java"
    click XUserSvc "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/service/XUserService.java"
    click ContestRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/ContestRepository.java"
    click ProblemRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/ProblemRepository.java"
    click SubmissionRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/SubmissionRepository.java"
    click TestFileRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/TestFileRepository.java"
    click GenFileRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/GeneratorFileRepository.java"
    click StandingsSnapshotRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/StandingsSnapshotRepository.java"
    click XUserRepo "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/repo/XUserRepository.java"
    click CppExec "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/judge/CppExecutor.java"
    click Broadcaster "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/live/StandingsBroadcaster.java"
    click Postgres "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/resources/application.yml"
    click FileStorage "https://github.com/nayeem10/xoroj/blob/main/backend/src/main/java/com/Judge_Mental/XorOJ/config/FileStorageConfig.java"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef db fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef storage fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
