# Architecture Overview quicprochat is an end-to-end encrypted group messaging system built in Rust. This page describes the high-level architecture: the services that compose the system, the dual-key cryptographic model, and how the pieces fit together. --- ## Two-Service Model The server exposes two logical services through a unified RPC endpoint bound to **port 5001** over QUIC + TLS 1.3: | Logical Service | Responsibility | |--------------------------|-----------------------------------------------------------------| | **Authentication Service (AS)** | Stores and distributes single-use MLS KeyPackages. Clients upload KeyPackages after identity generation; peers fetch them to add new members to a group. Also manages hybrid PQ public keys and identity resolution. | | **Delivery Service (DS)** | Store-and-forward relay for opaque payloads. The DS never inspects MLS ciphertext -- it routes solely by recipient Ed25519 public key (and optional channel ID). | Both services are accessed through a single QUIC connection using the v2 Protobuf framing protocol. Each RPC call gets a dedicated QUIC bidirectional stream to prevent head-of-line blocking. See [Service Architecture](service-architecture.md) for per-method details, connection lifecycle, and push event delivery. --- ## Identity Key Model Each quicprochat client holds a single Ed25519 signing keypair that serves as its long-term identity: ```text quicprochat Key Model +--------------------------------------------------+ | | | Ed25519 signing keypair (MLS identity) | | ------------------------------------------ | | - Generated once per user/device | | - Embedded in MLS BasicCredential | | - Signs KeyPackages, Commits, and group ops | | - Raw 32-byte public key is the AS index | | - Managed by IdentityKeypair, zeroize-on-drop | | | +--------------------------------------------------+ ``` | Property | Ed25519 (MLS) | |-------------------|--------------------------------------------| | Curve | Ed25519 (Twisted Edwards) | | Purpose | Identity binding, signing, MLS credentials | | Crate | `ed25519-dalek` | | Zeroize on drop | Yes (`Zeroizing<[u8; 32]>`) | | PQ protection | MLS key schedule uses DHKEM(X25519); hybrid X25519+ML-KEM-768 KEM available at envelope level | For details on the cryptographic properties, see [Ed25519 Identity Keys](../cryptography/identity-keys.md). --- ## System Diagram ```text +-----------------+ +-----------------+ | Alice Client | | Bob Client | | | | | | IdentityKeypair | | IdentityKeypair | | (Ed25519) | | (Ed25519) | | | | | | QpqClient | | QpqClient | | (SDK) | | (SDK) | +--------+---------+ +--------+---------+ | | | QUIC + TLS 1.3 (quinn/rustls) ALPN: "qpc" | | | v v +------------------------------------------------------------------------+ | quicprochat-server (port 5001) | | | | +---------------------------+ +--------------------------------+ | | | Authentication Service | | Delivery Service | | | | | | | | | | OpaqueRegisterStart(100) | | Enqueue(200) | | | | OpaqueRegisterFinish(101)| | Fetch(201) | | | | OpaqueLoginStart(102) | | FetchWait(202) | | | | OpaqueLoginFinish(103) | | Peek(203) | | | | | | Ack(204) | | | | UploadKeyPackage(300) | | BatchEnqueue(205) | | | | FetchKeyPackage(301) | | | | | | UploadHybridKey(302) | | Store: SQLCipher | | | | FetchHybridKey(303) | | DashMap waiters | | | | FetchHybridKeys(304) | +--------------------------------+ | | +---------------------------+ | | | | + 34 more methods: Keys, Channel, Group, User, KT, Blob, Device, | | P2P, Federation, Moderation, Recovery, Account (see method_ids) | | | +------------------------------------------------------------------------+ ``` **Key observations:** 1. The server never sees plaintext message content. MLS ciphertext is opaque to the DS -- it merely routes by `recipientKey`. 2. KeyPackages are single-use (RFC 9420 requirement). The AS atomically removes a KeyPackage on fetch to enforce this invariant. 3. QUIC + TLS 1.3 is the sole transport layer. The ALPN identifier is `qpc`. 4. Push events (new messages, typing, presence, membership changes) are delivered server-to-client on QUIC uni-streams using a separate push frame format. --- ## Protocol Layering The system stacks three protocol layers: 1. **Transport** -- QUIC + TLS 1.3. Provides confidentiality, integrity, and server authentication. See [Protocol Stack](protocol-stack.md). 2. **Framing / RPC** -- Custom binary header + Protobuf serialisation. Each request frame is `[method_id: u16][request_id: u32][payload_len: u32][protobuf]`. Responses are `[status: u8][request_id: u32][payload_len: u32][protobuf]`. See [Protobuf Framing](../protocol-layers/capn-proto.md). 3. **End-to-End Encryption** -- MLS (RFC 9420). Provides group key agreement, forward secrecy, and post-compromise security. The server never holds group keys. See [MLS (RFC 9420)](../protocol-layers/mls.md). An optional fourth layer -- the **hybrid KEM envelope** (X25519 + ML-KEM-768) -- wraps MLS payloads for post-quantum confidentiality at the per-message level. See [Hybrid KEM](../protocol-layers/hybrid-kem.md). --- ## Crate Map The implementation is split across nine workspace crates: | Crate | Role | |------------------------------|-------------------------------------------------------------------| | `quicprochat-core` | Crypto primitives, MLS state machine, hybrid KEM | | `quicprochat-proto` | Cap'n Proto legacy types + Protobuf (prost) v2 generated types | | `quicprochat-kt` | Key transparency (append-only log, revocation) | | `quicprochat-plugin-api` | `#![no_std]` C-ABI plugin interface | | `quicprochat-rpc` | QUIC RPC framework: framing, server dispatch, client, middleware | | `quicprochat-sdk` | Client SDK: `QpqClient`, event broadcast, `ConversationStore` | | `quicprochat-server` | RPC server + domain services | | `quicprochat-client` | CLI/TUI client binary | | `quicprochat-p2p` | iroh P2P endpoint publish/resolve (feature-flagged) | See [Crate Responsibilities](crate-responsibilities.md) for a full breakdown and dependency diagram. --- ## Further Reading - [Protocol Stack](protocol-stack.md) -- layered protocol stack description - [Service Architecture](service-architecture.md) -- 44 RPC methods, connection lifecycle, push events - [End-to-End Data Flow](data-flow.md) -- registration, group creation, and message exchange sequence diagrams - [Wire Format Reference](../wire-format/overview.md) -- Protobuf schema reference and method ID table - [Cryptography Overview](../cryptography/overview.md) -- detailed cryptographic properties and threat model