# superfly/rchab architecture

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

- Interactive diagram: https://gitdiagram.com/superfly/rchab
- Repository: https://github.com/superfly/rchab

## Overview

##### Main Components
- Docker Proxy Service: The heart of the system is in the dockerproxy directory (with files like main.go, auth.go, dockerd.go, etc.). This Go-based service intercepts and manages Docker build requests.
- Docker Entrypoint Script(s): Managed via the docker-entrypoint.d directory and the separate “entrypoint” file. These scripts initialize the environment and adjust system configurations before the service runs.
- Configuration Files: These include deployment and environment config files such as Dockerfile, Procfile, Vagrantfile (for local development), fly.toml, and the daemon.json file inside etc/docker. These files indicate how the service is built, deployed, and behaves in production versus development.
- CI/CD Pipeline: The .github directory (with workflows such as ci.yaml) represents an automated build/test/deployment pipeline, ensuring code changes are integrated and deployed correctly (by GitHub Actions deploying changes to the main branch).
- Utility Scripts and Tools: Files like Makefile, build.sh, and rsyncd.conf support building, testing, and syncing the development environment.

##### Relationships and Workflows
- Client Interaction: External tools (like flyctl, as described in the README) connect to the proxy service. For local development, Vagrant is used to run an isolated VM that has the service and its own Docker daemon.
- Remote Build Triggering: When a user triggers a build (e.g., using the fly deploy command), flyctl communicates with this proxy service, which then directs the Docker commands to its locally managed Docker daemon.
- CI/CD Integration: GitHub Actions automatically build and deploy updates when changes are merged into the main branch. This updates the running service on Fly.
- Service Initialization: The dockerentrypoint scripts and the separate “entrypoint” are responsible for setting up and configuring the Docker environment, including possibly sysctl and other system-level configuration.

##### Important Architectural Patterns & Design Principles
- Separation of Concerns: The design clearly separates the proxy service’s logic (dockerproxy implementation) from the environment setup (entrypoint scripts, configuration in etc/ and Dockerfile).
- Remote Build Abstraction: The architecture is designed to abstract away local Docker interactions, using a remote builder that can be overridden (via FLY_RCHAB_OVERRIDE_HOST) for testing.
- CI/CD and Infrastructure as Code: The project leverages GitHub Actions and configuration files (fly.toml, Vagrantfile) to manage deployment and environmental consistency.

##### Specify Relevant Technologies
- Go: The primary language for the dockerproxy service.
- Docker: Both as the container platform (with its Dockerfile and daemon configuration) and the service’s target environment for build operations.
- Fly.io: The deployment and remote build environment driven by flyctl commands.
- Vagrant: For local development to simulate an isolated environment running Docker without interfering with the host setup.
- GitHub Actions: Used for continuous integration and deployment (ci.yaml in .github/workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External & CI/CD Inputs
    subgraph "External & CI/CD"
        A1["Flyctl Client / External Request"]:::client
        A2["CI/CD Pipeline (GitHub Actions)"]:::ci
        A3["Local Development VM (Vagrant)"]:::vagrant
    end

    %% Deployment & Configuration Artifacts
    subgraph "Deployment & Configuration"
        B1["Docker Proxy Service"]:::service

        subgraph "Entrypoint & Config Setup"
            C1["Entrypoint Scripts"]:::config
            C2["Entrypoint File"]:::config
        end

        subgraph "Configuration Files"
            D1["Dockerfile"]:::config
            D2["Procfile"]:::config
            D3["Vagrantfile"]:::config
            D4["fly.toml"]:::config
            D5["daemon.json (Docker)"]:::config
        end

        subgraph "Utility Scripts & Tools"
            E1["Makefile"]:::utility
            E2["build.sh"]:::utility
            E3["rsyncd.conf"]:::utility
        end
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        F1["Local/Remote Docker Daemon"]:::runtime
    end

    %% Relationships
    A1 -->|"build_request"| B1
    A2 -->|"deploy_update"| B1
    A3 -->|"simulate_env"| F1
    A3 -->|"init_script"| C1

    B1 -->|"exec_Docker_cmd"| F1
    B1 -->|"init_env"| C1

    C1 -->|"configure_Daemon"| F1
    C2 -->|"start_Daemon"| F1

    D1 -->|"config"| B1
    D2 -->|"config"| B1
    D3 -->|"config"| B1
    D4 -->|"config"| B1
    D5 -->|"config"| B1

    E1 -->|"build_support"| B1
    E2 -->|"build_support"| B1
    E3 -->|"build_support"| B1

    %% Click Events
    click B1 "https://github.com/superfly/rchab/blob/main/dockerproxy/main.go"
    click C1 "https://github.com/superfly/rchab/tree/main/docker-entrypoint.d/"
    click C2 "https://github.com/superfly/rchab/tree/main/entrypoint"
    click D1 "https://github.com/superfly/rchab/tree/main/Dockerfile"
    click D2 "https://github.com/superfly/rchab/tree/main/Procfile"
    click D3 "https://github.com/superfly/rchab/tree/main/Vagrantfile"
    click D4 "https://github.com/superfly/rchab/blob/main/fly.toml"
    click D5 "https://github.com/superfly/rchab/blob/main/etc/docker/daemon.json"
    click A2 "https://github.com/superfly/rchab/blob/main/.github/workflows/ci.yaml"
    click E1 "https://github.com/superfly/rchab/tree/main/Makefile"
    click E2 "https://github.com/superfly/rchab/blob/main/build.sh"
    click E3 "https://github.com/superfly/rchab/blob/main/rsyncd.conf"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ci fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef vagrant fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef service fill:#c3e6cb,stroke:#333,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef utility fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef runtime fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
