# schlagmichdoch/pairdrop architecture

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

- Interactive diagram: https://gitdiagram.com/schlagmichdoch/pairdrop
- Repository: https://github.com/schlagmichdoch/pairdrop

## Overview

#### Purpose and Entry Points
PairDrop is a browser-based, peer-to-peer file and text sharing system for local networks and internet-connected peers. The Node.js service starts from `server/index.js`; browser clients load `public/index.html` and initialize through `public/scripts/main.js`. The product is deployable as a container via `Dockerfile` and `docker-compose.yml`.

#### Browser Application Shell
The frontend is a vanilla HTML/ES6/CSS progressive web app. `public/index.html` defines the application document and loads the client scripts/styles. `public/scripts/main.js` coordinates application initialization, while `public/scripts/ui-main.js` and `public/scripts/ui.js` manage interaction and transfer-facing UI. `public/service-worker.js` provides PWA/offline asset behavior.

#### Client Signaling and Peer Connections
`public/scripts/network.js` is the browser networking boundary: it communicates with the signaling backend over WebSockets and establishes WebRTC data channels for direct transfers. WebRTC is the primary transfer path; signaling only coordinates discovery, connection negotiation, rooms, and pairing. `rtc_config_example.json` documents deployer-supplied ICE/STUN/TURN configuration.

#### Transfer and Device State
The browser maintains durable client-side identity, paired-device, and related state through IndexedDB-oriented logic in `public/scripts/persistent-storage.js`. Browser-tab coordination is handled by `public/scripts/browser-tabs-connector.js`, allowing concurrent tabs to share application behavior. Transfer payloads travel peer-to-peer over WebRTC; files may be grouped/downloaded using browser-side libraries referenced by the application.

#### Signaling Backend
The Node backend serves the static application and owns ephemeral connection/discovery state. `server/server.js` is the application-server layer, `server/ws-server.js` manages WebSocket signaling clients/messages, and `server/peer.js` models peer-level identity, visibility, pairing, room membership, or routing concerns. `server/helper.js` supports shared server behavior. This backend does not carry normal file payloads; it enables peers to form WebRTC connections.

#### Discovery, Pairing, and Rooms
Client/server signaling exposes peers based on local-network visibility, temporary public rooms, and persistent pairing secrets. Local peers can be discovered from private-IP context; public rooms and paired devices extend reach across networks. Pairing and room codes are control-plane mechanisms, while peer approval and WebRTC data channels remain the transfer boundary.

#### Deployment and Network Infrastructure
The production runtime is Node.js in Docker (`Dockerfile`, `docker-compose.yml`). Internet traversal may require a TURN service; `docker-compose-coturn.yml` provides an optional Coturn deployment and `turnserver_example.conf` is its configuration template. Development HTTPS/reverse-proxy setup is represented by `docker-compose-dev.yml` and `dev/nginx/default.conf`, with local OpenSSL certificate generation under `dev/openssl/create.sh`.

#### Localization and External Platform APIs
Localized UI strings are static browser assets under `public/lang/en.json` and sibling language files, loaded through `public/scripts/localization.js`. Important browser/runtime APIs are WebSocket, WebRTC, IndexedDB, Service Workers, and sharing/download APIs. Weblate is the translation service; STUN/TURN servers are the principal external network services.

Main entry points: [`public/scripts/main.js`](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/main.js) (Client initialization), [`public/scripts/network.js`](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/network.js) (Signaling & WebRTC), [`server/server.js`](https://github.com/schlagmichdoch/pairdrop/blob/master/server/server.js) (Static app server), [`server/ws-server.js`](https://github.com/schlagmichdoch/pairdrop/blob/master/server/ws-server.js) (WebSocket signaling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser PWA"]
  node_browser_shell["App document<br/>HTML shell<br/>[index.html]"]
  node_client_main["Client initialization<br/>ES6 client<br/>[main.js]"]
  node_ui["Transfer UI<br/>UI controllers<br/>[ui-main.js]"]
  node_network{{"Signaling &amp; WebRTC<br/>network boundary<br/>[network.js]"}}
  node_storage[("Persistent device state<br/>IndexedDB client")]
  node_tab_coordination["Tab coordination<br/>browser coordination"]
  node_service_worker["Offline assets<br/>service worker<br/>[service-worker.js]"]
  node_localization["Localized strings<br/>localization loader<br/>[localization.js]"]
  node_translations["Language catalog<br/>static JSON<br/>[en.json]"]
end

subgraph group_backend["Signaling backend"]
  node_node_entry["Node entrypoint<br/>Node.js entry<br/>[index.js]"]
  node_app_server["Static app server<br/>application server<br/>[server.js]"]
  node_ws_server{{"WebSocket signaling<br/>signaling server<br/>[ws-server.js]"}}
  node_peer_model["Peer routing state<br/>peer model<br/>[peer.js]"]
end

subgraph group_deployment["Deployment &amp; traversal"]
  node_container_runtime["Node container<br/>Docker deployment"]
  node_compose["Application compose<br/>container orchestration<br/>[docker-compose.yml]"]
  node_turn{{"TURN traversal service<br/>Coturn"}}
  node_ice_config["ICE configuration<br/>STUN/TURN template"]
end

node_browser_shell -->|"loads"| node_client_main
node_client_main -->|"initializes"| node_ui
node_client_main -->|"initializes"| node_network
node_client_main -->|"uses"| node_storage
node_client_main -->|"coordinates"| node_tab_coordination
node_browser_shell -->|"registers"| node_service_worker
node_client_main -->|"loads UI text"| node_localization
node_localization -->|"fetches"| node_translations
node_ui -->|"starts transfers"| node_network
node_network -->|"WebSocket signaling"| node_ws_server
node_network -.->|"WebRTC payload transfer between peers"| node_network
node_network -.->|"uses ICE servers"| node_ice_config
node_ice_config -.->|"may reference"| node_turn
node_node_entry -->|"starts"| node_app_server
node_app_server -->|"hosts"| node_ws_server
node_ws_server -->|"maintains"| node_peer_model
node_container_runtime -->|"runs"| node_app_server
node_compose -->|"builds and deploys"| node_container_runtime

click node_browser_shell "https://github.com/schlagmichdoch/pairdrop/blob/master/public/index.html"
click node_client_main "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/main.js"
click node_ui "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/ui-main.js"
click node_network "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/network.js"
click node_storage "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/persistent-storage.js"
click node_tab_coordination "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/browser-tabs-connector.js"
click node_service_worker "https://github.com/schlagmichdoch/pairdrop/blob/master/public/service-worker.js"
click node_localization "https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/localization.js"
click node_translations "https://github.com/schlagmichdoch/pairdrop/blob/master/public/lang/en.json"
click node_node_entry "https://github.com/schlagmichdoch/pairdrop/blob/master/server/index.js"
click node_app_server "https://github.com/schlagmichdoch/pairdrop/blob/master/server/server.js"
click node_ws_server "https://github.com/schlagmichdoch/pairdrop/blob/master/server/ws-server.js"
click node_peer_model "https://github.com/schlagmichdoch/pairdrop/blob/master/server/peer.js"
click node_container_runtime "https://github.com/schlagmichdoch/pairdrop/blob/master/Dockerfile"
click node_compose "https://github.com/schlagmichdoch/pairdrop/blob/master/docker-compose.yml"
click node_turn "https://github.com/schlagmichdoch/pairdrop/blob/master/docker-compose-coturn.yml"
click node_ice_config "https://github.com/schlagmichdoch/pairdrop/blob/master/rtc_config_example.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_shell,node_client_main,node_ui,node_network,node_storage,node_tab_coordination,node_service_worker,node_localization,node_translations toneBlue
class node_node_entry,node_app_server,node_ws_server,node_peer_model toneAmber
class node_container_runtime,node_compose,node_turn,node_ice_config toneMint
```

## Components

### Browser PWA

- [App document](https://github.com/schlagmichdoch/pairdrop/blob/master/public/index.html): HTML shell · Loads the PWA assets and client entrypoint. · `public/index.html`
- [Client initialization](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/main.js): ES6 client · `public/scripts/main.js`
- [Transfer UI](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/ui-main.js): UI controllers · `public/scripts/ui-main.js`
- [Signaling & WebRTC](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/network.js): network boundary · Uses signaling for negotiation and WebRTC data channels for payloads. · `public/scripts/network.js`
- [Persistent device state](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/persistent-storage.js): IndexedDB client · Stores identity and paired-device state. · `public/scripts/persistent-storage.js`
- [Tab coordination](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/browser-tabs-connector.js): browser coordination · `public/scripts/browser-tabs-connector.js`
- [Offline assets](https://github.com/schlagmichdoch/pairdrop/blob/master/public/service-worker.js): service worker · `public/service-worker.js`
- [Localized strings](https://github.com/schlagmichdoch/pairdrop/blob/master/public/scripts/localization.js): localization loader · `public/scripts/localization.js`
- [Language catalog](https://github.com/schlagmichdoch/pairdrop/blob/master/public/lang/en.json): static JSON · `public/lang/en.json`

### Signaling backend

- [Node entrypoint](https://github.com/schlagmichdoch/pairdrop/blob/master/server/index.js): Node.js entry · `server/index.js`
- [Static app server](https://github.com/schlagmichdoch/pairdrop/blob/master/server/server.js): application server · Serves browser assets and owns ephemeral discovery state. · `server/server.js`
- [WebSocket signaling](https://github.com/schlagmichdoch/pairdrop/blob/master/server/ws-server.js): signaling server · Coordinates discovery, rooms, pairing, and WebRTC negotiation. · `server/ws-server.js`
- [Peer routing state](https://github.com/schlagmichdoch/pairdrop/blob/master/server/peer.js): peer model · Represents identity, visibility, pairing, and room membership. · `server/peer.js`

### Deployment & traversal

- [Node container](https://github.com/schlagmichdoch/pairdrop/blob/master/Dockerfile): Docker deployment · `Dockerfile`
- [Application compose](https://github.com/schlagmichdoch/pairdrop/blob/master/docker-compose.yml): container orchestration · `docker-compose.yml`
- [TURN traversal service](https://github.com/schlagmichdoch/pairdrop/blob/master/docker-compose-coturn.yml): Coturn · Optional relay for internet-connected peers. · `docker-compose-coturn.yml`
- [ICE configuration](https://github.com/schlagmichdoch/pairdrop/blob/master/rtc_config_example.json): STUN/TURN template · `rtc_config_example.json`

## Connections

- App document → Client initialization: loads
- Client initialization → Transfer UI: initializes
- Client initialization → Signaling & WebRTC: initializes
- Client initialization → Persistent device state: uses
- Client initialization → Tab coordination: coordinates
- App document → Offline assets: registers
- Client initialization → Localized strings: loads UI text
- Localized strings → Language catalog: fetches
- Transfer UI → Signaling & WebRTC: starts transfers
- Signaling & WebRTC → WebSocket signaling: WebSocket signaling
- Signaling & WebRTC → Signaling & WebRTC: WebRTC payload transfer between peers
- Signaling & WebRTC → ICE configuration: uses ICE servers
- ICE configuration → TURN traversal service: may reference
- Node entrypoint → Static app server: starts
- Static app server → WebSocket signaling: hosts
- WebSocket signaling → Peer routing state: maintains
- Node container → Static app server: runs
- Application compose → Node container: builds and deploys
