# jmalloc/echo-server architecture

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

- Interactive diagram: https://gitdiagram.com/jmalloc/echo-server
- Repository: https://github.com/jmalloc/echo-server

## Overview

##### Project type and purpose
- This is a single‐service, Go-based HTTP “echo” server tool.
- Its core purpose is to accept HTTP, WebSocket, or SSE connections and echo request headers and bodies back to the client, aiding in testing HTTP proxies and clients.

##### File structure
- Top-level files: Dockerfile, Makefile, CI workflow, configuration files (.gitignore, .dockerignore).
- “cmd/echo-server”: houses the Go entry point (main.go) and an HTML template (frontend.tmpl.html) under “html/” for the .ws UI.
- go.mod/go.sum define dependencies; .github/workflows/ci.yml runs tests/builds on push.

##### Key insights from the README
- Endpoints:
- Any URL → plain-text echo
- “.ws” suffix → serve a basic WebSocket UI
- “.sse” suffix → stream server-sent events
- Configured entirely via environment variables (port, logging flags, header injection).
- Deployable locally or via Docker (Makefile target “docker”; published image jmalloc/echo-server).

##### Main components
a. External Actors
- HTTP Client (e.g. curl)
- WebSocket Client (e.g. browser UI served by .ws template)
- SSE Client
b. Echo-Server Process
- HTTP Listener / Router
- Handler Modules:
- Plain HTTP echo handler
- WebSocket handler (upgrades connections, echoes messages)
- SSE handler (streams events)
- Template Renderer (serves frontend.tmpl.html when “.ws” is requested)
- Configuration Loader (reads PORT, LOG_*, SEND_HEADER_* env vars)
- Logger (conditionally logs headers/bodies to STDOUT)
c. Supporting Elements
- File system access for HTML template
- Docker container (runtime packaging)
- CI pipeline (GitHub Actions)
- Makefile build targets

##### Relationships and interactions
- The Template Renderer is invoked by the Router on “.ws” requests.
- All handlers invoke the Logger component (conditional path based on env flags).
- The Configuration Loader sits alongside the Listener, feeding runtime settings.
- File system is accessed only by the Template Renderer.
- Docker container encloses the Echo-Server process; CI pipeline feeds the Docker build.

##### Architectural patterns and design principles
- Single-process, modular handler pattern (separate handlers for HTTP, WS, SSE).
- Configuration-via-environment (12-factor app style).
- Template separation (logic vs. UI).
- Minimal external dependencies, no database or persistent storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        HTTPClient["HTTP Client (curl)"]:::external
        WSClient["WebSocket Client (browser)"]:::external
        SSEClient["SSE Client"]:::external
    end

    %% Deployment and Build
    subgraph "Deployment & CI"
        CI["CI Pipeline"]:::deploy
        Make["Makefile"]:::deploy
        DockerBuild["Docker Build"]:::deploy
    end

    CI -->|"runs tests/build"| Make
    Make -->|"docker target"| DockerBuild
    DockerBuild -->|"build image"| HTTPListener

    %% Docker Container Envelope
    subgraph "Docker Container"
        direction TB
        subgraph "Echo-Server Process"
            direction TB
            Config["Configuration Loader\n(env vars)"]:::infra
            HTTPListener["HTTP Listener / Router"]:::runtime
            PlHTTP["Plain HTTP Handler"]:::runtime
            WSHandler["WebSocket Handler"]:::runtime
            SSEHandler["SSE Handler"]:::runtime
            TemplateRenderer["Template Renderer"]:::runtime
            Logger["Logger"]:::infra
            FS["File System"]:::infra
        end
    end

    %% Client to Listener
    HTTPClient -->|"HTTP request"| HTTPListener
    WSClient -->|"HTTP .ws request"| HTTPListener
    SSEClient -->|"HTTP .sse request"| HTTPListener

    %% Routing to Handlers
    HTTPListener -->|"route"| PlHTTP
    HTTPListener -->|"route"| WSHandler
    HTTPListener -->|"route"| SSEHandler
    HTTPListener -->|".ws route"| TemplateRenderer

    %% Template flow
    TemplateRenderer -->|"read template"| FS
    TemplateRenderer -->|"serve UI"| WSClient

    %% Handlers back to Clients
    PlHTTP -->|"echo HTTP"| HTTPClient
    WSHandler -->|"echo WS message"| WSClient
    SSEHandler -->|"stream SSE event"| SSEClient

    %% Logging
    PlHTTP -->|"log if enabled"| Logger
    WSHandler -->|"log if enabled"| Logger
    SSEHandler -->|"log if enabled"| Logger

    %% Config usage
    Config --> HTTPListener
    Config --> PlHTTP
    Config --> WSHandler
    Config --> SSEHandler
    Config --> TemplateRenderer
    Config --> Logger

    %% Click Events
    click HTTPListener "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click PlHTTP "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click WSHandler "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click SSEHandler "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click TemplateRenderer "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click FS "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/html/frontend.tmpl.html"
    click Config "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click Logger "https://github.com/jmalloc/echo-server/blob/main/cmd/echo-server/main.go"
    click DockerBuild "https://github.com/jmalloc/echo-server/tree/main/Dockerfile"
    click Make "https://github.com/jmalloc/echo-server/tree/main/Makefile"
    click CI "https://github.com/jmalloc/echo-server/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef runtime fill:#e0f7fa,stroke:#0288d1,color:#01579b
    classDef infra fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef external fill:#e8f5e9,stroke:#43a047,color:#1b5e20
    classDef deploy fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
```
