# etragardh/cutout architecture

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

- Interactive diagram: https://gitdiagram.com/etragardh/cutout
- Repository: https://github.com/etragardh/cutout

## Overview

Cutout is a self-hosted encrypted messenger: the PWA lets people manage servers, contacts, groups, and conversations; the client engine handles identity and messaging flows, while the server acts as an encrypted mailbox. The graph includes the documented protocol, trust, audit, and storage capabilities. Several UI screens and protocol modules were not sampled, so those branches are shown at subsystem level; edges are limited to indexed references or explicit README statements.

Main entry points: [`packages/app-core/src/engine/engine.ts`](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/engine.ts) (Messaging engine), [`server/cmd/cutout/main.go`](https://github.com/etragardh/cutout/blob/main/server/cmd/cutout/main.go) (Server runtime), [`apps/pwa/src/engine/EngineProvider.tsx`](https://github.com/etragardh/cutout/blob/main/apps/pwa/src/engine/EngineProvider.tsx) (Engine provider), [`packages/app-core/src/engine/connection.ts`](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/connection.ts) (Server connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pwa["PWA client"]
  node_ui["PWA screens"]
  node_ui_components["UI components"]
  node_provider["Engine provider<br/>[EngineProvider.tsx]"]
  node_browser_storage[("Browser storage<br/>[browser.ts]")]
  node_wasm["ML-DSA WASM<br/>[mldsaWasm.ts]"]
end

subgraph group_core["Client engine"]
  node_engine["Messaging engine<br/>[engine.ts]"]
  node_connection["Server connection<br/>[connection.ts]"]
  node_server_api["Mailbox API client<br/>[serverApi.ts]"]
  node_cover["Cover scheduler<br/>[cover.ts]"]
  node_inbound["Inbound processing<br/>[inbound.ts]"]
  node_outbox["Message outbox<br/>[outbox.ts]"]
  node_streams["Message streams<br/>[streams.ts]"]
  node_flows["Identity and group flows"]
  node_trust["Trust graph<br/>[trust.ts]"]
  node_audit["Identity audit log<br/>[auditlog.ts]"]
  node_repo[("Client repository<br/>[repo.ts]")]
  node_model["Local domain model<br/>[model.ts]"]
end

subgraph group_protocol["Wire protocol"]
  node_protocol_suite["Wire protocol suite"]
  node_cbor["Deterministic CBOR<br/>[cbor.ts]"]
end

subgraph group_server["Mailbox server"]
  node_server_main["Server runtime<br/>[main.go]"]
  node_http_api["Mailbox HTTP API<br/>[api.go]"]
  node_auth["Mailbox authentication<br/>[auth.go]"]
  node_rate_limit["Rate limiting<br/>[ratelimit.go]"]
  node_mailbox[("Mailbox store<br/>[store.go]")]
  node_server_protocol["Server protocol codec<br/>[encode.go]"]
  node_tls["TLS modes<br/>[tlsmode.go]"]
end

node_person(("Messenger user"))
node_operator(("Server operator"))
node_peer(("Other messenger"))

node_person -->|"uses"| node_ui
node_ui -.->|"drives"| node_provider
node_provider -->|"opens storage"| node_browser_storage
node_provider -->|"constructs and starts"| node_engine
node_provider -->|"loads"| node_wasm
node_provider -->|"uses"| node_repo
node_ui -.->|"renders"| node_ui_components
node_engine -->|"persists via"| node_repo
node_engine -->|"records identity history"| node_audit
node_engine -->|"derives trust"| node_trust
node_engine -->|"uses identity and group flows"| node_flows
node_engine -->|"uses"| node_connection
node_engine -->|"uses"| node_inbound
node_engine -->|"uses"| node_outbox
node_engine -->|"uses"| node_streams
node_engine -->|"models"| node_model
node_connection -->|"uses"| node_server_api
node_connection -->|"uses"| node_cover
node_connection -->|"dispatches"| node_outbox
node_connection -->|"uses"| node_streams
node_inbound -->|"uses"| node_streams
node_audit -->|"stores entries"| node_repo
node_repo -->|"encodes records"| node_model
node_engine -->|"uses wire protocol"| node_protocol_suite
node_protocol_suite -.->|"encodes values"| node_cbor
node_peer -.->|"sends mailbox traffic"| node_server_main
node_operator -->|"runs"| node_server_main
node_server_main -->|"serves"| node_http_api
node_server_main -->|"opens and cleans"| node_mailbox
node_server_main -->|"configures"| node_tls
node_http_api -->|"uses"| node_auth
node_http_api -->|"uses"| node_rate_limit
node_http_api -->|"uses"| node_mailbox
node_server_api -.->|"exchanges encrypted mailbox traffic"| node_http_api
node_server_main -.->|"supports wire encoding"| node_server_protocol

click node_ui "https://github.com/etragardh/cutout/tree/main/apps/pwa/src/screens"
click node_ui_components "https://github.com/etragardh/cutout/tree/main/apps/pwa/src/components"
click node_provider "https://github.com/etragardh/cutout/blob/main/apps/pwa/src/engine/EngineProvider.tsx"
click node_browser_storage "https://github.com/etragardh/cutout/blob/main/apps/pwa/src/platform/browser.ts"
click node_wasm "https://github.com/etragardh/cutout/blob/main/apps/pwa/src/platform/mldsaWasm.ts"
click node_engine "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/engine.ts"
click node_connection "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/connection.ts"
click node_server_api "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/serverApi.ts"
click node_cover "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/cover.ts"
click node_inbound "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/inbound.ts"
click node_outbox "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/outbox.ts"
click node_streams "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/streams.ts"
click node_flows "https://github.com/etragardh/cutout/tree/main/packages/app-core/src/flows"
click node_trust "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/trust.ts"
click node_audit "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/auditlog.ts"
click node_repo "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/store/repo.ts"
click node_model "https://github.com/etragardh/cutout/blob/main/packages/app-core/src/model.ts"
click node_protocol_suite "https://github.com/etragardh/cutout/tree/main/packages/protocol/src"
click node_cbor "https://github.com/etragardh/cutout/blob/main/packages/protocol/src/cbor.ts"
click node_server_main "https://github.com/etragardh/cutout/blob/main/server/cmd/cutout/main.go"
click node_http_api "https://github.com/etragardh/cutout/blob/main/server/internal/api/api.go"
click node_auth "https://github.com/etragardh/cutout/blob/main/server/internal/auth/auth.go"
click node_rate_limit "https://github.com/etragardh/cutout/blob/main/server/internal/ratelimit/ratelimit.go"
click node_mailbox "https://github.com/etragardh/cutout/blob/main/server/internal/store/store.go"
click node_server_protocol "https://github.com/etragardh/cutout/blob/main/server/internal/protocol/encode.go"
click node_tls "https://github.com/etragardh/cutout/blob/main/server/internal/tlsmode/tlsmode.go"

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_ui,node_ui_components,node_provider,node_browser_storage,node_wasm,node_person toneBlue
class node_engine,node_connection,node_server_api,node_cover,node_inbound,node_outbox,node_streams,node_flows,node_trust,node_audit,node_repo,node_model toneAmber
class node_protocol_suite,node_cbor,node_operator toneMint
class node_server_main,node_http_api,node_auth,node_rate_limit,node_mailbox,node_server_protocol,node_tls toneRose
class node_peer toneIndigo
```

## Components

### PWA client

- [PWA screens](https://github.com/etragardh/cutout/tree/main/apps/pwa/src/screens): `apps/pwa/src/screens`
- [UI components](https://github.com/etragardh/cutout/tree/main/apps/pwa/src/components): `apps/pwa/src/components`
- [Engine provider](https://github.com/etragardh/cutout/blob/main/apps/pwa/src/engine/EngineProvider.tsx): `apps/pwa/src/engine/EngineProvider.tsx`
- [Browser storage](https://github.com/etragardh/cutout/blob/main/apps/pwa/src/platform/browser.ts): `apps/pwa/src/platform/browser.ts`
- [ML-DSA WASM](https://github.com/etragardh/cutout/blob/main/apps/pwa/src/platform/mldsaWasm.ts): `apps/pwa/src/platform/mldsaWasm.ts`

### Client engine

- [Messaging engine](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/engine.ts): `packages/app-core/src/engine/engine.ts`
- [Server connection](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/connection.ts): `packages/app-core/src/engine/connection.ts`
- [Mailbox API client](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/serverApi.ts): `packages/app-core/src/engine/serverApi.ts`
- [Cover scheduler](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/cover.ts): `packages/app-core/src/engine/cover.ts`
- [Inbound processing](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/inbound.ts): `packages/app-core/src/engine/inbound.ts`
- [Message outbox](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/outbox.ts): `packages/app-core/src/engine/outbox.ts`
- [Message streams](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/engine/streams.ts): `packages/app-core/src/engine/streams.ts`
- [Identity and group flows](https://github.com/etragardh/cutout/tree/main/packages/app-core/src/flows): `packages/app-core/src/flows`
- [Trust graph](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/trust.ts): `packages/app-core/src/trust.ts`
- [Identity audit log](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/auditlog.ts): `packages/app-core/src/auditlog.ts`
- [Client repository](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/store/repo.ts): `packages/app-core/src/store/repo.ts`
- [Local domain model](https://github.com/etragardh/cutout/blob/main/packages/app-core/src/model.ts): `packages/app-core/src/model.ts`

### Wire protocol

- [Wire protocol suite](https://github.com/etragardh/cutout/tree/main/packages/protocol/src): `packages/protocol/src`
- [Deterministic CBOR](https://github.com/etragardh/cutout/blob/main/packages/protocol/src/cbor.ts): `packages/protocol/src/cbor.ts`

### Mailbox server

- [Server runtime](https://github.com/etragardh/cutout/blob/main/server/cmd/cutout/main.go): `server/cmd/cutout/main.go`
- [Mailbox HTTP API](https://github.com/etragardh/cutout/blob/main/server/internal/api/api.go): `server/internal/api/api.go`
- [Mailbox authentication](https://github.com/etragardh/cutout/blob/main/server/internal/auth/auth.go): `server/internal/auth/auth.go`
- [Rate limiting](https://github.com/etragardh/cutout/blob/main/server/internal/ratelimit/ratelimit.go): `server/internal/ratelimit/ratelimit.go`
- [Mailbox store](https://github.com/etragardh/cutout/blob/main/server/internal/store/store.go): `server/internal/store/store.go`
- [Server protocol codec](https://github.com/etragardh/cutout/blob/main/server/internal/protocol/encode.go): `server/internal/protocol/encode.go`
- [TLS modes](https://github.com/etragardh/cutout/blob/main/server/internal/tlsmode/tlsmode.go): `server/internal/tlsmode/tlsmode.go`

### Other components

- **Messenger user**
- **Server operator**
- **Other messenger**

## Connections

- Messenger user → PWA screens: uses (evidence: `README.md`)
- PWA screens → Engine provider: drives
- Engine provider → Browser storage: opens storage (evidence: `apps/pwa/src/engine/EngineProvider.tsx`)
- Engine provider → Messaging engine: constructs and starts (evidence: `apps/pwa/src/engine/EngineProvider.tsx`)
- Engine provider → ML-DSA WASM: loads (evidence: `apps/pwa/src/engine/EngineProvider.tsx`)
- Engine provider → Client repository: uses (evidence: `apps/pwa/src/engine/EngineProvider.tsx`)
- PWA screens → UI components: renders (evidence: `apps/pwa/src/screens/Contacts.tsx`)
- Messaging engine → Client repository: persists via (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Identity audit log: records identity history (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Trust graph: derives trust (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Identity and group flows: uses identity and group flows (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Server connection: uses (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Inbound processing: uses (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Message outbox: uses (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Message streams: uses (evidence: `packages/app-core/src/engine/engine.ts`)
- Messaging engine → Local domain model: models (evidence: `packages/app-core/src/engine/engine.ts`)
- Server connection → Mailbox API client: uses (evidence: `packages/app-core/src/engine/connection.ts`)
- Server connection → Cover scheduler: uses (evidence: `packages/app-core/src/engine/connection.ts`)
- Server connection → Message outbox: dispatches (evidence: `packages/app-core/src/engine/connection.ts`)
- Server connection → Message streams: uses (evidence: `packages/app-core/src/engine/connection.ts`)
- Inbound processing → Message streams: uses (evidence: `packages/app-core/src/engine/inbound.ts`)
- Identity audit log → Client repository: stores entries (evidence: `packages/app-core/src/auditlog.ts`)
- Client repository → Local domain model: encodes records (evidence: `packages/app-core/src/store/repo.ts`)
- Messaging engine → Wire protocol suite: uses wire protocol (evidence: `packages/app-core/src/engine/engine.ts`)
- Wire protocol suite → Deterministic CBOR: encodes values (evidence: `packages/protocol/src/qr.ts`)
- Other messenger → Server runtime: sends mailbox traffic
- Server operator → Server runtime: runs (evidence: `server/cmd/cutout/main.go`)
- Server runtime → Mailbox HTTP API: serves (evidence: `server/cmd/cutout/main.go`)
- Server runtime → Mailbox store: opens and cleans (evidence: `server/cmd/cutout/main.go`)
- Server runtime → TLS modes: configures (evidence: `server/cmd/cutout/main.go`)
- Mailbox HTTP API → Mailbox authentication: uses (evidence: `server/internal/api/api.go`)
- Mailbox HTTP API → Rate limiting: uses (evidence: `server/internal/api/api.go`)
- Mailbox HTTP API → Mailbox store: uses (evidence: `server/internal/api/api.go`)
- Mailbox API client → Mailbox HTTP API: exchanges encrypted mailbox traffic
- Server runtime → Server protocol codec: supports wire encoding
