How schlagmichdoch/pairdrop works
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: main.js Client initialization · network.js Signaling & WebRTC · server.js Static app server · ws-server.js WebSocket signaling
Components 17
Browser PWA
- App document · Loads the PWA assets and client entrypoint.
public/index.html - Client initialization
public/scripts/main.js - Transfer UI
public/scripts/ui-main.js - Signaling & WebRTC · Uses signaling for negotiation and WebRTC data channels for payloads.
public/scripts/network.js - Persistent device state · Stores identity and paired-device state.
public/scripts/persistent-storage.js - Tab coordination
public/scripts/browser-tabs-connector.js - Offline assets
public/service-worker.js - Localized strings
public/scripts/localization.js - Language catalog
public/lang/en.json
Signaling backend
- Node entrypoint
server/index.js - Static app server · Serves browser assets and owns ephemeral discovery state.
server/server.js - WebSocket signaling · Coordinates discovery, rooms, pairing, and WebRTC negotiation.
server/ws-server.js - Peer routing state · Represents identity, visibility, pairing, and room membership.
server/peer.js
Deployment & traversal
- Node container
Dockerfile - Application compose
docker-compose.yml - TURN traversal service · Optional relay for internet-connected peers.
docker-compose-coturn.yml - ICE configuration
rtc_config_example.json
Connections 18
- 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