# yosupo06/library-checker-judge architecture

> Architecture diagram of the GitHub repository yosupo06/library-checker-judge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yosupo06/library-checker-judge
- Repository: https://github.com/yosupo06/library-checker-judge

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interface
    ExternalClient("Client (Evans/Submission Tool)"):::external

    %% Backend Services
    subgraph "Backend Services"
        API("API Server (gRPC)"):::coreServices
        Database("Database (PostgreSQL)"):::db
    end

    %% Judge Engine
    subgraph "Judge Engine"
        Judge("Judge Server"):::coreServices
        Lang("Language Executor Containers"):::coreServices
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        CICD("CI/CD Pipelines"):::infra
        Packer("Packer"):::infra
        Terraform("Terraform"):::infra
    end

    %% Peripheral Modules
    subgraph "Peripheral Modules"
        Uploader("Uploader Module"):::peripherals
        Storage("Storage Module"):::peripherals
        Firebase("Firebase Integration"):::peripherals
        Utils("Utility Scripts"):::peripherals
    end

    %% Connections
    ExternalClient -->|"calls"| API
    API -->|"CRUD"| Database
    API -->|"submission"| Judge
    Judge -->|"executes"| Lang

    CICD -->|"deploys"| API
    CICD -->|"deploys"| Judge
    CICD -->|"runs"| Packer
    CICD -->|"provisions"| Terraform

    API -->|"uploads"| Uploader
    Uploader -->|"saves"| Storage
    Firebase -->|"integrates"| API
    Utils -->|"aids"| API

    %% Click Events
    click API "https://github.com/yosupo06/library-checker-judge/tree/master/api/"
    click Database "https://github.com/yosupo06/library-checker-judge/tree/master/database/"
    click Judge "https://github.com/yosupo06/library-checker-judge/tree/master/judge/"
    click Lang "https://github.com/yosupo06/library-checker-judge/tree/master/langs/"
    click Packer "https://github.com/yosupo06/library-checker-judge/tree/master/packer/"
    click Terraform "https://github.com/yosupo06/library-checker-judge/tree/master/terraform/"
    click CICD "https://github.com/yosupo06/library-checker-judge/tree/master/.github/workflows/"
    click Uploader "https://github.com/yosupo06/library-checker-judge/tree/master/uploader/"
    click Storage "https://github.com/yosupo06/library-checker-judge/tree/master/storage/"
    click Firebase "https://github.com/yosupo06/library-checker-judge/tree/master/firebase/"
    click Utils "https://github.com/yosupo06/library-checker-judge/tree/master/utils/"

    %% Styles
    classDef coreServices fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef db fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef infra fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef peripherals fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
