# ouyangyanhuo/hydronext architecture

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

- Interactive diagram: https://gitdiagram.com/ouyangyanhuo/hydronext
- Repository: https://github.com/ouyangyanhuo/hydronext

## Overview

Hydro is a modular programming-contest and online-judge platform. Its central user workflow is to browse or configure a problem, submit a solution, have it compiled and evaluated, and inspect the resulting record; contests, homework, training, and multi-domain administration extend that workflow. The map also includes documented imports, plugins, and contest integrations. README capabilities guide the unsampled areas; source excerpts are partial, so links there show product stages rather than unverified method-level calls.

Main entry points: [`packages/hydrooj/src/handler`](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrooj/src/handler) (Domain handlers), [`packages/hydrooj/src/model/record.ts`](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/record.ts) (Submission records), [`framework/framework/server.ts`](https://github.com/ouyangyanhuo/hydronext/blob/master/framework/framework/server.ts) (HTTP / WS server), [`packages/hydrooj/src/service/db.ts`](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/db.ts) (MongoDB data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Web interface"]
  node_nextui["Next UI"]
  node_problemconfig["Problem editor"]
end

subgraph group_core["Hydro core"]
  node_server["HTTP / WS server<br/>[server.ts]"]
  node_handlers["Domain handlers"]
  node_contest["Contest / homework<br/>[contest.ts]"]
  node_problems["Problem model<br/>[problem.ts]"]
  node_records["Submission records<br/>[record.ts]"]
  node_usersdomains["Users / domains<br/>[domain.ts]"]
  node_database[("MongoDB data<br/>[db.ts]")]
  node_storage["File storage<br/>[storage.ts]"]
end

subgraph group_judging["Judging"]
  node_tasks["Task processing<br/>[task.ts]"]
  node_worker["Judge worker<br/>[worker.ts]"]
  node_judge["Judge engine"]
  node_sandbox["Execution sandbox"]
  node_testdata["Test data<br/>[testdataConfig.ts]"]
end

subgraph group_extensions["Extensions"]
  node_imports["Problem importers<br/>[index.ts]"]
  node_vjudge["Virtual judge"]
  node_plugins["Plugin API<br/>[plugin-api.ts]"]
  node_replay["Code replay<br/>[index.ts]"]
  node_scoreboard["External scoreboard<br/>[index.ts]"]
end

node_student(("Student / admin"))
node_remotejudge(("Remote judge hosts"))
node_s3[("S3-compatible storage")]
node_scoreboardservice(("XCPC scoreboard"))

node_student -->|"uses"| node_webui
node_student -.->|"uses"| node_nextui
node_webui -->|"sends requests"| node_server
node_nextui -.->|"sends requests"| node_server
node_server -->|"dispatches routes"| node_handlers
node_problemconfig -->|"saves configuration"| node_server
node_handlers -->|"reads / updates"| node_problems
node_handlers -->|"reads / updates"| node_contest
node_handlers -->|"checks identity / scope"| node_usersdomains
node_handlers -->|"creates / reads"| node_records
node_problems -->|"persists problem data"| node_database
node_contest -->|"persists contest data"| node_database
node_records -->|"persists records"| node_database
node_usersdomains -->|"persists accounts / domains"| node_database
node_handlers -->|"queues evaluation"| node_tasks
node_tasks -->|"dispatches work"| node_worker
node_worker -->|"runs evaluation"| node_judge
node_judge -->|"executes programs"| node_sandbox
node_judge -->|"uses test data"| node_testdata
node_worker -->|"updates result"| node_records
node_handlers -->|"manages files"| node_storage
node_storage -.->|"reads / writes objects"| node_s3
node_imports -->|"imports problem packages"| node_handlers
node_vjudge -.->|"fetches remote problems"| node_remotejudge
node_plugins -->|"extends routes"| node_handlers
node_records -.->|"provides submission context"| node_replay
node_scoreboard -->|"observes judged records"| node_records
node_scoreboard -.->|"publishes standings"| node_scoreboardservice

click node_webui "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-default"
click node_nextui "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-next/src"
click node_problemconfig "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-default/components/problemconfig"
click node_server "https://github.com/ouyangyanhuo/hydronext/blob/master/framework/framework/server.ts"
click node_handlers "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrooj/src/handler"
click node_contest "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/contest.ts"
click node_problems "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/problem.ts"
click node_records "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/record.ts"
click node_usersdomains "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/domain.ts"
click node_database "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/db.ts"
click node_tasks "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/task.ts"
click node_worker "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/worker.ts"
click node_judge "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/judge"
click node_sandbox "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/sandbox"
click node_testdata "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/lib/testdataConfig.ts"
click node_storage "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/storage.ts"
click node_imports "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/fps-importer/index.ts"
click node_vjudge "https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/hosts"
click node_plugins "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/plugin-api.ts"
click node_replay "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/code-replay/index.ts"
click node_scoreboard "https://github.com/ouyangyanhuo/hydronext/blob/master/packages/scoreboard-xcpcio/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_nextui,node_problemconfig toneBlue
class node_server,node_handlers,node_contest,node_problems,node_records,node_usersdomains,node_database,node_storage,node_s3 toneAmber
class node_tasks,node_worker,node_judge,node_sandbox,node_testdata toneMint
class node_imports,node_vjudge,node_plugins,node_replay,node_scoreboard toneRose
class node_student,node_remotejudge,node_scoreboardservice toneIndigo
```

## Components

### Web experience

- [Web interface](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-default): `packages/ui-default`
- [Next UI](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-next/src): `packages/ui-next/src`
- [Problem editor](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/ui-default/components/problemconfig): `packages/ui-default/components/problemconfig`

### Hydro core

- [HTTP / WS server](https://github.com/ouyangyanhuo/hydronext/blob/master/framework/framework/server.ts): `framework/framework/server.ts`
- [Domain handlers](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrooj/src/handler): `packages/hydrooj/src/handler`
- [Contest / homework](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/contest.ts): `packages/hydrooj/src/model/contest.ts`
- [Problem model](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/problem.ts): `packages/hydrooj/src/model/problem.ts`
- [Submission records](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/record.ts): `packages/hydrooj/src/model/record.ts`
- [Users / domains](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/domain.ts): `packages/hydrooj/src/model/domain.ts`
- [MongoDB data](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/db.ts): `packages/hydrooj/src/service/db.ts`
- [File storage](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/storage.ts): `packages/hydrooj/src/service/storage.ts`

### Judging

- [Task processing](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/model/task.ts): `packages/hydrooj/src/model/task.ts`
- [Judge worker](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/service/worker.ts): `packages/hydrooj/src/service/worker.ts`
- [Judge engine](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/judge): `packages/hydrojudge/src/judge`
- [Execution sandbox](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/sandbox): `packages/hydrojudge/src/sandbox`
- [Test data](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/lib/testdataConfig.ts): `packages/hydrooj/src/lib/testdataConfig.ts`

### Extensions

- [Problem importers](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/fps-importer/index.ts): `packages/fps-importer/index.ts`
- [Virtual judge](https://github.com/ouyangyanhuo/hydronext/tree/master/packages/hydrojudge/src/hosts): `packages/hydrojudge/src/hosts`
- [Plugin API](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/hydrooj/src/plugin-api.ts): `packages/hydrooj/src/plugin-api.ts`
- [Code replay](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/code-replay/index.ts): `packages/code-replay/index.ts`
- [External scoreboard](https://github.com/ouyangyanhuo/hydronext/blob/master/packages/scoreboard-xcpcio/index.ts): `packages/scoreboard-xcpcio/index.ts`

### Other components

- **Student / admin**
- **Remote judge hosts**
- **S3-compatible storage**
- **XCPC scoreboard**

## Connections

- Student / admin → Web interface: uses
- Student / admin → Next UI: uses
- Web interface → HTTP / WS server: sends requests
- Next UI → HTTP / WS server: sends requests
- HTTP / WS server → Domain handlers: dispatches routes
- Problem editor → HTTP / WS server: saves configuration
- Domain handlers → Problem model: reads / updates
- Domain handlers → Contest / homework: reads / updates
- Domain handlers → Users / domains: checks identity / scope
- Domain handlers → Submission records: creates / reads
- Problem model → MongoDB data: persists problem data
- Contest / homework → MongoDB data: persists contest data
- Submission records → MongoDB data: persists records
- Users / domains → MongoDB data: persists accounts / domains
- Domain handlers → Task processing: queues evaluation
- Task processing → Judge worker: dispatches work
- Judge worker → Judge engine: runs evaluation
- Judge engine → Execution sandbox: executes programs
- Judge engine → Test data: uses test data
- Judge worker → Submission records: updates result
- Domain handlers → File storage: manages files
- File storage → S3-compatible storage: reads / writes objects
- Problem importers → Domain handlers: imports problem packages
- Virtual judge → Remote judge hosts: fetches remote problems
- Plugin API → Domain handlers: extends routes
- Submission records → Code replay: provides submission context
- External scoreboard → Submission records: observes judged records
- External scoreboard → XCPC scoreboard: publishes standings