# andy-blum/ddev-websocket architecture

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

- Interactive diagram: https://gitdiagram.com/andy-blum/ddev-websocket
- Repository: https://github.com/andy-blum/ddev-websocket

## Overview

##### Project Type and Purpose
- This is an **open-source add-on** for DDEV (local Docker-based PHP/dev environment) that provides a **simple, extensible WebSocket server**.
- Key use case: enable bi-directional, real-time communication between browser clients and server without page refresh.
- It’s packaged as a Docker-service sidecar within a DDEV project, customizable via JavaScript “plugins.”

##### File Structure Analysis
- Top-level directories:
– `.github/`: CI workflows (tests.yml), issue and PR templates
– `js/`: client helper (SocketClient.js) and plugin stubs
– `nginx/`: custom nginx configuration for WebSocket proxying
– `web-build/`: Dockerfile and server entrypoint (SocketServer.js)
– `tests/`: Bats tests and test data
- Key config files:
– `config.websocket.yml` & `install.yaml`: DDEV add-on definitions
– `nginx/ddev-websocket.conf`: proxies incoming WebSocket traffic to the Node.js server
- Build/deploy artifacts:
– `web-build/Dockerfile` builds the Node.js WebSocket server image

##### README Insights
- Describes plugin interface (onConnection, onMessage, onError, onClose).
- Usage pattern: browser WebSocket → `wss://<project>.ddev.site:8080` → server.
- Dependencies: Node.js, ws package, DDEV CLI.
- Developer hooks: drop `.js` files into `.ddev/js/plugins`; logs via `ddev logs -s websocket`.

##### Components
a. Main Components
– Browser Client: Web pages or console scripts using native WebSocket API or `js/SocketClient.js`.
– DDEV Network & Reverse Proxy: Docker network, nginx proxy forwarding wss:// calls to container.
– WebSocket Server Container: Node.js app (SocketServer.js) built via `web-build/Dockerfile`.
– Plugin Loader & Modules: dynamic loader that requires each plugin in `.ddev/js/plugins`.
– DDEV CLI / Add-on Framework: `install.yaml` triggers service startup; `config.websocket.yml` configures port, image.
– Logging & Testing: DDEV logging subsystem; `tests` directory for automated Bats tests.

b. Relationships and Data Flow
1. Browser issues `wss://…:8080` → hits nginx in DDEV web container.
2. nginx proxy forwards → WebSocket Server Container on internal port.
3. Server accepts connection → Plugin Loader attaches event handlers.
4. onMessage events → dispatched to each plugin’s `onMessage` handler → plugin may call `this.send()`.
5. Responses flow back along the same socket → Browser.
6. CLI commands (`ddev logs`, `ddev restart`) manage service lifecycle and surface logs.

c. Architectural Patterns
– **Plugin Pattern**: runtime loading of modules implementing optional hooks.
– **Event-Driven**: Node.js event loop with ws’s connection/message/error/close events.
– **Sidecar Service**: runs alongside the main web container, integrated via DDEV network and configuration.

d. Key Technologies
– Node.js & ws package (WebSocketServer)
– Docker & Dockerfile (web-build/)
– nginx (proxy configuration for DDEV)
– DDEV add-on YAML files (install.yaml, config.websocket.yml)
– JavaScript plugin API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    BrowserClient["Browser Client\n(js/SocketClient.js)"]:::module
    CI["CI Workflow\n(.github/workflows/tests.yml)"]:::tool
    Tests["Automated Tests\n(tests/test.bats)"]:::tool
    TestData["Test Data\n(tests/testdata/)"]:::tool
    IssueTemplates["GitHub Issue Templates\n(.github/ISSUE_TEMPLATE/)"]:::tool
    PRTemplate["GitHub PR Template\n(.github/PULL_REQUEST_TEMPLATE.md)"]:::tool
    README["README & Debug\n(README.md, README_DEBUG.md)"]:::tool

    %% DDEV Project Boundary
    subgraph "DDEV Project Boundary"
        direction TB
        subgraph "Configuration" 
            direction TB
            DDEVConfig["DDEV Add-on Config\n(config.websocket.yml)"]:::tool
            DDEVInstall["DDEV Install Definition\n(install.yaml)"]:::tool
        end

        subgraph "Runtime Services" 
            direction TB
            nginxProxy["nginx Proxy\n(nginx/ddev-websocket.conf)"]:::container
            WSContainer["WebSocket Server\n(web-build/SocketServer.js)"]:::container

            subgraph "WebSocket Server Build" 
                direction TB
                webBuild["Dockerfile\n(web-build/Dockerfile)"]:::module
            end

            subgraph "Plugins" 
                direction TB
                PluginLoader["Plugin Loader"]:::module
                ExamplePlugin["Example Plugin\n(pong.example.js)"]:::module
            end
        end

        subgraph "Tooling & Tests"
            direction TB
            DDEVCLI["DDEV CLI / Add-on Framework"]:::tool
            Logs["DDEV Logs"]:::tool
        end
    end

    %% Data Flows
    BrowserClient -->|"wss://…:8080"| nginxProxy
    nginxProxy -->|"proxy to internal port"| WSContainer
    WSContainer -->|"load plugins"| PluginLoader
    PluginLoader -->|"require modules"| ExamplePlugin
    ExamplePlugin -->|"onMessage/send()"| WSContainer
    WSContainer -->|"response over socket"| BrowserClient

    DDEVConfig -->|configures| DDEVCLI
    DDEVInstall -->|installs sidecar| DDEVCLI
    DDEVCLI -->|starts/stops| WSContainer
    DDEVCLI -->|view logs| Logs

    CI -->|runs| Tests
    Tests -->|uses| TestData
    Tests -->|validates| WSContainer

    %% Click events
    click BrowserClient "https://github.com/andy-blum/ddev-websocket/blob/main/js/SocketClient.js"
    click nginxProxy "https://github.com/andy-blum/ddev-websocket/blob/main/nginx/ddev-websocket.conf"
    click webBuild "https://github.com/andy-blum/ddev-websocket/tree/main/web-build/Dockerfile"
    click WSContainer "https://github.com/andy-blum/ddev-websocket/blob/main/web-build/SocketServer.js"
    click PluginLoader "https://github.com/andy-blum/ddev-websocket/tree/main/js/plugins/"
    click ExamplePlugin "https://github.com/andy-blum/ddev-websocket/blob/main/js/plugins/pong.example.js"
    click DDEVConfig "https://github.com/andy-blum/ddev-websocket/blob/main/config.websocket.yml"
    click DDEVInstall "https://github.com/andy-blum/ddev-websocket/blob/main/install.yaml"
    click Tests "https://github.com/andy-blum/ddev-websocket/blob/main/tests/test.bats"
    click TestData "https://github.com/andy-blum/ddev-websocket/tree/main/tests/testdata/"
    click CI "https://github.com/andy-blum/ddev-websocket/blob/main/.github/workflows/tests.yml"
    click IssueTemplates "https://github.com/andy-blum/ddev-websocket/tree/main/.github/ISSUE_TEMPLATE/"
    click PRTemplate "https://github.com/andy-blum/ddev-websocket/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    click README "https://github.com/andy-blum/ddev-websocket/blob/main/README.md"

    %% Styles
    classDef container fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef module fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef tool fill:#E5E7E9,stroke:#566573,color:#1C2833;
```
