The Design Intent
PeerPass is a deliberate exercise in removing the abstraction layer. No cloud storage, no HTTP API, no third-party SDK. Files move directly between peers over a TCP connection designed and implemented from scratch — protocol, concurrency model, and all.
The goal was to understand what networking actually requires at the socket level: the handshake design, buffer management, concurrency constraints, and failure modes that libraries quietly absorb.
The Protocol
Before any file data moves, the sender transmits a binary header containing filename, file size, and a SHA-256 checksum. The receiver validates the checksum post-transfer to detect corruption. File data is chunked through an 8KB byte buffer — large files transfer without holding the entire payload in memory.
Concurrency Model
The server uses a thread-per-connection model: each client connection spawns a dedicated thread for that session. The critical constraint was handling multiple simultaneous transfers without shared mutable state causing race conditions. State is kept strictly thread-local throughout. The server runs on EC2 behind Nginx; the frontend is a React app showing live transfer progress via Axios.
System architecture: client–server socket flow, upload/download handlers, multiport routing, and the thread-per-connection model.
Key Technical Decisions
- —Binary handshake protocol — filename, file size, SHA-256 checksum transmitted before any data moves
- —8KB chunked byte buffer — large file transfers without holding payload in memory
- —Thread-per-connection with strictly thread-local state — concurrent transfers without race conditions
- —EC2 deployment behind Nginx with connection pooling for concurrent sessions
What Broke It
PeerPass is live and reliable for real transfers. The most valuable debugging session: an early bug where transfers silently corrupted files on unstable connections — bytes went missing with no error thrown. Tracking it down required understanding exactly what TCP guarantees and what it doesn't. The textbook explanation became real understanding.