Early-stage software. Shurli is experimental and built with AI assistance. It will have bugs. Not recommended for production or safety-critical use. Read the disclaimer.
Documentation
Engineering Journal

Engineering Journal

This document captures the why behind every significant architecture decision in Shurli. Each entry follows a lightweight ADR (Architecture Decision Record) format: what problem we faced, what options we considered, what we chose, and what trade-offs we accepted.

New developers, contributors, and future-us should be able to read this and understand not just what the code does, but why it’s shaped the way it is.

Reading Guide

  • ADR-0XX: Core architecture decisions made before the batch system
  • ADR-X0Y: Batch-specific decisions (A=reliability, B=code quality, etc.)
  • Each ADR is self-contained - read any entry independently
  • Entries link to source files and commits where relevant

Sections

SectionADRsFocus
Core ArchitectureADR-001 to ADR-008Foundational technology choices
Batch A: ReliabilityADR-A01 to ADR-A04Timeouts, retries, DHT, integration tests
Batch B: Code QualityADR-B01 to ADR-B04Dedup, logging, errors, versioning
Batch C: Self-HealingADR-C01 to ADR-C03Config backup, commit-confirmed, watchdog
Batch D: libp2p FeaturesADR-D01 to ADR-D04AutoNAT, QUIC, Identify, smart dialing
Batch E: New CapabilitiesADR-E01 to ADR-E02Relay health, headless invite/join
Batch F: Daemon ModeADR-F01 to ADR-F04Unix socket, cookie auth, hot-reload
Batch G: Test CoverageADR-G01 to ADR-G04Docker tests, relay binary, injectable exit, audit protocol
Batch H: ObservabilityADR-H01 to ADR-H03Prometheus, nil-safe pattern, auth callback
Pre-Batch IADR-Ia01 to ADR-Ib02Makefile, PAKE invite, DHT namespaces
Batch I: Adaptive Path SelectionADR-I01 to ADR-I06Interface discovery, dial racing, path tracking, network monitoring, STUN, peer relay
Post-I-2: Trust & DeliveryADR-J01 to ADR-J06Peer notify, HMAC, relay admin, SAS verification, reachability, history
Pre-Phase 5 HardeningADR-K01 to ADR-K03Startup race, CGNAT detection, stale addresses, service deployment
Phase 5: Network ResilienceADR-L01 to ADR-L08Native mDNS, PeerManager, stale cleanup, IPv6 probing, relay-discard
Phase 5: Relay DecentralizationADR-RD01 to ADR-RD05Peer relay, DHT relay discovery, health-aware selection, bandwidth, layered bootstrap
Dev ToolingADR-DT01 to ADR-DT03Go doc sync pipeline, relay setup subcommand, directory consolidation
Phase 6: ACL + Relay Security + Client InvitesADR-M01 to ADR-M08Roles, macaroons, invite deposits, sealed vault, remote unseal, 2FA
Phase 7: ZKP Privacy LayerADR-N01 to ADR-N18gnark PLONK, Poseidon2 Merkle tree, membership proofs, range proofs, BIP39 keys
Phase 8: Identity & Remote AdminADR-O01 to ADR-O17Unified BIP39 seed, encrypted identity, recovery, remote admin, MOTD, goodbye, session tokens
Seed Relay Separation & Init FlowADR-P01 to ADR-P05Discovery-only seed relays, server-side circuit ACL, init flow, config set
Phase 9: SDK, Plugins & Protocol ConsolidationADR-Q01 to ADR-Q05Invite v1/v2 deletion, protocol ID helpers, bootstrap extraction, file transfer plugin
Phase 9: File Transfer ArchitectureADR-R01 to ADR-R09FastCDC, BLAKE3, zstd, Reed-Solomon, RaptorQ, parallel streams, receive permissions, rate limiting
Post-Chaos Network HardeningADR-S01 to ADR-S07Black hole reset, ForceReachabilityPrivate, constrained dial, VPN detection, gateway tracking, dial worker workaround, autorelay tuning
File Transfer HardeningADR-R10 to ADR-R16DDoS defense (7 layers), queue persistence (HMAC), path privacy, checkpoint resume, queue backpressure, name normalization, relay transport
Phase 8B: Per-Peer Data GrantsADR-T01 to ADR-T10Node-level enforcement, macaroon grants, dual-store (GrantStore + Pouch), binary stream header, P2P delivery protocol, delegation, notifications, audit log, rate limiting, backoff reset
Phase 9: Plugin Security Threat AnalysisADR-U01 to ADR-U08Trusted computing base, WASM host function API, supply chain defense, decomposed permissions, lifecycle state machine, credential isolation, AI-era constraints, registry design
Phase 9: Grant Receipt ProtocolADR-V01 to ADR-V05Relay-issued receipts, client-side grant cache, smart pre-transfer check, per-chunk circuit byte tracking, smart reconnection
Phase 9: Relay Circuit InvestigationADR-W01 to ADR-W03Tier-aware session limits, receiver busy retry, seed relay churn (superseded by Grant Receipt Protocol)