# d-a-s-h-o/droplets architecture

> Architecture diagram of the GitHub repository d-a-s-h-o/droplets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d-a-s-h-o/droplets
- Repository: https://github.com/d-a-s-h-o/droplets

## Overview

##### Project Type and Purpose
- Type: CLI-driven Docker orchestration tool for spinning up PHP web-hosting stacks (with Tor support) plus generic Ubuntu containers.
- Purpose: Automate building and running Docker containers (web + ubuntu) via a simple CLI (app.py), serve PHP sites over clearnet and Tor, and expose an optional API/QR/TOTP layer.

##### File Structure
- Top-level:
– app.py + shell scripts (ddd CLI entrypoint)
– api/ (PHP & Python API endpoints)
– webui/ (PHP-based UI helper)
– qr/ & totp.sh (QR code and TOTP support libraries)
– docker/ubuntu & docker/web (Dockerfiles + config dumps)
- Patterns:
– CLI invokes Docker builds and runs
– docker/web image bundles Nginx, PHP, Tor, site files under /var/www/html/.files
– docker/ubuntu provides a generic sandbox container

##### Key Insights from the README
- The CLI (app.py) named “ddd” builds and runs images with three simple commands.
- Two prebuilt images: ghcr.io/d-a-s-h-o/droplets/web and …/ubuntu.
- After “ddd -n <name>,” your container is live on clearnet and as a Tor hidden service.

##### Main Components
a. ddd CLI (app.py + support scripts)
b. Docker Engine (daemon on host)
c. Docker Images:
- droplets/web
- droplets/ubuntu
d. Running Containers:
- Web Container:
– Nginx (reverse proxy)
– Tor daemon (hidden-service)
– PHP interpreter + .files folder (index.php, config.php, UI assets)
- Ubuntu Container: generic environment for custom services
e. Volumes & Config Mappings:
– Host ↔ Container mounts for /etc/nginx, torrc, site files
f. API Layer (api/api.php, api/api.py, config.py)
g. QR & TOTP Modules (qr/*, totp.sh)
h. External Networks:
– Clearnet (HTTP/S on host port → Nginx)
– Tor Network (TCP 9050 → Tor daemon → hidden service)

##### Relationships and Data Flows
- The ddd CLI issues Docker build/run commands to Docker Engine.
- Docker Engine spins up containers from the two images.
- Web Container:
– Nginx listens on forwarded host ports.
– Nginx proxies PHP requests to the PHP-FPM interpreter reading .files.
– Tor daemon registers a hidden service pointing at the local Nginx port.
- Ubuntu Container: used for arbitrary workloads (NodeJS, Python, etc.) under the same orchestration flow.
- API Layer: inside the web container (or separate) exposes control endpoints for container management.
- QR/TOTP scripts: either invoked by web UI (webui/app.php) or CLI to generate codes.

##### Architectural Patterns & Principles
- Separation of concerns: CLI vs. orchestrator vs. runtime images.
- Immutable infrastructure: containers built from Dockerfiles with versioned configs.
- Plug-in flexibility: generic Ubuntu container alongside specialized web container.
- Single responsibility: one container = one service (web, tor, php under web image).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    Terminal["Terminal"]:::external
    Browser["Browser / Tor Browser"]:::external

    %% Control Layer
    subgraph "Control Layer"
        AppPy["app.py"]:::control
        AppSh["app.sh"]:::control
        UbuntuRun["ubuntu_run.sh"]:::control
        WebRun["web_run.sh"]:::control
    end

    %% Orchestration Layer
    DockerEngine["Docker Engine"]:::control

    %% Images Layer
    subgraph "Docker Images"
        subgraph "droplets/web"
            WebDockerfile["Dockerfile"]:::image
            EntrypointSH["entrypoint.sh"]:::image
            SitesConfig["sites_config"]:::image
            HostsFile["hosts"]:::image
            TorrcFile["torrc"]:::image
            FilesFolder[".files"]:::image
            HostMD["host.md"]:::image
        end
        subgraph "droplets/ubuntu"
            UbuntuDockerfile["Dockerfile"]:::image
            UbuntuTorrcDump["etc/tor/torrc"]:::image
            UbuntuDumpEtc["var/dump/etc"]:::image
            UbuntuDumpHostMD["var/dump/var/host.md"]:::image
        end
    end

    %% Service Layer
    subgraph "Web Container" 
        Nginx["Nginx"]:::runtime
        PHPFiles["PHP-FPM & .files"]:::runtime
        TorDaemon["Tor daemon"]:::runtime
        subgraph "API Layer"
            APIConfig["config.py"]:::support
            APIpy["api.py"]:::support
            APIphp["api.php"]:::support
        end
        subgraph "Web UI Helper"
            WebUI["app.php & words.txt"]:::support
        end
        subgraph "QR Module"
            QR["qr PHP library"]:::support
        end
        TOTP["totp.sh"]:::support
    end

    UbuntuContainer["Ubuntu Container"]:::runtime

    %% Network Layer
    Clearnet["Clearnet HTTP/S"]:::external
    TorNetwork["Tor Network"]:::external

    %% Flows
    Terminal -->|"runs"| AppPy
    AppPy -->|"calls scripts"| AppSh
    AppSh -->|"invokes"| DockerEngine
    UbuntuRun -->|"invokes"| DockerEngine
    WebRun -->|"invokes"| DockerEngine

    DockerEngine -->|"build droplets/web"| WebDockerfile
    DockerEngine -->|"build droplets/web"| EntrypointSH
    DockerEngine -->|"build droplets/web"| SitesConfig
    DockerEngine -->|"build droplets/web"| HostsFile
    DockerEngine -->|"build droplets/web"| TorrcFile
    DockerEngine -->|"build droplets/web"| FilesFolder
    DockerEngine -->|"build droplets/web"| HostMD

    DockerEngine -->|"build droplets/ubuntu"| UbuntuDockerfile
    DockerEngine -->|"build droplets/ubuntu"| UbuntuTorrcDump
    DockerEngine -->|"build droplets/ubuntu"| UbuntuDumpEtc
    DockerEngine -->|"build droplets/ubuntu"| UbuntuDumpHostMD

    DockerEngine -->|"run web container"| Nginx
    DockerEngine -->|"run web container"| PHPFiles
    DockerEngine -->|"run web container"| TorDaemon
    DockerEngine -->|"run ubuntu container"| UbuntuContainer

    Nginx -->|"proxies to"| PHPFiles
    PHPFiles -->|"serves files"| Browser
    TorDaemon -->|"hidden service"| TorNetwork
    Nginx -->|"listen on host port"| Clearnet

    APIConfig -->|"exposes endpoints"| Nginx
    APIpy -->|"exposes endpoints"| Nginx
    APIphp -->|"exposes endpoints"| Nginx

    WebUI -->|"UI helper"| PHPFiles

    QR -->|"generates codes"| WebUI
    TOTP -->|"generates codes"| AppPy

    %% Click events
    click AppPy "https://github.com/d-a-s-h-o/droplets/blob/master/app.py"
    click AppSh "https://github.com/d-a-s-h-o/droplets/blob/master/app.sh"
    click UbuntuRun "https://github.com/d-a-s-h-o/droplets/blob/master/ubuntu_run.sh"
    click WebRun "https://github.com/d-a-s-h-o/droplets/blob/master/web_run.sh"

    click APIConfig "https://github.com/d-a-s-h-o/droplets/blob/master/api/config.py"
    click APIpy "https://github.com/d-a-s-h-o/droplets/blob/master/api/api.py"
    click APIphp "https://github.com/d-a-s-h-o/droplets/blob/master/api/api.php"

    click WebDockerfile "https://github.com/d-a-s-h-o/droplets/tree/master/docker/web/Dockerfile"
    click EntrypointSH "https://github.com/d-a-s-h-o/droplets/blob/master/docker/web/entrypoint.sh"
    click SitesConfig "https://github.com/d-a-s-h-o/droplets/tree/master/docker/web/etc/nginx/sites-available/sites_config"
    click HostsFile "https://github.com/d-a-s-h-o/droplets/tree/master/docker/web/etc/hosts"
    click TorrcFile "https://github.com/d-a-s-h-o/droplets/tree/master/docker/web/etc/tor/torrc"
    click FilesFolder "https://github.com/d-a-s-h-o/droplets/blob/master/docker/web/var/www/html/.files"
    click HostMD "https://github.com/d-a-s-h-o/droplets/blob/master/docker/web/var/www/html/host.md"

    click UbuntuDockerfile "https://github.com/d-a-s-h-o/droplets/tree/master/docker/ubuntu/Dockerfile"
    click UbuntuTorrcDump "https://github.com/d-a-s-h-o/droplets/tree/master/docker/ubuntu/var/dump/etc/tor/torrc"
    click UbuntuDumpEtc "https://github.com/d-a-s-h-o/droplets/tree/master/docker/ubuntu/var/dump/etc"
    click UbuntuDumpHostMD "https://github.com/d-a-s-h-o/droplets/blob/master/docker/ubuntu/var/dump/var/host.md"

    click WebUI "https://github.com/d-a-s-h-o/droplets/blob/master/webui/app.php"
    click QR "https://github.com/d-a-s-h-o/droplets/blob/master/qr/phpqrcode.php"
    click TOTP "https://github.com/d-a-s-h-o/droplets/blob/master/totp.sh"

    %% Styles
    classDef control fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#000,stroke-width:1px
    classDef support fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef image fill:#E0FFFF,stroke:#000,stroke-width:1px
```
