# liteacz/whalesome architecture

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

- Interactive diagram: https://gitdiagram.com/liteacz/whalesome
- Repository: https://github.com/liteacz/whalesome

## Overview

##### Project type and purpose
- Whalesome is an open-source, Docker-centric utility toolkit. Its purpose is to provide a modular collection of shell scripts (under src/) that simplify “dockerizing” common server components (Apache, Nginx, PHP, Composer, Xdebug, etc.) by packaging each as a self-contained module with install hooks and init.d scripts. It exposes a small CLI (`cmd.sh`, `src/bin/*`) and a Dockerfile that assembles a Docker image containing all of these utilities.

##### File structure
- Top-level:
- `.github/workflows/main.yml` – CI pipeline (build & push image).
- `Dockerfile` – single multi-stage build that installs each package and copies in scripts.
- `cmd.sh` – entrypoint wrapper for invoking internal CLI.
- `src/bin` – actual CLI entrypoints: `docker-entrypoint`, `lit`, `loop`.
- `src/init.d` – global init scripts run at container start (create user, fix ownership, etc.).
- `src/packages/*` – modular packages, each with:
- `install.sh` – installation steps during image build.
- `init.d/*.sh` – runtime configuration scripts.
- configuration templates (e.g., `httpd.conf`, `nginx.conf`, `php-fpm.conf`).
- error pages where relevant.
- No separate “frontend/backend”: this is a tooling image.

##### README
- Single‐line summary: “Docker image holding utility scripts for convenient dockerizing.”
- No additional architecture notes—architecture is implicit in file layout.

##### Main components & relationships
a. Components:
1. Developer / CI system (.github)
2. Docker build (Dockerfile + `src/packages/*`)
3. CLI tools (`src/bin/docker-entrypoint`, `lit`, `loop`)
4. Global init.d scripts (`src/init.d/`)
5. Modular packages (Apache-FPM, Nginx-FPM, PHP-FPM, Composer, Xdebug)
6. Runtime container with all installed utilities
b. Interactions:
- CI triggers Docker build → reads Dockerfile → invokes each package’s `install.sh` in sequence → yields final image.
- At container startup, Docker ENTRYPOINT calls `docker-entrypoint` (from src/bin) → sources `src/init.d/*` scripts → invokes each package’s `init.d/*.sh` to configure services based on environment variables.
- CLI commands (`lit`, `loop`) available inside container for further scripting.
c. Architectural patterns:
- Modular plugin pattern: each package is a self-contained plugin with its own installation and init steps.
- Init-style configuration pattern: uses SysV-style init.d ordering to configure at runtime.
d. Key technologies:
- Docker multi-stage builds
- Shell scripting (bash)
- Init.d ordering (100-, 101-, etc.)
- GitHub Actions for CI

##### Detail guidance
- Central role of `src/bin/docker-entrypoint` orchestrating runtime configuration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External CI
    CI["GitHub Actions (CI)"]:::external
    click CI "https://github.com/liteacz/whalesome/blob/master/.github/workflows/main.yml"

    %% Build-time
    subgraph "Build-time Phase" 
        direction TB
        DB["Docker Build"]:::build
        click DB "https://github.com/liteacz/whalesome/tree/master/Dockerfile"
        subgraph "Modular Packages" 
            direction TB
            AP["Apache-FPM"]:::plugins
            click AP "https://github.com/liteacz/whalesome/blob/master/src/packages/apache/fpm/install.sh"
            NG["Nginx-FPM"]:::plugins
            click NG "https://github.com/liteacz/whalesome/blob/master/src/packages/nginx/fpm/install.sh"
            PH["PHP-FPM"]:::plugins
            click PH "https://github.com/liteacz/whalesome/blob/master/src/packages/php/fpm/install.sh"
            CO["Composer"]:::plugins
            click CO "https://github.com/liteacz/whalesome/blob/master/src/packages/php/composer/install.sh"
            XD["Xdebug"]:::plugins
            click XD "https://github.com/liteacz/whalesome/blob/master/src/packages/php/xdebug/install.sh"
        end
    end

    CI -->|"triggers"| DB
    AP -->|"install.sh"| DB
    NG -->|"install.sh"| DB
    PH -->|"install.sh"| DB
    CO -->|"install.sh"| DB
    XD -->|"install.sh"| DB

    DB -->|"produces"| Image["Whalesome Docker Image"]:::runtime

    %% Runtime
    subgraph "Runtime Phase"
        direction TB
        EP["ENTRYPOINT & CLI tools"]:::runtime
        click EP "https://github.com/liteacz/whalesome/blob/master/cmd.sh"
        subgraph "Global init.d Scripts" 
            direction TB
            G0["000-do_nothing.sh"]:::runtime
            click G0 "https://github.com/liteacz/whalesome/blob/master/src/init.d/000-do_nothing.sh"
            G1["001-create_user.sh"]:::runtime
            click G1 "https://github.com/liteacz/whalesome/blob/master/src/init.d/001-create_user.sh"
            G9["999-chown_project.sh"]:::runtime
            click G9 "https://github.com/liteacz/whalesome/blob/master/src/init.d/999-chown_project.sh"
        end
        subgraph "CLI Commands"
            direction TB
            DENT["docker-entrypoint"]:::runtime
            click DENT "https://github.com/liteacz/whalesome/tree/master/src/bin/docker-entrypoint"
            LIT["lit"]:::runtime
            click LIT "https://github.com/liteacz/whalesome/tree/master/src/bin/lit"
            LOOP["loop"]:::runtime
            click LOOP "https://github.com/liteacz/whalesome/tree/master/src/bin/loop"
        end
    end

    Image -->|"runs"| EP
    EP -->|"sources"| G0
    G0 -->|"then"| G1
    G1 -->|"then"| G9
    G9 -->|"then"| DENT
    EP -.->|"optional"| LIT
    EP -.->|"optional"| LOOP

    classDef external fill:#A999E3,stroke:#47317B,color:#000;
    classDef build fill:#9ED9F6,stroke:#036B8E,color:#000;
    classDef plugins fill:#F9D36B,stroke:#B47B00,color:#000;
    classDef runtime fill:#A3E99D,stroke:#177A3F,color:#000;
```
