# venugopalreddy787/jurge-engine architecture

> Architecture diagram of the GitHub repository venugopalreddy787/jurge-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venugopalreddy787/jurge-engine
- Repository: https://github.com/venugopalreddy787/jurge-engine

## Overview

Jurge Engine accepts Judge0-compatible code submissions, queues them for isolated execution, and exposes results by token. The main flow spans submission intake, persistence and queueing, language-specific workers, sandbox execution, and result retrieval; callbacks are optional. Separate runtime APIs and admin tools manage runtimes, language registration, metrics, and pool scaling. The graph follows the supplied README and sampled source; some service and dispatcher wiring is not shown, so uncertain call edges are omitted.

Main entry points: [`src/services/admin.service.js`](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/admin.service.js) (Admin service), [`src/sandbox/containerManager.js`](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/sandbox/containerManager.js) (Container pool), [`src/workers/generic.worker.js`](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/generic.worker.js) (Language worker), [`src/services/runtime.service.js`](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/runtime.service.js) (Runtime service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and submissions"]
  node_server["HTTP server<br/>[server.js]"]
  node_submission_routes["Submission routes"]
  node_submission_controller["Submission controller"]
end

subgraph group_execution["Execution pipeline"]
  node_execution_service["Execution service"]
  node_dispatcher["Submission dispatcher"]
  node_queue_service["Queue service<br/>[queue.service.js]"]
  node_workers["Worker launcher<br/>[launchWorkers.js]"]
  node_worker["Language worker<br/>[generic.worker.js]"]
  node_java_worker["Java worker<br/>[java.worker.js]"]
  node_docker_runner["Sandbox runner<br/>[dockerRunner.js]"]
  node_container_manager["Container pool"]
end

subgraph group_operations["Runtime operations"]
  node_runtime_routes["Runtime routes<br/>[runtime.routes.js]"]
  node_runtime_controller["Runtime controller"]
  node_runtime_service["Runtime service<br/>[runtime.service.js]"]
  node_admin_routes["Admin routes<br/>[admin.routes.js]"]
  node_admin_controller["Admin controller"]
  node_admin_service["Admin service<br/>[admin.service.js]"]
  node_language_registry["Language registry"]
  node_scaler["Pool autoscaler<br/>[workerScaler.js]"]
end

subgraph group_state["State and infrastructure"]
  node_queue["BullMQ queues<br/>[queue.js]"]
  node_submission_model[("Submission records<br/>[Submission.js]")]
  node_runtime_model[("Runtime records<br/>[Runtime.js]")]
  node_language_config[("Language configuration<br/>[LanguageConfig.js]")]
end

node_client(("API client"))
node_docker["Docker"]
node_callback(("Callback endpoint"))
node_redis[("Redis")]
node_mongo[("MongoDB")]

node_client -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_submission_routes
node_submission_routes -->|"dispatches"| node_submission_controller
node_submission_controller -->|"creates submission"| node_execution_service
node_execution_service -->|"persists payload"| node_submission_model
node_execution_service -->|"dispatches job"| node_dispatcher
node_dispatcher -->|"queues job"| node_queue_service
node_queue_service -->|"creates queues"| node_queue
node_workers -->|"starts workers"| node_worker
node_workers -->|"starts Java worker"| node_java_worker
node_worker -->|"consumes jobs"| node_queue
node_java_worker -->|"consumes jobs"| node_queue
node_worker -->|"loads and saves"| node_submission_model
node_worker -->|"runs sandbox"| node_docker_runner
node_docker_runner -->|"acquires container"| node_container_manager
node_container_manager -->|"manages containers"| node_docker
node_container_manager -->|"tracks pool"| node_redis
node_worker -.->|"posts results"| node_callback
node_submission_controller -->|"reads results"| node_submission_model
node_server -->|"mounts routes"| node_runtime_routes
node_runtime_routes -->|"dispatches"| node_runtime_controller
node_runtime_controller -->|"reads runtime state"| node_runtime_model
node_runtime_controller -->|"requests upgrade"| node_runtime_service
node_runtime_service -->|"updates runtime state"| node_runtime_model
node_runtime_service -->|"checks pool"| node_container_manager
node_runtime_service -->|"builds runtime image"| node_docker
node_server -->|"mounts routes"| node_admin_routes
node_admin_routes -->|"dispatches"| node_admin_controller
node_admin_controller -->|"delegates operations"| node_admin_service
node_admin_service -->|"reads queue metrics"| node_queue_service
node_admin_service -->|"reads pool metrics"| node_container_manager
node_admin_service -->|"aggregates submissions"| node_submission_model
node_admin_service -->|"builds runtimes"| node_runtime_service
node_admin_service -->|"registers language"| node_language_config
node_admin_service -->|"records runtime"| node_runtime_model
node_admin_service -->|"registers language"| node_language_registry
node_admin_service -->|"creates language queue"| node_queue
node_admin_service -->|"notifies workers"| node_redis
node_workers -->|"restores registrations"| node_redis
node_scaler -->|"checks idleness"| node_queue
node_scaler -->|"scales down pool"| node_container_manager
node_submission_model -->|"stores submissions"| node_mongo
node_runtime_model -->|"stores runtime state"| node_mongo
node_language_config -->|"stores language config"| node_mongo

click node_server "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/server.js"
click node_submission_routes "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/submission.routes.js"
click node_submission_controller "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/submission.controller.js"
click node_execution_service "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/execution.service.js"
click node_dispatcher "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/dispatcher/submissionDispatcher.js"
click node_queue_service "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/queue.service.js"
click node_queue "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/queues/queue.js"
click node_workers "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/launchWorkers.js"
click node_worker "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/generic.worker.js"
click node_java_worker "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/java.worker.js"
click node_docker_runner "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/sandbox/dockerRunner.js"
click node_container_manager "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/sandbox/containerManager.js"
click node_submission_model "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/Submission.js"
click node_runtime_routes "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/runtime.routes.js"
click node_runtime_controller "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/runtime.controller.js"
click node_runtime_service "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/runtime.service.js"
click node_runtime_model "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/Runtime.js"
click node_admin_routes "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/admin.routes.js"
click node_admin_controller "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/admin.controller.js"
click node_admin_service "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/admin.service.js"
click node_language_registry "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/utils/languageRegistry.js"
click node_language_config "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/LanguageConfig.js"
click node_scaler "https://github.com/venugopalreddy787/jurge-engine/blob/main/src/autoscaling/workerScaler.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_submission_routes,node_submission_controller,node_client toneBlue
class node_execution_service,node_dispatcher,node_queue_service,node_workers,node_worker,node_java_worker,node_docker_runner,node_container_manager,node_redis,node_mongo toneAmber
class node_runtime_routes,node_runtime_controller,node_runtime_service,node_admin_routes,node_admin_controller,node_admin_service,node_language_registry,node_scaler toneMint
class node_queue,node_submission_model,node_runtime_model,node_language_config toneRose
class node_docker,node_callback toneIndigo
```

## Components

### API and submissions

- [HTTP server](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/server.js): `src/server.js`
- [Submission routes](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/submission.routes.js): `src/routes/submission.routes.js`
- [Submission controller](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/submission.controller.js): `src/controllers/submission.controller.js`

### Execution pipeline

- [Execution service](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/execution.service.js): `src/services/execution.service.js`
- [Submission dispatcher](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/dispatcher/submissionDispatcher.js): `src/dispatcher/submissionDispatcher.js`
- [Queue service](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/queue.service.js): `src/services/queue.service.js`
- [Worker launcher](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/launchWorkers.js): `src/workers/launchWorkers.js`
- [Language worker](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/generic.worker.js): `src/workers/generic.worker.js`
- [Java worker](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/workers/java.worker.js): `src/workers/java.worker.js`
- [Sandbox runner](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/sandbox/dockerRunner.js): `src/sandbox/dockerRunner.js`
- [Container pool](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/sandbox/containerManager.js): `src/sandbox/containerManager.js`

### Runtime operations

- [Runtime routes](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/runtime.routes.js): `src/routes/runtime.routes.js`
- [Runtime controller](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/runtime.controller.js): `src/controllers/runtime.controller.js`
- [Runtime service](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/runtime.service.js): `src/services/runtime.service.js`
- [Admin routes](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/routes/admin.routes.js): `src/routes/admin.routes.js`
- [Admin controller](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/controllers/admin.controller.js): `src/controllers/admin.controller.js`
- [Admin service](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/services/admin.service.js): `src/services/admin.service.js`
- [Language registry](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/utils/languageRegistry.js): `src/utils/languageRegistry.js`
- [Pool autoscaler](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/autoscaling/workerScaler.js): `src/autoscaling/workerScaler.js`

### State and infrastructure

- [BullMQ queues](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/queues/queue.js): `src/queues/queue.js`
- [Submission records](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/Submission.js): `src/models/Submission.js`
- [Runtime records](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/Runtime.js): `src/models/Runtime.js`
- [Language configuration](https://github.com/venugopalreddy787/jurge-engine/blob/main/src/models/LanguageConfig.js): `src/models/LanguageConfig.js`

### Other components

- **API client**
- **Docker**
- **Callback endpoint**
- **Redis**
- **MongoDB**

## Connections

- API client → HTTP server: sends requests
- HTTP server → Submission routes: mounts routes
- Submission routes → Submission controller: dispatches
- Submission controller → Execution service: creates submission
- Execution service → Submission records: persists payload
- Execution service → Submission dispatcher: dispatches job
- Submission dispatcher → Queue service: queues job
- Queue service → BullMQ queues: creates queues
- Worker launcher → Language worker: starts workers
- Worker launcher → Java worker: starts Java worker
- Language worker → BullMQ queues: consumes jobs
- Java worker → BullMQ queues: consumes jobs
- Language worker → Submission records: loads and saves
- Language worker → Sandbox runner: runs sandbox
- Sandbox runner → Container pool: acquires container
- Container pool → Docker: manages containers
- Container pool → Redis: tracks pool
- Language worker → Callback endpoint: posts results
- Submission controller → Submission records: reads results
- HTTP server → Runtime routes: mounts routes
- Runtime routes → Runtime controller: dispatches
- Runtime controller → Runtime records: reads runtime state
- Runtime controller → Runtime service: requests upgrade
- Runtime service → Runtime records: updates runtime state
- Runtime service → Container pool: checks pool
- Runtime service → Docker: builds runtime image
- HTTP server → Admin routes: mounts routes
- Admin routes → Admin controller: dispatches
- Admin controller → Admin service: delegates operations
- Admin service → Queue service: reads queue metrics
- Admin service → Container pool: reads pool metrics
- Admin service → Submission records: aggregates submissions
- Admin service → Runtime service: builds runtimes
- Admin service → Language configuration: registers language
- Admin service → Runtime records: records runtime
- Admin service → Language registry: registers language
- Admin service → BullMQ queues: creates language queue
- Admin service → Redis: notifies workers
- Worker launcher → Redis: restores registrations
- Pool autoscaler → BullMQ queues: checks idleness
- Pool autoscaler → Container pool: scales down pool
- Submission records → MongoDB: stores submissions
- Runtime records → MongoDB: stores runtime state
- Language configuration → MongoDB: stores language config