# asp3x/shroud architecture

> Architecture diagram of the GitHub repository asp3x/shroud, 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/asp3x/shroud
- Repository: https://github.com/asp3x/shroud

## Overview

Shroud is an end-to-end encrypted messenger with native iOS and web clients backed by a Rust API. The main workflow is a user signing in, establishing device identity, then sending and receiving encrypted messages; clients also support calls, media, notifications, and voice transcription. Client-side crypto and local history remain on devices, while the server stores and relays ciphertext. The graph combines documented deployment/data boundaries with source-index relationships; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`server/crates/shroud-server/src/routes/mod.rs`](https://github.com/asp3x/shroud/blob/master/server/crates/shroud-server/src/routes/mod.rs) (Rust API), [`web/src/App.tsx`](https://github.com/asp3x/shroud/blob/master/web/src/App.tsx) (Web app), [`ios/shroud/App/ShroudApp.swift`](https://github.com/asp3x/shroud/blob/master/ios/shroud/App/ShroudApp.swift) (iOS app), [`ios/shroud/Services/Auth/SessionController.swift`](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Auth/SessionController.swift) (iOS session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_iosapp["iOS app<br/>[ShroudApp.swift]"]
  node_webapi["Web API client<br/>[client.ts]"]
  node_iossession["iOS session"]
end

subgraph group_identity["Identity and crypto"]
  node_webidentity["Web identity crypto<br/>[bytes.ts]"]
  node_ioscrypto["iOS crypto controller"]
  node_ioskeymaterial["Identity key material"]
end

subgraph group_messaging["Messaging and media"]
  node_webmessaging["Web messaging<br/>[messaging.ts]"]
  node_iosmessaging["iOS messaging controller"]
  node_localrepo[("Local message repository")]
  node_localstore[("Local message store")]
  node_localmedia[("Local media cache")]
  node_transcription["Voice transcription"]
end

subgraph group_realtime["Calls and realtime"]
  node_webcalls["Web call controller<br/>[controller.ts]"]
  node_webcallcrypto["Web call crypto<br/>[crypto.ts]"]
  node_ioscalls["iOS call controller"]
  node_callmedia["WebRTC media engine"]
  node_realtimeclient["iOS realtime client"]
end

subgraph group_backend["Server services"]
  node_api["Rust API<br/>[mod.rs]"]
  node_authroutes["Authentication routes<br/>[auth.rs]"]
  node_postgres[("PostgreSQL")]
  node_media[("Nebular media store")]
  node_redis[("Redis fan-out")]
end

node_person(("User"))

node_person -->|"uses"| node_webapp
node_person -->|"uses"| node_iosapp
node_webapp -->|"requests"| node_webapi
node_iosapp -.->|"routes session"| node_iossession
node_iossession -->|"unlocks"| node_ioscrypto
node_ioscrypto -->|"loads keys"| node_ioskeymaterial
node_webapp -->|"uses crypto"| node_webidentity
node_webapp -.->|"presents chats"| node_webmessaging
node_iosapp -.->|"presents chats"| node_iosmessaging
node_iosmessaging -->|"persists locally"| node_localrepo
node_localrepo -.->|"stores messages"| node_localstore
node_iosmessaging -.->|"caches media"| node_localmedia
node_webapp -.->|"offers calls"| node_webcalls
node_webcalls -->|"derives call keys"| node_webcallcrypto
node_ioscalls -->|"controls media"| node_callmedia
node_ioscalls -->|"signals calls"| node_realtimeclient
node_webmessaging -.->|"transcribes voice"| node_transcription
node_webapi -->|"HTTP requests"| node_api
node_iossession -.->|"auth requests"| node_api
node_api -->|"routes auth"| node_authroutes
node_api -->|"reads and writes"| node_postgres
node_api -->|"stores ciphertext blobs"| node_media
node_api -->|"fans out realtime"| node_redis

click node_webapp "https://github.com/asp3x/shroud/blob/master/web/src/App.tsx"
click node_iosapp "https://github.com/asp3x/shroud/blob/master/ios/shroud/App/ShroudApp.swift"
click node_webapi "https://github.com/asp3x/shroud/blob/master/web/src/api/client.ts"
click node_iossession "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Auth/SessionController.swift"
click node_webidentity "https://github.com/asp3x/shroud/blob/master/web/src/crypto/bytes.ts"
click node_ioscrypto "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Crypto/CryptoController.swift"
click node_ioskeymaterial "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Crypto/IdentityKeyMaterial.swift"
click node_webmessaging "https://github.com/asp3x/shroud/blob/master/web/src/messaging.ts"
click node_iosmessaging "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/MessagingController.swift"
click node_localrepo "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/MessagingLocalRepository.swift"
click node_localstore "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/LocalMessageStore.swift"
click node_localmedia "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/LocalMediaCache.swift"
click node_webcalls "https://github.com/asp3x/shroud/blob/master/web/src/calls/controller.ts"
click node_webcallcrypto "https://github.com/asp3x/shroud/blob/master/web/src/calls/crypto.ts"
click node_ioscalls "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Calls/CallController.swift"
click node_callmedia "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Calls/CallMediaEngine.swift"
click node_realtimeclient "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Realtime/RealtimeClient.swift"
click node_transcription "https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Transcription/WhisperKitEngine.swift"
click node_api "https://github.com/asp3x/shroud/blob/master/server/crates/shroud-server/src/routes/mod.rs"
click node_authroutes "https://github.com/asp3x/shroud/blob/master/server/crates/shroud-server/src/routes/auth.rs"

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_webapp,node_iosapp,node_webapi,node_iossession,node_person toneBlue
class node_webidentity,node_ioscrypto,node_ioskeymaterial toneAmber
class node_webmessaging,node_iosmessaging,node_localrepo,node_localstore,node_localmedia,node_transcription toneMint
class node_webcalls,node_webcallcrypto,node_ioscalls,node_callmedia,node_realtimeclient toneRose
class node_api,node_authroutes,node_postgres,node_media,node_redis toneIndigo
```

## Components

### Client apps

- [Web app](https://github.com/asp3x/shroud/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [iOS app](https://github.com/asp3x/shroud/blob/master/ios/shroud/App/ShroudApp.swift): `ios/shroud/App/ShroudApp.swift`
- [Web API client](https://github.com/asp3x/shroud/blob/master/web/src/api/client.ts): `web/src/api/client.ts`
- [iOS session](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Auth/SessionController.swift): `ios/shroud/Services/Auth/SessionController.swift`

### Identity and crypto

- [Web identity crypto](https://github.com/asp3x/shroud/blob/master/web/src/crypto/bytes.ts): `web/src/crypto/bytes.ts`
- [iOS crypto controller](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Crypto/CryptoController.swift): `ios/shroud/Services/Crypto/CryptoController.swift`
- [Identity key material](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Crypto/IdentityKeyMaterial.swift): `ios/shroud/Services/Crypto/IdentityKeyMaterial.swift`

### Messaging and media

- [Web messaging](https://github.com/asp3x/shroud/blob/master/web/src/messaging.ts): `web/src/messaging.ts`
- [iOS messaging controller](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/MessagingController.swift): `ios/shroud/Services/Messaging/MessagingController.swift`
- [Local message repository](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/MessagingLocalRepository.swift): `ios/shroud/Services/Messaging/MessagingLocalRepository.swift`
- [Local message store](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/LocalMessageStore.swift): `ios/shroud/Services/Messaging/LocalMessageStore.swift`
- [Local media cache](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Messaging/LocalMediaCache.swift): `ios/shroud/Services/Messaging/LocalMediaCache.swift`
- [Voice transcription](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Transcription/WhisperKitEngine.swift): `ios/shroud/Services/Transcription/WhisperKitEngine.swift`

### Calls and realtime

- [Web call controller](https://github.com/asp3x/shroud/blob/master/web/src/calls/controller.ts): `web/src/calls/controller.ts`
- [Web call crypto](https://github.com/asp3x/shroud/blob/master/web/src/calls/crypto.ts): `web/src/calls/crypto.ts`
- [iOS call controller](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Calls/CallController.swift): `ios/shroud/Services/Calls/CallController.swift`
- [WebRTC media engine](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Calls/CallMediaEngine.swift): `ios/shroud/Services/Calls/CallMediaEngine.swift`
- [iOS realtime client](https://github.com/asp3x/shroud/blob/master/ios/shroud/Services/Realtime/RealtimeClient.swift): `ios/shroud/Services/Realtime/RealtimeClient.swift`

### Server services

- [Rust API](https://github.com/asp3x/shroud/blob/master/server/crates/shroud-server/src/routes/mod.rs): `server/crates/shroud-server/src/routes/mod.rs`
- [Authentication routes](https://github.com/asp3x/shroud/blob/master/server/crates/shroud-server/src/routes/auth.rs): `server/crates/shroud-server/src/routes/auth.rs`
- **PostgreSQL**
- **Nebular media store**
- **Redis fan-out**

### Other components

- **User**

## Connections

- User → Web app: uses (evidence: `README.md`)
- User → iOS app: uses (evidence: `README.md`)
- Web app → Web API client: requests (evidence: `web/src/App.tsx`)
- iOS app → iOS session: routes session
- iOS session → iOS crypto controller: unlocks (evidence: `ios/shroud/Services/Crypto/CryptoController.swift`)
- iOS crypto controller → Identity key material: loads keys (evidence: `ios/shroud/Services/Crypto/CryptoController.swift`)
- Web app → Web identity crypto: uses crypto (evidence: `web/src/App.tsx`)
- Web app → Web messaging: presents chats
- iOS app → iOS messaging controller: presents chats
- iOS messaging controller → Local message repository: persists locally (evidence: `ios/shroud/Services/Messaging/MessagingController.swift`)
- Local message repository → Local message store: stores messages (evidence: `ios/shroud/Services/Messaging/MessagingLocalRepository.swift`)
- iOS messaging controller → Local media cache: caches media
- Web app → Web call controller: offers calls
- Web call controller → Web call crypto: derives call keys (evidence: `web/src/calls/controller.ts`)
- iOS call controller → WebRTC media engine: controls media (evidence: `ios/shroud/Services/Calls/CallController.swift`)
- iOS call controller → iOS realtime client: signals calls (evidence: `ios/shroud/Services/Calls/CallController.swift`)
- Web messaging → Voice transcription: transcribes voice
- Web API client → Rust API: HTTP requests (evidence: `README.md`)
- iOS session → Rust API: auth requests
- Rust API → Authentication routes: routes auth (evidence: `server/crates/shroud-server/src/routes/auth.rs`)
- Rust API → PostgreSQL: reads and writes (evidence: `README.md`)
- Rust API → Nebular media store: stores ciphertext blobs (evidence: `README.md`)
- Rust API → Redis fan-out: fans out realtime (evidence: `README.md`)
