Documentation
Note
wayhouse is a work in progress. These documents describe the design the code implements, but details can still change. See the notice in the top-level README.
Design documents (00–12)
The numbered chapters are the source of truth for the design: when the code and a chapter disagree, the chapter wins and the code (or the chapter) gets fixed.
Start here: 00 Overview for the problem and the vocabulary, then 02 Architecture for how the pieces fit together.
| Read this | When you want to know |
|---|---|
| 00 Overview | What problem this solves, goals, non-goals, glossary |
| 01 Requirements | Functional and non-functional requirements (the NFR latency budgets live here) |
| 02 Architecture | Data plane vs. control plane, components, data flows |
| 03 Routing | Route rules, matchers, balancers, sniffers, external resolvers |
| 04 Transport and client IP | TCP/UDP handling, PROXY protocol, TPROXY transparent mode |
| 05 Configuration | The full config schema with examples |
| 06 Operations and observability | Metrics, logs, health checks, draining, admin and fleet endpoints, HA operations |
| 07 Security and DDoS | Filters, rate limits, amplification guard, sniffer sandbox |
| 08 Roadmap | Phases 0–14 with their status, and what is left |
| 09 Technology choices | Libraries, alternatives and the ADR table of locked decisions |
| 10 Distributed control plane | wayhouse-controller, wayhouse-aggregator, wayhouse-ui, Raft HA, canary rollout, regional health |
| 11 Backend transport | WireGuard transport and wayhouse-agent for origins on other networks |
| 12 Deployment | Container images, many-port proxies under Docker and Kubernetes |
| ACME certificates | Controller-issued certificates (DNS-01), sites, renewal, metrics |
Feature specs and plans
superpowers/ holds the design spec and the step-by-step
implementation plan written before each larger change since the roadmap phases were
finished. They are kept as a record of why things were built the way they were; see
superpowers/README.md.
Elsewhere in the repository
../deploy/README.md: reference images, Compose demo and Kubernetes manifests.../crates/wayhouse-sniffer-abi/README.md: the WASM sniffer ABI (guest side); the official sniffers are inwayhouse-proxy/sniffers.upgrading.md: upgrading a fleet one component at a time: compatibility window, version table, order of operations, rollback.web-proxy.md: publishing HTTP(S) sites through the packaged Caddy (wayhouse-web-sync, thewayhouse-caddyimage, compose and Kubernetes recipes).sniffers.md: sniffer manifest, registry index and verification formats.../crates/wayhouse-bench/README.md: the latency / load harness.../crates/wayhouse-config/fuzz/README.md: fuzz targets.../HANDOVER.md: current state, known follow-ups and gotchas.