# denisorehovsky/docker-code-sandbox architecture

> Architecture diagram of the GitHub repository denisorehovsky/docker-code-sandbox, 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/denisorehovsky/docker-code-sandbox
- Repository: https://github.com/denisorehovsky/docker-code-sandbox

## Overview

##### Project type and purpose
- This is an open-source Node.js library (“docker-python-sandbox”) whose sole responsibility is to execute untrusted Python code inside isolated Docker containers.
- It exposes a simple API (via the Sandbox class) so that any Node.js application can spin up a pool of disposable containers, send Python code to them, collect stdout/stderr, and enforce time/memory limits.

##### File structure
- Top‐level:
- container/ – Docker image definition and entrypoint for the “minimalistic API” running inside each sandbox container
- lib/ – core classes (Container, Job, PoolManager, Sandbox) implementing pool management, container lifecycle, code execution orchestration
- scripts/ – helper scripts to build the Docker image and run tests
- test/ – unit and integration tests, mocks for each core class
- package.json, .travis.yml, wallaby.js – build/test configuration
- Patterns:
- PoolManager maintains a fixed‐size pool of Container instances
- Each Container wraps a single Docker container (created, used once, then destroyed)
- Job objects encapsulate one code execution request/response cycle
- Deployment concerns:
- container/Dockerfile and build.sh define the sandbox runtime image
- start.sh in container/ wires up a small HTTP API inside the container

##### README for additional insights
- Core flow:
- initialize(): PoolManager → Docker daemon creates N containers using the pulled image
- run(): pick an idle Container → proxy the code to the container’s HTTP API → await result → destroy that container → replace it
- Security: one-time containers, CPU/memory/time limits, no inter-container comms

##### Diagramming recommendations
- Grey rectangle for Client Application
- Client → Sandbox (initialize/run)
- Sandbox → PoolManager → Docker Engine (create/destroy)
- Container ↔ Docker container (HTTP code execution)
- Container → PoolManager (job completion)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    ClientApp["Client Application"]:::client

    %% External Docker Registry
    DockerRegistry(["Docker Registry"]):::registry

    %% Docker Engine on host
    DockerEngine(["Docker Engine\n(REST API/CLI)"]):::docker

    %% Node.js Library Components
    subgraph "Node.js Library"
        direction TB
        Sandbox["Sandbox\n(public API)"]:::library
        PoolManager["PoolManager"]:::library
        ContainerClass["Container"]:::library
        Job["Job"]:::library
    end

    %% Docker Image Definition
    subgraph "Sandbox Docker Image"
        direction TB
        Dockerfile["Dockerfile"]:::dockerfile
        BuildScript["build.sh"]:::dockerfile
        StartupScript["start.sh"]:::dockerfile
        IndexJS["index.js"]:::dockerfile
        PackageJSON["package.json"]:::dockerfile
    end

    %% Relationships
    ClientApp -->|"initialize()/run()"| Sandbox
    Sandbox -->|"calls"| PoolManager
    PoolManager -->|"docker pull/run/rm"| DockerEngine
    DockerRegistry -->|"pull image"| DockerEngine
    DockerEngine -->|"spawns container"| ContainerClass
    ContainerClass -->|"wraps"| DockerContainer[("Docker Container\n(isolated)")]:::docker
    ContainerClass -->|"HTTP POST /execute"| DockerContainer
    DockerContainer -->|"stdout/stderr"| ContainerClass
    ContainerClass -->|"creates Job instance"| Job
    Job -->|"callback"| PoolManager
    PoolManager -->|"destroy & replace"| DockerEngine

    %% File inclusion in Docker Image
    Dockerfile --> BuildScript
    BuildScript --> StartupScript
    StartupScript --> IndexJS
    StartupScript --> PackageJSON

    %% Click Events for library files
    click Sandbox "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/lib/Sandbox.js"
    click PoolManager "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/lib/PoolManager.js"
    click ContainerClass "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/lib/Container.js"
    click Job "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/lib/Job.js"

    %% Click Events for Docker image files
    click Dockerfile "https://github.com/denisorehovsky/docker-code-sandbox/tree/master/container/Dockerfile"
    click BuildScript "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/container/build.sh"
    click StartupScript "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/container/start.sh"
    click IndexJS "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/container/shared/index.js"
    click PackageJSON "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/container/shared/package.json"

    %% Click Events for tests and scripts
    click TestSandboxMocks "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/helpers/SandboxMocks.js"
    click TestPoolManagerInt "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/integration/pool_manager_spec.js"
    click TestSandboxInt "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/integration/sandbox_spec.js"
    click TestContainerUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/ContainerTest.js"
    click TestJobUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/JobTest.js"
    click TestPoolManagerUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/PoolManagerTest.js"
    click TestSandboxUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/SandboxTest.js"
    click RunTests "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/scripts/run_tests.sh"

    %% Styles
    classDef library fill:#D6EAF8,stroke:#2980B9,stroke-width:2px
    classDef docker fill:#FAD7A0,stroke:#D35400,stroke-width:2px
    classDef registry fill:#A9DFBF,stroke:#27AE60,stroke-width:2px
    classDef client fill:#E5E7E9,stroke:#5D6D7E,stroke-width:2px
    classDef dockerfile fill:#FDEBD0,stroke:#B9770E,stroke-width:1px

    %% Test file nodes (not in main flow)
    subgraph "Test and Scripts"
        direction TB
        TestSandboxMocks["Sandbox Mocks"]:::library
        TestPoolManagerInt["PoolManager Integration"]:::library
        TestSandboxInt["Sandbox Integration"]:::library
        TestContainerUnit["Container Unit"]:::library
        TestJobUnit["Job Unit"]:::library
        TestPoolManagerUnit["PoolManager Unit"]:::library
        TestSandboxUnit["Sandbox Unit"]:::library
        RunTests["run_tests.sh"]:::dockerfile
    end

    %% Test click events
    click TestSandboxMocks "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/helpers/SandboxMocks.js"
    click TestPoolManagerInt "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/integration/pool_manager_spec.js"
    click TestSandboxInt "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/integration/sandbox_spec.js"
    click TestContainerUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/ContainerTest.js"
    click TestJobUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/JobTest.js"
    click TestPoolManagerUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/PoolManagerTest.js"
    click TestSandboxUnit "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/test/unit/lib/SandboxTest.js"
    click RunTests "https://github.com/denisorehovsky/docker-code-sandbox/blob/master/scripts/run_tests.sh"
```
