Architecture and Docs
SignalShare is an open-source transfer engine focused on direct browser-to-browser delivery first, with secure relay fallback when required. This page summarizes how transport, signaling, security, and operational behavior work in the current codebase.
System Overview
Client Layer
Next.js App Router UI with Zustand stores, transfer hooks, animated status views, and IndexedDB history.
Signaling Layer
Fastify WebSocket route (`/api/ws`) coordinates discovery, session creation, code/link joins, and WebRTC message relay.
Transfer Layer
Local mode uses WebRTC DataChannels. Remote mode streams chunks via in-memory relay + SSE progress channels.
Network Flow
Transmission Modes
Direct Channel (LAN)
- Devices must be on same local network
- Transfers via WebRTC data channels
- Zero bytes stored on any server
- Highest potential throughput
Relay Mode (Remote)
- Temporary server memory stream
- Used when peers are not local
- Complete auto-deletion upon reception
- Time-limited secure keys
Session Lifecycle
1. Sender creates session (`create-session`) and receives code + share link.
2. Receiver joins via code (`join-by-code`) or link (`join-by-link`).
3. Server determines `local` or `remote` based on subnet relation.
4. Local mode: `receiver-rtc-ready` triggers offer/answer + ICE exchange.
5. Remote mode: sender streams chunks; receiver consumes SSE download + progress.
6. Session completes, errors, or cancels, then cleanup occurs automatically.
API Endpoints
HTTP
GET /health - service heartbeat and timestamp.
GET /api/transfer/:id - transfer metadata for a session.
GET /api/transfer/:id/download - SSE stream for relay chunks.
GET /api/transfer/:id/progress - SSE stream for progress events.
WebSocket (`/api/ws`)
create-session, join-by-code, join-by-link
send-to-peer, accept-transfer, decline-transfer
rtc-offer, rtc-answer, rtc-ice-candidate, receiver-rtc-ready
file-chunk, file-chunk-end, transfer-progress, transfer-complete
transfer-cancel, transfer-error, update-identity
Security Philosophy
✓ No account system or identity tracking
✓ No permanent storage (SSD/HDD) used
✓ Files are streamed directly in-memory
✓ Relay data automatically detonates after transmission
✓ Local Transfer History is securely stored in your browser's IndexedDB
Client Capabilities
Global Drag & Drop
Drag files anywhere on the application window to initiate an instant transfer overlay. Highly optimized for desktop users.
Directory Auto-Zipping
Drop entire folders onto the scanner. The client uses jszip to aggregate and compress the directory tree into a single archive before sending it over WebRTC.
Open Source Notes
SignalShare is maintained as an open-source project with active changelog tracking and architecture-first documentation.
Start with README.md for setup and architecture, then see the in-app timeline at /change-logs for release history.
Contributions are welcome via issues and pull requests on GitHub.
Known Constraints
• Requires a browser with WebRTC support.
• Strict NATs or corporate firewalls may block direct P2P connections.
• Heavy background tabs on mobile OS (iOS/Android) may pause WebSocket signaling.