# duongnotnhan/themis-onlan-judge architecture

> Architecture diagram of the GitHub repository duongnotnhan/themis-onlan-judge, 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/duongnotnhan/themis-onlan-judge
- Repository: https://github.com/duongnotnhan/themis-onlan-judge

## Overview

##### Main Components
- Web Server & PHP Execution Environment: The project is deployed on UniServerZ (Apache on Windows), which runs the PHP-based web application.
- Frontend/UI: Comprising various PHP pages (e.g., index.php, admin_dashboard.php, auth.php) along with assets (CSS, JS, fonts). This includes screens for user login, problem submission, viewing results, and the administrative dashboard.
- Backend/Business Logic: A set of PHP scripts that implement functionalities such as user authentication, problem management, submissions handling, ranking, and configuration.
- Database: MariaDB is used to store user accounts, problems, submission records, contest settings, etc. Files like config.php and .env contain configuration details for connecting to this database.
- Judge Worker/Queue Processor: A separate PHP script (judge_worker.php) is responsible for processing queued submissions. This worker likely interacts directly with submission data in the database and possibly with the file system (as indicated by “bài nộp” directory configurations mentioned in the README).

##### File Structure for Architectural Insights
- The PHP files at the root (e.g., index.php, auth.php, create_problem.php) indicate that the application is not split into a classic modern MVC structure but is organized around functional pages.
- The assets folder clearly separates static files (CSS and JS) for the presentation layer.
- Configuration files (.env, config.php) and the SQL database setup script (online-judge-setup-database.sql) hint at a simple but structured deployment and initialization process.
- Files for actions (like edit_problem.php, delete_submission.php, rejudge_submission.php) illustrate that the app performs CRUD-like operations across multiple contest features.

##### Interactions and Data Flow
- Clients (users and administrators) access the system via a web browser. Their requests (HTTP calls) are handled by the PHP pages served by Apache.
- The PHP pages interact with the MariaDB database to retrieve and update data. For instance, user authentication, contest configurations, and submission data are stored in the database.
- When a contestant submits a solution (via submit.php), the system places the submission into a queue (or marks it in the database) for processing.
- The judge worker (judge_worker.php) runs as a separate process, accessing submissions from the database, executing the judging logic, updating submission status, and recording the detailed results back into the database.
- The administrative functions (on the admin dashboard and related pages) allow for managing contest settings, rejudging submissions, and modifying problems.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Although the PHP scripts are largely function-based, the project distinguishes between frontend (UI assets, presentation PHP pages) and backend (processing files, judge worker, configuration, database scripts).
- Client-Server Architecture: Clear separation between user-interface (client side) and server-side logic.
- Asynchronous Processing: By incorporating a judge worker that processes judging tasks separately from the immediate HTTP request cycle, the system effectively uses an asynchronous/queue-based approach for handling resource-intensive operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["Client Browser"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        B["UniServerZ/Apache Web Server"]:::server

        %% PHP Application Subgraph
        subgraph "PHP Application"
            %% Frontend/UI Subgraph
            subgraph "Frontend/UI"
                F1["UI Page: index.php"]:::frontend
                F2["UI Page: admin_dashboard.php"]:::frontend
                F3["Assets Directory"]:::assets
            end
            %% Backend/Business Logic Subgraph
            subgraph "Backend/Business Logic"
                BE1["auth.php"]:::backend
                BE2["create_problem.php"]:::backend
                BE3["edit_problem.php"]:::backend
                BE4["delete_submission.php"]:::backend
                BE5["rejudge_submission.php"]:::backend
                BE6["submit.php"]:::backend
                BE7["view_submission.php"]:::backend
            end
        end

        %% Database and its Configuration
        D["MariaDB Database"]:::database

        subgraph "Database Configuration"
            DB1[".env"]:::database
            DB2["config.php"]:::database
            DB3["online-judge-setup-database.sql"]:::database
        end

        %% Judge Worker
        JW["Judge Worker Process (judge_worker.php)"]:::worker
    end

    %% Connections
    A -->|"HTTP_Request"| B
    B -->|"Serve_Home"| F1
    B -->|"Serve_Admin"| F2
    B -->|"Submit_Solution"| BE6

    %% Backend interactions with Database
    BE1 -->|"User_Auth"| D
    BE2 -->|"Add_Problem"| D
    BE3 -->|"Edit_Problem"| D
    BE4 -->|"Remove_Submission"| D
    BE5 -->|"Rejudge"| D
    BE6 -->|"Insert_Submission"| D
    BE7 -->|"Fetch_Submission"| D
    F2  -->|"Admin_Query"| D

    %% Queue flow from submission to Judge Worker
    BE6 -->|"Queue_Submission"| JW
    JW -->|"Update_Results"| D

    %% Database Configuration to Database
    DB1 -->|"DB_Config"| D
    DB2 -->|"DB_Config"| D
    DB3 -->|"DB_Setup"| D

    %% Click Events
    click F1 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/index.php"
    click F2 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/admin_dashboard.php"
    click F3 "https://github.com/duongnotnhan/themis-onlan-judge/tree/main/assets/"
    click BE1 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/auth.php"
    click BE2 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/create_problem.php"
    click BE3 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/edit_problem.php"
    click BE4 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/delete_submission.php"
    click BE5 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/rejudge_submission.php"
    click BE6 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/submit.php"
    click BE7 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/view_submission.php"
    click DB1 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/.env"
    click DB2 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/config.php"
    click DB3 "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/online-judge-setup-database.sql"
    click JW "https://github.com/duongnotnhan/themis-onlan-judge/blob/main/judge_worker.php"

    %% Styles
    classDef client fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef server fill:#D5D8DC,stroke:#95A5A6,stroke-width:2px;
    classDef frontend fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef assets fill:#82E0AA,stroke:#16A085,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
    classDef database fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef worker fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
```
