# apteryxxyz/next-ws architecture

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

- Interactive diagram: https://gitdiagram.com/apteryxxyz/next-ws
- Repository: https://github.com/apteryxxyz/next-ws

## Overview

##### Project type and purpose
- Next WS is a Node.js CLI tool and library that “patches” a Next.js app (app-directory only) to add native WebSocket support.

##### File structure
- Top-level:
- src/cli.ts + src/commands/** → CLI entrypoint and commands (patch, verify)
- src/patches/** → Code that applies/unapplies source edits to Next.js internals
- src/server/** → Runtime server logic: hooks into Next.js’ createServer, sets up ws.Server, resolves user API route handlers
- src/client/** → Front-end React context & helpers for connecting to your new WebSocket endpoints
- examples/** → Four sample Next.js apps showing usage (echo server, chat room, base-path, custom server)
- tests/** → Integration tests driving each example via Playwright
- tsup.config.ts, pnpm-workspace.yaml, package.json → build and workspace config

##### README for additional insights
- Confirms this is a server-based plugin, not for serverless hosts
- Describes installation, usage (exporting `SOCKET()` in API route files), and point to examples
- Clarifies peer dependency on `ws` and that it patches Next.js internals

a. Main components
- Developer / CLI Layer:
– `next-ws patch` CLI (src/cli.ts → commands/patch.ts → patches/index.ts)
– Patcher module that modifies Next.js server code on disk
- Next.js Core (unmodified + patched):
– HTTP(S) server instanced via patched `createServer`
– App directory API route loader
- next-ws Runtime (src/server):
– `setup()` invoked inside patched createServer
– Instantiates `ws.WebSocketServer`, registers HTTP ‘upgrade’ listener
– Scans app/api/**/ws/** for exported `SOCKET` handlers
– On WebSocket connection, dispatches to the correct handler
- Client Library (src/client):
– React context and hook to open WS connections to `/api/.../ws`
- External services
– `ws` library (WebSocketServer & WebSocket)
– Node.js HTTP/HTTPS server
- WebSocket Clients (browsers, other services)

b. Relationships and interactions
1. Developer runs `npm install next-ws ws` → `prepare` script executes `next-ws patch` → on-disk patch
2. Developer starts Next.js server → patched `createServer` calls next-ws `setup()`
3. `setup()` creates a `ws.Server` attached to the HTTP server’s ‘upgrade’ event
4. Incoming browser WS handshake → ws.Server accepts upgrade → looks up matching `SOCKET` handler → invokes it with `(client, request, server, context)`
5. Front-end React code uses next-ws client context to open WebSocket to the API route → bi-directional messaging
6. Tests and examples drive end-to-end flows via Playwright

c. Architectural patterns and design principles
- Plugin / patch pattern: injecting behavior into an existing system by source transformation
- Adapter pattern: adapting Node.js HTTP server to WebSocket-aware server
- Modular CLI commands (single-responsibility for patch and verify)
- Convention-over-configuration: auto-discovering `SOCKET` exports under app/api/**/ws

d. Key technologies and libraries
- Node.js + TypeScript
- Next.js (app directory)
- ws (WebSocket library)
- pnpm / npm / yarn
- tsup (build bundler)
- Playwright (tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build/Patch Time (Orange)
  subgraph "Build/Patch Time"
    direction TB
    CLI["CLI: next-ws patch"]:::patchtime
    subgraph "src/commands"
      direction TB
      CMD_INDEX["commands/index.ts"]:::patchtime
      CMD_PATCH["commands/patch.ts"]:::patchtime
      CMD_VERIFY["commands/verify.ts"]:::patchtime
      subgraph "helpers"
        direction TB
        CMD_HELP_CONS["helpers/console.ts"]:::patchtime
        CMD_HELP_DEF["helpers/define.ts"]:::patchtime
        CMD_HELP_SEM["helpers/semver.ts"]:::patchtime
      end
    end
    subgraph "src/patches"
      direction TB
      PATCH_INDEX["patches/index.ts"]:::patchtime
      PATCH1["patches/patch-1.ts"]:::patchtime
      PATCH2["patches/patch-2.ts"]:::patchtime
      subgraph "helpers"
        direction TB
        PCH_HELP_DEF["helpers/define.ts"]:::patchtime
        PCH_HELP_NEXT["helpers/next.ts"]:::patchtime
      end
    end
    CLI -->|"uses"| CMD_INDEX
    CMD_INDEX --> CMD_PATCH
    CMD_INDEX --> CMD_VERIFY
    CMD_INDEX --> CMD_HELP_CONS
    CMD_INDEX --> CMD_HELP_DEF
    CMD_INDEX --> CMD_HELP_SEM
    CMD_PATCH --> PATCH_INDEX
    PATCH_INDEX --> PATCH1
    PATCH_INDEX --> PATCH2
    PATCH_INDEX --> PCH_HELP_DEF
    PATCH_INDEX --> PCH_HELP_NEXT
    click CLI "https://github.com/apteryxxyz/next-ws/blob/main/src/cli.ts"
    click CMD_INDEX "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/index.ts"
    click CMD_PATCH "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/patch.ts"
    click CMD_VERIFY "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/verify.ts"
    click CMD_HELP_CONS "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/helpers/console.ts"
    click CMD_HELP_DEF "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/helpers/define.ts"
    click CMD_HELP_SEM "https://github.com/apteryxxyz/next-ws/blob/main/src/commands/helpers/semver.ts"
    click PATCH_INDEX "https://github.com/apteryxxyz/next-ws/blob/main/src/patches/index.ts"
    click PATCH1 "https://github.com/apteryxxyz/next-ws/blob/main/src/patches/patch-1.ts"
    click PATCH2 "https://github.com/apteryxxyz/next-ws/blob/main/src/patches/patch-2.ts"
    click PCH_HELP_DEF "https://github.com/apteryxxyz/next-ws/blob/main/src/patches/helpers/define.ts"
    click PCH_HELP_NEXT "https://github.com/apteryxxyz/next-ws/blob/main/src/patches/helpers/next.ts"
  end

  %% Runtime Server (Green)
  subgraph "Runtime Server"
    direction TB
    SERVER_ENTRY["src/server/index.ts"]:::runtime
    SERVER_SETUP["src/server/setup.ts"]:::runtime
    subgraph "helpers"
      direction TB
      S_HELP_PERS["helpers/persistent.ts"]:::runtime
      S_HELP_ROUTE["helpers/route.ts"]:::runtime
      S_HELP_SOCKET["helpers/socket.ts"]:::runtime
    end
    SERVER_ENTRY --> SERVER_SETUP
    SERVER_SETUP --> S_HELP_PERS
    SERVER_SETUP --> S_HELP_ROUTE
    SERVER_SETUP --> S_HELP_SOCKET
    click SERVER_ENTRY "https://github.com/apteryxxyz/next-ws/blob/main/src/server/index.ts"
    click SERVER_SETUP "https://github.com/apteryxxyz/next-ws/blob/main/src/server/setup.ts"
    click S_HELP_PERS "https://github.com/apteryxxyz/next-ws/blob/main/src/server/helpers/persistent.ts"
    click S_HELP_ROUTE "https://github.com/apteryxxyz/next-ws/blob/main/src/server/helpers/route.ts"
    click S_HELP_SOCKET "https://github.com/apteryxxyz/next-ws/blob/main/src/server/helpers/socket.ts"
  end

  %% Next.js Core and WebSocketServer (External)
  subgraph "Next.js Core (Patched)"
    direction TB
    NX_SERVER["Next.js HTTP Server"]:::external
    WS_SERVER["WebSocketServer (ws)"]:::external
    NX_SERVER -->|"upgrade event"| WS_SERVER
  end

  %% User SOCKET Handlers (Examples)
  subgraph "User SOCKET Handlers (examples)"
    direction TB
    EB_BASE["base-path/app/(simple)/api/ws/route.ts"]:::external
    EB_CHAT1["chat-room/app/(simple)/api/ws/route.ts"]:::external
    EB_CHAT2["chat-room/app/(dynamic)/[code]/api/ws/route.ts"]:::external
    ECU_S1["custom-server/app/(simple)/api/ws/route.ts"]:::external
    ECU_S2["custom-server/app/(dynamic)/[code]/api/ws/route.ts"]:::external
    WS_SERVER -->|"dispatch to"| EB_BASE
    WS_SERVER --> EB_CHAT1
    WS_SERVER --> EB_CHAT2
    WS_SERVER --> ECU_S1
    WS_SERVER --> ECU_S2
    click EB_BASE "https://github.com/apteryxxyz/next-ws/blob/main/examples/base-path/app/(simple)/api/ws/route.ts"
    click EB_CHAT1 "https://github.com/apteryxxyz/next-ws/blob/main/examples/chat-room/app/(simple)/api/ws/route.ts"
    click EB_CHAT2 "https://github.com/apteryxxyz/next-ws/blob/main/examples/chat-room/app/(dynamic)/[code]/api/ws/route.ts"
    click ECU_S1 "https://github.com/apteryxxyz/next-ws/blob/main/examples/custom-server/app/(simple)/api/ws/route.ts"
    click ECU_S2 "https://github.com/apteryxxyz/next-ws/blob/main/examples/custom-server/app/(dynamic)/[code]/api/ws/route.ts"
  end

  %% Client Library (Blue)
  subgraph "Client Library"
    direction TB
    CLIENT_INDEX["src/client/index.ts"]:::client
    CLIENT_CTX["src/client/context.tsx"]:::client
    CLIENT_INDEX --> CLIENT_CTX
    click CLIENT_INDEX "https://github.com/apteryxxyz/next-ws/blob/main/src/client/index.ts"
    click CLIENT_CTX "https://github.com/apteryxxyz/next-ws/blob/main/src/client/context.tsx"
  end

  %% Browser Client and Tests
  BROWSER["Browser WS Client"]:::client
  WS_SERVER -->|"handshake"| BROWSER
  subgraph "Integration Tests"
    direction TB
    T_BASE["tests/base-path.test.ts"]:::external
    T_CHAT["tests/chat-room.test.ts"]:::external
    T_CUSTOM["tests/custom-server.test.ts"]:::external
    T_BASE --> BROWSER
    T_CHAT --> BROWSER
    T_CUSTOM --> BROWSER
    click T_BASE "https://github.com/apteryxxyz/next-ws/blob/main/tests/base-path.test.ts"
    click T_CHAT "https://github.com/apteryxxyz/next-ws/blob/main/tests/chat-room.test.ts"
    click T_CUSTOM "https://github.com/apteryxxyz/next-ws/blob/main/tests/custom-server.test.ts"
  end

  %% Interactions
  CMD_PATCH -->|"patches Next.js source"| NX_SERVER
  SERVER_SETUP -->|"attach to"| NX_SERVER
  CLIENT_CTX -->|"connects via WS to"| WS_SERVER

  classDef patchtime fill:#f96,stroke:#333,stroke-width:1px;
  classDef runtime fill:#6f6,stroke:#333,stroke-width:1px;
  classDef client fill:#6cf,stroke:#333,stroke-width:1px;
  classDef external fill:#ccc,stroke:#333,stroke-width:1px;
```
