# shonnay/k3ncrypt architecture

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

- Interactive diagram: https://gitdiagram.com/shonnay/k3ncrypt
- Repository: https://github.com/shonnay/k3ncrypt

## Overview

K3NCRYPT is a privacy-first messaging and calling product: clients hold identity and encryption keys, while the service SDK coordinates encrypted communication and the backend authorizes operations and relays opaque data. The main user path runs from setup and conversation use in the browser through the SDK to backend APIs and relays; attachments, calls, device trust, and private-network authority are additional capabilities. Android mirrors several client responsibilities, though the README identifies the browser as the supported client. Some subsystem links are documented only at a high level, so the graph omits unverified internal wiring.

Main entry points: [`client/src/App.tsx`](https://github.com/shonnay/k3ncrypt/blob/main/client/src/App.tsx) (App shell), [`backend/api/index.ts`](https://github.com/shonnay/k3ncrypt/blob/main/backend/api/index.ts) (HTTP API), [`android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt`](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt) (Android messaging), [`android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt`](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt) (Android identity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_app["App shell<br/>[App.tsx]"]
  node_chatui["Chat interface<br/>[ChatContainer.tsx]"]
  node_setupui["Conversation setup<br/>[SetupOverlay.tsx]"]
  node_chatcontext["Chat state<br/>[ChatContext.tsx]"]
  node_mediaui["Media gateway"]
end

subgraph group_sdk["Communication SDK"]
  node_sdkcrypto["Conversation crypto"]
  node_sdkdevices["Device identity<br/>[lifecycle.ts]"]
  node_sdksync["Encrypted sync<br/>[runtime.ts]"]
  node_sdkcalls["Call services<br/>[service.ts]"]
  node_sdkattachments["Attachment workflow<br/>[service.ts]"]
  node_sdkprivate["Private network<br/>[runtime.ts]"]
end

subgraph group_backend["Backend services"]
  node_api["HTTP API<br/>[index.ts]"]
  node_trust["Trust authority<br/>[deviceTrust.ts]"]
  node_membership["Membership authority"]
  node_attachmentservice["Attachment authorization"]
  node_relay["Socket relay<br/>[listeners.ts]"]
end

subgraph group_state["Persistence"]
  node_mongo[("Mongo persistence<br/>[index.ts]")]
  node_browserstore[("Browser secure storage<br/>[secureVault.ts]")]
end

subgraph group_android["Android client"]
  node_androidapp["Android application<br/>[MainActivity.kt]"]
  node_androidmessaging["Android messaging"]
  node_androididentity["Android identity"]
  node_androidcalls["Android calls"]
  node_androidcrypto["Android crypto<br/>[CryptoPort.kt]"]
  node_androidnetwork["Android network<br/>[K3ncryptApi.kt]"]
  node_androidstore[("Android encrypted state")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"initializes"| node_chatcontext
node_app -->|"renders"| node_setupui
node_app -->|"renders"| node_chatui
node_chatcontext -->|"opens vault"| node_browserstore
node_chatcontext -.->|"coordinates encryption"| node_sdkcrypto
node_chatcontext -.->|"coordinates sync"| node_sdksync
node_app -->|"configures"| node_mediaui
node_mediaui -->|"uses workflow"| node_sdkattachments
node_app -.->|"provides call interface"| node_sdkcalls
node_sdkcrypto -.->|"uses device identity"| node_sdkdevices
node_sdkdevices -.->|"requests trust authority"| node_trust
node_sdksync -.->|"relays ciphertext"| node_relay
node_sdkcalls -.->|"relays call signaling"| node_relay
node_sdkattachments -.->|"requests protected media"| node_attachmentservice
node_sdkprivate -.->|"checks membership"| node_membership
node_api -->|"routes"| node_trust
node_api -->|"routes"| node_membership
node_api -->|"routes attachments"| node_attachmentservice
node_attachmentservice -->|"delegates operations"| node_sdkattachments
node_api -.->|"separate relay interface"| node_relay
node_api -.->|"persists metadata"| node_mongo
node_relay -.->|"stores operational state"| node_mongo
node_user -.->|"uses"| node_androidapp
node_androidapp -.->|"provides messaging"| node_androidmessaging
node_androidapp -.->|"manages identity"| node_androididentity
node_androidapp -.->|"controls calls"| node_androidcalls
node_androidmessaging -->|"encrypts messages"| node_androidcrypto
node_androidmessaging -->|"persists state"| node_androidstore
node_androidmessaging -->|"sends relay data"| node_androidnetwork
node_androididentity -->|"uses crypto"| node_androidcrypto
node_androididentity -->|"requests lifecycle services"| node_androidnetwork
node_androididentity -->|"persists identity"| node_androidstore
node_androidcalls -->|"sends call signals"| node_androidmessaging
node_androidcalls -->|"reads identity"| node_androididentity

click node_app "https://github.com/shonnay/k3ncrypt/blob/main/client/src/App.tsx"
click node_chatui "https://github.com/shonnay/k3ncrypt/blob/main/client/src/components/ChatContainer/ChatContainer.tsx"
click node_setupui "https://github.com/shonnay/k3ncrypt/blob/main/client/src/components/SetupOverlay/SetupOverlay.tsx"
click node_chatcontext "https://github.com/shonnay/k3ncrypt/blob/main/client/src/context/ChatContext.tsx"
click node_mediaui "https://github.com/shonnay/k3ncrypt/blob/main/client/src/media/HttpAttachmentGateway.ts"
click node_sdkcrypto "https://github.com/shonnay/k3ncrypt/blob/main/service/src/crypto/modernConversation.ts"
click node_sdkdevices "https://github.com/shonnay/k3ncrypt/blob/main/service/src/devices/lifecycle.ts"
click node_sdksync "https://github.com/shonnay/k3ncrypt/blob/main/service/src/sync/runtime.ts"
click node_sdkcalls "https://github.com/shonnay/k3ncrypt/blob/main/service/src/calls/service.ts"
click node_sdkattachments "https://github.com/shonnay/k3ncrypt/blob/main/service/src/attachments/service.ts"
click node_sdkprivate "https://github.com/shonnay/k3ncrypt/blob/main/service/src/privateNetwork/runtime.ts"
click node_api "https://github.com/shonnay/k3ncrypt/blob/main/backend/api/index.ts"
click node_trust "https://github.com/shonnay/k3ncrypt/blob/main/backend/api/deviceTrust.ts"
click node_membership "https://github.com/shonnay/k3ncrypt/blob/main/backend/api/networkMembership.ts"
click node_attachmentservice "https://github.com/shonnay/k3ncrypt/blob/main/backend/security/authenticatedAttachmentService.ts"
click node_relay "https://github.com/shonnay/k3ncrypt/blob/main/backend/socket.io/listeners.ts"
click node_mongo "https://github.com/shonnay/k3ncrypt/blob/main/backend/db/index.ts"
click node_androidapp "https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/MainActivity.kt"
click node_androidmessaging "https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt"
click node_androididentity "https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt"
click node_androidcalls "https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidCallController.kt"
click node_androidcrypto "https://github.com/shonnay/k3ncrypt/blob/main/android/crypto/src/main/kotlin/com/k3ncrypt/crypto/CryptoPort.kt"
click node_androidnetwork "https://github.com/shonnay/k3ncrypt/blob/main/android/network/src/main/kotlin/com/k3ncrypt/network/K3ncryptApi.kt"
click node_androidstore "https://github.com/shonnay/k3ncrypt/blob/main/android/storage/src/main/kotlin/com/k3ncrypt/storage/CryptoStateStore.kt"
click node_browserstore "https://github.com/shonnay/k3ncrypt/blob/main/service/src/storage/secureVault.ts"

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_app,node_chatui,node_setupui,node_chatcontext,node_mediaui,node_user toneBlue
class node_sdkcrypto,node_sdkdevices,node_sdksync,node_sdkcalls,node_sdkattachments,node_sdkprivate toneAmber
class node_api,node_trust,node_membership,node_attachmentservice,node_relay toneMint
class node_mongo,node_browserstore toneRose
class node_androidapp,node_androidmessaging,node_androididentity,node_androidcalls,node_androidcrypto,node_androidnetwork,node_androidstore toneIndigo
```

## Components

### Browser client

- [App shell](https://github.com/shonnay/k3ncrypt/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Chat interface](https://github.com/shonnay/k3ncrypt/blob/main/client/src/components/ChatContainer/ChatContainer.tsx): `client/src/components/ChatContainer/ChatContainer.tsx`
- [Conversation setup](https://github.com/shonnay/k3ncrypt/blob/main/client/src/components/SetupOverlay/SetupOverlay.tsx): `client/src/components/SetupOverlay/SetupOverlay.tsx`
- [Chat state](https://github.com/shonnay/k3ncrypt/blob/main/client/src/context/ChatContext.tsx): `client/src/context/ChatContext.tsx`
- [Media gateway](https://github.com/shonnay/k3ncrypt/blob/main/client/src/media/HttpAttachmentGateway.ts): `client/src/media/HttpAttachmentGateway.ts`

### Communication SDK

- [Conversation crypto](https://github.com/shonnay/k3ncrypt/blob/main/service/src/crypto/modernConversation.ts): `service/src/crypto/modernConversation.ts`
- [Device identity](https://github.com/shonnay/k3ncrypt/blob/main/service/src/devices/lifecycle.ts): `service/src/devices/lifecycle.ts`
- [Encrypted sync](https://github.com/shonnay/k3ncrypt/blob/main/service/src/sync/runtime.ts): `service/src/sync/runtime.ts`
- [Call services](https://github.com/shonnay/k3ncrypt/blob/main/service/src/calls/service.ts): `service/src/calls/service.ts`
- [Attachment workflow](https://github.com/shonnay/k3ncrypt/blob/main/service/src/attachments/service.ts): `service/src/attachments/service.ts`
- [Private network](https://github.com/shonnay/k3ncrypt/blob/main/service/src/privateNetwork/runtime.ts): `service/src/privateNetwork/runtime.ts`

### Backend services

- [HTTP API](https://github.com/shonnay/k3ncrypt/blob/main/backend/api/index.ts): `backend/api/index.ts`
- [Trust authority](https://github.com/shonnay/k3ncrypt/blob/main/backend/api/deviceTrust.ts): `backend/api/deviceTrust.ts`
- [Membership authority](https://github.com/shonnay/k3ncrypt/blob/main/backend/api/networkMembership.ts): `backend/api/networkMembership.ts`
- [Attachment authorization](https://github.com/shonnay/k3ncrypt/blob/main/backend/security/authenticatedAttachmentService.ts): `backend/security/authenticatedAttachmentService.ts`
- [Socket relay](https://github.com/shonnay/k3ncrypt/blob/main/backend/socket.io/listeners.ts): `backend/socket.io/listeners.ts`

### Persistence

- [Mongo persistence](https://github.com/shonnay/k3ncrypt/blob/main/backend/db/index.ts): `backend/db/index.ts`
- [Browser secure storage](https://github.com/shonnay/k3ncrypt/blob/main/service/src/storage/secureVault.ts): `service/src/storage/secureVault.ts`

### Android client

- [Android application](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/MainActivity.kt): `android/app/src/main/kotlin/com/k3ncrypt/app/MainActivity.kt`
- [Android messaging](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt): `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt`
- [Android identity](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt): `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt`
- [Android calls](https://github.com/shonnay/k3ncrypt/blob/main/android/app/src/main/kotlin/com/k3ncrypt/app/AndroidCallController.kt): `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidCallController.kt`
- [Android crypto](https://github.com/shonnay/k3ncrypt/blob/main/android/crypto/src/main/kotlin/com/k3ncrypt/crypto/CryptoPort.kt): `android/crypto/src/main/kotlin/com/k3ncrypt/crypto/CryptoPort.kt`
- [Android network](https://github.com/shonnay/k3ncrypt/blob/main/android/network/src/main/kotlin/com/k3ncrypt/network/K3ncryptApi.kt): `android/network/src/main/kotlin/com/k3ncrypt/network/K3ncryptApi.kt`
- [Android encrypted state](https://github.com/shonnay/k3ncrypt/blob/main/android/storage/src/main/kotlin/com/k3ncrypt/storage/CryptoStateStore.kt): `android/storage/src/main/kotlin/com/k3ncrypt/storage/CryptoStateStore.kt`

### Other components

- **User**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Chat state: initializes (evidence: `client/src/App.tsx`)
- App shell → Conversation setup: renders (evidence: `client/src/App.tsx`)
- App shell → Chat interface: renders (evidence: `client/src/App.tsx`)
- Chat state → Browser secure storage: opens vault (evidence: `client/src/context/ChatContext.tsx`)
- Chat state → Conversation crypto: coordinates encryption
- Chat state → Encrypted sync: coordinates sync
- App shell → Media gateway: configures (evidence: `client/src/App.tsx`)
- Media gateway → Attachment workflow: uses workflow
- App shell → Call services: provides call interface
- Conversation crypto → Device identity: uses device identity
- Device identity → Trust authority: requests trust authority (evidence: `README.md`)
- Encrypted sync → Socket relay: relays ciphertext (evidence: `README.md`)
- Call services → Socket relay: relays call signaling (evidence: `README.md`)
- Attachment workflow → Attachment authorization: requests protected media (evidence: `README.md`)
- Private network → Membership authority: checks membership (evidence: `README.md`)
- HTTP API → Trust authority: routes (evidence: `backend/api/index.ts`)
- HTTP API → Membership authority: routes (evidence: `backend/api/index.ts`)
- HTTP API → Attachment authorization: routes attachments (evidence: `backend/api/index.ts`)
- Attachment authorization → Attachment workflow: delegates operations (evidence: `backend/security/authenticatedAttachmentService.ts`)
- HTTP API → Socket relay: separate relay interface
- HTTP API → Mongo persistence: persists metadata (evidence: `README.md`)
- Socket relay → Mongo persistence: stores operational state (evidence: `README.md`)
- User → Android application: uses (evidence: `README.md`)
- Android application → Android messaging: provides messaging
- Android application → Android identity: manages identity
- Android application → Android calls: controls calls
- Android messaging → Android crypto: encrypts messages (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt`)
- Android messaging → Android encrypted state: persists state (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt`)
- Android messaging → Android network: sends relay data (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidMessagingRepository.kt`)
- Android identity → Android crypto: uses crypto (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt`)
- Android identity → Android network: requests lifecycle services (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt`)
- Android identity → Android encrypted state: persists identity (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidIdentityLifecycleRepository.kt`)
- Android calls → Android messaging: sends call signals (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidCallController.kt`)
- Android calls → Android identity: reads identity (evidence: `android/app/src/main/kotlin/com/k3ncrypt/app/AndroidCallController.kt`)
