# huythedev/k23oj architecture

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

- Interactive diagram: https://gitdiagram.com/huythedev/k23oj
- Repository: https://github.com/huythedev/k23oj

## Overview

K23OJ is a Django-based online judge for programming practice and contests. The principal workflow is problem discovery, code submission, sandboxed judging, and publication of results; contest formats and ratings add a distinct competition stage. The map also includes local problem data, judge-to-site synchronization, live updates, and asynchronous tasks. Edges use README statements or shown source references; unsampled runtime wiring is omitted or marked unverified.

Main entry points: [`judge/bridge/judge_handler.py`](https://github.com/huythedev/k23oj/blob/master/judge/bridge/judge_handler.py) (Judge Protocol Handler), [`judge/models/submission.py`](https://github.com/huythedev/k23oj/blob/master/judge/models/submission.py) (Submission Records), [`judge/models/contest.py`](https://github.com/huythedev/k23oj/blob/master/judge/models/contest.py) (Contest Records), [`judge/views/submission.py`](https://github.com/huythedev/k23oj/blob/master/judge/views/submission.py) (Submission Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Problem Platform"]
  node_problem_views["Problem Views<br/>[problem.py]"]
  node_problem_model[("Problem Archive<br/>[problem.py]")]
  node_problem_data[("Problem Data<br/>[problem_data.py]")]
  node_submission_views["Submission Views<br/>[submission.py]"]
  node_forms["Submission Forms<br/>[forms.py]"]
  node_profile_model[("User Profiles<br/>[profile.py]")]
end

subgraph group_judging["Judging System"]
  node_submission_model[("Submission Records<br/>[submission.py]")]
  node_judge_handler["Judge Protocol Handler<br/>[judge_handler.py]"]
  node_packet_handler["Packet Transport<br/>[base_handler.py]"]
  node_runtime_model[("Judge Runtimes<br/>[runtime.py]")]
  node_cache["Judge Cache Sync<br/>[caching.py]"]
end

subgraph group_contests["Contest Scoring"]
  node_contest_model[("Contest Records<br/>[contest.py]")]
  node_format_registry["Format Registry<br/>[registry.py]"]
  node_default_format["Default Scoring<br/>[default.py]"]
  node_legacy_ioi["Legacy IOI Scoring<br/>[legacy_ioi.py]"]
  node_ratings["Contest Ratings<br/>[ratings.py]"]
end

subgraph group_live["Async and Live Updates"]
  node_task_modules["Background Tasks<br/>[submission.py]"]
  node_event_poster["Event Publisher<br/>[event_poster.py]"]
  node_websocket["Websocket Service<br/>[daemon.js]"]
end

subgraph group_presentation["UI and Localization"]
  node_template_filters["Date Filters<br/>[datetime.py]"]
  node_datetime_utils["Time Utilities<br/>[timedelta.py]"]
end

node_user(("Participant"))

node_user -.->|"browses problems"| node_problem_views
node_user -.->|"submits code"| node_submission_views
node_submission_views -.->|"uses forms"| node_forms
node_submission_views -.->|"creates submissions"| node_submission_model
node_problem_views -.->|"displays archive"| node_problem_model
node_problem_model -->|"uses problem data"| node_problem_data
node_submission_model -.->|"enters judging"| node_judge_handler
node_judge_handler -->|"uses transport"| node_packet_handler
node_judge_handler -->|"updates results"| node_submission_model
node_judge_handler -->|"loads problem"| node_problem_model
node_judge_handler -->|"syncs cache"| node_cache
node_judge_handler -->|"dispatches tasks"| node_task_modules
node_contest_model -->|"resolves format"| node_format_registry
node_format_registry -->|"registers formats"| node_default_format
node_format_registry -->|"registers formats"| node_legacy_ioi
node_contest_model -->|"scores submissions"| node_submission_model
node_contest_model -->|"calculates ratings"| node_ratings
node_contest_model -->|"tracks participants"| node_profile_model
node_event_poster -.->|"publishes live events"| node_websocket
node_submission_model -->|"announces updates"| node_event_poster
node_template_filters -.->|"formats times"| node_datetime_utils

click node_problem_views "https://github.com/huythedev/k23oj/blob/master/judge/views/problem.py"
click node_problem_model "https://github.com/huythedev/k23oj/blob/master/judge/models/problem.py"
click node_problem_data "https://github.com/huythedev/k23oj/blob/master/judge/models/problem_data.py"
click node_submission_views "https://github.com/huythedev/k23oj/blob/master/judge/views/submission.py"
click node_forms "https://github.com/huythedev/k23oj/blob/master/judge/forms.py"
click node_submission_model "https://github.com/huythedev/k23oj/blob/master/judge/models/submission.py"
click node_judge_handler "https://github.com/huythedev/k23oj/blob/master/judge/bridge/judge_handler.py"
click node_packet_handler "https://github.com/huythedev/k23oj/blob/master/judge/bridge/base_handler.py"
click node_runtime_model "https://github.com/huythedev/k23oj/blob/master/judge/models/runtime.py"
click node_cache "https://github.com/huythedev/k23oj/blob/master/judge/caching.py"
click node_contest_model "https://github.com/huythedev/k23oj/blob/master/judge/models/contest.py"
click node_format_registry "https://github.com/huythedev/k23oj/blob/master/judge/contest_format/registry.py"
click node_default_format "https://github.com/huythedev/k23oj/blob/master/judge/contest_format/default.py"
click node_legacy_ioi "https://github.com/huythedev/k23oj/blob/master/judge/contest_format/legacy_ioi.py"
click node_ratings "https://github.com/huythedev/k23oj/blob/master/judge/ratings.py"
click node_profile_model "https://github.com/huythedev/k23oj/blob/master/judge/models/profile.py"
click node_task_modules "https://github.com/huythedev/k23oj/blob/master/judge/tasks/submission.py"
click node_event_poster "https://github.com/huythedev/k23oj/blob/master/judge/event_poster.py"
click node_websocket "https://github.com/huythedev/k23oj/blob/master/websocket/daemon.js"
click node_template_filters "https://github.com/huythedev/k23oj/blob/master/judge/jinja2/datetime.py"
click node_datetime_utils "https://github.com/huythedev/k23oj/blob/master/judge/utils/timedelta.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_problem_views,node_problem_model,node_problem_data,node_submission_views,node_forms,node_profile_model toneBlue
class node_submission_model,node_judge_handler,node_packet_handler,node_runtime_model,node_cache toneAmber
class node_contest_model,node_format_registry,node_default_format,node_legacy_ioi,node_ratings toneMint
class node_task_modules,node_event_poster,node_websocket toneRose
class node_template_filters,node_datetime_utils,node_user toneIndigo
```

## Components

### Problem Platform

- [Problem Views](https://github.com/huythedev/k23oj/blob/master/judge/views/problem.py): `judge/views/problem.py`
- [Problem Archive](https://github.com/huythedev/k23oj/blob/master/judge/models/problem.py): `judge/models/problem.py`
- [Problem Data](https://github.com/huythedev/k23oj/blob/master/judge/models/problem_data.py): `judge/models/problem_data.py`
- [Submission Views](https://github.com/huythedev/k23oj/blob/master/judge/views/submission.py): `judge/views/submission.py`
- [Submission Forms](https://github.com/huythedev/k23oj/blob/master/judge/forms.py): `judge/forms.py`
- [User Profiles](https://github.com/huythedev/k23oj/blob/master/judge/models/profile.py): `judge/models/profile.py`

### Judging System

- [Submission Records](https://github.com/huythedev/k23oj/blob/master/judge/models/submission.py): `judge/models/submission.py`
- [Judge Protocol Handler](https://github.com/huythedev/k23oj/blob/master/judge/bridge/judge_handler.py): `judge/bridge/judge_handler.py`
- [Packet Transport](https://github.com/huythedev/k23oj/blob/master/judge/bridge/base_handler.py): `judge/bridge/base_handler.py`
- [Judge Runtimes](https://github.com/huythedev/k23oj/blob/master/judge/models/runtime.py): `judge/models/runtime.py`
- [Judge Cache Sync](https://github.com/huythedev/k23oj/blob/master/judge/caching.py): `judge/caching.py`

### Contest Scoring

- [Contest Records](https://github.com/huythedev/k23oj/blob/master/judge/models/contest.py): `judge/models/contest.py`
- [Format Registry](https://github.com/huythedev/k23oj/blob/master/judge/contest_format/registry.py): `judge/contest_format/registry.py`
- [Default Scoring](https://github.com/huythedev/k23oj/blob/master/judge/contest_format/default.py): `judge/contest_format/default.py`
- [Legacy IOI Scoring](https://github.com/huythedev/k23oj/blob/master/judge/contest_format/legacy_ioi.py): `judge/contest_format/legacy_ioi.py`
- [Contest Ratings](https://github.com/huythedev/k23oj/blob/master/judge/ratings.py): `judge/ratings.py`

### Async and Live Updates

- [Background Tasks](https://github.com/huythedev/k23oj/blob/master/judge/tasks/submission.py): `judge/tasks/submission.py`
- [Event Publisher](https://github.com/huythedev/k23oj/blob/master/judge/event_poster.py): `judge/event_poster.py`
- [Websocket Service](https://github.com/huythedev/k23oj/blob/master/websocket/daemon.js): `websocket/daemon.js`

### UI and Localization

- [Date Filters](https://github.com/huythedev/k23oj/blob/master/judge/jinja2/datetime.py): `judge/jinja2/datetime.py`
- [Time Utilities](https://github.com/huythedev/k23oj/blob/master/judge/utils/timedelta.py): `judge/utils/timedelta.py`

### Other components

- **Participant**

## Connections

- Participant → Problem Views: browses problems
- Participant → Submission Views: submits code
- Submission Views → Submission Forms: uses forms
- Submission Views → Submission Records: creates submissions
- Problem Views → Problem Archive: displays archive
- Problem Archive → Problem Data: uses problem data (evidence: `judge/models/problem.py`)
- Submission Records → Judge Protocol Handler: enters judging
- Judge Protocol Handler → Packet Transport: uses transport (evidence: `judge/bridge/judge_handler.py`)
- Judge Protocol Handler → Submission Records: updates results (evidence: `judge/bridge/judge_handler.py`)
- Judge Protocol Handler → Problem Archive: loads problem (evidence: `judge/bridge/judge_handler.py`)
- Judge Protocol Handler → Judge Cache Sync: syncs cache (evidence: `judge/bridge/judge_handler.py`)
- Judge Protocol Handler → Background Tasks: dispatches tasks (evidence: `judge/bridge/judge_handler.py`)
- Contest Records → Format Registry: resolves format (evidence: `judge/models/contest.py`)
- Format Registry → Default Scoring: registers formats (evidence: `judge/contest_format/__init__.py`)
- Format Registry → Legacy IOI Scoring: registers formats (evidence: `judge/contest_format/__init__.py`)
- Contest Records → Submission Records: scores submissions (evidence: `judge/models/contest.py`)
- Contest Records → Contest Ratings: calculates ratings (evidence: `judge/models/contest.py`)
- Contest Records → User Profiles: tracks participants (evidence: `judge/models/contest.py`)
- Event Publisher → Websocket Service: publishes live events
- Submission Records → Event Publisher: announces updates
- Date Filters → Time Utilities: formats times
