# q7xk/q7-chat architecture

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

- Interactive diagram: https://gitdiagram.com/q7xk/q7-chat
- Repository: https://github.com/q7xk/q7-chat

## Overview

Q7 Chat is a local-first, end-to-end encrypted messenger: users create an on-device identity, pair with contacts, exchange expiring messages and attachments, and keep conversation data in browser storage. The main UI is composed around a shared store and P2P manager; transport prefers WebRTC and can relay sealed traffic through public MQTT brokers. Backup, vault locking, linked-device sync, and group conversations are distinct capabilities. The sampled excerpts and README support the central architecture; some UI and transport details are unsampled.

Main entry points: [`lib/p2p/manager.ts`](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/manager.ts) (P2P manager), [`lib/p2p/context.tsx`](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/context.tsx) (P2P provider), [`components/Shell.tsx`](https://github.com/q7xk/q7-chat/blob/main/components/Shell.tsx) (App shell), [`lib/store.tsx`](https://github.com/q7xk/q7-chat/blob/main/lib/store.tsx) (Conversation store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_shell["App shell<br/>[Shell.tsx]"]
  node_thread["Conversation view<br/>[Thread.tsx]"]
  node_composer["Message composer<br/>[Composer.tsx]"]
  node_connect["Pairing UI<br/>[Connect.tsx]"]
  node_groupui["Group controls<br/>[GroupDialog.tsx]"]
  node_settings["Settings and backup<br/>[Settings.tsx]"]
  node_onboarding["Setup flow<br/>[Onboarding.tsx]"]
end

subgraph group_identity["Identity and safety"]
  node_crypto["Protocol crypto<br/>[crypto.ts]"]
  node_vault["Local vault<br/>[vault.ts]"]
end

subgraph group_runtime["Messaging runtime"]
  node_provider["P2P provider<br/>[context.tsx]"]
  node_manager["P2P manager<br/>[manager.ts]"]
  node_wire["Q7RP framing<br/>[q7rp.ts]"]
  node_rtc["WebRTC transport<br/>[rtc.ts]"]
  node_mqtt["MQTT relay transport<br/>[mqtt.ts]"]
end

subgraph group_localdata["Local data"]
  node_store["Conversation store<br/>[store.tsx]"]
  node_db[("IndexedDB<br/>[db.ts]")]
  node_attachments["Attachment handling<br/>[attach.ts]"]
  node_sync["Device sync<br/>[sync.ts]"]
  node_backup["Encrypted backup<br/>[backup.ts]"]
end

subgraph group_platform["Device platform"]
  node_native["Android WebView bridge<br/>[WebAppInterface.kt]"]
end

node_user(("User"))
node_peers(("Other devices"))
node_brokers{{"Public MQTT brokers"}}

node_user -->|"uses"| node_shell
node_shell -->|"renders"| node_thread
node_shell -->|"renders"| node_connect
node_shell -->|"renders"| node_settings
node_shell -->|"renders"| node_onboarding
node_thread -->|"renders"| node_composer
node_thread -->|"uses"| node_provider
node_composer -->|"sends through"| node_provider
node_connect -->|"pairs through"| node_provider
node_groupui -->|"manages groups"| node_provider
node_settings -->|"updates"| node_store
node_settings -->|"exports and imports"| node_backup
node_provider -->|"bridges state"| node_store
node_provider -->|"initializes"| node_manager
node_manager -->|"seals and signs"| node_crypto
node_manager -->|"uses framing"| node_wire
node_manager -->|"uses transport"| node_rtc
node_manager -->|"uses fallback"| node_mqtt
node_rtc -->|"carries live traffic"| node_peers
node_mqtt -->|"relays ciphertext"| node_brokers
node_manager -->|"exchanges messages"| node_peers
node_manager -->|"loads identity"| node_db
node_store -->|"persists records"| node_db
node_store -->|"merges snapshots"| node_sync
node_store -->|"uses backup functions"| node_backup
node_manager -->|"syncs linked devices"| node_sync
node_manager -->|"transfers attachments"| node_attachments
node_manager -->|"checks vault"| node_vault
node_backup -->|"encrypts archive"| node_crypto
node_backup -->|"restores records"| node_db
node_user -.->|"may use"| node_native

click node_shell "https://github.com/q7xk/q7-chat/blob/main/components/Shell.tsx"
click node_thread "https://github.com/q7xk/q7-chat/blob/main/components/Thread.tsx"
click node_composer "https://github.com/q7xk/q7-chat/blob/main/components/Composer.tsx"
click node_connect "https://github.com/q7xk/q7-chat/blob/main/components/Connect.tsx"
click node_groupui "https://github.com/q7xk/q7-chat/blob/main/components/GroupDialog.tsx"
click node_settings "https://github.com/q7xk/q7-chat/blob/main/components/Settings.tsx"
click node_onboarding "https://github.com/q7xk/q7-chat/blob/main/components/Onboarding.tsx"
click node_provider "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/context.tsx"
click node_manager "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/manager.ts"
click node_crypto "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/crypto.ts"
click node_wire "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/q7rp.ts"
click node_rtc "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/rtc.ts"
click node_mqtt "https://github.com/q7xk/q7-chat/blob/main/lib/p2p/mqtt.ts"
click node_store "https://github.com/q7xk/q7-chat/blob/main/lib/store.tsx"
click node_db "https://github.com/q7xk/q7-chat/blob/main/lib/db.ts"
click node_attachments "https://github.com/q7xk/q7-chat/blob/main/lib/attach.ts"
click node_sync "https://github.com/q7xk/q7-chat/blob/main/lib/sync.ts"
click node_backup "https://github.com/q7xk/q7-chat/blob/main/lib/backup.ts"
click node_vault "https://github.com/q7xk/q7-chat/blob/main/lib/vault.ts"
click node_native "https://github.com/q7xk/q7-chat/blob/main/android/app/src/main/java/com/q7/chat/WebAppInterface.kt"

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_shell,node_thread,node_composer,node_connect,node_groupui,node_settings,node_onboarding,node_user toneBlue
class node_crypto,node_vault toneAmber
class node_provider,node_manager,node_wire,node_rtc,node_mqtt toneMint
class node_store,node_db,node_attachments,node_sync,node_backup toneRose
class node_native,node_peers,node_brokers toneIndigo
```

## Components

### Chat experience

- [App shell](https://github.com/q7xk/q7-chat/blob/main/components/Shell.tsx): `components/Shell.tsx`
- [Conversation view](https://github.com/q7xk/q7-chat/blob/main/components/Thread.tsx): `components/Thread.tsx`
- [Message composer](https://github.com/q7xk/q7-chat/blob/main/components/Composer.tsx): `components/Composer.tsx`
- [Pairing UI](https://github.com/q7xk/q7-chat/blob/main/components/Connect.tsx): `components/Connect.tsx`
- [Group controls](https://github.com/q7xk/q7-chat/blob/main/components/GroupDialog.tsx): `components/GroupDialog.tsx`
- [Settings and backup](https://github.com/q7xk/q7-chat/blob/main/components/Settings.tsx): `components/Settings.tsx`
- [Setup flow](https://github.com/q7xk/q7-chat/blob/main/components/Onboarding.tsx): `components/Onboarding.tsx`

### Identity and safety

- [Protocol crypto](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/crypto.ts): `lib/p2p/crypto.ts`
- [Local vault](https://github.com/q7xk/q7-chat/blob/main/lib/vault.ts): `lib/vault.ts`

### Messaging runtime

- [P2P provider](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/context.tsx): `lib/p2p/context.tsx`
- [P2P manager](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/manager.ts): `lib/p2p/manager.ts`
- [Q7RP framing](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/q7rp.ts): `lib/p2p/q7rp.ts`
- [WebRTC transport](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/rtc.ts): `lib/p2p/rtc.ts`
- [MQTT relay transport](https://github.com/q7xk/q7-chat/blob/main/lib/p2p/mqtt.ts): `lib/p2p/mqtt.ts`

### Local data

- [Conversation store](https://github.com/q7xk/q7-chat/blob/main/lib/store.tsx): `lib/store.tsx`
- [IndexedDB](https://github.com/q7xk/q7-chat/blob/main/lib/db.ts): `lib/db.ts`
- [Attachment handling](https://github.com/q7xk/q7-chat/blob/main/lib/attach.ts): `lib/attach.ts`
- [Device sync](https://github.com/q7xk/q7-chat/blob/main/lib/sync.ts): `lib/sync.ts`
- [Encrypted backup](https://github.com/q7xk/q7-chat/blob/main/lib/backup.ts): `lib/backup.ts`

### Device platform

- [Android WebView bridge](https://github.com/q7xk/q7-chat/blob/main/android/app/src/main/java/com/q7/chat/WebAppInterface.kt): `android/app/src/main/java/com/q7/chat/WebAppInterface.kt`

### Other components

- **User**
- **Other devices**
- **Public MQTT brokers**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Conversation view: renders (evidence: `components/Shell.tsx`)
- App shell → Pairing UI: renders (evidence: `components/Shell.tsx`)
- App shell → Settings and backup: renders (evidence: `components/Shell.tsx`)
- App shell → Setup flow: renders (evidence: `components/Shell.tsx`)
- Conversation view → Message composer: renders (evidence: `components/Thread.tsx`)
- Conversation view → P2P provider: uses (evidence: `components/Thread.tsx`)
- Message composer → P2P provider: sends through (evidence: `components/Composer.tsx`)
- Pairing UI → P2P provider: pairs through (evidence: `components/Connect.tsx`)
- Group controls → P2P provider: manages groups
- Settings and backup → Conversation store: updates (evidence: `components/Settings.tsx`)
- Settings and backup → Encrypted backup: exports and imports (evidence: `components/Settings.tsx`)
- P2P provider → Conversation store: bridges state (evidence: `lib/p2p/context.tsx`)
- P2P provider → P2P manager: initializes (evidence: `lib/p2p/context.tsx`)
- P2P manager → Protocol crypto: seals and signs (evidence: `lib/p2p/manager.ts`)
- P2P manager → Q7RP framing: uses framing (evidence: `lib/p2p/manager.ts`)
- P2P manager → WebRTC transport: uses transport (evidence: `lib/p2p/manager.ts`)
- P2P manager → MQTT relay transport: uses fallback (evidence: `lib/p2p/manager.ts`)
- WebRTC transport → Other devices: carries live traffic (evidence: `README.md`)
- MQTT relay transport → Public MQTT brokers: relays ciphertext (evidence: `README.md`)
- P2P manager → Other devices: exchanges messages (evidence: `README.md`)
- P2P manager → IndexedDB: loads identity (evidence: `lib/p2p/manager.ts`)
- Conversation store → IndexedDB: persists records (evidence: `lib/store.tsx`)
- Conversation store → Device sync: merges snapshots (evidence: `lib/store.tsx`)
- Conversation store → Encrypted backup: uses backup functions (evidence: `lib/store.tsx`)
- P2P manager → Device sync: syncs linked devices (evidence: `lib/p2p/manager.ts`)
- P2P manager → Attachment handling: transfers attachments (evidence: `lib/p2p/manager.ts`)
- P2P manager → Local vault: checks vault (evidence: `lib/p2p/manager.ts`)
- Encrypted backup → Protocol crypto: encrypts archive (evidence: `lib/backup.ts`)
- Encrypted backup → IndexedDB: restores records (evidence: `lib/backup.ts`)
- User → Android WebView bridge: may use