A high-performance, fault-tolerant distributed system for secure code compilation and execution.
Engineered for massive horizontal scalability, strictly isolating the API ingestion layer from the heavy-compute execution environment.
| 🛡️ Ephemeral Sandboxing Untrusted code is executed inside strictly isolated, network-disabled Docker containers with hard limits on memory and CPU. |
🌊 Asynchronous Queuing API requests are never blocked. Submissions are pushed to a Redis-backed BullMQ cluster for guaranteed delivery and retry mechanisms. |
| 📡 Real-Time Telemetry Execution metrics, stdout, and stderr are streamed instantly to the client via WebSockets and Redis Pub/Sub without long-polling. |
🚀 Horizontal Scalability Worker nodes operate independently. Need more compute? Simply spin up more worker instances to drain the queue faster. |
DCEP utilizes a microservice architecture to separate the ingestion pipeline from the compute-heavy execution workers.
graph LR
%% Colors and Styles
classDef client fill:#1E293B,stroke:#334155,stroke-width:2px,color:#fff;
classDef gateway fill:#0284C7,stroke:#0369A1,stroke-width:2px,color:#fff;
classDef broker fill:#DC2626,stroke:#991B1B,stroke-width:2px,color:#fff;
classDef compute fill:#10B981,stroke:#047857,stroke-width:2px,color:#fff;
%% Nodes
Client[("💻 React UI")]:::client
API["🌐 API Gateway<br>(Express)"]:::gateway
WS["⚡ WebSocket Hub<br>(Socket.io)"]:::gateway
Queue[("📋 BullMQ<br>(Redis)")]:::broker
PubSub(("📻 Pub/Sub<br>(Redis)")):::broker
Worker["⚙️ Node.js Worker"]:::compute
Docker{"🐳 Docker<br>Sandbox"}:::compute
%% Edges
Client -- "1. POST Code" --> API
API -- "2. Enqueue Job" --> Queue
Client -. "3. Listen" .- WS
Queue -- "4. Pull Job" --> Worker
Worker -- "5. Spawn" --> Docker
Worker -- "6. Broadcast" --> PubSub
PubSub -- "7. Forward" --> WS
Click to expand: How the Execution Engine works
- Ingestion & Rate Limiting: The Gateway receives a payload containing the source code and target language. It validates the request and applies strict IP/API-Key rate limiting to prevent DDoS.
- Message Broker (BullMQ): The job is serialized and pushed to a Redis queue. The Gateway responds immediately with a HTTP 201 and a
jobId. - Worker Processing: An idle worker picks up the job. It utilizes
Dockerodeto dynamically provision an ephemeral Docker container. - Execution & Resource Quotas: The container is booted with no external network access, a strict timeout (e.g., 3 seconds), and memory limits. The standard output (stdout) and error (stderr) are captured via streams.
- Pub/Sub Telemetry: Upon completion or timeout, the worker publishes the execution payload (exit code, logs, execution time) to a Redis Pub/Sub channel.
- WebSocket Bridge: The API Gateway, listening to the Pub/Sub channel, intercepts the message and routes it via
Socket.iodirectly to the specific client observing thatjobId.
- Node.js (v18+)
- Docker Desktop (Engine must be running)
- Redis (Running locally on port 6379)
git clone [https://github.com/yourusername/distributed-code-execution.git](https://github.com/yourusername/distributed-code-execution.git)
cd distributed-code-execution
# Install microservice dependencies
npm install
cd frontend && npm install && cd ..
# Setup Environment
cp .env.example .envTo replicate the distributed environment locally, run these components in separate terminals:
Terminal 1 (The Gateway):
npm run dev:serverTerminal 2 (The Compute Node):
npm run dev:workerTerminal 3 (The Command Center UI):
cd frontend && npm run devThis project is actively evolving from a robust Proof-of-Concept into a production-grade enterprise system.
- Asynchronous Job Queuing (BullMQ)
- Ephemeral Docker Sandboxing (Dockerode)
- Real-time WebSocket Telemetry (Socket.io + Redis Pub/Sub)
- DevOps Command Center UI (React/Vite/Tailwind)
- Strict Input Validation: Integrating
Zodfor deterministic payload validation. - API Documentation: Implementing
Swagger UI/ OpenAPI specifications. - Infrastructure Health: Exposing
/healthendpoints for Kubernetes readiness/liveness probes.
- Testing: Full coverage using
JestandSupertestwith mocked Redis/Docker boundaries. - Orchestration: Unified
docker-compose.ymlfor single-click cluster booting. - CI/CD: GitHub Actions pipeline for automated linting, testing, and Docker image builds.
- Structured Logging: Migrating from standard console outputs to JSON-structured
Pinologs. - Metrics: Tracking queue latency and execution times (Prometheus/Grafana ready).
Architected and engineered by Aryan Mishra.