# esonwong/network-rc architecture

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

- Interactive diagram: https://gitdiagram.com/esonwong/network-rc
- Repository: https://github.com/esonwong/network-rc

## Overview

##### Project type and purpose
- This is a full-stack IoT control system for a remote-control car based on Raspberry Pi.
- The front-end is a React SPA (in front-end/) that offers UI for video streaming, controls, settings, voice chat, etc.
- The back-end is a Node.js server (root index.js + lib/) running on the Pi, exposing HTTP/WebSocket endpoints, managing WebRTC, GPIO channels, cameras, audio and TTS.

##### File structure
- Top level:
- index.js: server entrypoint
- lib/: back-end modules (AudioServer, CameraServer, MicrophoneServer, WebRTC, GPIO drivers, TTS, session, stream, updater, etc.)
- front-end/: React app with components, Redux store, WebRTC helper, static assets
- deploy.js + install.sh: deployment scripts
- test/: unit tests for hardware modules
- Patterns & technologies:
- MVC-style separation: front-end (V) ↔ server routes & WebSocket handlers (C) ↔ hardware modules (M)
- WebRTC for real-time audio/video
- WebSocket (via @clusterws/cws) for signaling and control messages
- FFmpeg & Pulseaudio for media handling
- GPIO libraries (rpio, rpio-pwm) for channel control
- FRP for tunneling traffic over 4G/5G

##### README for insights
- Purpose: low-latency remote control with video, multi-camera, multi-channel PWM, voice, audio playback, auto server/RTC switch.
- Dependencies: ffmpeg, pulseaudio, Node.js.
- Deployment: single-node on Raspberry Pi, expose HTTP at port 8080, optional FRP server externally.

a. Components:
1. Front-end React SPA (Browser)
2. Node.js Control Server
- HTTP Server (static assets, REST APIs)
- WebSocket / signaling server
- WebRTC media gateway
- Hardware Controllers:
– CameraServer (spawns FFmpeg, streams video)
– AudioServer & MicrophoneServer (Pulseaudio)
– GPIO Controller (27 PWM channels, rpio)
– TTS Engine
3. Raspberry Pi hardware
- Cameras, microphones, speakers, motors/servos (GPIO)
4. External services (optional)
- FRP tunnel server (for NAT traversal)
- STUN/TURN (if used)
- Remote WebRTC peers (gamepad/keyboard clients)
b. Relationships & data flow:
- Browser ↔ HTTP ➔ Control Server (serves UI, config APIs)
- Browser ↔ WebSocket ➔ Control Server (control commands, channel updates, status)
- Browser ↔ WebRTC ➔ Control Server ↔ hardware media modules ➔ camera/audio hardware
- Control Server ↔ GPIO libs ➔ motor controllers
- Control Server ↔ TTS module ➔ speaker hardware
- Control Server ↔ FRP (outgoing connection to public server)
c. Architectural patterns:
- Component-based front-end + central Signal & Media Gateway on back-end
- Adapter pattern for hardware abstraction (CameraServer, AudioServer, GPIO)
- Pub/Sub or EventEmitter for inter-module messaging (session, stream, status)
d. Key technologies/frameworks:
- React, Redux (front-end)
- Node.js, @clusterws/cws, ws-avc-player
- FFmpeg, Pulseaudio
- WebRTC (native, via wrtc library)
- rpio, rpio-pwm (GPIO)
- FRP (remote port forwarding)

##### Detail without over-splitting
- Key modules and their groupings
- Event/control flows and media flows separately for clarity
- Hardware pins/channels if critical

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    Browser["ControlUI<br/>(React SPA)"]:::frontend
    click Browser "https://github.com/esonwong/network-rc/tree/master/front-end/"

    %% Node.js Server
    subgraph "Node.js Control Server"
        direction TB
        Entrypoint["Entry Point<br/>(index.js)"]:::backend
        click Entrypoint "https://github.com/esonwong/network-rc/blob/master/index.js"
        HTTP["HTTP Server<br/>(Express)"]:::api
        click HTTP "https://github.com/esonwong/network-rc/blob/master/lib/app.js"
        WS["WebSocket Signaling<br/>(@clusterws/cws)"]:::api
        click WS "https://github.com/esonwong/network-rc/blob/master/lib/WebRTC/index.js"
        subgraph "WebRTC Media Gateway"
            direction TB
            MediaUtils["WebRTC Utils"]:::media
            click MediaUtils "https://github.com/esonwong/network-rc/tree/master/lib/WebRTC/"
        end
        subgraph "Hardware Controllers"
            direction TB
            Camera["CameraServer<br/>(FFmpeg)"]:::hardware
            click Camera "https://github.com/esonwong/network-rc/blob/master/lib/CameraServer.js"
            Audio["AudioServer<br/>(PulseAudio)"]:::hardware
            click Audio "https://github.com/esonwong/network-rc/blob/master/lib/AudioServer.js"
            Mic["MicrophoneServer<br/>(PulseAudio)"]:::hardware
            click Mic "https://github.com/esonwong/network-rc/blob/master/lib/MicrophoneServer.js"
            GPIO["GPIO Controller<br/>(rpio, PWM)"]:::hardware
            click GPIO "https://github.com/esonwong/network-rc/blob/master/lib/gpio.js"
            LED["LED Control"]:::hardware
            click LED "https://github.com/esonwong/network-rc/blob/master/lib/led.js"
            ADC["ADC Interface<br/>(ADS1115)"]:::hardware
            click ADC "https://github.com/esonwong/network-rc/blob/master/lib/ads1115.js"
            TTS["TTS Engine"]:::hardware
            click TTS "https://github.com/esonwong/network-rc/blob/master/lib/tts/index.js"
        end
        Session["Session Management"]:::backend
        click Session "https://github.com/esonwong/network-rc/blob/master/lib/session.js"
        Stream["Stream Management"]:::backend
        click Stream "https://github.com/esonwong/network-rc/blob/master/lib/stream.js"
        Status["Status Reporting"]:::backend
        click Status "https://github.com/esonwong/network-rc/blob/master/lib/status.js"
        subgraph "FRP Tunnel Client"
            FRPClient["frpc Client"]:::external
            click FRPClient "https://github.com/esonwong/network-rc/blob/master/lib/frpc/index.js"
            FRPBin["frpc Binary"]:::external
            click FRPBin "https://github.com/esonwong/network-rc/tree/master/lib/frpc/frpc"
        end
    end

    %% Hardware Layer
    subgraph "Raspberry Pi Hardware"
        direction TB
        Cameras["Cameras"]:::device
        Microphones["Microphones"]:::device
        Speakers["Speakers"]:::device
        Motors["Motors/Servos"]:::device
    end

    %% External Services
    subgraph "External Services"
        direction TB
        FRPServer["FRP Tunnel Server"]:::external
        STUN["STUN/TURN"]:::external
    end

    %% Arrows - Control/Config Flows
    Browser -.->|HTTPS 8080| HTTP
    Browser -.->|WSS 8443| WS
    HTTP -->|REST APIs| Session
    WS -->|Signaling| Session
    Session -->|route events| Stream
    Session -->|status events| Status

    %% Arrows - Media Flows
    Browser -->|"WebRTC DTLS/SRTP"| MediaUtils
    MediaUtils -->|transport| Camera
    MediaUtils -->|transport| Audio
    MediaUtils -->|transport| Mic
    Camera -->|video stream| Browser
    Audio -->|audio playback| Browser
    Mic -->|audio capture| Browser

    %% Arrows - Hardware Commands
    Stream -->|frame commands| Camera
    Stream -->|audio commands| Audio
    Status -->|report| GPIO
    GPIO -->|PWM signals| Motors
    TTS -->|play speech| Speakers
    Status -->|read| ADC

    %% FRP Tunnel
    Entrypoint -.->|connect| FRPClient
    FRPClient -.->|tunnel| FRPServer

    %% External STUN/TURN
    MediaUtils -.->|STUN/TURN| STUN

    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef api fill:#e6f7ff,stroke:#66ccff,color:#000;
    classDef backend fill:#f2f2f2,stroke:#999,color:#000;
    classDef media fill:#e6ffe6,stroke:#33cc33,color:#000;
    classDef hardware fill:#fff0e6,stroke:#ff9933,color:#000;
    classDef external fill:#f2f2f2,stroke:#999,color:#000;
    classDef device fill:#fff5e6,stroke:#cc9900,color:#000;
```
