UltiCode

Open-source online judge platform · From problem practice to contest judging

Java 17 · Spring Boot · Vue 3 · TypeScript · Docker

English · 简体中文

Quick Start · Screenshots · Documentation · Contributing

MIT License · Report an issue · CI workflow

---

Overview

UltiCode is a full-stack online judge platform providing a problem library, contests, online judging, editorials, community, and an admin console.

Core Capabilities

Area	Capability
Practice	Problem library, contests, code submissions, and judging records
Learning and community	Editorials, forum, achievements, and user profile
Platform administration	Problem and contest management, moderation, audit, notifications, and operational queries
Judging	A standalone Judge worker consumes Submissions from Redis Streams and runs code in a Docker sandbox

Screenshots

The screenshots below are the design and regression reference screenshots maintained in this repository; see the screenshot index for more pages.

Console · Problem detail	Management · Dashboard

Tech Stack

Layer	Technology
Backend	Java 17, Spring Boot, Maven, MyBatis-Plus, Flyway, Dubbo
Frontend	Vue 3, TypeScript, Vite, pnpm workspace
Infrastructure	Docker Compose, MySQL, Redis, Nacos, MeiliSearch

Quick Start

1. Get the project

git clone https://github.com/DavidHLP/UltiCode.git
cd UltiCode

2. Prepare the environment

Prerequisites: Docker Compose v2, mise, Node.js 22.x (22.22.2 or newer on that line for the locked frontend dependencies), pnpm 11.0.0, PM2, plus curl, timeout, and openssl. Frontend CI selects Node 22.x and pins pnpm 11.0.0; the app manifests' >=22.12.0 minimum alone does not cover every locked dependency. Backend startup runs through the repository's services/mvnw and the mise-managed Zulu Java 17. See development prerequisites for Dev Container toolchain selection and rebuild guidance.

Contributors can also use Dev Containers / Codespaces directly; creating the container only installs dependencies and then runs the unit gate by default — it does not start the full stack:

./ulticode doctor --json

./scripts/dev/init-env.sh

3. Finish the database preparation

Required reading for the first start

init-env.sh generates SUBMISSION_CUTOVER_COMPLETE as false. Both dev-lite and dev-full require APP_SUBMISSION_ROUTING_MODE=remote and a completed Submission cutover marker; the startup scripts refuse to run when either is missing.

Read Database migrations first, and complete migration and verification according to the authorized cutover/backfill runbook. Do not skip the checks by only changing the marker.

4. Start the development environment

Once the preparation above is done, choose a mode:

Mode	Search	Frontends
dev-lite	Database-backed search; no Search worker	Not started by default
dev-full	Indexed search with the Search worker	Both frontends started

./scripts/dev/up.sh --mode dev-lite

dev-lite uses database search, does not start the Search worker, and does not start either frontend by default; run the following when you need the browser UI:

./scripts/dev/up.sh --frontend-only

dev-full enables indexed search, the Search worker, and both frontends, still behind the same cutover gate:

./scripts/dev/up.sh --mode dev-full

Once the frontends are running: Console · Management. See Local development for scopes, logs, and troubleshooting entry points.

Optional Core pilot and rollback notes

The Core convergence pilot uses an explicit scope and keeps Judge as a separate process:

./scripts/dev/up.sh --scope core
./scripts/dev/test.sh core

The Core parent listens on 9108 with readiness at /api/v1/core/health/ready; that profile currently serves owner assembly and boundary verification and has not yet replaced the default distributed topology.

This version no longer supports legacy-rollback; up.sh fails closed for that legacy mode and for unknown modes. Production rollback can only use the last complete release descriptor retained and verified by the deployer — the current binaries cannot restore the old implementation (see Deployment, release, and rollback).

Project Structure

UltiCode/
├── apps/
│   ├── console/       # Console (user application)
│   └── management/    # Management (admin application)
├── packages/          # Shared frontend packages
├── services/          # Backend services, API contracts, and workers
├── init-db/           # Database initialization and Flyway migrations
├── docker/            # Infrastructure and judging sandbox
├── scripts/           # Development, verification, and operations entry points
└── docs/              # Architecture, development, and deployment documents

The default topology is distributed. Auth, Admin, App, Submission, and Notification each own their data and write boundaries; Judge runs judging, and Search maintains derived indexes. See the architecture overview.

Documentation

Long-form documentation is currently maintained in Chinese.

• Documentation index: the six core sources for product, architecture, development, operations, and API/reference.
• Product and domain: product positioning, roles, capabilities, and boundaries.
• Architecture: service boundaries, Owner/Worker topology, data flow, contracts, and security boundaries.
• Development and testing: local startup, verification, configuration, rules, and troubleshooting.
• Operations: deployment, release, rollback, migrations, backup, monitoring, and incident response.
• API and authentication reference: browser flows, API entry points, and internal contracts.

Implementation, configuration, migration scripts, tests, and executable runbooks are the source of truth for behavior; this repository has no production environment, and production deployment, real traffic, and external credentials are the deployer's responsibility.

Contributing

Report issues and discuss improvements through Issues, or open a Pull Request.

1. When reporting an issue, include reproduction steps, expected vs. actual behavior, and sanitized environment details.
2. Read AGENTS.md and the relevant directory guides before starting; discuss the scope in an Issue first for larger changes.
3. Add tests for behavior changes and run the matching checks from the development guide.
4. Explain the reason, verification method, and known limitations in the Pull Request.

Before submitting, run git diff --check and the ./scripts/dev/test.sh gate matching the surface you touched. Never commit .env, credentials, private keys, or generated runtime artifacts.

License

Released under the MIT License.