# tarampampam/error-pages architecture

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

- Interactive diagram: https://gitdiagram.com/tarampampam/error-pages
- Repository: https://github.com/tarampampam/error-pages

## Overview

##### Project type and purpose
- This is a single‐binary Go application that serves two purposes:
a) a CLI tool (commands: serve, build, healthcheck, perftest)
b) an ultra‐lightweight HTTP server that dynamically renders and caches error pages in multiple formats.
- It bundles a set of Go‐template HTML “themes,” supports localization (l10n), in‐memory caching, on‐the‐fly minification, JSON/XML/plaintext responses, health checks, and integrates easily into Docker/K8s/Traefik/Ingress setups.

##### File structure
- cmd/error-pages/main.go
→ entrypoint for the CLI
- internal/cli/…
→ command definitions (serve, build, healthcheck, perftest, update_readme)
- internal/config/…
→ parsing flags+env, rotation modes, code definitions, template lists
- internal/logger/…
→ structured JSON logger abstraction
- internal/http/…
→ HTTP server: server.go, middleware (logreq), handlers (error_page, static, live, version), httptest helpers
- internal/template/…
→ Go‐template renderer + HTML/CSS/JS minification + properties injection
- l10n/…
→ JavaScript localization logic, translation files
- templates/…
→ embedded HTML themes (app-down, cats, connection, etc.)
- Dockerfile, Makefile, GitHub Actions, and .github/ CI/CD files
→ build, test, release pipelines, container packaging

##### README for additional insights
- Confirms a “serve” mode for live HTTP error page serving and a “build” mode for static page generation
- Describes CLI flags for templating, rotation, logging, formats, headers, K8s/Ing-Nginx/Traefik usage
- Emphasizes minimal resource usage, distroless Docker image, unprivileged user

##### Essential architectural elements to capture
- Separation of modes: serve vs. build
- Config → logger → HTTP server startup
- Middleware → handler → template engine → themes + localization
- Static‐build path using the same template engine
- Docker image build embedding all assets
- Integration hooks for Traefik/Ingress/K8s

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI_Main["cmd/error-pages/main.go"]:::cli
        CLI_CLIpkg["internal/cli"]:::cli
    end
    click CLI_Main "https://github.com/tarampampam/error-pages/blob/master/cmd/error-pages/main.go"
    click CLI_CLIpkg "https://github.com/tarampampam/error-pages/tree/master/internal/cli"

    %% Configuration Module
    subgraph "Configuration Module"
        direction TB
        Config_Main["internal/config/config.go"]:::config
        Config_Codes["codes.go"]:::config
        Config_Rotation["rotation_mode.go"]:::config
        Config_Templates["templates.go"]:::config
    end
    click Config_Main "https://github.com/tarampampam/error-pages/blob/master/internal/config/config.go"
    click Config_Codes "https://github.com/tarampampam/error-pages/blob/master/internal/config/codes.go"
    click Config_Rotation "https://github.com/tarampampam/error-pages/blob/master/internal/config/rotation_mode.go"
    click Config_Templates "https://github.com/tarampampam/error-pages/blob/master/internal/config/templates.go"

    %% Logging Module
    subgraph "Logging Module"
        direction TB
        Logger_Main["internal/logger/logger.go"]:::logger
        Logger_STD["std.go"]:::logger
        Logger_Format["format.go"]:::logger
        Logger_Level["level.go"]:::logger
    end
    click Logger_Main "https://github.com/tarampampam/error-pages/blob/master/internal/logger/logger.go"
    click Logger_STD "https://github.com/tarampampam/error-pages/blob/master/internal/logger/std.go"
    click Logger_Format "https://github.com/tarampampam/error-pages/blob/master/internal/logger/format.go"
    click Logger_Level "https://github.com/tarampampam/error-pages/blob/master/internal/logger/level.go"

    %% App Metadata
    AppMeta["internal/appmeta/version.go"]:::appmeta
    click AppMeta "https://github.com/tarampampam/error-pages/blob/master/internal/appmeta/version.go"

    %% Build Module
    subgraph "Build Module"
        direction TB
        Build_Cmd["internal/cli/build/command.go"]:::build
        Build_Index["index.html"]:::build
    end
    click Build_Cmd "https://github.com/tarampampam/error-pages/blob/master/internal/cli/build/command.go"
    click Build_Index "https://github.com/tarampampam/error-pages/blob/master/internal/cli/build/index.html"

    %% Template Engine
    subgraph "Template Engine"
        direction TB
        Template_Main["internal/template/template.go"]:::template
        Template_Minify["minify.go"]:::template
        Template_Props["props.go"]:::template
    end
    click Template_Main "https://github.com/tarampampam/error-pages/blob/master/internal/template/template.go"
    click Template_Minify "https://github.com/tarampampam/error-pages/blob/master/internal/template/minify.go"
    click Template_Props "https://github.com/tarampampam/error-pages/blob/master/internal/template/props.go"

    %% Localization Layer
    subgraph "Localization Layer"
        direction TB
        L10n_Embed["l10n/enbed.go"]:::l10n
        L10n_JS["l10n/l10n.js"]:::l10n
        L10n_Readme["l10n/readme.md"]:::l10n
    end
    click L10n_Embed "https://github.com/tarampampam/error-pages/blob/master/l10n/enbed.go"
    click L10n_JS "https://github.com/tarampampam/error-pages/blob/master/l10n/l10n.js"
    click L10n_Readme "https://github.com/tarampampam/error-pages/blob/master/l10n/readme.md"

    %% Embedded Themes
    subgraph "Embedded Themes"
        direction TB
        Themes_HTML["templates/*.html"]:::themes
        Themes_Embed["templates/embed.go"]:::themes
    end
    click Themes_Embed "https://github.com/tarampampam/error-pages/blob/master/templates/embed.go"

    %% HTTP Server
    subgraph "HTTP Server"
        direction TB
        HTTP_Server["internal/http/server.go"]:::http
        subgraph "Middleware"
            direction TB
            HTTP_MW["middleware/logreq/middleware.go"]:::http
        end
        subgraph "Handlers"
            direction TB
            Handler_Error["error_page/handler.go"]:::http
            Handler_Static["static/handler.go"]:::http
            Handler_Live["live/handler.go"]:::http
            Handler_Version["version/handler.go"]:::http
        end
        Handler_Error --> Cache_Layer
    end
    click HTTP_Server "https://github.com/tarampampam/error-pages/blob/master/internal/http/server.go"
    click HTTP_MW "https://github.com/tarampampam/error-pages/blob/master/internal/http/middleware/logreq/middleware.go"
    click Handler_Error "https://github.com/tarampampam/error-pages/blob/master/internal/http/handlers/error_page/handler.go"
    click Handler_Static "https://github.com/tarampampam/error-pages/blob/master/internal/http/handlers/static/handler.go"
    click Handler_Live "https://github.com/tarampampam/error-pages/blob/master/internal/http/handlers/live/handler.go"
    click Handler_Version "https://github.com/tarampampam/error-pages/blob/master/internal/http/handlers/version/handler.go"

    %% Caching Layer
    Cache_Layer["internal/http/handlers/error_page/cache.go"]:::cache
    click Cache_Layer "https://github.com/tarampampam/error-pages/blob/master/internal/http/handlers/error_page/cache.go"

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        Traefik["Traefik"]:::external
        Nginx["Nginx Ingress"]:::external
        Kubernetes["Kubernetes Ingress"]:::external
        DockerRegistry["Docker Registry"]:::external
    end

    %% Docker Packaging
    subgraph "Docker Packaging"
        direction TB
        Dockerfile["Dockerfile"]:::external
        Makefile["Makefile"]:::external
        CI_Release[".github/workflows/release.yml"]:::external
        CI_Tests[".github/workflows/tests.yml"]:::external
    end

    %% Flows
    CLI_Main -->|"loads flags/env"| Config_Main
    CLI_Main -->|"injects version"| AppMeta
    CLI_Main -->|"initializes"| Logger_Main

    CLI_Main -->|"on serve"| HTTP_Server
    HTTP_Server --> HTTP_MW
    HTTP_MW --> Handler_Error
    HTTP_MW --> Handler_Static
    HTTP_MW --> Handler_Live
    HTTP_MW --> Handler_Version

    Handler_Error -->|"uses cache"| Cache_Layer
    Cache_Layer --> Template_Main
    Template_Main --> Themes_HTML
    Template_Main --> L10n_JS
    Template_Main -->|"renders"| Handler_Error

    CLI_Main -->|"on build"| Build_Cmd
    Build_Cmd --> Template_Main
    Build_Cmd --> Build_Index

    Dockerfile -->|"builds binary"| CLI_Main
    Dockerfile -->|"embeds assets"| Themes_HTML
    Dockerfile -->|"embeds localization"| L10n_JS
    Dockerfile --> DockerRegistry

    Traefik -->|"routes errors"| HTTP_Server
    Nginx -->|"routes errors"| HTTP_Server
    Kubernetes -->|"routes errors"| HTTP_Server

    %% Styles
    classDef cli fill:#D6EFFF,stroke:#0366d6,stroke-width:1px;
    classDef config fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px;
    classDef logger fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px;
    classDef http fill:#E3F2FD,stroke:#1976D2,stroke-width:1px;
    classDef template fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px;
    classDef l10n fill:#E0F7FA,stroke:#006064,stroke-width:1px;
    classDef themes fill:#FCE4EC,stroke:#C2185B,stroke-width:1px;
    classDef cache fill:#FFFDE7,stroke:#F9A825,stroke-width:1px;
    classDef build fill:#E8EAF6,stroke:#3949AB,stroke-width:1px;
    classDef appmeta fill:#ECEFF1,stroke:#546E7A,stroke-width:1px;
    classDef external fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px,stroke-dasharray: 5 5;
```
