AstraCode
AstraCode is a self-hosted, event-driven Online Judge built with Go services, a modern Next.js workspace, and isolated program execution. It covers the core competitive-programming lifecycle: author a problem, moderate it, solve it, run code, submit against official testcases, and review results and statistics.
See GitHub Releases for version history and release notes.
Highlights
- Competitive-programming workspace — searchable problem catalog,
- Durable asynchronous judging — Submission Service writes a submission,
- Correctness-aware results —
AttemptIDcorrelates a submit or rejudge
- Authoring and moderation — Contributors own hidden drafts and testcase
- User-facing product — authentication, profiles, aggregate competitive
Architecture
AstraCode separates services by data ownership: Auth owns identity and sessions, Problem owns catalog and testcase metadata, Submission owns submission state and statistics, and Judge Worker owns asynchronous execution orchestration.
flowchart TB
browser[Browser] --> edge[Envoy edge]
edge --> website[Next.js workspace]
edge --> gateway[KrakenD gateway]
gateway --> auth[Auth Service]
gateway --> problem[Problem Service]
gateway --> submission[Submission Service]
auth --> authdb[(auth_db)]
auth --> redis[(Redis)]
auth --> minio[(MinIO)]
problem --> problemdb[(problem_db)]
problem --> minio
submission --> submissiondb[(submission_db)]
submission -->|transactional outbox| jobs[(Kafka jobs)]
jobs --> worker[Judge Worker]
worker -->|testcase metadata| problem
worker -->|presigned testcase ZIP| minio
worker --> executor[go-judge executor]
worker -->|judge results| results[(Kafka results)]
results --> submission
submission -->|SSE updates| browser
Production topology
The diagram above describes the logical runtime relationships. The verified production deployment separates those components across two physical roles:
- App Node — runs
website,auth-service,problem-service,
submission-service, Envoy, KrakenD, PostgreSQL, Redis, Kafka, and MinIO. It
does not run Judge Worker or the go-judge executor.
- Judge Node — runs
judge-workerand the go-judge sandbox/executor.
Official judging lifecycle
- The browser submits source code through Envoy and KrakenD to Submission Service.
- Submission Service validates the request and Problem access, then creates a
- The outbox relay publishes the committed job to
judge.submission.jobs. - Judge Worker consumes the job, obtains testcase metadata from Problem Service,
- The worker invokes the go-judge executor with configured compilation, time,
- The worker publishes
judge.submission.results, or sends a job to the DLT
- Submission Service transactionally applies only the result for the current
AttemptID and ignores stale terminal duplicates.
- After commit, Submission Service emits an in-process SSE update to the client.
Product capabilities
Solving and judging
- Public catalog with search, filters, tags, difficulty, and limits.
- Structured statements: description, input, output, constraints, hints, and examples.
- Browser editor with syntax highlighting, local drafts, custom testcase runs,
- Official execution for C++, Go, Python, and Java.
- Submission detail/history and Moderator/Admin rejudge support.
Authoring and moderation
- Contributor-owned hidden drafts with authoritative server-side
author_id. - Structured problem authoring for content, tags, examples, constraints, and hints.
- Private testcase ZIP management for an owned hidden draft.
- Moderator/Admin publication, hiding, catalog management, and tag taxonomy
Accounts and profiles
- Registration, email verification, password reset/change, refresh, logout, and logout-all.
- Public profiles and user search for active, non-suspended accounts.
- Submission-owned solved/attempted totals, verdict/language distributions, and
Services
| Component | Responsibility |
| --- | --- |
| website | Next.js application for solvers, contributors, and administrators. |
| auth-service | Identity, sessions, profile media, roles, suspension, and public-user lookup. |
| problem-service | Problems, tags, contributor ownership, testcase metadata, and object storage access. |
| submission-service | Submission/attempt/result state, transactional outbox, profile statistics, and SSE. |
| judge-worker | Kafka consumption, testcase retrieval, executor orchestration, and result publication. |
| gateway | KrakenD API composition, JWT validation, and trusted identity propagation. |
| envoy | Public edge routing for the website, API, avatars, and submission-event traffic. |
| go-judge | Executorserver-based isolated program execution runtime. |
Technology stack
| Area | Technology |
| --- | --- |
| Services | Go 1.25.8, Gin, gRPC, GORM, Google Wire, Zap |
| Frontend | Next.js 15.5.21, React 19.1.1, TypeScript |
| Messaging | Apache Kafka 4.0.0 in KRaft mode, Sarama |
| Data | PostgreSQL 15.6, Redis 7.2, MinIO |
| Execution | criyle/executorserver-based go-judge image with C/C++, Python, and Go tooling |
| Edge | Envoy 1.34.2, KrakenD 2.6.0 |
| Local topology | Docker Compose, persistent volumes, health checks, and resource limits |
Roles and authoring workflow
| Role | Primary product responsibility | | --- | --- | | User | Browse public problems, run code, submit solutions, and view personal statistics. | | Contributor | Manage owned hidden problem drafts and testcase packages. Published contributions are read-only in the Contributor Workspace. | | Moderator | Review and manage the problem catalog, including publication/hiding and moderation actions. | | Admin | Platform administration plus the full Admin Console management surface. |
Contributor Workspace and Admin Console are deliberately separate product surfaces. Backend role inheritance does not make Moderator/Admin accounts use the Contributor navigation workflow.
Quick start
Requirements
- Git
- Docker Engine with Docker Compose
- Node.js and npm for the Next.js frontend
- Go 1.25.8 only when running Go modules outside Docker
Start the local judge stack
git clone https://github.com/nvawntien/go-judge-system.git
cd go-judge-system
test -f environment/postgres.env || \
cp environment/postgres.env.example environment/postgres.env
test -f environment/redis.env || \
cp environment/redis.env.example environment/redis.env
test -f environment/service.env || \
cp environment/service.env.example environment/service.env
docker compose --profile dev --profile worker up -d --build
docker compose ps
The worker profile is required for official asynchronous judging; dev enables
MailHog and Kafka UI. Compose starts the edge, gateway, services, Kafka,
storage, and executor. Start the Next.js app separately.
Start the frontend
cd website
test -f .env.local || cp .env.example .env.local
npm ci
npm run dev
The example frontend configuration targets the local Envoy edge. Adjust it for your environment before opening the browser app.
Local endpoints
| Endpoint | Purpose |
| --- | --- |
| http://localhost:3000 | AstraCode frontend after npm run dev |
| http://localhost:8080 | Envoy public edge and API gateway |
| http://localhost:8081 | Kafka UI with the dev profile |
| http://localhost:8025 | MailHog UI with the dev profile |
Stop the local stack with:
docker compose down
Development and validation
This is a Go workspace with separate modules. Run Go checks per module rather than assuming a root-level test target:
for module in pkg services/auth services/problem services/submission workers/judge; do
(cd "$module" && go test ./... && go vet ./... && go test -race ./...)
done
(cd website && npm run typecheck && npm run build)
docker compose config --quiet
Service configuration is under services/*/config/ and workers/judge/config/.
Compose reads local runtime values from ignored files under environment/; safe
templates are checked in beside them. The frontend template is
website/.env.example. Do not reuse local credentials,
the development JWK, or JWT secrets for any shared or public deployment.
Further technical documentation:
- Overview
- Architecture
- Services
- Domain model
- Data ownership
- Execution flows
- Concurrency
- Development
- Technical debt
Repository structure
.
├── website/ # Next.js AstraCode frontend
├── services/
│ ├── auth/ # identity, sessions, roles, profiles
│ ├── problem/ # catalog, authoring, tags, testcases
│ └── submission/ # submission state, outbox, results, SSE
├── workers/judge/ # Kafka judge consumer and run-code gRPC service
├── pkg/ # shared Go configuration, middleware, contracts, clients
├── proto/ # internal gRPC contracts
├── gateway/ # KrakenD configuration and endpoint definitions
├── envoy/ # public edge proxy configuration
├── build/sandbox/ # executor image definition
├── infra/ # PostgreSQL and Kafka bootstrap assets
├── environment/ # local Compose runtime configuration
├── .github/workflows/ # CI, immutable image release, manual production CD
├── scripts/ # production activation and rollback helper
├── docs/codebase/ # source-grounded architecture and operations notes
├── docker-compose.yml # self-hosted local/reference topology
├── docker-compose.prod.yml # image-based production overlay
└── go.work # Go workspace definition
Production deployment
Production uses immutable GHCR images and includes the standalone Next.js website in the Compose topology. Envoy provides same-origin routes for the UI, API, SSE, and avatars; only its configurable loopback port is bound by default. Production has separate App and Judge nodes. The release path is:
develop
↓
main
↓
immutable vX.Y.Z tag
↓
Release container images workflow
↓
six GHCR images
↓
manual Deploy production workflow
↓
Judge Node → App Node → health verification
The deployment workflow checks out the exact immutable tag and verifies that
all six release image manifests exist before connecting to either node. Judge
is deployed and verified first, followed by App. If App activation fails after
Judge has moved forward, the workflow restores Judge to its pre-workflow
release; the App script independently supports rollback and uses an explicit,
fail-safe health gate. The App Compose project identity remains
go-judge-system, and node-owned configuration under /etc/astracode stays
outside deployment bundles.
Normal node-specific activation and emergency rollback commands use semantic release tags:
# On the relevant production node only:
/opt/astracode/scripts/deploy-app-node.sh vX.Y.Z
/opt/astracode/scripts/deploy-app-node.sh --rollback
/opt/astracode/scripts/deploy-judge-node.sh vX.Y.Z
/opt/astracode/scripts/deploy-judge-node.sh --rollback
The dedicated release workflow publishes version and full-commit SHA image tags;
the separate manual deployment workflow accepts only the protected semantic
release tag and records the deployment through the GitHub production
Environment. Application secrets and node-specific Compose/configuration files
stay outside the checkout.
Read Production deployment before operating the stack. It covers first bootstrap, TLS, strict SSH host verification, GHCR, external secret files, firewall rules, backups, smoke checks, and schema-aware rollback limits. The reference Compose deployment is intentionally not described as zero downtime.
Known limits include in-process SSE fan-out, no checked-in DLT replay consumer,
and runtime AutoMigrate schema changes. Review technical debt
before a multi-replica or public deployment.
Security model
- KrakenD validates JWTs for protected gateway routes and propagates trusted
- Auth records Redis-backed issued-at cutoffs for logout-all, suspension, and
- Role middleware and Problem ownership checks enforce contributor, moderator,
- Hidden testcase packages are separate from public problem statements; workers
- Untrusted code executes through go-judge with configured resource limits.
Roadmap
Delivered
- Problem authoring and moderation.
- Solving, sandboxed execution, asynchronous judging, submissions, and statistics.
- Accounts, profiles, and the Admin Console.
- Dual-node production deployment and an immutable release pipeline.
Next engineering work
- Judge throughput benchmarking and capacity planning.
- Evidence-based concurrency tuning.
- Horizontal Judge fleet and scaling design.
Longer-term product work
- Contests, standings, and rating.
- Editorials and solution workflows.
- Discussions.
Contributing and security
- Read Contributing before proposing a change.
- Participation is governed by the Code of Conduct.
- Follow the Security Policy for private vulnerability reports;
License
Distributed under the MIT License.