How cht-oj/oj works
Main Components
• Django Web Application: At the core is the Django project (files like manage.py, dmoj/settings.py, and a plethora of templates under the “templates” directory). This includes admin interfaces, user registration, contest listings, problem management, etc.
• Judge Engine and Bridge: The “judge” module (with subdirectories such as admin, bridge, models, views, tasks, etc.) encapsulates the judging logic. The “bridge” subdirectory shows components for interacting with external judge servers, handling submissions, and relaying data.
• Worker Processes / Celery: Files like dmoj/celery.py, dmoj_celery.py, and the commands under “judge/management/commands” indicate asynchronous background processing (for tasks such as evaluating submissions, sending notifications, etc.). These typically run as Celery workers.
• Problem Data & Test Files: The README calls out that you must define DMOJ_PROBLEM_DATA_ROOT. This means there’s an external repository of problem test cases that the judge system references.
• Frontend Assets & WebSockets: The “resources” folder contains extensive SCSS, JavaScript, and static assets. There is also a “websocket” directory which indicates real-time communication components (perhaps for updates on submissions or contest events).
• Auxiliary Services: Based on the README, a caching service (memcached or redis) is suggested for synchronizing the judge server and caching responses. In addition, an external compile-time precompiled header for testlib.h and possibly a message broker (often RabbitMQ, though not explicitly stated) is used by the Celery configuration.
Relationships and Data Flow
• Users interact with the Web Frontend (Django templates) via HTTP(S), submitting solutions and accessing contest/problem information.
• The Django Backend processes these requests, invoking business logic from various “judge” modules and managing database transactions.
• When a submission is received, it is queued via Celery and passed to judge processes (or separate judge daemons via the “judge/bridge” components) that execute the submission against the problem’s test cases.
• The judge server sends back status/results to the Django application, which then updates the user’s view.
• Real-time updates (e.g., for submission status) could be managed via the WebSocket components.
• Data persistence is handled by the project’s configured database (e.g., PostgreSQL/MySQL—implied by Django’s usage).
• Caching (memcached/redis) enhances performance, particularly for high-traffic contest events.
Architectural Patterns and Design Principles
• MVC (Model-View-Controller) Pattern: Django’s structure inherently employs this, evident in the “models”, “views”, “templates” directories.
• Modular Decomposition: The separation of “judge”, “dmoj”, and “django_ace” demonstrates clear division of concerns.
• Asynchronous Processing: The use of Celery and separate background tasks for judging submissions highlights the separation of real-time user interaction from computationally heavy processes.
• Extensibility: With a well-structured admin interface, pluggable “bridge” components, and clearly defined management commands, the system is designed for extensibility and adaptation.
Relevant Technologies & Frameworks
• Django Framework for the web application.
• Celery for asynchronous task processing.
• WebSockets (with accompanying JavaScript and TypeScript components) for real-time communications.
• Frontend libraries/assets (SCSS, JavaScript) for user interface rendering.
• External cache systems (memcached/redis) as per deployment needs.
• Possibly a message queue (commonly RabbitMQ) that underlies Celery tasks.
Detailing the Architecture
• Different modules like contest formatting (judge/contest_format) and middleware aspects (judge/middleware).
• Relationship between the management commands (under judge/management/commands) that help administer and maintain the judge system.
• Do note the “bridge” subdirectory that handles the interface between Django and the submission judging daemons.