# kengonakajima/nodephone architecture

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

- Interactive diagram: https://gitdiagram.com/kengonakajima/nodephone
- Repository: https://github.com/kengonakajima/nodephone

## Overview

##### Main Components
- Client Application:
– The core “phone.js” acts as the main client connecting to the server.
– Other client variants (recplay.js for microphone-speaker testing; cancel.js, which adds echo cancellation on top of recplay).
– A suite of supporting modules (for echo cancellation, e.g., aec3.js with its associated WASM and native modules, along with additional audio processing scripts like fft_ifft.js, matched.js, etc.).
– Audio I/O dependency components (e.g., “node-record-lpcm16” for recording and “speaker” for playback, as indicated in the README).
- Server Application:
– The “sv.js” script and accompanying files (like cl.js, package.json) indicate that the server uses Node.js with WebSockets listening on TCP port 13478.
– This server is responsible for relaying audio data among connected clients.
- External Dependencies & Resources:
– NPM modules (as referenced in the installation instructions).
– Platform dependencies (the use of x86_64 Rosetta2 on macOS and the Homebrew-installed sox).
– Audio files in the “sounds” directory for demo and testing.

##### Relationships and Data Flow
- Clients connect to the server via WebSockets (TCP port 13478) and send/receive audio data.
- On the client side:
– The microphone captures audio which then gets possibly processed by the echo cancellation module (or bypassed, depending on the app variant being executed).
– Processed audio is sent over the network to the server.
– Incoming audio data from other clients is played back via the speaker.
- The server acts as a broadcaster – routing every connected user’s audio to all other clients (or acting as a relay for voice communication).
- There is dependency on low-level native modules and WebAssembly (e.g., aec3.wasm and NativeAudioMac.node) for performance-critical audio processing.

##### Architectural Patterns and Design Principles
- Modularization: The separation into an “app” (client code), “server” (server code), and “sounds” (assets) directories shows a clear division of concerns.
- Real-time data streaming: The use of WebSockets ensures low-latency communication between clients and server.
- Platform-specific optimizations: Native modules (.node files like PAmac.node, opusmac.node, and opuswin.node) along with compiled WASM code indicate an emphasis on performance for audio processing.
- Extensibility: By offering multiple client entry points (phone.js, recplay.js, cancel.js), the architecture provides flexibility for testing versus production use.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    subgraph "Client Application"
        subgraph "Entry Points"
            P["Phone App"]:::entry
            R["Recplay Variant"]:::entry
            C["Cancel Variant"]:::entry
        end
        subgraph "Audio Modules"
            AC["Audio Capture (Microphone)"]:::capture
            EC["Echo Cancellation (aec3.js)"]:::processing
            W["WASM Module (aec3.wasm)"]:::processing
            WM["WASM Map (aec3.wasm.map)"]:::processing
            F["FFT Processing (fft_ifft.js)"]:::processing
            M["Matched Filter (matched.js)"]:::processing
            PLY["Audio Playback (Speaker)"]:::playback
        end
    end

    %% Network Interface and Server
    NI["Network Interface (WebSocket over TCP 13478)"]:::network

    subgraph "Server Side"
        S["NodePhone Server"]:::server
    end

    %% Audio Resources
    AR["Audio Resources (Sounds)"]:::resource

    %% Connections inside Client Application Entry Points to Audio Modules
    P -->|"init"| AC
    R -->|"init"| AC
    C -->|"init"| AC

    %% Audio processing chain
    AC --> EC
    EC --> W
    W --> WM
    WM --> F
    F --> M
    M --> NI

    %% From Network Interface to Server and back to Playback
    NI -->|"WebSocketData"| S
    S -->|"BroadcastStream"| NI
    NI -->|"AudioStream"| PLY

    %% Audio Resources used for demonstration
    AR ---|"TestSamples"| PLY

    %% Click Events
    click P "https://github.com/kengonakajima/nodephone/blob/main/app/phone.js"
    click R "https://github.com/kengonakajima/nodephone/blob/main/app/recplay.js"
    click C "https://github.com/kengonakajima/nodephone/blob/main/app/cancel.js"
    click EC "https://github.com/kengonakajima/nodephone/blob/main/app/aec3.js"
    click W "https://github.com/kengonakajima/nodephone/blob/main/app/aec3.wasm"
    click WM "https://github.com/kengonakajima/nodephone/blob/main/app/aec3.wasm.map"
    click F "https://github.com/kengonakajima/nodephone/blob/main/app/fft_ifft.js"
    click M "https://github.com/kengonakajima/nodephone/blob/main/app/matched.js"
    click S "https://github.com/kengonakajima/nodephone/blob/main/server/sv.js"
    click AR "https://github.com/kengonakajima/nodephone/tree/main/sounds"

    %% Styling
    classDef entry fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef capture fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef processing fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef playback fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef network fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef server fill:#f5c6cb,stroke:#333,stroke-width:2px;
    classDef resource fill:#d6d8db,stroke:#333,stroke-width:2px;
```
