# aileron-projects/go architecture

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

- Interactive diagram: https://gitdiagram.com/aileron-projects/go
- Repository: https://github.com/aileron-projects/go

## Overview

##### Project Type and Purpose
- This is an open‐source Go module (monorepo) that provides extension APIs to the Go standard library. It is not a standalone service or full‐stack app, but a collection of reusable packages (logging, networking, crypto, error handling, time utilities, load balancing, etc.) plus a set of CLI “devtools.”
- The README underlines its role: “Go standard library extensions” with categories like zlog, znet/zhttp, ztime/zcron, zx/zlb, etc.

##### High‐Level Architecture & Components
a. Core Extension Packages
- zlog (logging)
- znet (networking): zhttp (HTTP middleware & proxy), ztcp (TCP proxy), zudp (UDP proxy)
- ztime (time utilities): zcron (cron jobs), zrate (rate limiting)
- zx (load balancing): zlb
- zencoding (XML encoders/decoders), zerrors (error frames & tracing), zio, zsync, zplugin, zruntime (debug), zos (env/files), zmath, zmaps, zcrypto (AES, HMAC, hashes, ciphers)
b. Internal Support Packages
- internal/helper, internal/ihash, internal/pragma
- Used by core packages for low‐level functionality
c. Devtools (CLI utilities)
- Under /_scripts and /devtools: helpers like http-server, proxy-http, backoff, cron runner, dotenv loader, trace, dump, rateserver, etc.
- Standalone Go binaries for operational tasks and demonstrations
d. External Dependencies
- Go “std” library (net/http, time, crypto, io, sync, etc.)
- golang.org/x packages and two permitted third‐party libs (kr/pretty, davecgh/go-spew)

##### Component Interactions & Dependencies
- Each public package depends on zero or more lower‐level extensions or std libs.
Example: znet/zhttp → znet/internal → std net/http; znet/zhttp also uses zerrors and zlog.
ztime/zcron → std time + zos/env; ztime/zrate → std time + sync.
zx/zlb uses znet (to distribute TCP/HTTP) and ztime for health checks/rates.
zcrypto subpackages depend on each other only if exposing layered APIs (bcrypt, pbkdf2 over underlying hash).
- Devtools depend on core packages to perform their tasks (e.g., devtools/proxy-http uses znet/zhttp or std net/http).
- Internal packages are only used by siblings or parent namespaces, never by unrelated packages.

##### Architectural Patterns & Principles
- Layered modular design: lower‐level primitives → higher‐level abstractions.
- Package dependency rule: parent packages cannot import child packages; children can import parents.
- Single Responsibility per package: logging, error framing, encoding, networking, time, etc.
- CLI tools are separate binaries grouped in /devtools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Std["Go std library"]:::external
        Xpkg["golang.org/x"]:::external
        Pretty["kr/pretty"]:::external
        Spew["go-spew"]:::external
    end

    %% Core Extensions
    subgraph "Core Extensions"
        direction TB
        zlog["zlog"]:::core
        subgraph "znet" 
            direction TB
            zhttp["zhttp"]:::core
            ztcp["ztcp"]:::core
            zudp["zudp"]:::core
        end
        subgraph "ztime"
            direction TB
            zcron["zcron"]:::core
            zrate["zrate"]:::core
            zbackoff["zbackoff"]:::core
        end
        subgraph "zx"
            direction TB
            zlb["zlb"]:::core
        end
        zencoding["zxml"]:::core
        zerrors["zerrors"]:::core
        zio["zio"]:::core
        zsync["zsync"]:::core
        zplugin["zplugin"]:::core
        zruntime["zruntime"]:::core
        zos["zos"]:::core
        zmath["zmath"]:::core
        zmaps["zmaps"]:::core
        subgraph "zcrypto"
            direction TB
            zcryptoint["internal"]:::core
            zaes["zaes"]:::core
            zargon2["zargon2"]:::core
            zbcrypt["zbcrypt"]:::core
            zblake2b["zblake2b"]:::core
            zblake2s["zblake2s"]:::core
            zchacha20["zchacha20"]:::core
            zdes["zdes"]:::core
            zhmac["zhmac"]:::core
            zmd4["zmd4"]:::core
            zmd5["zmd5"]:::core
            zpbkdf2["zpbkdf2"]:::core
            zrc4["zrc4"]:::core
            zripemd160["zripemd160"]:::core
            zscrypt["zscrypt"]:::core
            zsha1["zsha1"]:::core
            zsha256["zsha256"]:::core
            zsha3["zsha3"]:::core
            zsha512["zsha512"]:::core
        end
    end

    %% Internal Support
    subgraph "Internal Support"
        direction TB
        IHelper["internal/helper"]:::internal
        IHash["internal/ihash"]:::internal
        IPragma["internal/pragma"]:::internal
    end

    %% Devtools
    subgraph "Devtools (CLI)"
        direction TB
        DBackoff["backoff"]:::devtools
        DCron["cron"]:::devtools
        DDotenv["dotenv"]:::devtools
        DDump["dump"]:::devtools
        DHTTP["http-server"]:::devtools
        DListener["listener"]:::devtools
        DLogical["logicalfile"]:::devtools
        DProxyHTTP["proxy-http"]:::devtools
        DProxyTCP["proxy-tcp"]:::devtools
        DProxyUDP["proxy-udp"]:::devtools
        DRateserver["rateserver"]:::devtools
        DSocket["socket"]:::devtools
        DTrace["trace"]:::devtools
        Scripts["_scripts"]:::devtools
    end

    %% Dependencies: Core -> External
    zlog -->|"imports"| Std
    zerrors -->|"imports"| Std
    zencoding -->|"imports"| Std
    zio -->|"imports"| Std
    zsync -->|"imports"| Std
    zos -->|"imports"| Std
    zruntime -->|"imports"| Std

    zhttp -->|"imports"| zlog
    zhttp -->|"imports"| zerrors
    zhttp -->|"imports"| Std

    zcron -->|"imports"| Std
    zcron -->|"imports"| zos

    zrate -->|"imports"| Std

    zlb -->|"uses"| zhttp
    zlb -->|"uses"| ztcp
    zlb -->|"uses"| zudp
    zlb -->|"imports"| zrate

    %% Core -> Internal
    zhttp -->|"helper"| IHelper
    ztcp -->|"helper"| IHash
    zudp -->|"helper"| IPragma

    %% Devtools -> Core & External
    DProxyHTTP -->|"uses"| zhttp
    DProxyTCP -->|"uses"| ztcp
    DProxyUDP -->|"uses"| zudp
    DCron -->|"uses"| zcron
    DBackoff -->|"uses"| zbackoff
    DRateserver -->|"uses"| zrate
    DHTTP -->|"imports"| Std

    %% Devtools -> Scripts
    Scripts -->|"helpers"| DHTTP

    %% Click Events
    click zlog "https://github.com/aileron-projects/go/tree/main/zlog/"
    click znet "https://github.com/aileron-projects/go/tree/main/znet/"
    click zhttp "https://github.com/aileron-projects/go/tree/main/znet/zhttp/"
    click ztcp "https://github.com/aileron-projects/go/tree/main/znet/ztcp/"
    click zudp "https://github.com/aileron-projects/go/tree/main/znet/zudp/"
    click ztime "https://github.com/aileron-projects/go/tree/main/ztime/"
    click zcron "https://github.com/aileron-projects/go/tree/main/ztime/zcron/"
    click zrate "https://github.com/aileron-projects/go/tree/main/ztime/zrate/"
    click zbackoff "https://github.com/aileron-projects/go/tree/main/ztime/zbackoff/"
    click zx "https://github.com/aileron-projects/go/tree/main/zx/"
    click zlb "https://github.com/aileron-projects/go/tree/main/zx/zlb/"
    click zencoding "https://github.com/aileron-projects/go/tree/main/zencoding/zxml/"
    click zerrors "https://github.com/aileron-projects/go/tree/main/zerrors/"
    click zio "https://github.com/aileron-projects/go/tree/main/zio/"
    click zsync "https://github.com/aileron-projects/go/tree/main/zsync/"
    click zplugin "https://github.com/aileron-projects/go/tree/main/zplugin/"
    click zruntime "https://github.com/aileron-projects/go/tree/main/zruntime/"
    click zos "https://github.com/aileron-projects/go/tree/main/zos/"
    click zmath "https://github.com/aileron-projects/go/tree/main/zmath/"
    click zmaps "https://github.com/aileron-projects/go/tree/main/zmaps/"
    click zcrypto "https://github.com/aileron-projects/go/tree/main/zcrypto/"
    click zcryptoint "https://github.com/aileron-projects/go/tree/main/zcrypto/internal/"
    click zaes "https://github.com/aileron-projects/go/tree/main/zcrypto/zaes/"
    click zargon2 "https://github.com/aileron-projects/go/tree/main/zcrypto/zargon2/"
    click zbcrypt "https://github.com/aileron-projects/go/tree/main/zcrypto/zbcrypt/"
    click zblake2b "https://github.com/aileron-projects/go/tree/main/zcrypto/zblake2b/"
    click zblake2s "https://github.com/aileron-projects/go/tree/main/zcrypto/zblake2s/"
    click zchacha20 "https://github.com/aileron-projects/go/tree/main/zcrypto/zchacha20/"
    click zdes "https://github.com/aileron-projects/go/tree/main/zcrypto/zdes/"
    click zhmac "https://github.com/aileron-projects/go/tree/main/zcrypto/zhmac/"
    click zmd4 "https://github.com/aileron-projects/go/tree/main/zcrypto/zmd4/"
    click zmd5 "https://github.com/aileron-projects/go/tree/main/zcrypto/zmd5/"
    click zpbkdf2 "https://github.com/aileron-projects/go/tree/main/zcrypto/zpbkdf2/"
    click zrc4 "https://github.com/aileron-projects/go/tree/main/zcrypto/zrc4/"
    click zripemd160 "https://github.com/aileron-projects/go/tree/main/zcrypto/zripemd160/"
    click zscrypt "https://github.com/aileron-projects/go/tree/main/zcrypto/zscrypt/"
    click zsha1 "https://github.com/aileron-projects/go/tree/main/zcrypto/zsha1/"
    click zsha256 "https://github.com/aileron-projects/go/tree/main/zcrypto/zsha256/"
    click zsha3 "https://github.com/aileron-projects/go/tree/main/zcrypto/zsha3/"
    click zsha512 "https://github.com/aileron-projects/go/tree/main/zcrypto/zsha512/"
    click IHelper "https://github.com/aileron-projects/go/tree/main/internal/helper/"
    click IHash "https://github.com/aileron-projects/go/tree/main/internal/ihash/"
    click IPragma "https://github.com/aileron-projects/go/tree/main/internal/pragma/"
    click DBackoff "https://github.com/aileron-projects/go/tree/main/devtools/backoff/"
    click DCron "https://github.com/aileron-projects/go/tree/main/devtools/cron/"
    click DDotenv "https://github.com/aileron-projects/go/tree/main/devtools/dotenv/"
    click DDump "https://github.com/aileron-projects/go/tree/main/devtools/dump/"
    click DHTTP "https://github.com/aileron-projects/go/tree/main/devtools/http-server/"
    click DListener "https://github.com/aileron-projects/go/tree/main/devtools/listener/"
    click DLogical "https://github.com/aileron-projects/go/tree/main/devtools/logicalfile/"
    click DProxyHTTP "https://github.com/aileron-projects/go/tree/main/devtools/proxy-http/"
    click DProxyTCP "https://github.com/aileron-projects/go/tree/main/devtools/proxy-tcp/"
    click DProxyUDP "https://github.com/aileron-projects/go/tree/main/devtools/proxy-udp/"
    click DRateserver "https://github.com/aileron-projects/go/tree/main/devtools/rateserver/"
    click DSocket "https://github.com/aileron-projects/go/tree/main/devtools/socket/"
    click DTrace "https://github.com/aileron-projects/go/tree/main/devtools/trace/"
    click Scripts "https://github.com/aileron-projects/go/tree/main/_scripts/"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef core fill:#d0e7ff,stroke:#0366d6,stroke-width:1px
    classDef internal fill:#e0e0e0,stroke:#888,stroke-width:1px
    classDef devtools fill:#fff9c4,stroke:#f1c232,stroke-width:1px
```
