aeroxy/drift

• Overall shape: drift is a single Rust binary that bundles a React/TypeScript frontend and a WebSocket-based transfer engine. The binary can act as a local server, an outbound client to another drift instance, or a one-shot CLI tool for send/list/pull operations.

• Primary runtime boundary: there are two peers in every transfer. One side listens on a port and serves the web UI; the other side may connect outbound to --target. Once connected, both peers can expose their own filesystem and browse the remote one, so the app is naturally bidirectional rather than “server vs client” in a fixed sense.

• CLI entry layer: src/main.rs and src/config.rs parse the command set (serve, send, ls, pull, plus legacy flat args) and decide whether the process should launch the web server, open an outbound session, or do a one-off transfer and exit.

• Server subsystem: src/server/ contains the HTTP/WebSocket-facing backend. ws_handler.rs manages the encrypted WebSocket session, file_api.rs serves browse/info requests, browser_transfer.rs coordinates transfers initiated from the UI, and transfer_receiver.rs writes incoming data and handles extraction. This is the main boundary between the UI and filesystem.

• Client subsystem: src/client/ is the outbound side that connects to a remote drift instance when --target is set. browse.rs supports remote directory listing for ls, pull.rs implements downloading from a remote host, send.rs handles push/send mode, and reconnect.rs provides session re-establishment after disconnects.

• Protocol layer: src/protocol/ defines the wire contract. Control traffic uses encrypted JSON ControlMessage values; file payloads use a binary chunk format with a UUID and offset. The protocol is designed for concurrent requests and out-of-order replies, so correlation IDs matter to the architecture.

• Security layer: src/crypto/ implements the session security model. Peers perform an X25519 handshake, derive directional symmetric keys with HKDF-SHA256, optionally authenticate with a password-based HMAC challenge/response, and then encrypt all traffic with ChaCha20-Poly1305. The security boundary is the network link; the code assumes trusted peers after connection.

• Filesystem operations: src/fileops/ isolates local file access. browse.rs canonicalizes and validates browse paths against the root to prevent traversal, reader.rs and writer.rs implement chunked async I/O, and compress.rs / decompress.rs convert directories to and from .tar.gz for recursive folder transfer.

• Transfer behavior: file data moves in 64 KB chunks over encrypted WebSocket binary frames. Files are streamed directly; folders are compressed before upload and extracted on receipt. Large transfers therefore flow through the protocol layer into chunked file I/O rather than through a single buffered payload.

• Frontend subsystem: frontend/ is a React + TypeScript UI built with Vite/Bun. The main UI is a two-pane file browser with connection modal, path bar, file list, toolbar, and transfer progress bar. Hooks such as useWebSocket and useTransfer bind the UI to backend events and transfer state.

• Embedding and packaging: build.rs builds the frontend before Rust compilation, and src/frontend.rs serves the generated assets from the binary via embedded static files. That makes the shipped artifact self-contained: no separate web app deployment is required.

• Operational modes: the same codebase supports three distinct flows: interactive browsing via the web UI, direct CLI file movement (send, pull, ls), and reconnectable long-lived sessions. This is important for diagramming because the UI and CLI are thin entry points into the same underlying transport and filesystem subsystems.

• Testing and validation: frontend integration tests in frontend/test/ spin up real drift processes, transfer actual files over WebSocket, and verify checksums plus cleanup of temporary .drift/ directories. The tests exercise the full stack, not just isolated units.

• Useful diagram boundary: a good architecture diagram should show four main boxes: CLI/runtime orchestration, encrypted WebSocket protocol + crypto, filesystem/transfer services, and embedded frontend UI — with the WebSocket link as the central data path and the local filesystem as the protected backend resource.