---
last_verified: 2026-05-30
verified_version: 0.1.34
owner: backend
freshness_days: 30
---

# Architecture — pvtcoms

## Overview

pvtcoms is a serverless, peer-to-peer, **anonymous, post-quantum** encrypted messenger. A shared **Rust core** (crypto,
transport, protocol, storage) is exposed to native UIs via UniFFI. v1 ships Android + Desktop (Tauri); 1:1 text only over
Tor. Full reference: [`../DESIGN.md`](../DESIGN.md); v1 scope: [`../BUILD_PLAN.md`](../BUILD_PLAN.md); boundary:
[`../THREAT_MODEL.md`](../THREAT_MODEL.md).

## Tech Stack

- **Language (core)**: Rust 1.95+
- **FFI**: UniFFI (auto-generated Swift + Kotlin bindings; typed UniFFI command API)
- **UI**: Jetpack Compose (Android), Tauri 2 (Desktop Win/Linux/macOS), SwiftUI (iOS — v2)
- **Transport**: Tor via `arti` (v1); Nym mixnet (v3)
- **Storage**: SQLCipher (AES-256) at rest; key in OS keystore (Android Keystore / iOS Keychain)
- **Crypto**: hybrid `X25519 + ML-KEM-768` handshake, Double Ratchet, `Ed25519 + ML-DSA-65` identity, ChaCha20-Poly1305

## Directory Structure (planned)

```
pvtcoms/
├── core/            # Rust workspace: crypto, transport, mailbox, protocol, storage (the trust boundary)
├── bindings/        # UniFFI-generated Swift/Kotlin
├── android/         # Kotlin + Jetpack Compose UI
├── desktop/         # Tauri 2 app
├── docs/            # this documentation set
└── scripts/         # pipeline tooling
```

## Key Components (planned v1)

| Component | Path | Responsibility |
|-----------|------|----------------|
| Crypto core | `core/crypto` | Identity keys, hybrid handshake, Double Ratchet, AEAD |
| Transport | `core/transport` | `arti` Tor sessions, circuit lifecycle, padded envelopes |
| Mailbox/rendezvous | `core/mailbox` | Rotating-token oblivious mailbox, pull delivery, PoW gate |
| Onboarding | `core/onboarding` | Single-use invites, SAS verification, trust provenance |
| Storage | `core/store` | SQLCipher store, keystore wrapping, message TTL |
| FFI surface | `core/ffi` | Narrow UniFFI command/event API |

## Data Flow

Compose/Tauri UI → UniFFI command → Rust core → (encrypt via ratchet) → padded envelope → `arti` Tor → recipient's
oblivious mailbox. Recipient pulls its rotating token → decrypts in core → event → UI. No server learns the social graph;
presence is never published (pull-not-push).

## Key Decisions

See [`ADR/`](./ADR/). Crypto/transport/identity choices are recorded in [`../DESIGN.md`](../DESIGN.md); any change to a
crypto primitive or the threat boundary requires an ADR.