# bpforbes/keyquorum architecture

> Architecture diagram of the GitHub repository bpforbes/keyquorum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bpforbes/keyquorum
- Repository: https://github.com/bpforbes/keyquorum

## Overview

KeyQuorum is a hardware-key-quorum file-sharing system with a command-line interface and a browser lab that runs the real commands in a sandbox. The principal workflow registers keys, organizes them into a recursive threshold tree, protects a file, then reconstructs the key from presented shares to unlock it. The graph also includes device custody, transfers, bridges, relay/provider services, and the lab experience. Arrows use README statements or indexed source references; several implementation details are unsampled, so uncertain internal calls are omitted.

Main entry points: [`src/cli/mod.rs`](https://github.com/bpforbes/keyquorum/blob/main/src/cli/mod.rs) (KeyQuorum CLI), [`src/lab/state.rs`](https://github.com/bpforbes/keyquorum/blob/main/src/lab/state.rs) (Lab state), [`src/key_tree.rs`](https://github.com/bpforbes/keyquorum/blob/main/src/key_tree.rs) (Recursive key tree), [`src/quorum.rs`](https://github.com/bpforbes/keyquorum/blob/main/src/quorum.rs) (Quorum access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Command interfaces"]
  node_cli["KeyQuorum CLI<br/>[mod.rs]"]
  node_device_cli["Device CLI<br/>[device_cmd.rs]"]
end

subgraph group_keys["Keys and custody"]
  node_key_registry[("Key registry<br/>[keys.rs]")]
  node_device_custody["Device custody<br/>[device.rs]"]
  node_key_tree["Recursive key tree<br/>[key_tree.rs]"]
  node_quorum["Quorum access<br/>[quorum.rs]"]
  node_crypto["Cryptography<br/>[crypto.rs]"]
end

subgraph group_files["Protected files"]
  node_locked_files["Protected files<br/>[locked_files.rs]"]
  node_vault["Password vault<br/>[vault.rs]"]
  node_database[("SQLite store<br/>[mod.rs]")]
  node_storage["Storage backends<br/>[storage.rs]"]
end

subgraph group_sharing["Sharing and relay"]
  node_envelopes["Sealed envelopes<br/>[envelope.rs]"]
  node_transfers["Key transfers<br/>[transfer.rs]"]
  node_private_bridges["Private bridges<br/>[private_bridge.rs]"]
  node_relay_client["Relay client<br/>[client.rs]"]
  node_relay_service["Relay service<br/>[service.rs]"]
  node_provider["Provider identity<br/>[provider.rs]"]
end

subgraph group_lab["Browser lab"]
  node_lab_vm["Sandbox machine<br/>[vm.rs]"]
  node_lab_state[("Lab state<br/>[state.rs]")]
  node_lab_ui["Lab interface<br/>[App.tsx]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"manages devices"| node_device_cli
node_cli -->|"registers keys"| node_key_registry
node_cli -->|"manages trees"| node_key_tree
node_cli -->|"requests access"| node_quorum
node_cli -->|"protects files"| node_locked_files
node_device_cli -->|"manages slots"| node_device_custody
node_device_custody -->|"binds keys"| node_key_registry
node_key_tree -->|"reads tree"| node_database
node_key_tree -->|"checks keys"| node_key_registry
node_quorum -->|"reconstructs shares"| node_key_tree
node_quorum -->|"checks devices"| node_device_custody
node_quorum -->|"uses primitives"| node_crypto
node_locked_files -->|"encrypts content"| node_crypto
node_locked_files -->|"stores ciphertext"| node_storage
node_locked_files -->|"records files"| node_database
node_vault -->|"derives keys"| node_crypto
node_cli -->|"moves identities"| node_transfers
node_transfers -->|"seals letters"| node_envelopes
node_cli -->|"manages bridges"| node_private_bridges
node_private_bridges -->|"packages updates"| node_envelopes
node_cli -->|"uses relay"| node_relay_client
node_relay_client -.->|"sends requests"| node_relay_service
node_relay_service -->|"checks identity"| node_provider
node_lab_ui -->|"invokes actions"| node_lab_state
node_lab_state -->|"runs commands"| node_lab_vm
node_lab_state -->|"simulates custody"| node_device_custody
node_lab_state -->|"uses tree logic"| node_key_tree
node_lab_state -->|"supports transfers"| node_transfers
node_lab_state -->|"uses relay client"| node_relay_client

click node_cli "https://github.com/bpforbes/keyquorum/blob/main/src/cli/mod.rs"
click node_device_cli "https://github.com/bpforbes/keyquorum/blob/main/src/cli/device_cmd.rs"
click node_key_registry "https://github.com/bpforbes/keyquorum/blob/main/src/keys.rs"
click node_device_custody "https://github.com/bpforbes/keyquorum/blob/main/src/device.rs"
click node_key_tree "https://github.com/bpforbes/keyquorum/blob/main/src/key_tree.rs"
click node_quorum "https://github.com/bpforbes/keyquorum/blob/main/src/quorum.rs"
click node_crypto "https://github.com/bpforbes/keyquorum/blob/main/src/crypto.rs"
click node_locked_files "https://github.com/bpforbes/keyquorum/blob/main/src/locked_files.rs"
click node_vault "https://github.com/bpforbes/keyquorum/blob/main/src/vault.rs"
click node_database "https://github.com/bpforbes/keyquorum/blob/main/src/db/mod.rs"
click node_storage "https://github.com/bpforbes/keyquorum/blob/main/src/storage.rs"
click node_envelopes "https://github.com/bpforbes/keyquorum/blob/main/src/envelope.rs"
click node_transfers "https://github.com/bpforbes/keyquorum/blob/main/src/transfer.rs"
click node_private_bridges "https://github.com/bpforbes/keyquorum/blob/main/src/private_bridge.rs"
click node_relay_client "https://github.com/bpforbes/keyquorum/blob/main/src/relay/client.rs"
click node_relay_service "https://github.com/bpforbes/keyquorum/blob/main/src/relay/service.rs"
click node_provider "https://github.com/bpforbes/keyquorum/blob/main/src/provider.rs"
click node_lab_vm "https://github.com/bpforbes/keyquorum/blob/main/src/lab/vm.rs"
click node_lab_state "https://github.com/bpforbes/keyquorum/blob/main/src/lab/state.rs"
click node_lab_ui "https://github.com/bpforbes/keyquorum/blob/main/lab/src/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_device_cli toneBlue
class node_key_registry,node_device_custody,node_key_tree,node_quorum,node_crypto toneAmber
class node_locked_files,node_vault,node_database,node_storage toneMint
class node_envelopes,node_transfers,node_private_bridges,node_relay_client,node_relay_service,node_provider toneRose
class node_lab_vm,node_lab_state,node_lab_ui,node_operator toneIndigo
```

## Components

### Command interfaces

- [KeyQuorum CLI](https://github.com/bpforbes/keyquorum/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- [Device CLI](https://github.com/bpforbes/keyquorum/blob/main/src/cli/device_cmd.rs): `src/cli/device_cmd.rs`

### Keys and custody

- [Key registry](https://github.com/bpforbes/keyquorum/blob/main/src/keys.rs): `src/keys.rs`
- [Device custody](https://github.com/bpforbes/keyquorum/blob/main/src/device.rs): `src/device.rs`
- [Recursive key tree](https://github.com/bpforbes/keyquorum/blob/main/src/key_tree.rs): `src/key_tree.rs`
- [Quorum access](https://github.com/bpforbes/keyquorum/blob/main/src/quorum.rs): `src/quorum.rs`
- [Cryptography](https://github.com/bpforbes/keyquorum/blob/main/src/crypto.rs): `src/crypto.rs`

### Protected files

- [Protected files](https://github.com/bpforbes/keyquorum/blob/main/src/locked_files.rs): `src/locked_files.rs`
- [Password vault](https://github.com/bpforbes/keyquorum/blob/main/src/vault.rs): `src/vault.rs`
- [SQLite store](https://github.com/bpforbes/keyquorum/blob/main/src/db/mod.rs): `src/db/mod.rs`
- [Storage backends](https://github.com/bpforbes/keyquorum/blob/main/src/storage.rs): `src/storage.rs`

### Sharing and relay

- [Sealed envelopes](https://github.com/bpforbes/keyquorum/blob/main/src/envelope.rs): `src/envelope.rs`
- [Key transfers](https://github.com/bpforbes/keyquorum/blob/main/src/transfer.rs): `src/transfer.rs`
- [Private bridges](https://github.com/bpforbes/keyquorum/blob/main/src/private_bridge.rs): `src/private_bridge.rs`
- [Relay client](https://github.com/bpforbes/keyquorum/blob/main/src/relay/client.rs): `src/relay/client.rs`
- [Relay service](https://github.com/bpforbes/keyquorum/blob/main/src/relay/service.rs): `src/relay/service.rs`
- [Provider identity](https://github.com/bpforbes/keyquorum/blob/main/src/provider.rs): `src/provider.rs`

### Browser lab

- [Sandbox machine](https://github.com/bpforbes/keyquorum/blob/main/src/lab/vm.rs): `src/lab/vm.rs`
- [Lab state](https://github.com/bpforbes/keyquorum/blob/main/src/lab/state.rs): `src/lab/state.rs`
- [Lab interface](https://github.com/bpforbes/keyquorum/blob/main/lab/src/App.tsx): `lab/src/App.tsx`

### Other components

- **Operator**

## Connections

- Operator → KeyQuorum CLI: runs commands
- Operator → Device CLI: manages devices
- KeyQuorum CLI → Key registry: registers keys (evidence: `src/cli/mod.rs`)
- KeyQuorum CLI → Recursive key tree: manages trees (evidence: `src/cli/mod.rs`)
- KeyQuorum CLI → Quorum access: requests access (evidence: `src/cli/mod.rs`)
- KeyQuorum CLI → Protected files: protects files (evidence: `src/cli/mod.rs`)
- Device CLI → Device custody: manages slots
- Device custody → Key registry: binds keys (evidence: `src/device.rs`)
- Recursive key tree → SQLite store: reads tree (evidence: `src/key_tree.rs`)
- Recursive key tree → Key registry: checks keys (evidence: `src/key_tree.rs`)
- Quorum access → Recursive key tree: reconstructs shares (evidence: `src/quorum.rs`)
- Quorum access → Device custody: checks devices (evidence: `src/quorum.rs`)
- Quorum access → Cryptography: uses primitives (evidence: `src/quorum.rs`)
- Protected files → Cryptography: encrypts content (evidence: `src/locked_files.rs`)
- Protected files → Storage backends: stores ciphertext (evidence: `src/locked_files.rs`)
- Protected files → SQLite store: records files
- Password vault → Cryptography: derives keys (evidence: `src/vault.rs`)
- KeyQuorum CLI → Key transfers: moves identities (evidence: `src/cli/mod.rs`)
- Key transfers → Sealed envelopes: seals letters
- KeyQuorum CLI → Private bridges: manages bridges (evidence: `src/cli/mod.rs`)
- Private bridges → Sealed envelopes: packages updates (evidence: `src/private_bridge.rs`)
- KeyQuorum CLI → Relay client: uses relay (evidence: `src/cli/mod.rs`)
- Relay client → Relay service: sends requests (evidence: `src/relay/service.rs`)
- Relay service → Provider identity: checks identity (evidence: `src/relay/service.rs`)
- Lab interface → Lab state: invokes actions
- Lab state → Sandbox machine: runs commands (evidence: `src/lab/state.rs`)
- Lab state → Device custody: simulates custody (evidence: `src/lab/state.rs`)
- Lab state → Recursive key tree: uses tree logic (evidence: `src/lab/state.rs`)
- Lab state → Key transfers: supports transfers (evidence: `src/lab/state.rs`)
- Lab state → Relay client: uses relay client (evidence: `src/lab/state.rs`)