# djui/await architecture

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

- Interactive diagram: https://gitdiagram.com/djui/await
- Repository: https://github.com/djui/await

## Overview

##### Project type and purpose
- This is a Go-based command-line tool (“await”) whose sole purpose is to block until a set of “resources” (HTTP endpoints, TCP ports, files, databases, AMQP brokers, or arbitrary commands) become available, and then (optionally) run a user command.
- It’s designed as an extensible, self-contained CLI utility, often used in Docker Compose entrypoints or similar orchestration contexts.

##### File structure
- Top-level entrypoint:
- main.go / main_test.go – sets up CLI flags, parses arguments, and invokes the awaiter.
- Core orchestration:
- awaiter.go – central loop that takes a list of Resource objects, polls them until ready or timeout.
- resource.go – defines the Resource interface and common parsing/fragment mechanics.
- Resource implementations (strategy/plugin pattern):
- http.go / http_test.go
- websocket.go
- tcp.go
- file.go / resource_test.go
- postgresql.go
- mysql.go
- amqp.go
- command.go
- Supporting modules:
- log.go – logging, verbosity levels
- <other helper files> (none)
- Build & dependency files:
- Makefile, go.mod, go.sum

##### Insights from README
- The tool exposes flags (`-t`, `-v`, `-i`, etc.) to control timeout, verbosity, input source, and whether to force execution on failure.
- Supports resource URL syntax plus a generic “command” fallback.
- After successful waits, it can exec a child command.

a. Main components:
1. CLI Layer (main.go)
2. Parser & Config (flag parsing + resource URL/file input)
3. Awaiter Engine (awaiter.go)
4. Resource Strategy Modules (http, tcp, websocket, file, postgresql, mysql, amqp, command)
5. Logging Subsystem (log.go)
6. Child Command Executor (command.go)
7. External Resources (web servers, databases, message brokers, file system, shell commands)

b. Relationships & interactions:
- User invokes CLI → CLI Layer parses flags → builds a list of Resource objects
- Awaiter Engine receives the Resource list and the timeout/verbosity settings
- For each Resource, Awaiter calls its `Check()` method in a loop until it reports “available” or timeout
- Logging Subsystem records each check attempt (verbosity drives log level)
- Once all resources are ready (or if forced after timeout), Child Command Executor runs the user-specified command and returns its exit code

c. Architectural patterns & principles:
- Strategy pattern: each resource type implements a common interface (`Resource`)
- Single-responsibility: parsing, waiting, logging, and execution are cleanly separated
- Pluggability: new resource types can be added by implementing the `Resource` interface

d. Key technologies & libraries:
- Go standard library (`net/http`, `net`, `database/sql`, `os/exec`, etc.)
- lib/pq for PostgreSQL
- go-sql-driver/mysql for MySQL
- amqp client library (in amqp.go)

##### Final recommendations
- Every resource type module as its own sub-component to show the plugin boundary.
- Loop in the Awaiter Engine to convey “poll until available or timeout.”
- Don’t omit the child command execution path after successful waits.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Layer\n(main.go, main_test.go)"]:::cli
        Parser["Parser & Config\n(main.go)"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        Awaiter["Awaiter Engine\n(awaiter.go)\nFlags: timeout, verbosity"]:::core
        ResourceIF["Resource Interface\n(resource.go, resource_test.go)"]:::core
    end

    %% Resource Plugins
    subgraph "Resource Plugins"
        HTTP["HTTP Module\n(http.go, http_test.go)"]:::plugin
        WS["WebSocket Module\n(websocket.go)"]:::plugin
        TCP["TCP Module\n(tcp.go)"]:::plugin
        File["File Module\n(file.go)"]:::plugin
        PG["PostgreSQL Module\n(postgresql.go)"]:::plugin
        MySQL["MySQL Module\n(mysql.go)"]:::plugin
        AMQP["AMQP Module\n(amqp.go)"]:::plugin
    end

    %% Utilities
    subgraph "Utilities"
        Logger["Logging Subsystem\n(log.go)"]:::util
        Executor["Command Executor\n(command.go)"]:::util
        Build["Build & Dependencies\n(Makefile, go.mod, go.sum)"]:::build
    end

    %% External Services
    subgraph "External Services"
        ExtHTTP["Web Servers"]:::external
        ExtWS["WebSocket Servers"]:::external
        ExtTCP["TCP Endpoints"]:::external
        ExtFile["File System"]:::external
        ExtDB["Databases"]:::external
        ExtAMQP["AMQP Brokers"]:::external
        Shell["Shell/OS"]:::external
    end

    %% Connections
    CLI --> Parser
    Parser --> Awaiter
    Awaiter --> ResourceIF
    ResourceIF --> HTTP
    ResourceIF --> WS
    ResourceIF --> TCP
    ResourceIF --> File
    ResourceIF --> PG
    ResourceIF --> MySQL
    ResourceIF --> AMQP
    Awaiter --> Logger
    Awaiter --> Executor
    HTTP --> ExtHTTP
    WS --> ExtWS
    TCP --> ExtTCP
    File --> ExtFile
    PG --> ExtDB
    MySQL --> ExtDB
    AMQP --> ExtAMQP
    Executor --> Shell

    %% Click Events
    click CLI "https://github.com/djui/await/blob/master/main.go"
    click CLI "https://github.com/djui/await/blob/master/main_test.go"
    click Parser "https://github.com/djui/await/blob/master/main.go"
    click Awaiter "https://github.com/djui/await/blob/master/awaiter.go"
    click ResourceIF "https://github.com/djui/await/blob/master/resource.go"
    click ResourceIF "https://github.com/djui/await/blob/master/resource_test.go"
    click HTTP "https://github.com/djui/await/blob/master/http.go"
    click HTTP "https://github.com/djui/await/blob/master/http_test.go"
    click WS "https://github.com/djui/await/blob/master/websocket.go"
    click TCP "https://github.com/djui/await/blob/master/tcp.go"
    click File "https://github.com/djui/await/blob/master/file.go"
    click PG "https://github.com/djui/await/blob/master/postgresql.go"
    click MySQL "https://github.com/djui/await/blob/master/mysql.go"
    click AMQP "https://github.com/djui/await/blob/master/amqp.go"
    click Executor "https://github.com/djui/await/blob/master/command.go"
    click Logger "https://github.com/djui/await/blob/master/log.go"
    click Build "https://github.com/djui/await/tree/master/Makefile"
    click Build "https://github.com/djui/await/blob/master/go.mod"
    click Build "https://github.com/djui/await/blob/master/go.sum"

    %% Styles
    classDef cli fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef core fill:#98D8D8,stroke:#333,stroke-width:1px;
    classDef plugin fill:#D5A6BD,stroke:#333,stroke-width:1px;
    classDef util fill:#B6D7A8,stroke:#333,stroke-width:1px;
    classDef external fill:#F4CCCC,stroke:#333,stroke-width:1px;
    classDef build fill:#CCCCCC,stroke:#333,stroke-width:1px;
```
