### Start Owojudge Services with Docker Compose

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/setup.md

This command initiates all services defined in the Docker Compose configuration for the Owojudge project in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Start Production Server with pnpm

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/README.md

Starts the production-ready Next.js server. This command is typically used after building the application for deployment.

```bash
pnpm start
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/README.md

Installs project dependencies using the pnpm package manager. Ensure Node.js 20+ and pnpm are installed before running.

```bash
pnpm install
```

--------------------------------

### Copy Environment File

Source: https://github.com/owojudge-team/owojudge/blob/main/README.md

Copies the example environment file to a new file named .env. This is typically the first step in configuring the application, allowing users to customize settings without altering the original example.

```bash
cp .env.example .env
```

--------------------------------

### Run Development Server with pnpm

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/README.md

Starts the Next.js development server. This command is used for local development and allows for hot-reloading and other development-specific features.

```bash
pnpm dev
```

--------------------------------

### Problem Package Structure Example

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Illustrates the directory structure and essential files within a problem package, which is a tar.gz archive. This includes metadata, test case generators, validators, checkers, and solutions.

```bash
# Problem package structure
# problem-name/
# ├── problem.json          # Problem metadata
# ├── judgemeta.json        # Judge configuration
# ├── statement/
# │   └── description.md    # Problem description (Markdown)
# ├── gen/
# │   ├── data              # Test case specification
# │   ├── gen_subtask1.cpp  # Generator programs
# │   ├── manual/           # Manual test cases
# │   ├── testlib.h         # Testlib header
# │   └── jngen.h           # Random generation helper
# ├── validator/
# │   └── validator.cpp     # Input validator
# ├── checker/
# │   └── checker.cpp       # Output checker
# └── solution/
#     └── solution.cpp      # Model solution
```

--------------------------------

### Detailed Submission Response Example - JSON

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/submissions.md

Example JSON structure for a successful response when retrieving details for a single submission. It includes all submission metadata, source code, and detailed test case results.

```JSON
{
  "_id": "68fb7890a1b2c3d4e5f67890",
  "serialNumber": 1000000,
  "username": "admin",
  "userHandle": "Admin Administrator",
  "userID": "68fb6d6e6deaffa916ced917",
  "problemSerialNumber": 0,
  "problemTitle": "Problem Title",
  "language": "g++ c++17",
  "status": "AC",
  "score": 100,
  "time": 0.05,
  "memory": 2048,
  "createdTime": "2025-10-24T13:00:00.000Z",
  "userSolution": [
    {
      "filename": "main.cpp",
      "content": "#include <iostream>\nusing namespace std;\nint main() {\n    int a, b;\n    cin >> a >> b;\n    cout << a + b << endl;\n    return 0;\n}"
    }
  ],
  "results": {
    "sample": {
      "score": 0,
      "testcases": [
        {
          "testcase": "0-01",
          "status": "AC",
          "time": 0.01,
          "memory": 1024,
          "message": "ok"
        },
        {
          "testcase": "0-02",
          "status": "AC",
          "time": 0.01,
          "memory": 1024,
          "message": "ok"
        }
      ]
    },
    "subtask1": {
      "score": 100,
      "testcases": [
        {
          "testcase": "1-01",
          "status": "AC",
          "time": 0.02,
          "memory": 2048,
          "message": "ok"
        }
      ]
    }
  }
}
```

--------------------------------

### Configure Colima Docker Daemon

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/setup.md

This YAML configuration snippet sets the Docker daemon's cgroup driver to 'cgroupfs' within the Colima environment. This is often necessary for compatibility with certain containerized applications.

```yaml
docker:
  exec-opts:
    - native.cgroupdriver=cgroupfs
```

--------------------------------

### Input Validation with testlib.h

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

Example of using the 'testlib.h' library to validate input data for a problem. It demonstrates reading integers with constraints, handling end-of-line and end-of-file markers, and providing custom error messages.

```cpp
#include "testlib.h"

constexpr int kMaxN = 1e5;

int main(int argc, char* argv[]) {
  registerValidation(argc, argv);
  // Read an integer n with the constraint 1 <= n <= kMaxN. If the input is
  // invalid, the validator will notify you that "n" is invalid.
  int n = inf.readInt(1, kMaxN, "n");
  // Read '\n' at the end of the line.
  inf.readEoln();
  for (int i = 0; i < n; ++i) {
    // Here we pass "u[" + to_string(i) + "]" as the name. If the input u[5] is
    // invalid, the validator will notify you that "u[5]" is invalid.
    int u = inf.readInt(0, n, "u[" + to_string(i) + "]");
    // Read a space after the integer.
    inf.readSpace();
  }
  inf.readEoln();
  // Read the end of the file.
  inf.readEof();
}
```

--------------------------------

### C++ Submission Code Example

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/submissions.md

A simple C++ program that reads two integers and prints their sum. This is an example of source code that might be submitted.

```C++
#include <iostream>
using namespace std;
int main() {
    int a, b;
    cin >> a >> b;
    cout << a + b << endl;
    return 0;
}
```

--------------------------------

### Test Data Generation with jngen.h

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

Example of using the 'jngen.h' library to generate test data for a problem. It demonstrates registering the generator, parsing command-line arguments, and using the 'rnd.next' function for random number generation.

```cpp
#include "jngen.h"

int main(int argc, char* argv[]) {
  // Register the generator. The entire argv will form the random seed.
  registerGen(argc, argv, 1);
  // Parse important parameters from command line arguments
  int n = atoi(argv[1]), m = atoi(argv[2]), q = atoi(argv[3]);
  // Use rnd.next to generate random numbers [2, 15].
  rnd.next(2, 15);
}
```

--------------------------------

### List All Contests

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Retrieves a list of all available programming contests. Each contest entry includes its ID, title, description, start and end times, and associated problems with their scores.

```bash
curl -X GET "http://localhost:3000/api/contests" \
  -b cookies.txt
```

--------------------------------

### Testset and Subtask Definition

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

An example of a 'data' file format used by the TPS system to define testsets and subtasks. It shows how to include manual test cases and specify generator usage with command-line arguments.

```plaintext
@testset sample1
manual 0-01.in
manual 0-02.in

@testset sample2
manual 0-03.in

@subtask sample
@include sample1
@include sample2

@testset 5
gen_sub5 5 300000 100000 bon97dus2
```

--------------------------------

### Icon Usage Guidelines (React)

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/design_style.txt

Guidelines for using icons from the 'react-icons/fa6' library within the project. Specifies import patterns, standard sizes, and how icons should be paired with text, particularly in badges.

```javascript
// Import example
import { FaUser } from "react-icons/fa6";

// Standard usage in a component
<FaUser className="h-4 w-4" />

// Usage in a badge with text
<div className="flex items-center gap-1.5">
  <FaStar className="h-3.5 w-3.5" />
  <span>Rating</span>
</div>
```

--------------------------------

### List All Announcements (GET /api/announcement)

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Retrieves a list of all system-wide announcements, ordered from newest to oldest. This public endpoint does not require authentication and returns an array of announcement objects.

```bash
curl -X GET "http://localhost:3000/api/announcement" \
  -b cookies.txt
```

--------------------------------

### Problem Metadata (problem.json) Example

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Defines the core metadata for a programming problem, including its name, code, title, time and memory limits, and scoring policy. This JSON file is part of the problem package.

```json
{
    "name": "APlusB",
    "code": "a-plus-b",
    "title": "A Plus B Problem",
    "type": "Batch",
    "time_limit": 1.0,
    "memory_limit": 2048,
    "score_policy": "sum",
    "has_grader": false
}
```

--------------------------------

### Get Submission Details

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Retrieves detailed information about a specific submission, including the user's solution, judging results for each test case, execution time, and memory usage. This endpoint is crucial for analyzing submission performance.

```bash
curl -X GET "http://localhost:3000/api/submission/1000000" \
  -b cookies.txt
```

--------------------------------

### Reporting Checker Results in C++

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

Shows how to report the outcome of a checker in C++. It includes examples for reporting a Wrong Answer (WA) with detailed differences and an Accepted (AC) status with a token count. The `quitf` function is used for reporting.

```cpp
// WA
quitf(_wa, "%d%s words differ - expected: '%s', found: '%s'", n, englishEnding(n).c_str(),
                  compress(j).c_str(), compress(p).c_str());
// AC
quitf(_ok, "%d tokens", n);
```

--------------------------------

### Solution Verification Configuration (JSON)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

Lists the available solution files and their expected verdicts, used for verifying problem correctness. This JSON file helps in setting up automated checks against reference and correct solutions.

```json
{
    "sol.c": { "verdict": "model_solution" },
    "sol.cpp": { "verdict": "correct" }
}
```

--------------------------------

### Setup and Verify rclone for Google Drive

Source: https://context7.com/owojudge-team/owojudge/llms.txt

This demonstrates the steps to set up rclone for Google Drive integration with OwoJudge backups. It includes commands for configuring the rclone remote, copying the configuration file into the Docker environment, and verifying the remote connection.

```bash
# Setup rclone for Google Drive
rclone config  # Create 'gdrive' remote
cp ~/.config/rclone/rclone.conf backend/secrets/rclone.conf

# Verify rclone configuration
docker compose exec backend \
  rclone listremotes --config /secrets/rclone.conf

# Manual test upload
docker compose exec backend \
  rclone copy /app/scripts/backup-temp/periodic gdrive:owojudge-backups/test \
  --config /secrets/rclone.conf
```

--------------------------------

### Retrieve All Contests (GET /api/contests)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/contests.md

Fetches a list of all available contests. The response includes details such as contest ID, title, description, start and end times, and associated problems. This endpoint is useful for displaying a list of ongoing or upcoming contests.

```HTTP
GET /api/contests
```

--------------------------------

### Output Checker Implementation (C++)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

A C++ program using testlib.h to compare a user's output against the expected output or model solution. It takes input, user output, and answer file paths as arguments and performs the comparison.

```cpp
#include "testlib.h"
using namespace std;
int main(int argc, char* argv[]) {
    registerChecker("tps-example", argc, argv);
    // compareRemainingLines() is a helper to diff strict outputs
    compareRemainingLines(); 
}
```

--------------------------------

### Submission Response Example - JSON

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/submissions.md

Example JSON structure for a successful response when retrieving a list of submissions. It includes total count and an array of submission summaries.

```JSON
{
  "total": 123,
  "submissions": [
    {
      "_id": "68fb7890a1b2c3d4e5f67890",
      "serialNumber": 1000000,
      "username": "admin",
      "userHandle": "Admin Administrator",
      "userID": "68fb6d6e6deaffa916ced917",
      "problemSerialNumber": 0,
      "problemTitle": "Problem Title",
      "language": "g++ c++17",
      "status": "AC",
      "score": 100,
      "time": 0.05,
      "memory": 2048,
      "createdTime": "2025-10-24T13:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Get Specific Announcement (GET /api/announcement/{id})

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Fetches a single announcement based on its unique ID. This endpoint is publicly accessible and returns the details of the requested announcement.

```bash
curl -X GET "http://localhost:3000/api/announcement/68fb8a12b3c4d5e6f7890123" \
  -b cookies.txt
```

--------------------------------

### Rclone Usage for Owojudge Backups (Bash)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/README.md

This set of bash commands demonstrates the workflow for setting up and testing Google Drive backups for Owojudge. It covers creating the rclone configuration, copying it to the backend's secrets path, verifying the remote connection, listing remote directories, and performing a manual upload test. These commands are executed from the host machine or within the backend container.

```bash
# 1) On host machine: create/authorize Google Drive remote
rclone config

# 2) Copy generated config into repo-mounted secrets path
cp ~/.config/rclone/rclone.conf backend/secrets/rclone.conf

# 3) Verify remote from backend container
docker compose -f docker-compose.production.yml --env-file .env exec backend \
  rclone listremotes --config /secrets/rclone.conf

# 4) List top-level Drive folders
docker compose -f docker-compose.production.yml --env-file .env exec backend \
  rclone lsd gdrive: --config /secrets/rclone.conf

# 5) Manual test upload (before enabling automatic upload)
docker compose -f docker-compose.production.yml --env-file .env exec backend \
  rclone copy /app/scripts/backup-temp/periodic gdrive:owojudge-backups/manual-test \
  --config /secrets/rclone.conf
```

--------------------------------

### Create Accounts from CSV and Send Email with Bash

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/README.md

Creates multiple user accounts from a CSV file and sends welcome emails. The CSV requires 'email' and 'name' columns, with an optional 'role' column. Supports SMTP configuration via environment variables and includes options for dry runs and failed email reports. Assumes CSV is mounted at /app/scripts/ within the container.

```bash
# CSV must have header columns: email,name
# Optional column: role (student|ta|judgeAdmin)
# Example: students.csv
# email,name,role
# alice@example.edu,Alice Chen,student
# bob@example.edu,Bob Lin,ta
# admin2@example.edu,Admin Two,judgeAdmin

docker compose exec \
  -e SMTP_HOST=smtp.example.edu \
  -e SMTP_PORT=587 \
  -e SMTP_SECURE=false \
  -e SMTP_USER=mailer@example.edu \
  -e SMTP_PASS='your-smtp-password' \
  backend \
  node scripts/create-student-accounts-from-csv.js \
  --csv /app/scripts/students.csv \
  --from mailer@example.edu \
  --signature "OwoJudge Team" \
  --failed-email-report /app/scripts/failed-email-report.json \
  --default-role student

# Dry run (validate CSV only)
docker compose exec backend node scripts/create-student-accounts-from-csv.js \
  --csv /app/scripts/students.csv \
  --from mailer@example.edu \
  --dry-run
```

--------------------------------

### Get Allowed Languages for Problem (GET /api/problems/:serialNumber/allowed-languages)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/problems.md

Retrieves a list of programming languages that are permitted for submissions to a specific problem. This endpoint requires authentication and returns an array of language identifiers.

```json
[
    "gcc c17",
    "gcc c23",
    "g++ c++17", 
    "g++ c++23",
    "rust",
    "nodejs",
    "python3",
    "bash"
]
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/README.md

Sets up the environment variable for the backend API URL. This file should be created in the frontend directory and is used to configure the application's connection to the backend server.

```bash
NEXT_PUBLIC_API_URL=http://localhost:8787
```

--------------------------------

### GET /api/announcement/:id

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/announcements.md

Retrieves a specific announcement by its ID.

```APIDOC
## GET /api/announcement/:id

### Description
Retrieves a specific announcement by its ID.

### Method
GET

### Endpoint
/api/announcement/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the announcement.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the announcement.
- **topic** (string) - The topic of the announcement.
- **content** (string) - The main content of the announcement.
- **timestamp** (string) - The date and time the announcement was made.

#### Response Example
```json
{
  "_id": "68fb8a12b3c4d5e6f7890123",
  "topic": "Welcome to OwoJudge",
  "content": "We are excited to announce the launch of OwoJudge!",
  "timestamp": "2025-10-25T08:00:00.000Z"
}
```

#### Error Responses
- **404 Not Found**: Announcement does not exist.
```

--------------------------------

### GET /api/announcement

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/announcements.md

Retrieves a list of all announcements, sorted by timestamp (newest first).

```APIDOC
## GET /api/announcement

### Description
Retrieves a list of all announcements, sorted by timestamp (newest first).

### Method
GET

### Endpoint
/api/announcement

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the announcement.
- **topic** (string) - The topic of the announcement.
- **content** (string) - The main content of the announcement.
- **timestamp** (string) - The date and time the announcement was made.

#### Response Example
```json
[
  {
    "_id": "68fb8a12b3c4d5e6f7890123",
    "topic": "Welcome to OwoJudge",
    "content": "We are excited to announce the launch of OwoJudge!",
    "timestamp": "2025-10-25T08:00:00.000Z"
  }
]
```
```

--------------------------------

### Packaging Problem Files with tar.gz

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

Provides the command-line instruction for packaging problem files into a tar.gz archive. This is the standard method for distributing Owojudge problems.

```bash
tar -czvf problem_name.tar.gz problem_directory
```

--------------------------------

### GET /api/users

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/users.md

Retrieves a list of all users. Supports filtering by specified fields.

```APIDOC
## GET /api/users

### Description
Retrieves a list of all users. Supports filtering by specified fields.

### Method
GET

### Endpoint
/api/users

#### Query Parameters
- **filter** (string) - Optional - The field to filter on (e.g., `username`, `displayName`).
- **value** (string) - Optional - The value to search for (case-insensitive regex).

### Response
#### Success Response (200)
- **Array of User Objects**: Each object contains user details like `_id`, `username`, and `displayName`. If filters are applied, additional fields like `rating` may be included.

#### Response Example (No filter)
```json
[
  {
    "_id": "68fb6d6e6deaffa916ced917",
    "username": "admin",
    "displayName": "Admin Administrator"
  }
]
```

#### Response Example (With filter)
```json
[
  {
    "username": "admin",
    "displayName": "Admin Administrator",
    "rating": 1500
  }
]
```
```

--------------------------------

### GET /api/problems

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/problems.md

Retrieves a list of all programming problems. Includes submission and user statistics for each problem.

```APIDOC
## GET /api/problems

### Description
Retrieves a list of all problems. Each problem object includes submission statistics and user-specific details like solved and attempted counts.

### Method
GET

### Endpoint
/api/problems

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **submissionDetail** (object) - Statistics about submissions for the problem.
- **userDetail** (object) - User-specific statistics for the problem.
- **_id** (string) - Unique identifier for the problem.
- **serialNumber** (number) - A unique, human-readable identifier for the problem.
- **status** (string) - The current status of the problem (e.g., 'ready', 'waiting').
- **createdTime** (string) - The timestamp when the problem was created.
- **title** (string) - The title of the problem.
- **timeLimit** (number) - The time limit for submissions in seconds.
- **memoryLimit** (number) - The memory limit for submissions in MB.
- **tags** (array) - An array of tags associated with the problem.
- **problemRelatedTags** (array) - An array of related tags for the problem.
- **fullScore** (number) - The maximum possible score for the problem.
- **dailyQuota** (number) - The remaining daily submissions allowed for the authenticated user for this problem.

#### Response Example
```json
[
  {
    "submissionDetail": {
      "accepted": 0,
      "submitted": 0,
      "timeLimitExceeded": 0,
      "memoryLimitExceeded": 0,
      "wrongAnswer": 0,
      "runtimeError": 0,
      "compilationError": 0,
      "processLimitExceeded": 0
    },
    "userDetail": {
      "solved": 0,
      "attempted": 0
    },
    "_id": "68fb738f149ff1b7927a14a6",
    "serialNumber": 0,
    "status": "ready",
    "createdTime": "2025-10-24T12:39:43.750Z",
    "title": "Problem Title",
    "timeLimit": 1,
    "memoryLimit": 2048,
    "tags": [
      "basic"
    ],
    "problemRelatedTags": [
      "math"
    ],
    "fullScore": 100,
    "dailyQuota": 3
  }
]
```
```

--------------------------------

### GET /api/users/:username

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/users.md

Retrieves a specific user's information by their username. Requires authentication.

```APIDOC
## GET /api/users/:username

### Description
Retrieves a specific user's information by their username. Requires authentication.

### Method
GET

### Endpoint
/api/users/:username

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to retrieve.

### Authentication
Required.

### Response
#### Success Response (200 OK)
- **User Object**: Contains detailed information about the user, including `_id`, `username`, `displayName`, `role`, `rating`, etc.

#### Error Response (404 Not Found)
- If the user does not exist.

#### Response Example
```json
{
  "_id": "68fb6d6e6deaffa916ced917",
  "username": "admin",
  "displayName": "Admin Administrator",
  "role": "judgeAdmin",
  "solvedProblem": 0,
  "solvedProblems": [],
  "rating": 1500
}
```
```

--------------------------------

### Test Case Generation Script (Text)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

A script file that defines how test cases are generated for a problem. It supports commands for including manual tests, running generator executables with specific arguments, and including tests from other subtasks.

```text
@subtask samples
manual sample-01.in

@subtask full
@include samples
gen -n=10 -k=5
gen -n=100 -k=50
```

--------------------------------

### GET /api/problems/:serialNumber/allowed-languages

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/problems.md

Retrieves the list of programming languages that are permitted for submissions to a specific problem. Authentication is required.

```APIDOC
## GET /api/problems/:serialNumber/allowed-languages

### Description
Retrieves the list of programming languages that are permitted for submissions to a specific problem. Authentication is required.

### Method
GET

### Endpoint
/api/problems/:serialNumber/allowed-languages

#### Path Parameters
- **serialNumber** (number) - Required - The serial number of the problem.

### Response
#### Success Response (200 OK)
- **allowed_languages** (array) - An array of strings, where each string is an identifier for an allowed programming language.

#### Response Example
```json
[
    "gcc c17",
    "gcc c23",
    "g++ c++17", 
    "g++ c++23",
    "rust",
    "nodejs",
    "python3",
    "bash"
]
```

#### Error Response
- **401 Unauthorized**: User not authenticated.
- **404 Not Found**: Problem with the given serial number does not exist.
- **500 Internal Server Error**: Failed to read problem metadata.
```

--------------------------------

### Build for Production with pnpm

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/README.md

Builds the Next.js application for production deployment. This command optimizes the application for performance and size.

```bash
pnpm build
```

--------------------------------

### Create and Upload Problem Package

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Demonstrates the process of creating a problem package by archiving the problem files into a tar.gz archive and then uploading it to the judge system using a cURL command.

```bash
# Create the package
tar -czvf a-plus-b.tar.gz a-plus-b/

# Upload to judge
curl -X POST http://localhost:3000/api/problems \
  -b cookies.txt \
  -F "problem=@./a-plus-b.tar.gz"
```

--------------------------------

### GET /api/problems/:serialNumber

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/problems.md

Retrieves a single problem by its serial number, including its description and sample test cases. Requires authentication.

```APIDOC
## GET /api/problems/:serialNumber

### Description
Retrieves a single problem by its serial number. This endpoint returns the problem's full details, including its description, sample test cases, and other metadata. Authentication is required.

### Method
GET

### Endpoint
/api/problems/:serialNumber

### Parameters
#### Path Parameters
- **serialNumber** (number) - Required - The serial number of the problem to retrieve.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **submissionDetail** (object) - Statistics about submissions for the problem.
- **userDetail** (object) - User-specific statistics for the problem.
- **_id** (string) - Unique identifier for the problem.
- **serialNumber** (number) - A unique, human-readable identifier for the problem.
- **status** (string) - The current status of the problem (e.g., 'ready', 'waiting').
- **createdTime** (string) - The timestamp when the problem was created.
- **title** (string) - The title of the problem.
- **timeLimit** (number) - The time limit for submissions in seconds.
- **memoryLimit** (number) - The memory limit for submissions in MB.
- **processes** (number) - The number of processes allowed for the problem.
- **fullScore** (number) - The maximum possible score for the problem.
- **scorePolicy** (string) - The scoring policy for the problem.
- **tags** (array) - An array of tags associated with the problem.
- **problemRelatedTags** (array) - An array of related tags for the problem.
- **dailyQuota** (number) - The remaining daily submissions allowed for the authenticated user for this problem.
- **__v** (number) - Mongoose version key.
- **description** (string) - The detailed description of the problem, often in Markdown format.
- **sampleTestcases** (array) - An array of sample test cases, each with input and output.

#### Response Example
```json
{
  "submissionDetail": {
    "accepted": 0,
    "submitted": 0,
    "timeLimitExceeded": 0,
    "memoryLimitExceeded": 0,
    "wrongAnswer": 0,
    "runtimeError": 0,
    "compilationError": 0,
    "processLimitExceeded": 0
  },
  "userDetail": {
    "solved": 0,
    "attempted": 0
  },
  "_id": "68fb738f149ff1b7927a14a6",
  "serialNumber": 0,
  "status": "ready",
  "createdTime": "2025-10-24T12:39:43.750Z",
  "title": "Problem Title",
  "timeLimit": 1,
  "memoryLimit": 2048,
  "processes": 1,
  "fullScore": 100,
  "scorePolicy": "sum",
  "tags": [
    "basic"
  ],
  "problemRelatedTags": [
    "math"
  ],
  "dailyQuota": 3,
  "__v": 0,
  "description": "# TPS example problem (a + b)\n\n## Story\n\nThis is an example problem for the TPS (Testlib Problem Specification) format. The problem is a simple addition problem where the task is to read two integers from the input and output their sum.\n\n## Description\n\nGiven two integers \( a \) and \( b \), output their sum.\n\n## Input\n\nThe input consists of a single line containing two integers \( a \) and \( b \) separated by a space.\n\n## Output\n\nOutput a single integer which is the sum of \( a \) and \( b \).\n\n## Constraints\n\n- \( 1 \leq a, b \leq 100 \)",
  "sampleTestcases": [
    {
      "name": "0-01",
      "input": "1 2\n",
      "output": "3\n"
    }
  ]
}
```
```

--------------------------------

### Get Contest Standings

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/contests.md

Retrieves the current standings for a specific contest. Standings are sorted by total score and then by last submission time.

```APIDOC
## GET /api/contests/:id/standings

### Description
Retrieves the standings for a specific contest.

### Method
GET

### Endpoint
/api/contests/:id/standings

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contest.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Array of Standings Objects**: Each object represents a user's standing in the contest, including username, total score, problems solved, and detailed problem scores.

#### Response Example
```json
[
  {
    "username": "user1",
    "totalScore": 200,
    "solvedCount": 2,
    "problemScores": [
      {
        "serialNumber": 0,
        "score": 100,
        "lastSubmissionTime": "2025-11-01T10:00:00.000Z"
      },
      {
        "serialNumber": 1,
        "score": 100,
        "lastSubmissionTime": "2025-11-01T11:00:00.000Z"
      }
    ],
    "lastSubmissionTime": "2025-11-01T11:00:00.000Z"
  }
]
```

#### Error Responses
- **404 Not Found**: If the contest does not exist.
```

--------------------------------

### Problem Metadata Configuration (JSON)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

Defines the core metadata for a competitive programming problem, including name, code, title, type, time limit, memory limit, and score aggregation policy. This JSON file is essential for defining a problem's basic properties.

```json
{
    "name": "Problem",
    "code": "tps-example",
    "title": "Problem Title",
    "type": "Batch",          // We only support "Batch"
    "time_limit": 1.0,        // Seconds
    "memory_limit": 2048,     // Megabytes
    "score_policy": "sum"     // How subtask scores are aggregated
}
```

--------------------------------

### Create Single Test User with Bash

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/README.md

Creates a single test user with specified username, display name, password, and role. Supports 'judgeAdmin', 'ta', and 'student' roles. Executes within the backend container via docker compose.

```bash
# Create an admin user
docker compose exec -T backend node scripts/create-user.js "$USERNAME" "$DISPLAY_NAME" "$PASSWORD" "judgeAdmin"
# Create a TA user
docker compose exec -T backend node scripts/create-user.js "$USERNAME" "$DISPLAY_NAME" "$PASSWORD" "ta"
# Create a student user
docker compose exec -T backend node scripts/create-user.js "$USERNAME" "$DISPLAY_NAME" "$PASSWORD" "student"
```

--------------------------------

### Test Case Specification (gen/data) Example

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Specifies how test cases should be generated, including manual test cases and automatically generated ones for different subtasks. This file uses a custom format to define test case generation logic.

```bash
@testset sample
manual 0-01.in
manual 0-02.in

@subtask subtask1
# Format: generator_name arg1 arg2 ... random_seed
gen_small 10 100 seed1
gen_small 20 200 seed2

@subtask subtask2
gen_large 1000 1000000 seed3
gen_large 5000 1000000 seed4
```

--------------------------------

### Get Contest by ID

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/contests.md

Retrieves detailed information for a specific contest using its unique identifier. This is useful for displaying the details of a single contest page.

```APIDOC
## GET /api/contests/:id

### Description
Retrieves a single contest by its ID.

### Method
GET

### Endpoint
/api/contests/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contest.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Contest Object**: An object containing the full details of the specified contest.

#### Response Example
```json
{
  "_id": "68fb7a00b2c3d4e5f6789012",
  "title": "Fall Programming Contest 2025",
  "description": "Annual fall programming contest featuring algorithmic challenges.",
  "startTime": "2025-11-01T09:00:00.000Z",
  "endTime": "2025-11-01T14:00:00.000Z",
  "problems": [
    {
      "serialNumber": 0,
      "score": 100
    }
  ],
  "standings": [],
  "createdTime": "2025-10-24T13:30:00.000Z"
}
```

#### Error Responses
- **404 Not Found**: Contest does not exist.
```

--------------------------------

### ID Badge Component (TSX)

Source: https://github.com/owojudge-team/owojudge/blob/main/frontend/design_style.txt

A small, circular badge to display an ID. It has a semi-transparent dark background and light text, with rounded corners.

```tsx
<div className="flex h-8 w-8 items-center justify-center rounded-lg bg-slate-700/60 text-sm font-semibold text-slate-300">
  {id}
</div>

```

--------------------------------

### Input Validator Implementation (C++)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

A C++ program using the testlib.h library to validate input files against problem constraints. It reads test case input from stdin and exits with code 0 if valid, or asserts/crashes if invalid.

```cpp
#include "testlib.h"
using namespace std;
int main(int argc, char* argv[]) {
    registerValidation(argc, argv);
    int n = inf.readInt(1, 100, "n");
    inf.readEoln();
    inf.readEof();
}
```

--------------------------------

### OwoJudge Specific Metadata Configuration (JSON)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/tps-tutorial.md

Configures settings specific to the OwoJudge platform, such as full score, tags, allowed programming languages, process limits, and daily submission quotas. This file customizes problem behavior within the OwoJudge environment.

```json
{
  "full_score": 100,
  "tags": ["basic"],
  "problemRelatedTags": ["math"],
  "allowed_languages": ["gcc c17", "g++ c++17", "python3"],
  "process_limit": 1,
  "dailyQuota": 5
}
```

--------------------------------

### Bulk Create Student Accounts from CSV with Node.js Script

Source: https://context7.com/owojudge-team/owojudge/llms.txt

This script enables bulk creation of student accounts from a CSV file. It supports email notifications and requires SMTP configuration via environment variables. A dry-run option is available for validation.

```bash
# Bulk create from CSV with email notifications
# CSV format (students.csv):
# email,name,role
# alice@example.edu,Alice Chen,student
# bob@example.edu,Bob Lin,ta

docker compose exec \
  -e SMTP_HOST=smtp.example.edu \
  -e SMTP_PORT=587 \
  -e SMTP_SECURE=false \
  -e SMTP_USER=mailer@example.edu \
  -e SMTP_PASS='smtp-password' \
  backend \
  node scripts/create-student-accounts-from-csv.js \
  --csv /app/scripts/students.csv \
  --from mailer@example.edu \
  --signature "OwoJudge Team" \
  --default-role student

# Dry run to validate CSV
docker compose exec backend node scripts/create-student-accounts-from-csv.js \
  --csv /app/scripts/students.csv \
  --from mailer@example.edu \
  --dry-run
```

--------------------------------

### Configure Periodic Backups with Environment Variables

Source: https://context7.com/owojudge-team/owojudge/llms.txt

This section outlines the environment variables used to configure automated, periodic backups for OwoJudge. It includes settings for enabling backups, interval, output directory, inclusion of raw data, and Google Drive synchronization via rclone.

```bash
# Configure periodic backup in .env
AUTO_BACKUP_ENABLED=true
AUTO_BACKUP_INTERVAL_SECONDS=21600  # Every 6 hours
AUTO_BACKUP_OUTPUT_DIR=/app/scripts/backup-temp/periodic
AUTO_BACKUP_INCLUDE_RAW=true
AUTO_BACKUP_RUN_ON_START=false

# Google Drive upload configuration
AUTO_BACKUP_GDRIVE_ENABLED=true
AUTO_BACKUP_GDRIVE_REMOTE=gdrive
AUTO_BACKUP_GDRIVE_PATH=owojudge-backups
RCLONE_CONFIG=/secrets/rclone.conf
```

--------------------------------

### Get Contest Standings

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Retrieves the current standings for a specific programming contest. The standings are calculated based on participants' scores within the contest's active period.

```bash
curl -X GET "http://localhost:3000/api/contests/68fb7a00b2c3d4e5f6789012/standings" \
  -b cookies.txt
```

--------------------------------

### Retrieve All Users (GET /api/users)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/users.md

Fetches a list of all users. Supports optional filtering by a specified field and value (case-insensitive regex). Returns an array of user objects.

```HTTP
GET /api/users
GET /api/users?filter=username&value=admin
```

--------------------------------

### Configure rclone for Google Drive Remote

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/README.md

This section outlines the interactive steps required to configure a Google Drive remote using the rclone command-line tool. It specifies the inputs needed for naming the remote, selecting the storage type, and handling authentication and advanced settings. Ensure the remote name matches the AUTO_BACKUP_GDRIVE_REMOTE environment variable.

```text
n                              # New remote
name> gdrive                   # Must match AUTO_BACKUP_GDRIVE_REMOTE
Storage> drive                 # Google Drive backend name is "drive"
client_id>                     # optional, press Enter if not using your own app
client_secret>                 # optional, press Enter
scope> 1                       # Full access (recommended for backup folder management)
root_folder_id>                # optional, press Enter unless you need a specific folder root
service_account_file>          # optional, press Enter for OAuth flow
Edit advanced config? n
Use auto config? y             # if local machine has browser
Configure this as a Shared Drive? n   # choose y only if you really use Shared Drive
y                              # confirm and save
q                              # quit config menu
```

--------------------------------

### Check Authentication Status (GET /api/auth/status)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/api/auth.md

Checks if the current user is authenticated. Returns a 200 OK status with the user object if authenticated, or 401 Unauthorized if not.

--------------------------------

### Custom Validation Checks and Early Exit

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/example/README.md

Demonstrates advanced validation techniques using 'testlib.h', including using the 'ensure' macro for custom property checks (like verifying if input represents a tree) and the 'quitf' function for early program termination with specific error messages.

```cpp
inf.quitf(_fail, "Unknown operation %d", op);
```

--------------------------------

### Clone User Repository (Bash)

Source: https://github.com/owojudge-team/owojudge/blob/main/backend/docs/git.md

Command to clone your personal Git repository from the OwoJudge Git server. Replace placeholders with your actual domain and username.

```bash
git clone ssh://git@your-judge-domain:22/<username>/<username>-dsa.git
cd <username>-dsa
```

--------------------------------

### Run Project Script

Source: https://github.com/owojudge-team/owojudge/blob/main/README.md

Executes the main run script for the OwoJudge project. This script likely orchestrates the startup and operation of the application's services.

```bash
./run.sh
```

--------------------------------

### Get Contest Details

Source: https://context7.com/owojudge-team/owojudge/llms.txt

Fetches detailed information about a specific programming contest, identified by its unique ID. This includes all the data provided in the list contests endpoint but for a single contest.

```bash
curl -X GET "http://localhost:3000/api/contests/68fb7a00b2c3d4e5f6789012" \
  -b cookies.txt
```