# Architecture Overview

quicproquo 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 single **NodeService** RPC
interface, bound to **port 7000** 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. |
| **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). |

Combining both services into a single endpoint simplifies deployment and
reduces round-trips. The schema is defined in
[`schemas/node.capnp`](../wire-format/node-service-schema.md) as a unified
`NodeService` interface.

See [Service Architecture](service-architecture.md) for per-method details,
connection lifecycle, and the long-polling `fetchWait` mechanism.

---

## Identity Key Model

Each quicproquo client holds a single Ed25519 signing keypair that serves
as its long-term identity:

```text
                    quicproquo 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 PQ 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)       │
  │                  │                                      │                  │
  │  GroupMember     │                                      │  GroupMember     │
  │  (MLS state)     │                                      │  (MLS state)     │
  └────────┬─────────┘                                      └────────┬─────────┘
           │                                                         │
           │  QUIC + TLS 1.3  (quinn/rustls)                         │
           │                                                         │
           ▼                                                         ▼
  ┌────────────────────────────────────────────────────────────────────────────┐
  │                        NodeService  (port 7000)                            │
  │                                                                            │
  │   ┌──────────────────────────┐     ┌───────────────────────────────────┐   │
  │   │  Authentication Service  │     │       Delivery Service            │   │
  │   │                          │     │                                   │   │
  │   │  uploadKeyPackage()      │     │  enqueue(recipientKey, payload)   │   │
  │   │  fetchKeyPackage()       │     │  fetch(recipientKey)              │   │
  │   │  uploadHybridKey()       │     │  fetchWait(recipientKey, timeout) │   │
  │   │  fetchHybridKey()        │     │                                   │   │
  │   │                          │     │  Queues: DashMap + FileBackedStore│   │
  │   │  Store: DashMap +        │     │                                   │   │
  │   │         FileBackedStore  │     │                                   │   │
  │   └──────────────────────────┘     └───────────────────────────────────┘   │
  │                                                                            │
  │   health()                                                                 │
  │                                                                            │
  └────────────────────────────────────────────────────────────────────────────┘
```

**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.

---

## 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** -- Cap'n Proto serialisation and RPC. Provides zero-copy
   typed messages, schema versioning, and async method dispatch.
   See [Cap'n Proto Serialisation and RPC](../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 four workspace crates:

| Crate                      | Role                                                              |
|----------------------------|-------------------------------------------------------------------|
| `quicproquo-core`      | Crypto primitives, MLS state machine, hybrid KEM                 |
| `quicproquo-proto`     | Cap'n Proto schemas, codegen, and serialisation helpers            |
| `quicproquo-server`    | QUIC listener, NodeService RPC, storage                           |
| `quicproquo-client`    | QUIC client, CLI subcommands, state persistence                   |

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) -- NodeService RPC methods, connection lifecycle, long-polling
- [End-to-End Data Flow](data-flow.md) -- registration, group creation, and message exchange sequence diagrams
- [Wire Format Overview](../wire-format/overview.md) -- Cap'n Proto schema reference
- [Cryptography Overview](../cryptography/overview.md) -- detailed cryptographic properties and threat model