# christophetd/code-execution-api-demo architecture

> Architecture diagram of the GitHub repository christophetd/code-execution-api-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/christophetd/code-execution-api-demo
- Repository: https://github.com/christophetd/code-execution-api-demo

## Overview

##### Project type and purpose
- This is a small full-stack sample application exposing a “compile and run Python code” API and a static front-end that drives it.
- The back-end is a Node.js/Express service (in the `api/` folder) that uses the Docker Python Sandbox library to spin up ephemeral Docker containers for code execution.
- The front-end (in `www/`) is a static HTML+JS UI (uses CodeMirror and jQuery) served by the same Node process.

##### File structure
- Top-level:
- `api/` – contains `app.js` (Express app), `handler.js` (business logic), `config.js.sample`, and a set of middleware modules (rate limiter, IP whitelist, API key check, logger, favicon ignore).
- `www/` – static assets (HTML, CSS, JS) for the in-browser code editor and UI.
- `package.json` – Node dependencies (Express, Docker Sandbox lib, PM2).
- `pm2.json` – PM2 process definition.
- No database folders; the primary external dependency is Docker (the Docker daemon/socket).

##### Key components
a. Front-end client (browser)
– Loads static files from `www/index.html`.
– Shows a CodeMirror editor (via `codemirror.js`, `python.js`).
– Issues HTTP POST `compile` requests with JSON payload.
b. API server (Node.js/Express)
– Entry point: `api/app.js`.
– Middleware chain:
- `favicoIgnoreMiddleware` (ignore favicon requests)
- `loggerMiddleware` (log incoming requests)
- `rateLimiterMiddleware` (throttle traffic)
- `ipWhiteListMiddleware` (restrict by IP)
- `securityKeyMiddleware` (enforce X-API-Key)
– Handler: `api/handler.js` parses `{ code }`, invokes Docker Sandbox library.
– Configuration: `api/config.js` controls port, API key, rate limits, whitelisted IPs.
– Process managed by PM2 (`pm2.json`) or `npm start`.
c. Docker Python Sandbox library
– A Node wrapper around Docker Engine.
– Connects over `/var/run/docker.sock`.
– Spins up a fresh Python container per request, runs code, captures stdout/stderr.
d. Docker Engine (daemon)
– Underlying service that runs containers.
e. Optional external backend / client
– In production you’d likely have a private network where only your backend service (not the public internet) can call this API.

##### Relationships and data flow
1. Browser → HTTP(S) POST `/compile` on API
2. Express middleware authenticates, logs, rate-limits, etc.
3. Handler calls Docker Sandbox library → Docker daemon → new Python container
4. Container executes code → returns stdout/stderr
5. Handler formats response JSON → Express sends it back → Browser displays result

##### Architectural patterns and design principles
- Layered/middleware pattern in Express for separation of concerns (security, logging, rate-limiting).
- Stateless API: each request is independent; containers are ephemeral.
- Single-page/static front-end served by same HTTP server (no separate web server).
- Process management and zero-downtime restarts via PM2.
- Security best practices: API key, IP whitelist, rate limiting, private network.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Front-End Layer
    subgraph "Front-End (Browser)" 
        direction TB
        BrowserUI["Browser UI"]:::client
        CodeMirrorJS["codemirror.js"]:::client
        PythonModeJS["python.js"]:::client
        CodeMirrorCSS["codemirror.css"]:::client
        NeoCSS["neo.css"]:::client
        JQueryJS["jquery.js"]:::client
        BrowserUI -->|"loads assets"| CodeMirrorJS
        BrowserUI --> CodeMirrorCSS
        BrowserUI --> PythonModeJS
        BrowserUI --> NeoCSS
        BrowserUI --> JQueryJS
    end

    %% Server Layer
    subgraph "Server Side (Node/Express)" 
        direction TB
        ExpressApp["Express App"]:::server
        PM2["PM2"]:::pm2
        ExpressApp --> PM2
        subgraph "Middleware Layer" 
            direction TB
            MiddlewaresIndex["middlewares/index.js"]:::server
            FavIcon["favicoIgnoreMiddleware"]:::server
            Logger["loggerMiddleware"]:::server
            RateLimiter["rateLimiterMiddleware"]:::server
            IPWhitelist["ipWhiteListMiddleware"]:::server
            SecurityKey["securityKeyMiddleware"]:::server
            MiddlewaresIndex --> FavIcon
            MiddlewaresIndex --> Logger
            MiddlewaresIndex --> RateLimiter
            MiddlewaresIndex --> IPWhitelist
            MiddlewaresIndex --> SecurityKey
        end
        Handler["Handler"]:::server

        ExpressApp -->|"use middlewares"| MiddlewaresIndex
        MiddlewaresIndex -->|"after checks"| Handler
    end

    %% Execution Layer
    subgraph "Execution Pipeline"
        direction TB
        SandboxLib["Docker Python Sandbox Lib"]:::containerLayer
        DockerDaemon["Docker Daemon"]:::infra
        PythonContainer["Python Container"]:::containerLayer
        Handler --> SandboxLib
        SandboxLib --> DockerDaemon
        DockerDaemon --> PythonContainer
        PythonContainer -->|"stdout/stderr"| Handler
    end

    %% Data Flow
    BrowserUI -->|"POST /compile"| ExpressApp
    Handler -->|"response JSON"| ExpressApp
    ExpressApp -->|"returns result"| BrowserUI

    %% Optional External
    PrivateNetwork["Private Network / Firewall"]:::infra
    PrivateNetwork --> ExpressApp

    %% Click Events
    click BrowserUI "https://github.com/christophetd/code-execution-api-demo/blob/master/www/index.html"
    click CodeMirrorJS "https://github.com/christophetd/code-execution-api-demo/blob/master/www/codemirror.js"
    click PythonModeJS "https://github.com/christophetd/code-execution-api-demo/blob/master/www/python.js"
    click CodeMirrorCSS "https://github.com/christophetd/code-execution-api-demo/blob/master/www/codemirror.css"
    click NeoCSS "https://github.com/christophetd/code-execution-api-demo/blob/master/www/neo.css"
    click JQueryJS "https://github.com/christophetd/code-execution-api-demo/blob/master/www/jquery.js"
    click ExpressApp "https://github.com/christophetd/code-execution-api-demo/blob/master/api/app.js"
    click MiddlewaresIndex "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/index.js"
    click FavIcon "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/favicoIgnoreMiddleware.js"
    click Logger "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/loggerMiddleware.js"
    click RateLimiter "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/rateLimiterMiddleware.js"
    click IPWhitelist "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/ipWhiteListMiddleware.js"
    click SecurityKey "https://github.com/christophetd/code-execution-api-demo/blob/master/api/middlewares/securityKeyMiddleware.js"
    click Handler "https://github.com/christophetd/code-execution-api-demo/blob/master/api/handler.js"
    click PM2 "https://github.com/christophetd/code-execution-api-demo/blob/master/pm2.json"
    click Config "https://github.com/christophetd/code-execution-api-demo/blob/master/api/config.js.sample"

    %% Styles
    classDef client fill:#ADCFFF,stroke:#0366d6,color:#000;
    classDef server fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef containerLayer fill:#FFD59E,stroke:#FF8F00,color:#000;
    classDef infra fill:#E0E0E0,stroke:#9E9E9E,color:#000;
    classDef pm2 fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
