// Domain patterns for peer-to-peer system architecture — network topologies, NAT traversal, peer discovery, data distribution, consistency without central authority, identity and trust, and incentive mechanisms. Use when designing or evaluating a decentralized, peer-to-peer, or mesh-networked system.
| name | system-type-peer-to-peer |
| description | Domain patterns for peer-to-peer system architecture — network topologies, NAT traversal, peer discovery, data distribution, consistency without central authority, identity and trust, and incentive mechanisms. Use when designing or evaluating a decentralized, peer-to-peer, or mesh-networked system. |
Patterns, failure modes, and anti-patterns for decentralized peer-to-peer systems.
When to use. Systems where any peer can hold any data and queries are exploratory — file sharing (early Gnutella), social feeds, informal mesh networks. When simplicity and resilience to churn matter more than lookup efficiency. When to avoid. Systems that need efficient key-based lookups. Large networks where flooding creates unacceptable bandwidth overhead. When query latency must be predictable. Key decisions. TTL (time-to-live) on forwarded messages, fanout degree (how many peers each node forwards to), duplicate message suppression, supernode election for partial structure.
When to use. Efficient key-value lookups in a decentralized network — content-addressable storage, distributed hash tables (Kademlia, Chord, Pastry). When you need O(log n) lookups instead of flooding. When to avoid. When keyword search or range queries are needed (DHTs only do exact key lookup). When the network has extremely high churn (DHT routing tables become stale faster than they can repair). Very small networks where the DHT overhead exceeds the benefit. Key decisions. Hash function and key space design, replication factor (k-bucket size in Kademlia), routing table refresh strategy, handling network partitions and merges, iterative vs recursive lookup.
When to use. When pure decentralization is a goal but some coordination is practical — BitTorrent (trackers + DHT), Skype's original architecture, many production P2P systems. Super-peers handle discovery and coordination; regular peers handle data transfer. When to avoid. When the super-peers become single points of failure that negate the decentralization benefit. When regulatory requirements demand fully decentralized operation. Key decisions. Super-peer election and rotation, fallback when super-peers fail, load balancing across super-peers, preventing super-peer capture or censorship, graceful degradation to pure P2P when coordination layer fails.
When to use. Local-area networks, IoT device clusters, real-time collaboration with small groups. When peers need direct, low-latency communication and the group size is bounded. When to avoid. Large networks — full mesh is O(n^2) connections. Wide-area networks where direct connections between all peers are impossible. Key decisions. Mesh density (full vs partial), relay selection for peers that can't connect directly, mesh topology maintenance, partition detection and healing.
When to use. Discovering your public IP and port mapping when behind a NAT. The first step in establishing direct peer connections. Works for most consumer NATs (cone NATs). When to avoid. Symmetric NATs, which assign different external ports per destination — STUN alone can't traverse these. Enterprise firewalls that block UDP entirely. The hard part. STUN servers must be publicly reachable. You need fallback for the ~8-15% of networks where STUN fails.
When to use. Fallback when direct connection is impossible — symmetric NATs, restrictive firewalls, corporate networks. All traffic relays through a TURN server. When to avoid. As a primary strategy — TURN servers are expensive (they relay all traffic) and add latency. Use only when STUN and hole punching fail. Key decisions. TURN server provisioning and cost (bandwidth is proportional to usage), geographic distribution for latency, credential rotation, capacity planning for peak concurrent relayed connections.
When to use. The standard framework for trying multiple connectivity methods in order — direct connection, STUN, TURN — and selecting the best one. Used by WebRTC. The right default for any new P2P connection system. When to avoid. Systems where you control both endpoints and the network (e.g., data center to data center) — ICE's complexity isn't needed. Key decisions. Candidate gathering timeout (waiting too long delays connection; too short misses viable paths), aggressive vs regular nomination, trickle ICE for faster initial connection, handling ICE restart on network change.
When to use. Establishing direct connections through NATs by coordinating simultaneous outbound connections from both peers. Works for most cone-type NATs. Essential for keeping TURN costs down. When to avoid. Can't rely on it exclusively — success rate varies by NAT type (works ~80% of the time for UDP, ~60% for TCP in practice). The hard part. Requires a rendezvous server to coordinate the punch. Timing is critical — both sides must send within a narrow window. TCP hole punching is less reliable than UDP due to the three-way handshake. Some NAT devices randomize port mappings, defeating the technique.
When to use. The initial entry point for new peers joining the network. Every P2P system needs at least one discovery mechanism for the first connection. Bootstrap nodes are well-known, stable peers that provide initial routing information. When to avoid. As the only discovery mechanism — bootstrap nodes are centralized points that can be blocked or taken down. Key decisions. Number and geographic distribution of bootstrap nodes, hardcoded vs DNS-based discovery, fallback when all bootstrap nodes are unreachable, rate limiting to prevent abuse.
When to use. Finding peers on the same local network without any server infrastructure. LAN gaming, local file sharing, IoT device pairing. Works even when the internet is unavailable. When to avoid. Cross-network discovery. Networks where multicast is disabled (many enterprise networks, most cloud VPCs). Key decisions. Service type naming, conflict resolution when multiple instances exist, discovery refresh interval, privacy implications of announcing presence on the local network.
When to use. Decentralized discovery once the peer has joined the network. Peers publish their addresses under known keys; other peers look them up. Combines with bootstrap nodes — bootstrap gets you into the DHT, DHT handles ongoing discovery. When to avoid. When the DHT itself is not yet bootstrapped (chicken-and-egg problem). Very small or ephemeral networks where DHT maintenance overhead exceeds the benefit. Key decisions. Key design for peer records, record TTL and refresh, Sybil resistance in the DHT, handling peers behind NAT (store relay addresses, not direct addresses).
When to use. Peers share their known peer lists with each other. Reduces load on bootstrap nodes and trackers. BitTorrent uses this extensively — once connected to a few peers, you learn about more through gossip. When to avoid. When peer identity is sensitive (PEX reveals who knows whom). When Sybil attacks are a concern (a malicious peer can flood the network with fake peer addresses). Key decisions. Rate limiting peer exchange, validation of received addresses, preference for recently-seen peers, mixing PEX with other discovery mechanisms for resilience.
When to use. When data integrity is paramount — files are addressed by the hash of their content. IPFS, Git, Nix, Docker image layers. Enables deduplication, caching, and verification without trusting the source. When to avoid. Mutable data that changes frequently — each change produces a new address, requiring indirection (naming systems, mutable pointers) to track the latest version. Key decisions. Hash algorithm (SHA-256 is standard; avoid MD5/SHA-1), chunk size for large files, Merkle tree structure (determines parallel verification and partial downloads), garbage collection of unreferenced content.
When to use. Distributing large files to many recipients simultaneously. Each downloader becomes an uploader, distributing the bandwidth cost across the swarm. Scales better with more peers. When to avoid. Small files (the coordination overhead exceeds the benefit). Real-time streaming where pieces must arrive in order. When upload bandwidth is extremely constrained on most peers. Key decisions. Piece size (too small increases metadata overhead; too large reduces parallelism), piece selection strategy (rarest-first to maximize availability), choking/unchoking algorithm for fairness, endgame mode for the last few pieces.
When to use. Disseminating updates across a large, loosely-connected network where guaranteed delivery isn't critical — membership lists, configuration updates, eventually-consistent state. Simple, robust, and tolerant of failures. When to avoid. When strong consistency or ordering guarantees are needed. When message volume is high (gossip amplifies each message by the fanout factor). Key decisions. Fanout degree, push vs pull vs push-pull, message deduplication, crashing vs byzantine fault assumption, convergence time estimation, protocol period.
When to use. Topic-based message distribution without a central broker — decentralized social feeds, blockchain transaction propagation, collaborative editing. GossipSub (used by libp2p/Ethereum) adds mesh structure to reduce bandwidth. When to avoid. When message ordering is critical (P2P pub/sub is typically unordered or partially ordered). When message loss is unacceptable without additional reliability layers. Key decisions. Topic design and subscription management, mesh degree (D parameter in GossipSub), message validation before forwarding, score-based peer selection for reliability, flood publish for high-priority messages.
When to use. Concurrent editing without coordination — collaborative documents, shared counters, distributed sets. CRDTs guarantee convergence regardless of message ordering or network partitions. When to avoid. When the data model doesn't map to known CRDT types. When the metadata overhead (vector clocks, tombstones) exceeds the data size. When "last writer wins" is actually acceptable. Key decisions. CRDT type selection (G-Counter, PN-Counter, LWW-Register, OR-Set, RGA for sequences), compaction strategy for metadata growth, tombstone garbage collection, integration with persistence layer.
When to use. Tracking causality between events in a distributed system — knowing that event A happened before event B, or that they're concurrent. Essential for conflict detection in eventually-consistent systems. When to avoid. When the number of peers is very large (vector clocks grow linearly with participants). When wall-clock ordering is sufficient (i.e., last-writer-wins is acceptable). Key decisions. Clock pruning for large participant sets, dotted version vectors for better scalability, integration with merge functions, clock synchronization on peer join/leave.
When to use. Efficiently determining what data differs between two peers. Instead of comparing every record, compare tree hashes top-down — only descend into subtrees that differ. Used by Cassandra, Dynamo, IPFS. When to avoid. When the dataset is small enough that full comparison is cheap. When data changes so rapidly that the tree is constantly being rebuilt. Key decisions. Tree depth and branching factor, rebuild frequency vs incremental updates, hash function choice, key space partitioning.
When to use. When you need a tamper-evident, append-only log agreed upon by mutually untrusting parties. Financial transactions, provenance tracking, governance voting where auditability and censorship resistance are primary requirements. When to avoid. Almost always. If participants can trust a single party (or a small federation), a database is simpler, faster, and cheaper. If data needs to be mutable or deletable. If transaction throughput matters more than decentralization. Key decisions. Consensus mechanism (PoW is energy-expensive, PoS has different trust assumptions, PBFT works for permissioned networks), block size and time, smart contract language and VM, on-chain vs off-chain data, finality guarantees.
When to use. Every P2P system. Peers are identified by their public key (or a hash of it). No central authority issues identities — peers generate their own key pairs. This is the foundation of P2P authentication. When to avoid. Never — if your P2P system doesn't use cryptographic identity, it has no authentication. Key decisions. Key algorithm (Ed25519 is the modern default), key derivation and storage, key rotation mechanism, human-readable identifiers (mapping long keys to names — hard problem), multi-device identity.
When to use. Building trust without a central certificate authority. Peers vouch for each other, creating a graph of trust relationships. PGP's model. Useful in communities where social connections are meaningful. When to avoid. Systems where users don't know each other. Large-scale systems where the trust graph becomes unwieldy. When the consequences of misplaced trust are severe (financial, safety). Key decisions. Trust transitivity depth (how far trust propagates through the graph), revocation propagation, bootstrapping trust for new identities, handling key compromise in the trust graph.
When to use. Any P2P system where a single entity could gain disproportionate influence by creating many fake identities. Sybil attacks undermine voting, reputation, DHT routing, and fair resource allocation. When to avoid. Closed networks with authenticated membership (the Sybil problem doesn't exist if identities are verified out-of-band). Key decisions. Proof-of-work (computational cost per identity), proof-of-stake (economic cost), social verification (vouching), puzzle-based admission, rate-limiting identity creation, the tradeoff between openness and Sybil resistance.
When to use. Always. All peer-to-peer communication should be encrypted in transit — even on trusted networks, because P2P networks are inherently adversarial (you're connecting to strangers). When to avoid. Never. Unencrypted P2P traffic is trivially observable, modifiable, and injectable by any network intermediary. Key decisions. Noise Protocol Framework (used by libp2p, WireGuard — lightweight, modern), TLS 1.3 for TCP connections, DTLS for UDP, forward secrecy (ephemeral key exchange), peer authentication during handshake.
When to use. Encouraging reciprocal resource contribution — peers that upload get better download speeds. BitTorrent's choking algorithm is the canonical example. Simple, effective, and self-enforcing. When to avoid. When new peers can't bootstrap (they have nothing to offer yet). When the resource being shared isn't divisible (you can't partially share a database query result). Key decisions. Optimistic unchoking (giving new peers a chance), detection of free-riding, handling asymmetric bandwidth (peers with slow upload), interaction with super-seeding.
When to use. When tit-for-tat is too coarse — you want fine-grained accounting of resource contribution and consumption. Filecoin's storage market, bandwidth credits, compute tokens. When to avoid. When the accounting infrastructure is more complex than the system it's incentivizing. When the token introduces speculation and financialization that distracts from the system's purpose. Key decisions. On-chain vs off-chain accounting, double-spend prevention, price discovery mechanism, inflation/deflation policy, handling disputes.
When to use. Peer quality varies and users benefit from knowing which peers are reliable — marketplace trust scores, content quality ratings, service reliability metrics. When to avoid. When reputation can be trivially gamed (Sybil attacks to boost reputation). When reputation creates lock-in that prevents new participants from competing. Key decisions. Local vs global reputation (local is more Sybil-resistant but less portable), decay over time, bootstrapping reputation for newcomers, handling reputation manipulation, privacy implications.
Use when the /systems-design mode is active. 9-phase structured design methodology -- problem framing, system classification, constraints, candidate architectures, tradeoff analysis, risk review, refinement, migration planning, and documentation. Governs conversation flow, delegation patterns, and user validation checkpoints.
Use when the /systems-design-review mode is active. 7-step design review methodology -- understand the design, classify the system, evaluate against codebase, adversarial analysis, tradeoff validation, synthesis, and action items. Governs conversation flow, delegation patterns, and user validation checkpoints.
Adversarial review of a system design from 6 critical perspectives -- SRE, security, staff engineer, finance, operator, and developer advocate. Produces a unified risk assessment. Use for INTERACTIVE on-demand reviews during a design conversation (/adversarial-review). For RECIPE-DRIVEN reviews (where prior step context is needed), use the systems-design-critic agent instead.
Domain patterns for Azure cloud architecture — compute selection, managed services, identity (Entra ID), networking, data platform, messaging, deployment, cost management, and operational patterns. Use when designing or evaluating a system deployed on Microsoft Azure.
Domain patterns for single-page application architecture — client-side routing, state management, rendering strategies, authentication, performance, and offline support. Use when designing or evaluating a browser-based SPA, progressive web app, or rich client-side application.
Domain-Driven Design as a lens for system architecture — bounded contexts, aggregates, ubiquitous language, context mapping, domain events, and strategic vs tactical patterns. Use when modeling complex business domains, defining service boundaries, or evaluating whether a system's structure reflects its domain.
