Chris Nennemann
853ca4fec0
Rename the entire workspace:
- Crate packages: quicnprotochat-{core,proto,server,client,gui,p2p,mobile} -> quicproquo-*
- Binary names: quicnprotochat -> qpq, quicnprotochat-server -> qpq-server,
quicnprotochat-gui -> qpq-gui
- Default files: *-state.bin -> qpq-state.bin, *-server.toml -> qpq-server.toml,
*.db -> qpq.db
- Environment variable prefix: QUICNPROTOCHAT_* -> QPQ_*
- App identifier: chat.quicnproto.gui -> chat.quicproquo.gui
- Proto package: quicnprotochat.bench -> quicproquo.bench
- All documentation, Docker, CI, and script references updated
HKDF domain-separation strings and P2P ALPN remain unchanged for
backward compatibility with existing encrypted state and wire protocol.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.4 KiB
Design Decisions Overview
This section collects the Architecture Decision Records (ADRs) that document the key design choices in quicproquo. Each ADR follows a standard format: context (why the decision was needed), decision (what was chosen), and consequences (trade-offs, benefits, and residual risks).
These decisions are not immutable. Each ADR has a status field and can be superseded by a later ADR if circumstances change. The goal is to preserve the reasoning behind each choice so that future contributors understand why the system works the way it does, not just how.
ADR index
| ADR | Title | Status | One-line summary |
|---|---|---|---|
| ADR-002 | Cap'n Proto over MessagePack | Accepted | Zero-copy, schema-enforced serialisation with built-in async RPC replaces hand-rolled MessagePack dispatch. |
| ADR-004 | MLS-Unaware Delivery Service | Accepted | The DS routes opaque blobs by recipient key; it never inspects MLS content. |
| ADR-005 | Single-Use KeyPackages | Accepted | The AS atomically removes a KeyPackage on fetch to preserve MLS forward secrecy. |
Design comparison
For a broader comparison of quicproquo's design against alternative messaging protocols (Signal, Matrix/Olm/Megolm), see Why This Design, Not Signal/Matrix/....
How to read an ADR
Each ADR page follows this structure:
- Status -- One of: Proposed, Accepted, Deprecated, Superseded. All current ADRs are Accepted.
- Context -- The problem or force that motivated the decision. What constraints existed? What alternatives were considered?
- Decision -- The specific choice that was made. What was selected and what was rejected?
- Consequences -- The trade-offs that result from the decision. What are the benefits? What are the costs? What residual risks remain?
- Code references -- Links to the source files where the decision is implemented.
Cross-cutting themes
Several themes recur across multiple ADRs:
Layered security
The core principle is that no single layer is trusted alone. QUIC/TLS transport encryption protects metadata and provides authentication; MLS provides end-to-end content encryption with forward secrecy and post-compromise security.
Server minimalism
ADR-004 and ADR-005 reflect a design philosophy where the server does as little as possible. The DS does not parse MLS messages. The AS enforces single-use semantics through atomic removal rather than complex state tracking. This minimalism reduces the server's attack surface and makes it easier to audit.
Schema-first design
ADR-002 establishes Cap'n Proto as the single source of truth for the wire format. Every message and RPC call is defined in .capnp schema files, which are checked into the repository and used for code generation. This eliminates the class of bugs that arises from hand-rolled serialisation and ensures that the wire format is documented, versioned, and evolvable.
Further reading
- Why This Design, Not Signal/Matrix/... -- comparative analysis against alternative protocols
- Wire Format Overview -- the serialisation pipeline that implements these decisions
- Architecture Overview -- system-level view
- Protocol Layers Overview -- how the protocol layers stack