# omarahm3/squirrel architecture

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

- Interactive diagram: https://gitdiagram.com/omarahm3/squirrel
- Repository: https://github.com/omarahm3/squirrel

## Overview

##### Project type and purpose
- This is a distributed, real-time log-streaming system composed of two Go applications:
a) **squirrel (client/CLI)** – a command-line tool for broadcasting or listening to stdout streams.
b) **squirreld (server/daemon)** – an HTTP & WebSocket server that routes messages between broadcasters and subscribers.
- Use case: pipe any command’s stdout into `squirrel` to obtain a shareable link or ID, then view logs in a browser or another CLI instance in real time.

##### File structure
Top-level directories and role:
- **cmd/**
- squirrel (CLI entry point)
- squirreld (server entry point)
- **client/**
- Implementation of client logic (options parsing, HTTP/WebSocket client, piping)
- **server/**
- HTTP routes, WebSocket hub, message definitions, HTML template for web UI
- **internal/pkg/common/**
- Shared structs and utilities (message formats, templates, helpers)
- **Dockerfile.squirrel** & **Dockerfile.squirreld**
- CI/CD and release configs (.github/, Makefile, goreleaser.yaml)

##### README for additional insights
- The server is a pure in-memory WebSocket hub—no database or durable storage.
- Two modes for the client: broadcasting (default) and listening (`-l/--listen`).
- Configuration via flags or environment variables for both client and server.
- The web UI is served from `server/view/index.html` and connects back over WebSocket.

##### Main components & interactions
a. **Client (CLI)**
- Mode: Broadcaster → opens WebSocket to server, streams stdin as WebSocket messages.
- Mode: Listener → opens WebSocket using peer ID, displays incoming messages or pipes to stdout.
b. **Server (squirreld)**
- **HTTP Server** on port (default 3000):
- Serves web UI (`/client/{id}`) and health routes.
- **WebSocket Hub** (`hub.go`):
- Maintains maps of broadcaster→subscribers.
- Routes messages from broadcasters to all connected subscribers.
c. **Browser (Web UI)**
- Connects to server’s WebSocket endpoint, displays incoming log lines in real time.
d. **CI/CD & Packaging**
- GoReleaser, Docker images for both apps, GitHub workflows.

##### Relationships & data flows
1. **User pipes stdout → squirrel CLI**
→ CLI registers with server via HTTP or WS (handshake).
→ WebSocket connection established.
→ CLI sends each line as a JSON `Message`.
2. **Server hub receives message**
→ Broadcasts to all listening clients and any open web UI sessions.
3. **Browser / squirrel CLI listener**
→ Connects via WebSocket using the ID.
→ Receives JSON messages, renders to screen.

##### Important architectural patterns
- **Pub/Sub** over WebSocket: one publisher, many subscribers.
- **Hexagonal/Internal packages**: shared message types and utilities in `internal/pkg/common`.
- **Separation of concerns**:
- `cmd/` for wiring & CLI flags
- `client/` and `server/` for core logic
- `view/` for UI template
- **Concurrency**: Go routines and channels to manage connections and message distribution.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Subgraph: CLI Application
    subgraph "CLI Application"
        direction TB
        CLI_BC["CLI Broadcaster/Listener\n(squirrel)"]:::goapp
        ClientMain["client/main.go"]:::goapp
        ClientLogic["client/client.go"]:::goapp
        ClientOpts["client/options.go"]:::goapp
    end

    %% Subgraph: Server Application
    subgraph "Server Application"
        direction TB
        ServerEntry["Server Entry\n(squirreld)"]:::goapp
        subgraph "HTTP Server & Routing"
            direction TB
            HTTPMain["server/main.go"]:::goapp
            HTTPRoutes["server/http.go"]:::goapp
            HTTPOpts["server/options.go"]:::goapp
        end
        Hub["WebSocket Hub\n(pub/sub core)"]:::common
        MsgTypes["Server Message Types\n(server/message.go)"]:::common
        UI["Web UI Template\n(view/index.html)"]:::common
    end

    %% Subgraph: Shared Internal Package
    subgraph "Shared Internal Package"
        direction TB
        SharedMsg["Shared Message Definitions\n(internal/pkg/common/message.go)"]:::common
        SharedTpl["Shared Templates & Helpers\n(template.go, utils.go)"]:::common
    end

    %% External Browser
    Browser["Browser (Web UI)"]:::browser

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        DockerCLI["Dockerfile.squirrel"]:::docker
        DockerServ["Dockerfile.squirreld"]:::docker
        CICheck[".github/workflows/check.yml"]:::ci
        CIRelease[".github/workflows/release.yml"]:::ci
        GoRelease["goreleaser.yaml"]:::ci
        MakefileNode["Makefile"]:::ci
    end

    %% Connections: Client to Shared
    ClientMain --> SharedMsg
    ClientMain --> SharedTpl
    ClientLogic --> SharedMsg
    ClientLogic --> SharedTpl
    ClientOpts --> SharedMsg
    ClientOpts --> SharedTpl

    %% Connections: Server to Shared
    ServerEntry --> SharedMsg
    ServerEntry --> SharedTpl
    HTTPMain --> SharedMsg
    HTTPMain --> SharedTpl
    HTTPRoutes --> SharedMsg
    HTTPRoutes --> SharedTpl
    HTTPOpts --> SharedMsg
    HTTPOpts --> SharedTpl
    MsgTypes --> SharedMsg

    %% Main data flows
    CLI_BC -->|"WebSocket ws://.../ws?id={id}"| Hub
    Hub -->|"Broadcast messages"| CLI_BC
    Browser -->|"WebSocket ws://.../ws?id={id}"| Hub
    Hub -->|"Forward logs"| Browser
    Browser -->|"HTTP GET /client/{id}"| HTTPMain
    HTTPMain -->|"Serves HTML"| Browser

    %% CI/CD usage
    DockerCLI --> CLI_BC
    DockerServ --> ServerEntry
    CICheck --> MakefileNode
    CIRelease --> GoRelease

    %% Click Events
    click CLI_BC "https://github.com/omarahm3/squirrel/blob/master/cmd/squirrel/squirrel.go"
    click ClientMain "https://github.com/omarahm3/squirrel/blob/master/client/main.go"
    click ClientLogic "https://github.com/omarahm3/squirrel/blob/master/client/client.go"
    click ClientOpts "https://github.com/omarahm3/squirrel/blob/master/client/options.go"
    click ServerEntry "https://github.com/omarahm3/squirrel/blob/master/cmd/squirreld/squirreld.go"
    click HTTPMain "https://github.com/omarahm3/squirrel/blob/master/server/main.go"
    click HTTPRoutes "https://github.com/omarahm3/squirrel/blob/master/server/http.go"
    click HTTPOpts "https://github.com/omarahm3/squirrel/blob/master/server/options.go"
    click Hub "https://github.com/omarahm3/squirrel/blob/master/server/hub.go"
    click MsgTypes "https://github.com/omarahm3/squirrel/blob/master/server/message.go"
    click SharedMsg "https://github.com/omarahm3/squirrel/blob/master/internal/pkg/common/message.go"
    click SharedTpl "https://github.com/omarahm3/squirrel/blob/master/internal/pkg/common/template.go"
    click UI "https://github.com/omarahm3/squirrel/blob/master/server/view/index.html"
    click DockerCLI "https://github.com/omarahm3/squirrel/blob/master/Dockerfile.squirrel"
    click DockerServ "https://github.com/omarahm3/squirrel/blob/master/Dockerfile.squirreld"
    click CICheck "https://github.com/omarahm3/squirrel/blob/master/.github/workflows/check.yml"
    click CIRelease "https://github.com/omarahm3/squirrel/blob/master/.github/workflows/release.yml"
    click GoRelease "https://github.com/omarahm3/squirrel/blob/master/goreleaser.yaml"
    click MakefileNode "https://github.com/omarahm3/squirrel/tree/master/Makefile"

    %% Styles
    classDef goapp fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef common fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef browser fill:#98FB98,stroke:#333,stroke-width:1px
    classDef docker fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef ci fill:#F0E68C,stroke:#333,stroke-width:1px
```
