# swiftfiddle/swiftfiddle-runner architecture

> Architecture diagram of the GitHub repository swiftfiddle/swiftfiddle-runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swiftfiddle/swiftfiddle-runner
- Repository: https://github.com/swiftfiddle/swiftfiddle-runner

## Overview

##### Project Type and Purpose
- This is a backend microservice (“swiftfiddle-runner”) that provides an online sandboxed Swift code execution environment for the SwiftFiddle frontend (swiftfiddle.com).
- It’s implemented in Deno (main.ts, deps.ts), containerized via Docker, and orchestrated locally via docker-compose. CI/CD and deployment are handled through GitHub Actions.

##### File-Structure Analysis
- Top level:
- main.ts, deps.ts, versions.json → Deno entry point + vendored deps
- Dockerfile, docker-compose.yml → container build & local infra
- _Packages/ → vendored TypeScript modules for offline Deno import
- .github/workflows → CI/CD workflows (test, deploy, UDD)
- No DB or persistent store—execution is ephemeral.
- CI: renovate (dependency updates), test.yml (unit/integration), deploy.yml (build & push container).

##### README Insights
- Core function: receive Swift source via HTTP, spin up an isolated Docker sandbox, compile/execute, stream results back.
- No additional architecture notes in README.

a. Main Components
- SwiftFiddle Frontend (Browser UI)
- Runner API Service (Deno server)
- Docker Engine (host’s daemon or remote)
- Swift Sandbox Containers (ephemeral Docker containers with Swift toolchain)
- CI/CD Pipeline (GitHub Actions)
b. Relationships & Data Flow
1. Frontend issues HTTP POST → Runner API
2. Runner calls Docker Engine API → create new Swift sandbox container
3. Docker spins up container (mounts user code, runs `swift run` or `swiftc`)
4. Container streams stdout/stderr → Runner collects and forwards to frontend
5. Container stops and is destroyed
6. CI/CD: on push → GitHub Actions builds Docker image → pushes to registry → deploys new version of Runner service
c. Architectural Patterns & Principles
- Microservice for isolation of code-execution
- Container-based sandboxing for security and reproducibility
- Ephemeral job processing: no long-lived state, each code run is a self-contained task
d. Key Technologies & Frameworks
- Deno (TypeScript runtime)
- Docker & Docker Engine API
- docker-compose (local dev)
- GitHub Actions (CI/CD)
- Vendored modules in `_Packages` for deterministic builds

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External"
        FE["Browser UI (SwiftFiddle Frontend)"]:::external
    end

    subgraph "Compute"
        Runner["Deno Runner Service"]:::compute
    end

    subgraph "Container Orchestrator"
        DockerEngine["Docker Engine API"]:::container
    end

    subgraph "Swift Sandbox Pool"
        Sandbox["Swift Sandbox Container"]:::container
    end

    subgraph "CI/CD Pipeline"
        GHTest["GitHub Actions: Test"]:::ci
        GHDeploy["GitHub Actions: Deploy"]:::ci
        GHUDD["GitHub Actions: UDD"]:::ci
        Renovate["Renovate Bot"]:::ci
    end

    FE -->|HTTP POST /run| Runner
    Runner -->|Docker REST API| DockerEngine
    DockerEngine -->|launch container| Sandbox
    Sandbox -->|stdout/stderr| Runner
    Runner -->|HTTP Response| FE

    GHTest -.->|on push| Runner
    GHDeploy -.->|build & push image| Runner
    GHUDD -.->|UDD triggers| Runner
    Renovate -.->|update deps| deps.ts

    subgraph "Runner Codebase"
        MT["main.ts"]:::code
        DE["deps.ts"]:::code
        VJ["versions.json"]:::code
        PKG["_Packages"]:::vendor
        DF["Dockerfile"]:::infra
        DC["docker-compose.yml"]:::infra
        DAI[".dockerignore"]:::infra
        WFT[".github/workflows/test.yml"]:::ci
        WFD[".github/workflows/deploy.yml"]:::ci
        WFU[".github/workflows/udd.yml"]:::ci
        REN[".github/renovate.json"]:::ci
    end

    Runner -->|entrypoint| MT
    Runner -->|imports deps| DE
    Runner --> VJ
    Runner --> PKG
    Runner --> DF
    Runner --> DC
    Runner --> DAI
    Runner --> WFT
    Runner --> WFD
    Runner --> WFU
    Runner --> REN

    click MT "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/main.ts"
    click DE "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/deps.ts"
    click VJ "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/versions.json"
    click PKG "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/_Packages/Package.swift"
    click DF "https://github.com/swiftfiddle/swiftfiddle-runner/tree/main/Dockerfile"
    click DC "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/docker-compose.yml"
    click DAI "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/.dockerignore"
    click WFT "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/.github/workflows/test.yml"
    click WFD "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/.github/workflows/deploy.yml"
    click WFU "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/.github/workflows/udd.yml"
    click REN "https://github.com/swiftfiddle/swiftfiddle-runner/blob/main/.github/renovate.json"

    classDef compute fill:#D0E8FF,stroke:#0044CC,color:#0044CC
    classDef container fill:#E0FFE0,stroke:#00AA00,color:#006600
    classDef external fill:#FFE0B2,stroke:#FF8800,color:#BB5500
    classDef ci fill:#F3E5F5,stroke:#8E24AA,color:#6A0080
    classDef code fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef vendor fill:#F0F4C3,stroke:#827717,color:#616200
    classDef infra fill:#FFEBEE,stroke:#C62828,color:#880E4F
```
