How yosupo06/library-checker-judge works
Project Type and Purpose
• The project is an online judge system designed for library checking. It consists of a gRPC-based API server, a judge server (which evaluates code submissions), and multiple supporting components (such as the database, language-specific execution environments, deployment tooling, etc.).
• The README differentiates between an API server (listening at localhost:50051) and a Judge server that handles submission execution using lightweight containerized executors.
• It is clearly a full-stack system with backend API and judge functionality, infrastructure scripts (Packer, Terraform), and CI/CD workflows via GitHub Actions defined in the .github directory.
Analyzing the File Structure
• Top-level directories like “api”, “database”, “judge”, “langs”, “uploader”, “storage”, “utils” represent the core system components.
• The “api” directory contains the gRPC server (along with its protobuf definition under “api/proto”) exposing the main API endpoints.
• The “database” directory holds code for interacting with and validating database records (PostgreSQL as mentioned in the README and the docker-compose file).
• The “judge” directory implements the submission evaluation logic and interacts with “executor” containers (which are invoked externally based on instructions in the README).
• The “langs” directory includes Dockerfiles and build scripts for various language runtimes; these are used to create sandboxed environments for compiling/executing submitted code.
• The “packer” and “terraform” directories contain scripts and configurations for building container images and cloud infrastructure, respectively.
• Additional directories like “firebase”, “uploader”, and “utils” support peripheral functionality and integration.
System Components and Their Relationships
• API Server:
• Built in Go (files in “api”).
• Exposes gRPC endpoints (as noted in the README, e.g., accessed via Evans).
• Communicates with the database and forwards actual judge service requests.
• Database:
• Managed (likely PostgreSQL) and interfaced via the “database” package.
• Deployed through docker-compose alongside the API server.
• Judge Server:
• Implemented in the “judge” folder and runs as a standalone service.
• Coordinates with the API server and interacts with lightweight executors to run submitted codes.
• Language Execution Environments:
• Provided by “langs” where various Dockerfiles define containerized environments for different programming languages.
• Auxiliary Components:
• “uploader” handles file/source code uploads.
• “storage” contains modules for managing submission and problem data.
• “utils” offer additional functionalities like rejudgement.
• “packer” and “terraform” are used to build and deploy the production images and infrastructure on platforms like GCP.
Architectural Patterns and Design Principles
• The project adopts a microservices-style separation: API server, judge service, and various utility modules are all developed as distinct components.
• Containerization is central—using Docker for running the API server, SQL database, language executors, and CI/CD pipelines.
• The use of gRPC for communication between client and server (and likely between services) is a key design decision.
• There is strong emphasis on automated deployment and testing (multiple GitHub workflow files and build scripts).
• a. Identify Main Components:
• API Server (with gRPC interface)
• Database Server (PostgreSQL via docker-compose)
• Judge Server (submission evaluator and executor coordinator)
• Language Executor Containers (various Docker containers built using Dockerfiles from “langs”)
• Deployment/Infrastructure Tools (Packer, Terraform configurations)
• CI/CD Pipelines (GitHub Actions workflows)
• Peripheral modules: Uploader, Storage, Firebase integration, and Utility scripts.
• b. Determine Relationships and Interactions:
• Judge Server as a separate service that receives submission requests (either directly from API server or via a messaging queue if applicable) and interacts with language executor containers.
• That language execution environments are containerized (using Docker) and each Dockerfile in “langs” represents a different runtime.
• Deployment flows such as CI/CD pipelines (GitHub workflows) triggering builds, tests, and deployments through Packer/Terraform.
• c. Highlight Architectural Patterns:
• Service separation, container orchestration, automated deployment, and a microservices-inspired architecture.
• Point out the use of gRPC, Docker Compose for local test environments, and the clear split between API/judge services.
• d. Include Relevant Technologies:
• Languages/Frameworks: Go, and Docker-based ecosystems for each supported language.
• Infrastructure: Docker, Packer, Terraform, GitHub Actions for CI/CD.
• Communication Protocols: gRPC.