Christian Nennemann
9fdb37876a
Delete 8 Noise-specific documentation pages (noise-xx.md,
transport-keys.md, adr-001/003/006, framing-codec.md) and update
~30 remaining wiki pages to reflect QUIC+TLS as the sole transport.
Remove obsolete Noise-based integration tests (auth_service.rs,
mls_group.rs). Code-side Noise removal was done in f334ed3.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# Design Decisions Overview
|
|
|
|
This section collects the Architecture Decision Records (ADRs) that document the key design choices in quicnprotochat. 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](adr-002-capnproto.md) | Cap'n Proto over MessagePack | Accepted | Zero-copy, schema-enforced serialisation with built-in async RPC replaces hand-rolled MessagePack dispatch. |
|
|
| [ADR-004](adr-004-mls-unaware-ds.md) | MLS-Unaware Delivery Service | Accepted | The DS routes opaque blobs by recipient key; it never inspects MLS content. |
|
|
| [ADR-005](adr-005-single-use-keypackages.md) | Single-Use KeyPackages | Accepted | The AS atomically removes a KeyPackage on fetch to preserve MLS forward secrecy. |
|
|
|
|
---
|
|
|
|
## Design comparison
|
|
|
|
For a broader comparison of quicnprotochat's design against alternative messaging protocols (Signal, Matrix/Olm/Megolm), see [Why This Design, Not Signal/Matrix/...](why-not-signal.md).
|
|
|
|
---
|
|
|
|
## How to read an ADR
|
|
|
|
Each ADR page follows this structure:
|
|
|
|
1. **Status** -- One of: Proposed, Accepted, Deprecated, Superseded. All current ADRs are Accepted.
|
|
2. **Context** -- The problem or force that motivated the decision. What constraints existed? What alternatives were considered?
|
|
3. **Decision** -- The specific choice that was made. What was selected and what was rejected?
|
|
4. **Consequences** -- The trade-offs that result from the decision. What are the benefits? What are the costs? What residual risks remain?
|
|
5. **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/...](why-not-signal.md) -- comparative analysis against alternative protocols
|
|
- [Wire Format Overview](../wire-format/overview.md) -- the serialisation pipeline that implements these decisions
|
|
- [Architecture Overview](../architecture/overview.md) -- system-level view
|
|
- [Protocol Layers Overview](../protocol-layers/overview.md) -- how the protocol layers stack
|