# wxn0brp/gloveslink architecture

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

- Interactive diagram: https://gitdiagram.com/wxn0brp/gloveslink
- Repository: https://github.com/wxn0brp/gloveslink

## Overview

##### Project type and purpose
- This is an open-source WebSocket communication library (“GlovesLink”) that provides both a client API and a server API for real-time, room-based messaging with built-in reconnection, authentication, and logging.
- It is not a full-stack application but rather a toolkit to be embedded into other applications (e.g., a Node.js/FalconFrame HTTP server or a browser/Node.js client).

##### File structure
- Top-level files:
- package.json, tsconfig.json, build.js → build/configuration
- src/adapter/browser.ts & node.ts → environment-specific WebSocket adapters
- src/client.ts → entry point for the client library
- src/server/index.ts, room.ts, socket.ts, types.ts → server core modules
- .github/workflows/build.yml → CI/CD pipeline
- sugilite.json → custom build/publish settings
- README.md → usage, API docs, architecture hints

##### README for additional insights
- Server integrates with an external HTTP framework (FalconFrame) to piggy-back on its HTTP server.
- Client and server both manage rooms and event emission callbacks.
- Authentication is pluggable via an authFn.
- Logging is optional.

##### Main components and their relationships
a. Components:
- Client Module (GlovesLinkClient)
– Connection Manager (with reconnection logic)
– Adapter Layer (browser.ts or node.ts provides WebSocket implementation)
– Event Emitter/Handler API
– Room Manager (join/leave rooms)
- Server Module (GlovesLinkServer)
– HTTP Server (FalconFrame or any Node http.Server)
– WebSocket Server (built on adapter/node.ts)
– Authentication Layer (authFn)
– Socket Manager (wraps each connection into GLSocket)
– Room Manager (broadcast to rooms)
– Logging Module
- External HTTP Framework (FalconFrame)
- External Authentication Service (optional, via authFn)

b. Interactions:
- Client opens WebSocket to Server’s HTTP endpoint → Adapter connects
- Server performs authFn(headers, token) → accept/deny
- On success, server registers socket in Room Manager
- Client emits events → travels over WebSocket → Server dispatches to appropriate handlers
- Server emits responses → travels back → Client invokes callbacks
- Automatic reconnect: Client’s Connection Manager retries on disconnect
- Rooms: Both Client and Server maintain membership lists

c. Architectural patterns and design principles:
- Adapter Pattern: Separates environment-specific WebSocket implementations
- Event-Driven Architecture: All communication via emit/on handlers
- Dependency Injection: authFn, HTTP server are injected at instantiation
- Modularization: Clear separation of concerns—connection logic, auth, room management, logging

d. Key technologies and libraries:
- TypeScript for type safety
- Node.js http.Server and optional FalconFrame
- Native WebSocket in browsers and ws library in Node (implied by adapter)
- Yarn/NPM for packaging

##### Detailed elements
- Component names (exact filenames or class names)
- Interfaces between components (method calls, event names)
- Data flow direction (→ or ⇄)
- Internal library modules
- Host/third-party frameworks
- External services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        CL["GlovesLinkClient"]:::client
        Conn["Connection Manager & Event API"]:::client
        subgraph "Adapter"
            direction TB
            AD_B["Browser Adapter"]:::client
            AD_N["Node Adapter"]:::client
        end
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        GS["GlovesLinkServer"]:::server
        HTTP["HTTP Server (FalconFrame)"]:::external
        WS["WebSocket Server"]:::server
        Auth["Authentication Layer (authFn)"]:::server
        SM["Socket Manager (GLSocket)"]:::server
        RM["Room Manager"]:::server
        Log["Logging Module"]:::server
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AuthSvc["Authentication Service"]:::external
    end

    %% Connections
    Conn -->|"uses adapter"| AD_B
    Conn -->|"uses adapter"| AD_N
    AD_B -->|"WebSocket connection (wss://)"| WS
    AD_N -->|"WebSocket connection (wss://)"| WS
    HTTP -->|"Upgrade HTTP→WS"| WS
    WS -->|"onConnect"| Auth
    Auth -->|"authFn(token)"| AuthSvc
    Auth -->|"onSuccess"| SM
    SM -->|"joinRoom/leaveRoom"| RM
    Conn -->|"emit(event,data)"| SM
    SM -->|"emit(event,data)"| Conn
    RM -->|"broadcast"| SM
    Log -->|"logs events"| WS

    %% Click Events
    click CL "https://github.com/wxn0brp/gloveslink/blob/master/src/client.ts"
    click Conn "https://github.com/wxn0brp/gloveslink/blob/master/src/client.ts"
    click AD_B "https://github.com/wxn0brp/gloveslink/blob/master/src/adapter/browser.ts"
    click AD_N "https://github.com/wxn0brp/gloveslink/blob/master/src/adapter/node.ts"
    click GS "https://github.com/wxn0brp/gloveslink/blob/master/src/server/index.ts"
    click SM "https://github.com/wxn0brp/gloveslink/blob/master/src/server/socket.ts"
    click RM "https://github.com/wxn0brp/gloveslink/blob/master/src/server/room.ts"
    click TY "https://github.com/wxn0brp/gloveslink/blob/master/src/server/types.ts"
    click CFG1 "https://github.com/wxn0brp/gloveslink/blob/master/build.js"
    click CFG2 "https://github.com/wxn0brp/gloveslink/blob/master/tsconfig.json"
    click CFG3 "https://github.com/wxn0brp/gloveslink/blob/master/package.json"
    click CI "https://github.com/wxn0brp/gloveslink/blob/master/.github/workflows/build.yml"
    click MD "https://github.com/wxn0brp/gloveslink/blob/master/README.md"
    click IG "https://github.com/wxn0brp/gloveslink/blob/master/.gitignore"
    click SG "https://github.com/wxn0brp/gloveslink/blob/master/sugilite.json"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#00796B,stroke-width:2px
    classDef server fill:#E8F5E9,stroke:#388E3C,stroke-width:2px
    classDef external fill:#ECEFF1,stroke:#546E7A,stroke-width:2px
```
