tomevault-io PeaPod Architecture Guide
Use this skill when you need to understand or modify PeaPod's architecture.
Key architectural decisions
1. pea-core is host-driven with NO I/O
- pea-core is a pure-logic library. It never opens sockets, reads files, or makes HTTP calls.
- The host (platform implementation) calls pea-core with events and executes the returned actions.
- This makes pea-core portable across all platforms and testable without mocking network I/O.
- If you're about to add
tokio,std::net,reqwest, orstd::fsto pea-core — STOP. That belongs in the platform implementation.
2. All platforms share the same wire format
- Protocol messages are defined in
pea-core/src/protocol.rsand encoded with bincode + 4-byte LE length framing. - Every platform (Linux, Windows, Android, iOS, macOS) must produce and consume identical bytes on the wire.
- Never create platform-specific message types or encodings.
3. Discovery is LAN-only
- UDP multicast on 239.255.60.60:45678 with TTL=1.
- Beacons include protocol_version, device_id, public_key, and listen_port.
- No central server, no cloud discovery, no WAN discovery.
4. Security is not optional
- X25519 key exchange on every TCP connection.
- ChaCha20-Poly1305 AEAD encryption for all post-handshake traffic.
- SHA-256 integrity verification for every chunk.
- Counter-based nonces (never reuse).
Component boundaries
| Component | Crate | What it does | What it does NOT do |
|---|---|---|---|
| Protocol logic | pea-core | Chunk splitting, scheduling, integrity, wire codec | Any I/O |
| Identity/crypto | pea-core | Key generation, key exchange, encrypt/decrypt helpers | Key storage (host responsibility) |
| Discovery | pea-linux/windows/etc | UDP multicast send/receive, peer tracking | Protocol message parsing (uses pea-core wire codec) |
| Transport | pea-linux/windows/etc | TCP connections, handshake, encrypted framing | Chunk logic (calls pea-core on_message_received) |
| Proxy/VPN | pea-linux/windows/etc | Traffic interception, HTTP parsing | Scheduling (calls pea-core on_incoming_request) |
Data flow reference
See docs/ARCHITECTURE.md for Mermaid diagrams of:
- Layer placement
- System architecture (two-device view)
- Host ↔ pea-core interaction
- Accelerated download sequence
- Discovery and connection handshake
When to update architecture docs
Update docs/ARCHITECTURE.md when:
- Adding a new component or crate
- Changing how components interact
- Adding a new message type to the protocol
- Changing the security model
Update docs/PROTOCOL.md when:
- Adding or changing message types in
protocol.rs - Changing the wire format or encoding
- Changing discovery or handshake behavior
Converted and distributed by TomeVault — claim your Tome and manage your conversions.