# tfcis/ntoj architecture

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

- Interactive diagram: https://gitdiagram.com/tfcis/ntoj
- Repository: https://github.com/tfcis/ntoj
- Video tour (about a minute): https://gitdiagram.com/tfcis/ntoj/video

## Overview

NTOJ is a web-based online judge. Users submit code against problems, and the application records challenges and judging results; administrators manage problems and their files, while contest and scoreboard features support organized competitions. The sampled server code confirms Tornado routing and PostgreSQL/Redis initialization, and the sampled handlers confirm problem-type dispatch and file management. The README provides no capability details, and judging, contest, and persistence internals were not fully sampled, so uncertain runtime links are omitted.

Main entry points: [`src/server.py`](https://github.com/tfcis/ntoj/blob/v2.0/src/server.py) (HTTP server), [`src/url.py`](https://github.com/tfcis/ntoj/blob/v2.0/src/url.py) (URL routing), [`src/handlers/prospec/common/filemanager.py`](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/prospec/common/filemanager.py) (Problem file handlers), [`src/handlers/submit.py`](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/submit.py) (Submission handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_server["HTTP server<br/>[server.py]"]
  node_routes["URL routing<br/>[url.py]"]
  node_index["Web entry<br/>[index.py]"]
end

subgraph group_problem["Problems and judging"]
  node_submit["Submission handlers<br/>[submit.py]"]
  node_problem_manage["Problem management"]
  node_file_dispatch["File-manager dispatch<br/>[filemanager.py]"]
  node_file_handler["Problem file handlers<br/>[filemanager.py]"]
  node_file_store["Problem files<br/>[filemanager.py]"]
  node_problem_service["Problem service<br/>[pro.py]"]
  node_challenge_service["Challenge service<br/>[chal.py]"]
  node_spec_handlers["Problem-type handlers"]
  node_spec_services["Problem-type services"]
  node_program["Judging workflow<br/>[program.py]"]
  node_judge_service["Judge cluster service<br/>[judge.py]"]
end

subgraph group_contest["Contests and community"]
  node_contest_handlers["Contest handlers"]
  node_contest_service["Contest service<br/>[contests.py]"]
  node_scoreboard["Contest scoreboard"]
  node_community["Boards and questions<br/>[board.py]"]
end

subgraph group_state["State and integrations"]
  node_services_init["Service initialization<br/>[service.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_pack["Upload packs<br/>[pack.py]"]
end

node_user(("Participant"))
node_admin(("Administrator"))
node_judge_servers{{"Judge servers"}}

node_user -->|"sends requests"| node_server
node_admin -->|"sends requests"| node_server
node_server -->|"registers routes"| node_routes
node_routes -->|"dispatches pages"| node_index
node_routes -->|"dispatches requests"| node_submit
node_routes -->|"dispatches requests"| node_problem_manage
node_routes -->|"dispatches requests"| node_contest_handlers
node_submit -->|"records challenges"| node_challenge_service
node_submit -->|"dispatches by problem"| node_spec_handlers
node_spec_handlers -->|"uses problem type"| node_spec_services
node_challenge_service -->|"prepares judging"| node_program
node_program -->|"requests judging"| node_judge_service
node_judge_service -->|"connects to"| node_judge_servers
node_problem_manage -->|"loads problems"| node_problem_service
node_problem_manage -->|"handles file requests"| node_file_dispatch
node_file_dispatch -->|"dispatches by type"| node_file_handler
node_file_handler -->|"loads problem"| node_problem_service
node_file_handler -->|"manages files"| node_file_store
node_file_handler -->|"copies uploaded files"| node_pack
node_contest_handlers -->|"uses contest data"| node_contest_service
node_contest_service -->|"uses scoreboard"| node_scoreboard
node_server -->|"initializes services"| node_services_init
node_services_init -->|"provides database"| node_postgres
node_services_init -->|"provides cache"| node_redis
node_server -->|"opens connection pool"| node_postgres
node_server -->|"opens connection"| node_redis
node_file_store -->|"copies pack files"| node_pack

click node_server "https://github.com/tfcis/ntoj/blob/v2.0/src/server.py"
click node_routes "https://github.com/tfcis/ntoj/blob/v2.0/src/url.py"
click node_index "https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/index.py"
click node_submit "https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/submit.py"
click node_problem_manage "https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/manage/pro"
click node_file_dispatch "https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/manage/pro/filemanager.py"
click node_file_handler "https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/prospec/common/filemanager.py"
click node_file_store "https://github.com/tfcis/ntoj/blob/v2.0/src/services/filemanager.py"
click node_problem_service "https://github.com/tfcis/ntoj/blob/v2.0/src/services/pro.py"
click node_challenge_service "https://github.com/tfcis/ntoj/blob/v2.0/src/services/chal.py"
click node_spec_handlers "https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/prospec"
click node_spec_services "https://github.com/tfcis/ntoj/tree/v2.0/src/services/prospec"
click node_program "https://github.com/tfcis/ntoj/blob/v2.0/src/services/prospec/program.py"
click node_judge_service "https://github.com/tfcis/ntoj/blob/v2.0/src/services/judge.py"
click node_contest_handlers "https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/contests"
click node_contest_service "https://github.com/tfcis/ntoj/blob/v2.0/src/services/contests.py"
click node_scoreboard "https://github.com/tfcis/ntoj/blob/v2.0/src/services/contest_scoreboard.py"
click node_community "https://github.com/tfcis/ntoj/blob/v2.0/src/services/board.py"
click node_services_init "https://github.com/tfcis/ntoj/blob/v2.0/src/services/service.py"
click node_pack "https://github.com/tfcis/ntoj/blob/v2.0/src/services/pack.py"

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_server,node_routes,node_index toneBlue
class node_submit,node_problem_manage,node_file_dispatch,node_file_handler,node_file_store,node_problem_service,node_challenge_service,node_spec_handlers,node_spec_services,node_program,node_judge_service toneAmber
class node_contest_handlers,node_contest_service,node_scoreboard,node_community,node_judge_servers toneMint
class node_services_init,node_postgres,node_redis,node_pack toneRose
class node_user,node_admin toneIndigo
```

## Components

### Web application

- [HTTP server](https://github.com/tfcis/ntoj/blob/v2.0/src/server.py): `src/server.py`
- [URL routing](https://github.com/tfcis/ntoj/blob/v2.0/src/url.py): `src/url.py`
- [Web entry](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/index.py): `src/handlers/index.py`

### Problems and judging

- [Submission handlers](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/submit.py): `src/handlers/submit.py`
- [Problem management](https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/manage/pro): `src/handlers/manage/pro`
- [File-manager dispatch](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/manage/pro/filemanager.py): `src/handlers/manage/pro/filemanager.py`
- [Problem file handlers](https://github.com/tfcis/ntoj/blob/v2.0/src/handlers/prospec/common/filemanager.py): `src/handlers/prospec/common/filemanager.py`
- [Problem files](https://github.com/tfcis/ntoj/blob/v2.0/src/services/filemanager.py): `src/services/filemanager.py`
- [Problem service](https://github.com/tfcis/ntoj/blob/v2.0/src/services/pro.py): `src/services/pro.py`
- [Challenge service](https://github.com/tfcis/ntoj/blob/v2.0/src/services/chal.py): `src/services/chal.py`
- [Problem-type handlers](https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/prospec): `src/handlers/prospec`
- [Problem-type services](https://github.com/tfcis/ntoj/tree/v2.0/src/services/prospec): `src/services/prospec`
- [Judging workflow](https://github.com/tfcis/ntoj/blob/v2.0/src/services/prospec/program.py): `src/services/prospec/program.py`
- [Judge cluster service](https://github.com/tfcis/ntoj/blob/v2.0/src/services/judge.py): `src/services/judge.py`

### Contests and community

- [Contest handlers](https://github.com/tfcis/ntoj/tree/v2.0/src/handlers/contests): `src/handlers/contests`
- [Contest service](https://github.com/tfcis/ntoj/blob/v2.0/src/services/contests.py): `src/services/contests.py`
- [Contest scoreboard](https://github.com/tfcis/ntoj/blob/v2.0/src/services/contest_scoreboard.py): `src/services/contest_scoreboard.py`
- [Boards and questions](https://github.com/tfcis/ntoj/blob/v2.0/src/services/board.py): `src/services/board.py`

### State and integrations

- [Service initialization](https://github.com/tfcis/ntoj/blob/v2.0/src/services/service.py): `src/services/service.py`
- **PostgreSQL**
- **Redis**
- [Upload packs](https://github.com/tfcis/ntoj/blob/v2.0/src/services/pack.py): `src/services/pack.py`

### Other components

- **Participant**
- **Administrator**
- **Judge servers**

## Connections

- Participant → HTTP server: sends requests
- Administrator → HTTP server: sends requests
- HTTP server → URL routing: registers routes
- URL routing → Web entry: dispatches pages
- URL routing → Submission handlers: dispatches requests
- URL routing → Problem management: dispatches requests
- URL routing → Contest handlers: dispatches requests
- Submission handlers → Challenge service: records challenges
- Submission handlers → Problem-type handlers: dispatches by problem
- Problem-type handlers → Problem-type services: uses problem type
- Challenge service → Judging workflow: prepares judging
- Judging workflow → Judge cluster service: requests judging
- Judge cluster service → Judge servers: connects to
- Problem management → Problem service: loads problems
- Problem management → File-manager dispatch: handles file requests
- File-manager dispatch → Problem file handlers: dispatches by type
- Problem file handlers → Problem service: loads problem
- Problem file handlers → Problem files: manages files
- Problem file handlers → Upload packs: copies uploaded files
- Contest handlers → Contest service: uses contest data
- Contest service → Contest scoreboard: uses scoreboard
- HTTP server → Service initialization: initializes services
- Service initialization → PostgreSQL: provides database
- Service initialization → Redis: provides cache
- HTTP server → PostgreSQL: opens connection pool
- HTTP server → Redis: opens connection
- Problem files → Upload packs: copies pack files