# sangammishra9557/coding-compiler architecture

> Architecture diagram of the GitHub repository sangammishra9557/coding-compiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sangammishra9557/coding-compiler
- Repository: https://github.com/sangammishra9557/coding-compiler

## Overview

1. **Overall shape**
   - This is a NestJS monorepo with three deployable applications: `api-gateway`, `backend-engine`, and `cron-scheduler`.
   - Shared infrastructure code lives in `libs/common`, and persistence/schema lives under `prisma`.

2. **External API boundary: `apps/api-gateway`**
   - `api-gateway` is the public-facing HTTP layer described in the README.
   - It exposes the `/submit` and `/status/:submission_id` endpoints and translates HTTP requests into internal application workflows.
   - The module layout suggests one controller/service pair per API area: `submission` and `status`.

3. **Submission request flow**
   - A client sends base64-encoded source code and input array to `POST /submit`.
   - The gateway likely validates/transforms the request using helpers in `submission/utils`, then forwards it into the backend workflow through shared messaging or service calls.
   - The response contract centers on a generated `submission_id` plus timestamps and submission state.

4. **Status query flow**
   - `GET /status/:submission_id` is served by the gateway and returns the current state of a submission.
   - The response includes both orchestration-level state (`CREATED`, `IN_PROCESS`, `SUCCESS`, `RETRY`, `FAILURE`) and execution-level details such as compilation errors, per-input execution status, output, and metadata.

5. **Execution boundary: `apps/backend-engine`**
   - `backend-engine` is the worker/orchestration service responsible for code execution.
   - Its helpers indicate the core runtime responsibilities: creating directories, selecting language-specific scripts, interacting with Docker, and encoding/decoding payloads.
   - This service is the boundary where submitted code becomes an actual isolated execution.

6. **Execution model**
   - The presence of `docker-service.helper.ts` strongly suggests sandboxed execution inside containers rather than in-process execution.
   - Language-specific support is abstracted via `language-script.helper.ts`, which likely maps a requested language to compile/run commands.
   - `successExecutionData.ts`, `submission-status.ts`, and base64 helpers point to structured execution result handling and status transitions.

7. **Persistence and state**
   - `prisma/schema.prisma` indicates a relational datastore for submissions and execution metadata.
   - The API surface implies durable storage of submission records, per-run status, outputs, compilation errors, and modification timestamps.
   - `libs/common/src/database` provides a shared database module/service used by one or more apps.

8. **Messaging and async coordination**
   - `libs/common/src/rmq` and `rabbitmq.constants.ts` show RabbitMQ as the likely asynchronous integration layer.
   - This is the most probable handoff mechanism between the gateway and backend-engine, allowing submission creation to be decoupled from execution.
   - The architecture is therefore event/job-driven rather than a single synchronous request-response path.

9. **Caching / ephemeral coordination**
   - `libs/common/src/redis` indicates Redis is part of the system, likely for transient state, locking, rate-limiting, job tracking, or fast status reads.
   - Even without implementation details, its placement in shared libs suggests it supports cross-service coordination rather than domain logic.

10. **Operational utilities**
   - `libs/common/src/logger` centralizes logging across applications, which is important for tracing submission lifecycle across gateway and worker boundaries.
   - `libs/common/src/constants` collects cross-service values, especially queue/routing names and other shared identifiers.

11. **Scheduler component**
   - `apps/cron-scheduler` is a separate NestJS app, implying periodic background tasks.
   - In this kind of architecture, it typically drives cleanup, retries, stale-job handling, or maintenance, though its exact tasks are not shown in the tree.

12. **Deployment/runtime characteristics**
   - The repo includes `docker-compose.yml`, `pm2.config.js`, and built output in `dist/`, showing it is intended for containerized and process-managed deployment.
   - `backend-engine` also depends on Docker at runtime for isolation, which is a key architectural constraint for diagramming.

13. **Data format conventions**
   - Source code and program inputs/outputs are base64-encoded at the API boundary.
   - That encoding boundary is important: the gateway accepts encoded payloads, while the backend engine likely decodes them for execution and re-encodes results for storage/transport.

14. **Key diagram boundaries**
   - Draw the system as three main zones: client-facing gateway, async execution worker, and scheduled maintenance worker.
   - Put RabbitMQ between gateway and backend-engine, Prisma-backed storage behind both, Redis as shared fast-state infrastructure, and Docker as the execution sandbox around the backend-engine’s code runner.

Main entry points: [`apps/backend-engine/src/backend-engine.service.ts`](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/backend-engine.service.ts) (Engine service), [`apps/api-gateway/src/submission/submission.service.ts`](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/submission/submission.service.ts) (Submit flow), [`apps/cron-scheduler/src/cron-scheduler.module.ts`](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/cron-scheduler/src/cron-scheduler.module.ts) (Scheduler module), [`libs/common/src/database/database.module.ts`](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/database/database.module.ts) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_gateway["API Gateway"]
  node_node_gateway_app["API app<br/>NestJS app<br/>[main.ts]"]
  node_node_gateway_module["Gateway module<br/>Nest module"]
  node_node_submission_controller["Submit API<br/>HTTP controller"]
  node_node_submission_service["Submit flow"]
  node_node_status_controller["Status API<br/>HTTP controller"]
  node_node_status_service["Status lookup<br/>[status.service.ts]"]
  node_node_gateway_utils["Request utils<br/>helpers"]
end

subgraph group_group_worker["Backend Engine"]
  node_node_worker_app["Worker app<br/>NestJS app<br/>[main.ts]"]
  node_node_worker_module["Engine module<br/>Nest module"]
  node_node_worker_service["Engine service<br/>orchestrator"]
  node_node_docker_helper{{"Docker runner<br/>execution helper"}}
  node_node_lang_helper["Language scripts<br/>execution helper"]
  node_node_dir_helper["Workspace prep<br/>filesystem helper"]
  node_node_status_model["Exec states<br/>result model"]
end

subgraph group_group_shared["Shared Infrastructure"]
  node_node_common_db["Database<br/>shared module<br/>[database.module.ts]"]
  node_node_common_rmq["RabbitMQ<br/>message bus<br/>[rmq.module.ts]"]
  node_node_common_redis["Redis<br/>cache module<br/>[redis.module.ts]"]
  node_node_common_logger["Logger<br/>shared service<br/>[logger.module.ts]"]
  node_node_common_constants["Constants<br/>shared config"]
  node_node_prisma["Prisma schema<br/>[schema.prisma]"]
end

subgraph group_group_ops["Scheduler"]
  node_node_scheduler_app["Cron app<br/>NestJS app<br/>[main.ts]"]
  node_node_scheduler_module["Scheduler module<br/>Nest module"]
end

node_node_gateway_app -->|"starts"| node_node_gateway_module
node_node_gateway_module -->|"exposes"| node_node_submission_controller
node_node_gateway_module -->|"exposes"| node_node_status_controller
node_node_submission_controller -->|"calls"| node_node_submission_service
node_node_status_controller -->|"calls"| node_node_status_service
node_node_submission_service -->|"transforms"| node_node_gateway_utils
node_node_submission_service -->|"publishes"| node_node_common_rmq
node_node_status_service -->|"reads"| node_node_common_db
node_node_status_service -->|"reads"| node_node_common_redis
node_node_submission_service -->|"writes"| node_node_common_db
node_node_submission_service -->|"uses"| node_node_common_constants
node_node_worker_app -->|"starts"| node_node_worker_module
node_node_worker_module -->|"wires"| node_node_worker_service
node_node_worker_service -->|"consumes"| node_node_common_rmq
node_node_worker_service -->|"runs in"| node_node_docker_helper
node_node_worker_service -->|"selects"| node_node_lang_helper
node_node_worker_service -->|"prepares"| node_node_dir_helper
node_node_worker_service -->|"formats"| node_node_status_model
node_node_worker_service -->|"updates"| node_node_common_db
node_node_worker_service -->|"touches"| node_node_common_redis
node_node_worker_service -->|"logs"| node_node_common_logger
node_node_worker_service -->|"uses"| node_node_common_constants
node_node_worker_service -.->|"persists via"| node_node_prisma
node_node_scheduler_app -->|"starts"| node_node_scheduler_module
node_node_scheduler_module -->|"maintains"| node_node_common_db
node_node_scheduler_module -.->|"coordinates"| node_node_common_rmq
node_node_scheduler_module -->|"logs"| node_node_common_logger

click node_node_gateway_app "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/main.ts"
click node_node_gateway_module "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/api-gateway.module.ts"
click node_node_submission_controller "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/submission/submission.controller.ts"
click node_node_submission_service "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/submission/submission.service.ts"
click node_node_status_controller "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/status/status.controller.ts"
click node_node_status_service "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/status/status.service.ts"
click node_node_gateway_utils "https://github.com/sangammishra9557/coding-compiler/tree/main/apps/api-gateway/src/submission/utils"
click node_node_worker_app "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/main.ts"
click node_node_worker_module "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/backend-engine.module.ts"
click node_node_worker_service "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/backend-engine.service.ts"
click node_node_docker_helper "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/docker-service.helper.ts"
click node_node_lang_helper "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/language-script.helper.ts"
click node_node_dir_helper "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/directory-manager.helper.ts"
click node_node_status_model "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/functions/submission-status.ts"
click node_node_common_db "https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/database/database.module.ts"
click node_node_common_rmq "https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/rmq/rmq.module.ts"
click node_node_common_redis "https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/redis/redis.module.ts"
click node_node_common_logger "https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/logger/logger.module.ts"
click node_node_common_constants "https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/constants/rabbitmq.constants.ts"
click node_node_prisma "https://github.com/sangammishra9557/coding-compiler/blob/main/prisma/schema.prisma"
click node_node_scheduler_app "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/cron-scheduler/src/main.ts"
click node_node_scheduler_module "https://github.com/sangammishra9557/coding-compiler/blob/main/apps/cron-scheduler/src/cron-scheduler.module.ts"

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_node_gateway_app,node_node_gateway_module,node_node_submission_controller,node_node_submission_service,node_node_status_controller,node_node_status_service,node_node_gateway_utils toneBlue
class node_node_worker_app,node_node_worker_module,node_node_worker_service,node_node_docker_helper,node_node_lang_helper,node_node_dir_helper,node_node_status_model toneAmber
class node_node_common_db,node_node_common_rmq,node_node_common_redis,node_node_common_logger,node_node_common_constants,node_node_prisma toneMint
class node_node_scheduler_app,node_node_scheduler_module toneRose
```

## Components

### API Gateway

Public HTTP boundary for submission creation and status queries.

- [API app](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/main.ts): NestJS app · Bootstraps the public-facing HTTP gateway. · `apps/api-gateway/src/main.ts`
- [Gateway module](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/api-gateway.module.ts): Nest module · Wires submission and status features into the gateway. · `apps/api-gateway/src/api-gateway.module.ts`
- [Submit API](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/submission/submission.controller.ts): HTTP controller · Handles POST /submit requests. · `apps/api-gateway/src/submission/submission.controller.ts`
- [Submit flow](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/submission/submission.service.ts): service · Validates and forwards submission requests. · `apps/api-gateway/src/submission/submission.service.ts`
- [Status API](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/status/status.controller.ts): HTTP controller · Handles GET /status/:submission_id requests. · `apps/api-gateway/src/status/status.controller.ts`
- [Status lookup](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/api-gateway/src/status/status.service.ts): service · Retrieves and shapes submission state for clients. · `apps/api-gateway/src/status/status.service.ts`
- [Request utils](https://github.com/sangammishra9557/coding-compiler/tree/main/apps/api-gateway/src/submission/utils): helpers · Transforms submission payloads and responses, including base64-oriented request handling. · `apps/api-gateway/src/submission/utils`

### Backend Engine

Async execution and orchestration service for running submitted code.

- [Worker app](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/main.ts): NestJS app · Bootstraps the backend execution service. · `apps/backend-engine/src/main.ts`
- [Engine module](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/backend-engine.module.ts): Nest module · Connects execution controller and worker logic. · `apps/backend-engine/src/backend-engine.module.ts`
- [Engine service](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/backend-engine.service.ts): orchestrator · Coordinates submission processing and execution lifecycle. · `apps/backend-engine/src/backend-engine.service.ts`
- [Docker runner](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/docker-service.helper.ts): execution helper · Runs submitted code in isolated containers. · `apps/backend-engine/src/helpers/docker-service.helper.ts`
- [Language scripts](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/language-script.helper.ts): execution helper · Maps languages to compile and run commands. · `apps/backend-engine/src/helpers/language-script.helper.ts`
- [Workspace prep](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/helpers/directory-manager.helper.ts): filesystem helper · Creates and manages per-run directories. · `apps/backend-engine/src/helpers/directory-manager.helper.ts`
- [Exec states](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/backend-engine/src/functions/submission-status.ts): result model · Defines submission status and success payload shaping. · `apps/backend-engine/src/functions/submission-status.ts`

### Shared Infrastructure

Common modules for persistence, messaging, logging, and cache coordination.

- [Database](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/database/database.module.ts): shared module · Shared database integration used for persistent submission records. · `libs/common/src/database/database.module.ts`
- [RabbitMQ](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/rmq/rmq.module.ts): message bus · Shared async messaging layer for gateway-to-worker coordination. · `libs/common/src/rmq/rmq.module.ts`
- [Redis](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/redis/redis.module.ts): cache module · Shared fast-state and coordination store. · `libs/common/src/redis/redis.module.ts`
- [Logger](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/logger/logger.module.ts): shared service · Centralized logging across services. · `libs/common/src/logger/logger.module.ts`
- [Constants](https://github.com/sangammishra9557/coding-compiler/blob/main/libs/common/src/constants/rabbitmq.constants.ts): shared config · Cross-service identifiers and queue names. · `libs/common/src/constants/rabbitmq.constants.ts`
- [Prisma schema](https://github.com/sangammishra9557/coding-compiler/blob/main/prisma/schema.prisma): schema · Relational persistence model for submissions and execution metadata. · `prisma/schema.prisma`

### Scheduler

Periodic maintenance and background jobs.

- [Cron app](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/cron-scheduler/src/main.ts): NestJS app · Bootstraps periodic maintenance jobs. · `apps/cron-scheduler/src/main.ts`
- [Scheduler module](https://github.com/sangammishra9557/coding-compiler/blob/main/apps/cron-scheduler/src/cron-scheduler.module.ts): Nest module · Wires the cron scheduler service into the app. · `apps/cron-scheduler/src/cron-scheduler.module.ts`

## Connections

- API app → Gateway module: starts · Application bootstrap loads the gateway module.
- Gateway module → Submit API: exposes · Registers submission endpoints.
- Gateway module → Status API: exposes · Registers status endpoints.
- Submit API → Submit flow: calls · Delegates POST /submit handling.
- Status API → Status lookup: calls · Delegates submission status reads.
- Submit flow → Request utils: transforms · Uses request and response helpers for encoded payloads.
- Submit flow → RabbitMQ: publishes · Hands work off to the async backend pipeline.
- Status lookup → Database: reads · Looks up durable submission state.
- Status lookup → Redis: reads · Uses fast state when available.
- Submit flow → Database: writes · Stores submission records and metadata.
- Submit flow → Constants: uses · Relies on shared routing and queue identifiers.
- Worker app → Engine module: starts · Application bootstrap loads the worker module.
- Engine module → Engine service: wires · Registers orchestration and execution logic.
- Engine service → RabbitMQ: consumes · Receives queued submission jobs.
- Engine service → Docker runner: runs in · Executes submitted code inside containers.
- Engine service → Language scripts: selects · Chooses language-specific commands.
- Engine service → Workspace prep: prepares · Creates isolated run workspaces.
- Engine service → Exec states: formats · Builds success and status payloads.
- Engine service → Database: updates · Persists execution outcomes.
- Engine service → Redis: touches · Uses transient coordination or caching.
- Engine service → Logger: logs · Emits lifecycle and execution logs.
- Engine service → Constants: uses · Consumes shared queue and status constants.
- Engine service → Prisma schema: persists via · Backs the worker's state changes with relational storage.
- Cron app → Scheduler module: starts · Application bootstrap loads cron jobs.
- Scheduler module → Database: maintains · Supports cleanup or retry-oriented maintenance against stored state.
- Scheduler module → RabbitMQ: coordinates · May trigger delayed or maintenance work via messaging.
- Scheduler module → Logger: logs · Uses centralized logging.