# faustedition/faust-gen-docker architecture

> Architecture diagram of the GitHub repository faustedition/faust-gen-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faustedition/faust-gen-docker
- Repository: https://github.com/faustedition/faust-gen-docker

## Overview

##### Project Type & Purpose
- This is a containerized, multi‐service system focused on:
- Building and serving a static “www” site (via Gradle + Docker multi‐stage).
- Running two Python microservices (macrogen & downloadserver) behind an Apache reverse proxy.
- Providing a workflow for building “old” versions of the site and tagging images.

##### High‐Level Architecture Components
a. Docker Build Pipeline (local or CI)
- Input: Git repo with submodules (`downloadserver`, `macrogen`), XSL scripts, Gradle build files.
- Dockerfile with multi‐stage targets:
- `www` (build static site via Gradle)
- `www-old` (inject old/1.0rc tree via build‐arg)
- `macrogen` & `downloadserver` production images (copy code + entrypoint + Gunicorn config).
b. Container Orchestration (docker-compose)
- compose.yaml defines three containers on a custom network:
1. apache – Reverse proxy (apache.conf) serving static “www” & routing API calls.
2. macrogen – Python/Gunicorn service for text‐generation endpoints.
3. downloadserver – Python/Gunicorn service serving download metadata.
c. Configuration & Secrets
- `.env` files in each service folder for environment variables.
- `apache.conf` for vhost routing.
- `adjust-conf-files.xsl` for any XML transformations at build time.
d. Data Artifacts & Volumes
- Static site tree served by Apache (built into the `www` image).
- `downloads.json.gz` for downloadserver to serve/calculate.
- `macrogen.yaml`, `logging.yaml` for macrogen service configuration.

##### Relationships & Data Flow
- Client HTTP(S) → Apache container →
- GET “/static” → serves built site files
- API calls “/api/gen” → proxies to macrogen (Gunicorn)
- API calls “/api/downloads” → proxies to downloadserver
- macrogen reads its config from mounted files & environment; responds JSON.
- downloadserver reads `downloads.json.gz` and env, responds file metadata.

##### Key Architectural Patterns & Principles
- Microservices: each Python service is isolated, has its own Docker context, config, entrypoint, Gunicorn.
- Reverse Proxy Pattern: Apache sits in front, handling SSL (if any), static assets, and routing to services.
- Multi‐Stage Docker Builds: separate build vs. run stages to produce lean final images.
- Configuration as Code: XSL for config patching, YAML for service config, `.env` for secrets.

##### Technologies & Frameworks
- Docker, Docker Compose, Docker Bake/HCL for build orchestration.
- Gradle (Kotlin DSL) for static site generation.
- Apache HTTPD for reverse proxy & static file serving.
- Python + Gunicorn for microservices.
- XSLT for config adjustments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Phase
    subgraph "Build Pipeline" 
        direction TB
        GitRepo["Git Repository\n(submodules)"]:::build
        DockerBuild["Docker Build"]:::build
        GitRepo -->|submodules: downloadserver, macrogen| DockerBuild
        %% Artifacts
        Dockerfile["Dockerfile"]:::config
        dockerBake["docker-bake.hcl"]:::config
        adjustXSL["adjust-conf-files.xsl"]:::config
        extractScript["extract-build-dir.sh"]:::config
        gradleInit["init.gradle.kts"]:::config
        DockerBuild --> Dockerfile
        DockerBuild --> dockerBake
        DockerBuild --> adjustXSL
        DockerBuild --> extractScript
        DockerBuild --> gradleInit
        %% Images
        WWWImage["faustedition/www Image"]:::build
        MacroImage["faustedition/macrogen Image"]:::build
        DownloadImage["faustedition/downloadserver Image"]:::build
        DockerBuild --> WWWImage
        DockerBuild --> MacroImage
        DockerBuild --> DownloadImage
    end

    %% Runtime Phase
    subgraph "Runtime (Docker Compose)" 
        direction TB
        Compose["docker-compose (compose.yaml)"]:::config
        WWWImage --> Compose
        MacroImage --> Compose
        DownloadImage --> Compose

        %% Containers
        Apache["Apache Container\n(port 80)"]:::runtime
        Macrogen["macrogen Container\n(port 8000)"]:::runtime
        DownloadSvc["downloadserver Container\n(port 8001)"]:::runtime
        Compose --> Apache
        Compose --> Macrogen
        Compose --> DownloadSvc

        %% Config and Data Mounts
        apacheConf["apache.conf"]:::config
        Apache -->|vhost routing| apacheConf

        subgraph "macrogen Config" 
            direction TB
            mgEnv[".env"]:::config
            mgEntrypoint["entrypoint.sh"]:::config
            mgGunicorn["gunicorn.conf.py"]:::config
            mgLogging["logging.yaml"]:::config
            mgConfig["macrogen.yaml"]:::config
            Macrogen --> mgEnv
            Macrogen --> mgEntrypoint
            Macrogen --> mgGunicorn
            Macrogen --> mgLogging
            Macrogen --> mgConfig
        end

        subgraph "downloadserver Config/Data" 
            direction TB
            dsEnv[".env"]:::config
            dsDownloads["downloads.json.gz"]:::data
            dsEntrypoint["entrypoint.sh"]:::config
            dsGunicorn["gunicorn.conf.py"]:::config
            DownloadSvc --> dsEnv
            DownloadSvc --> dsDownloads
            DownloadSvc --> dsEntrypoint
            DownloadSvc --> dsGunicorn
        end

        %% Data Flow
        Client["Client HTTP(S)"]:::external
        Client -->|requests| Apache
        Apache -->|/static| Apache
        Apache -->|/api/gen → macrogen:8000| Macrogen
        Apache -->|/api/downloads → downloadserver:8001| DownloadSvc
    end

    %% Click Events
    click Dockerfile "https://github.com/faustedition/faust-gen-docker/tree/main/Dockerfile"
    click dockerBake "https://github.com/faustedition/faust-gen-docker/blob/main/docker-bake.hcl"
    click adjustXSL "https://github.com/faustedition/faust-gen-docker/blob/main/adjust-conf-files.xsl"
    click extractScript "https://github.com/faustedition/faust-gen-docker/blob/main/extract-build-dir.sh"
    click gradleInit "https://github.com/faustedition/faust-gen-docker/blob/main/init.gradle.kts"
    click Compose "https://github.com/faustedition/faust-gen-docker/blob/main/compose.yaml"
    click apacheConf "https://github.com/faustedition/faust-gen-docker/blob/main/apache.conf"
    click mgEnv "https://github.com/faustedition/faust-gen-docker/blob/main/macrogen/.env"
    click mgEntrypoint "https://github.com/faustedition/faust-gen-docker/blob/main/macrogen/entrypoint.sh"
    click mgGunicorn "https://github.com/faustedition/faust-gen-docker/blob/main/macrogen/gunicorn.conf.py"
    click mgLogging "https://github.com/faustedition/faust-gen-docker/blob/main/macrogen/logging.yaml"
    click mgConfig "https://github.com/faustedition/faust-gen-docker/blob/main/macrogen/macrogen.yaml"
    click dsEnv "https://github.com/faustedition/faust-gen-docker/blob/main/downloadserver/.env"
    click dsDownloads "https://github.com/faustedition/faust-gen-docker/blob/main/downloadserver/downloads.json.gz"
    click dsEntrypoint "https://github.com/faustedition/faust-gen-docker/blob/main/downloadserver/entrypoint.sh"
    click dsGunicorn "https://github.com/faustedition/faust-gen-docker/blob/main/downloadserver/gunicorn.conf.py"

    %% Styles
    classDef build fill:#cce5ff,stroke:#3399ff,color:#000
    classDef runtime fill:#d4edda,stroke:#28a745,color:#000
    classDef config fill:#fff3cd,stroke:#ffcc00,color:#000
    classDef data fill:#ffe5e5,stroke:#ff6666,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
