# thesouldev/goboxd architecture

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

- Interactive diagram: https://gitdiagram.com/thesouldev/goboxd
- Repository: https://github.com/thesouldev/goboxd

## Overview

goboxd is documented as an HTTP service that compiles and runs untrusted code in isolated sandboxes and returns results, optionally checking supplied test cases. The README also describes a YAML-driven language registry, queued bounded concurrency, per-request limits, and liveness/readiness probes. The supplied tree contains no implementation files beyond placeholders, so component paths use the documented entry-point directory or the enclosing internal directory; relationships not established by the README are omitted or marked unverified.

Main entry points: [`cmd/goboxd`](https://github.com/thesouldev/goboxd/tree/master/cmd/goboxd) (HTTP service), [`internal`](https://github.com/thesouldev/goboxd/tree/master/internal) (Isolated sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP service"]
  node_service["HTTP service"]
  node_result["Execution result"]
end

subgraph group_execution["Code execution"]
  node_registry["Language registry"]
  node_compiler["Compile and run"]
  node_testcases["Optional test cases"]
end

subgraph group_safety["Isolation and limits"]
  node_sandbox["Isolated sandbox"]
  node_process_isolation["Namespaces and cgroups"]
  node_resource_limits["Request limits"]
end

subgraph group_operations["Service operations"]
  node_concurrency["Bounded concurrency"]
  node_probes["Liveness and readiness"]
end

node_caller(("HTTP caller"))

node_caller -->|"submits code"| node_service
node_service -->|"executes within"| node_sandbox
node_service -->|"returns result"| node_result
node_service -.->|"uses languages"| node_registry
node_service -->|"compiles and runs"| node_compiler
node_service -->|"checks optionally"| node_testcases
node_sandbox -->|"isolated by"| node_process_isolation
node_service -.->|"applies per request"| node_resource_limits
node_service -.->|"queues requests"| node_concurrency
node_service -.->|"exposes"| node_probes

click node_service "https://github.com/thesouldev/goboxd/tree/master/cmd/goboxd"
click node_result "https://github.com/thesouldev/goboxd/tree/master/cmd/goboxd"
click node_registry "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_compiler "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_testcases "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_sandbox "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_process_isolation "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_resource_limits "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_concurrency "https://github.com/thesouldev/goboxd/tree/master/internal"
click node_probes "https://github.com/thesouldev/goboxd/tree/master/internal"

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_service,node_result toneBlue
class node_registry,node_compiler,node_testcases toneAmber
class node_sandbox,node_process_isolation,node_resource_limits toneMint
class node_concurrency,node_probes toneRose
class node_caller toneIndigo
```

## Components

### HTTP service

- [HTTP service](https://github.com/thesouldev/goboxd/tree/master/cmd/goboxd): `cmd/goboxd`
- [Execution result](https://github.com/thesouldev/goboxd/tree/master/cmd/goboxd): `cmd/goboxd`

### Code execution

- [Language registry](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`
- [Compile and run](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`
- [Optional test cases](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`

### Isolation and limits

- [Isolated sandbox](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`
- [Namespaces and cgroups](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`
- [Request limits](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`

### Service operations

- [Bounded concurrency](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`
- [Liveness and readiness](https://github.com/thesouldev/goboxd/tree/master/internal): `internal`

### Other components

- **HTTP caller**

## Connections

- HTTP caller → HTTP service: submits code (evidence: `README.md`)
- HTTP service → Isolated sandbox: executes within (evidence: `README.md`)
- HTTP service → Execution result: returns result (evidence: `README.md`)
- HTTP service → Language registry: uses languages
- HTTP service → Compile and run: compiles and runs (evidence: `README.md`)
- HTTP service → Optional test cases: checks optionally (evidence: `README.md`)
- Isolated sandbox → Namespaces and cgroups: isolated by (evidence: `README.md`)
- HTTP service → Request limits: applies per request
- HTTP service → Bounded concurrency: queues requests
- HTTP service → Liveness and readiness: exposes
