quicproquo/CLAUDE.md

product.quicproquo

End-to-end encrypted group messaging over QUIC with MLS key agreement and post-quantum crypto.

Tech Stack

• Rust 1.75+, Cargo workspace (12 crates)
• Crypto: OpenMLS 0.8, ML-KEM-768, X25519, ChaCha20-Poly1305, OPAQUE-KE
• Networking: Quinn (QUIC), Tokio, Tower middleware
• Serialization: Protobuf (prost) for v2, Cap'n Proto (legacy v1)
• DB: rusqlite with bundled SQLCipher
• Build: just (justfile), cargo-deny for supply chain audit

Commands

just build              # Build all workspace crates
just test               # Run all tests
just test-core          # Crypto tests only
just lint               # clippy --workspace -- -D warnings
just fmt                # Format check
just fmt-fix            # Format fix
just proto              # Rebuild protobuf codegen
just server             # Build server binary
just client             # Build client binary
cargo deny check        # Supply chain audit (deny.toml)

Architecture

crates/
  quicprochat-core/        # Crypto primitives, MLS, double ratchet
  quicprochat-proto/       # Protobuf definitions + prost codegen
  quicprochat-rpc/         # RPC framework over QUIC
  quicprochat-sdk/         # High-level client SDK
  quicprochat-server/      # Server binary
  quicprochat-client/      # CLI client binary
  quicprochat-p2p/         # P2P mesh via iroh (feature-gated: `mesh`)
  quicprochat-plugin-api/  # Plugin interface
  quicprochat-kt/          # Kotlin/JNI bindings
  meshservice/             # Generic decentralized service layer (FAPP, Housing)
apps/gui/                  # GUI application
proto/                     # .proto source files
schemas/                   # Data schemas
docker/                    # Container configs

Rules

• clippy::unwrap_used is deny workspace-wide -- use proper error handling
• unsafe_code is warn -- avoid unless absolutely necessary, document why
• P2P crate (quicprochat-p2p) pulls ~90 extra deps via iroh -- only compiled with mesh feature
• All crypto operations must go through quicprochat-core, never inline crypto
• Protobuf is the v2 wire format; Cap'n Proto is legacy v1 only

Do NOT

• Use .unwrap() or .expect() outside tests -- clippy will deny it
• Add crypto primitives outside of quicprochat-core
• Enable the mesh feature by default (heavy dependency tree)
• Mix v1 (capnp) and v2 (protobuf) serialization in new code
• Skip cargo deny check before adding new dependencies