# trap-jp/trao-judge-judge architecture

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

- Interactive diagram: https://gitdiagram.com/trap-jp/trao-judge-judge
- Repository: https://github.com/trap-jp/trao-judge-judge

## Overview

##### Project type and purpose
- It comprises several microservices/command‐line apps (backend_app, judge_control_app, exec_app), shared Rust libraries (domain, infra, usecase, gRPC crates, judge core, jobapi, problem_registry), database migrations, and Python utilities for building problems, running commands, and visualizing results.

##### File structure
- Top‐level “app” directory holds three main binaries:
- backend_app: HTTP API server (Cargo.toml, Dockerfile, src/handler, model, di.rs)
- judge_control_app: orchestrator for judge jobs (gRPC/proto, Dockerfile, mock code)
- exec_app: standalone executor that runs judging logic (main.rs)
- “lib” directory holds shared crates implementing:
- backend_domain, backend_usecase, backend_infra (clean‐architecture layers)
- back_judge_grpc & judge_exec_grpc (gRPC definitions + client/server stubs)
- judge_core (core judging algorithms)
- jobapi (job scheduling / AWS integration)
- judge_infra_mock (local/testing mocks)
- problem_registry (problem‐metadata service)
- Python libraries under “pylib”: traopy_builder, traopy_util, traopy_visualize, plus an example problem. These are CLI tools and utilities for problem setup and result visualization.
- CI/CD manifests in .github/workflows, Docker, nix flakes, Taskfiles, docker-compose.

##### Key architectural insights from README
- Although the README is sparse, naming conventions and Cargo features reveal a “hexagonal/clean‐architecture” approach (domain → usecase → infra), microservices communicating via gRPC, and containerized deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend/Client
    subgraph "Frontend/Client Layer"
        Client["CLI/SPA"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        BackendApp["backend_app"]:::backend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        JudgeControl["judge_control_app"]:::backend
    end

    %% Execution Layer
    subgraph "Execution Layer"
        ExecApp["exec_app"]:::executor
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Domain["backend_domain"]:::library
        Usecase["backend_usecase"]:::library
        Infra["backend_infra"]:::library
        BJGrpc["back_judge_grpc"]:::library
        JEGprc["judge_exec_grpc"]:::library
        Core["judge_core"]:::library
        JobAPI["jobapi"]:::library
        MockInfra["judge_infra_mock"]:::library
    end

    %% Problem Metadata Service
    subgraph "Services"
        ProblemReg["problem_registry"]:::backend
    end

    %% Python CLI Tools
    subgraph "Python CLI Tools"
        Builder["traopy_builder"]:::external
        Util["traopy_util"]:::external
        Viz["traopy_visualize"]:::external
    end

    %% External Resources
    subgraph "External Resources"
        DB[(PostgreSQL)]:::external
        MQ[(Message Broker)]:::external
        AWS["AWS Services"]:::external
        SMTP["SMTP Mail"]:::external
    end

    %% Data Flows
    Client -->|"HTTP/REST"| BackendApp
    BackendApp -->|"usecase"| Usecase
    Usecase -->|"domain calls"| Domain
    Domain -->|"infra repos"| Infra
    Infra -->|"SQL"| DB
    BackendApp -->|"gRPC"| JudgeControl
    JudgeControl -->|"gRPC"| ProblemReg
    JudgeControl -->|"schedule job"| JobAPI
    JobAPI -->|"queue"| MQ
    ExecApp -->|"pull jobs"| MQ
    ExecApp -->|"exec logic"| Core
    ExecApp -->|"gRPC"| JudgeControl
    Infra -->|"send mail"| SMTP
    Builder -->|"scaffold problems"| ProblemReg
    Viz -->|"fetch results"| BackendApp

    %% Click Events
    click BackendApp "https://github.com/trap-jp/trao-judge-judge/tree/develop/app/backend_app"
    click JudgeControl "https://github.com/trap-jp/trao-judge-judge/tree/develop/app/judge_control_app"
    click ExecApp "https://github.com/trap-jp/trao-judge-judge/tree/develop/app/exec_app"
    click BJGrpc "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/back_judge_grpc"
    click JEGprc "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/judge_exec_grpc"
    click Domain "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/backend_domain"
    click Usecase "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/backend_usecase"
    click Infra "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/backend_infra"
    click Core "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/judge_core"
    click JobAPI "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/jobapi"
    click MockInfra "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/judge_infra_mock"
    click ProblemReg "https://github.com/trap-jp/trao-judge-judge/tree/develop/lib/problem_registry"
    click Builder "https://github.com/trap-jp/trao-judge-judge/tree/develop/pylib/traopy_builder"
    click Util "https://github.com/trap-jp/trao-judge-judge/tree/develop/pylib/traopy_util"
    click Viz "https://github.com/trap-jp/trao-judge-judge/tree/develop/pylib/traopy_visualize"

    %% Styles
    classDef backend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef executor fill:#DFFFD0,stroke:#22863a,color:#22863a;
    classDef library fill:#FFE4B5,stroke:#d73a49,color:#d73a49;
    classDef external fill:#E8E8E8,stroke:#6a737d,color:#6a737d;
```
