# incatswetrust/whisper-backend architecture

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

## Overview

whisper-backend is an HTTP API for anonymous, self-destructing encrypted notes and files. Clients POST content and note settings; the notes route encrypts server-mode payloads or accepts opaque client ciphertext, then stores a record. On GET, it checks access conditions, optionally decrypts, atomically burns a view, and returns content or ciphertext. PostgreSQL backs notes and fixed-window rate limits; an authorized cleanup endpoint sweeps expired data. The README documents the API and Vercel Cron integration; relationships for unsampled deployment wiring are shown only where documented.

Main entry points: [`src/app.ts`](https://github.com/incatswetrust/whisper-backend/blob/main/src/app.ts) (HTTP App), [`src/routes/notes.ts`](https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/notes.ts) (Read Notes), [`src/rateLimit.ts`](https://github.com/incatswetrust/whisper-backend/blob/main/src/rateLimit.ts) (Rate Limits), [`src/routes/internal.ts`](https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/internal.ts) (Expiry Cleanup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_app["HTTP App<br/>[app.ts]"]
end

subgraph group_notes["Note Lifecycle"]
  node_create["Create Notes<br/>[notes.ts]"]
  node_read["Read Notes<br/>[notes.ts]"]
  node_crypto["Note Encryption<br/>[crypto.ts]"]
end

subgraph group_guards["Access Controls"]
  node_ip["IP Gate<br/>[ip.ts]"]
  node_limits["Rate Limits<br/>[rateLimit.ts]"]
  node_config["Runtime Config<br/>[config.ts]"]
end

subgraph group_data["Persistence and Cleanup"]
  node_store["Note Store<br/>[store.ts]"]
  node_sql["SQL Client<br/>[db.ts]"]
  node_postgres[("PostgreSQL")]
  node_cleanup["Expiry Cleanup<br/>[internal.ts]"]
end

node_clients(("API Clients"))
node_cron(("Vercel Cron"))

node_clients -->|"send requests"| node_app
node_app -->|"routes POST"| node_create
node_app -->|"routes GET"| node_read
node_app -->|"routes internal"| node_cleanup
node_app -->|"reads stats"| node_store
node_app -->|"configures CORS"| node_config
node_create -->|"applies limiter"| node_limits
node_read -->|"applies limiters"| node_limits
node_create -->|"encrypts payload"| node_crypto
node_read -->|"decrypts payload"| node_crypto
node_create -->|"writes note"| node_store
node_read -->|"fetches and burns"| node_store
node_read -->|"checks allowlist"| node_ip
node_create -->|"reads limits and defaults"| node_config
node_read -->|"reads limits"| node_config
node_limits -->|"gets client IP"| node_ip
node_limits -->|"updates buckets"| node_sql
node_store -->|"reads and writes notes"| node_sql
node_sql -->|"queries database"| node_postgres
node_cleanup -->|"deletes expired rows"| node_sql
node_cleanup -->|"checks cron secret"| node_config
node_cron -->|"requests cleanup"| node_cleanup

click node_app "https://github.com/incatswetrust/whisper-backend/blob/main/src/app.ts"
click node_create "https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/notes.ts"
click node_read "https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/notes.ts"
click node_crypto "https://github.com/incatswetrust/whisper-backend/blob/main/src/crypto.ts"
click node_ip "https://github.com/incatswetrust/whisper-backend/blob/main/src/ip.ts"
click node_limits "https://github.com/incatswetrust/whisper-backend/blob/main/src/rateLimit.ts"
click node_config "https://github.com/incatswetrust/whisper-backend/blob/main/src/config.ts"
click node_store "https://github.com/incatswetrust/whisper-backend/blob/main/src/store.ts"
click node_sql "https://github.com/incatswetrust/whisper-backend/blob/main/src/db.ts"
click node_cleanup "https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/internal.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_clients toneBlue
class node_create,node_read,node_crypto toneAmber
class node_ip,node_limits,node_config toneMint
class node_store,node_sql,node_postgres,node_cleanup toneRose
class node_cron toneIndigo
```

## Components

### HTTP API

- [HTTP App](https://github.com/incatswetrust/whisper-backend/blob/main/src/app.ts): `src/app.ts`

### Note Lifecycle

- [Create Notes](https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/notes.ts): `src/routes/notes.ts`
- [Read Notes](https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/notes.ts): `src/routes/notes.ts`
- [Note Encryption](https://github.com/incatswetrust/whisper-backend/blob/main/src/crypto.ts): `src/crypto.ts`

### Access Controls

- [IP Gate](https://github.com/incatswetrust/whisper-backend/blob/main/src/ip.ts): `src/ip.ts`
- [Rate Limits](https://github.com/incatswetrust/whisper-backend/blob/main/src/rateLimit.ts): `src/rateLimit.ts`
- [Runtime Config](https://github.com/incatswetrust/whisper-backend/blob/main/src/config.ts): `src/config.ts`

### Persistence and Cleanup

- [Note Store](https://github.com/incatswetrust/whisper-backend/blob/main/src/store.ts): `src/store.ts`
- [SQL Client](https://github.com/incatswetrust/whisper-backend/blob/main/src/db.ts): `src/db.ts`
- **PostgreSQL**
- [Expiry Cleanup](https://github.com/incatswetrust/whisper-backend/blob/main/src/routes/internal.ts): `src/routes/internal.ts`

### Other components

- **API Clients**
- **Vercel Cron**

## Connections

- API Clients → HTTP App: send requests (evidence: `README.md`)
- HTTP App → Create Notes: routes POST (evidence: `src/app.ts`)
- HTTP App → Read Notes: routes GET (evidence: `src/app.ts`)
- HTTP App → Expiry Cleanup: routes internal (evidence: `src/app.ts`)
- HTTP App → Note Store: reads stats (evidence: `src/app.ts`)
- HTTP App → Runtime Config: configures CORS (evidence: `src/app.ts`)
- Create Notes → Rate Limits: applies limiter (evidence: `src/routes/notes.ts`)
- Read Notes → Rate Limits: applies limiters (evidence: `src/routes/notes.ts`)
- Create Notes → Note Encryption: encrypts payload (evidence: `src/routes/notes.ts`)
- Read Notes → Note Encryption: decrypts payload (evidence: `src/routes/notes.ts`)
- Create Notes → Note Store: writes note (evidence: `src/routes/notes.ts`)
- Read Notes → Note Store: fetches and burns (evidence: `src/routes/notes.ts`)
- Read Notes → IP Gate: checks allowlist (evidence: `src/routes/notes.ts`)
- Create Notes → Runtime Config: reads limits and defaults (evidence: `src/routes/notes.ts`)
- Read Notes → Runtime Config: reads limits (evidence: `src/routes/notes.ts`)
- Rate Limits → IP Gate: gets client IP (evidence: `src/rateLimit.ts`)
- Rate Limits → SQL Client: updates buckets (evidence: `src/rateLimit.ts`)
- Note Store → SQL Client: reads and writes notes (evidence: `src/store.ts`)
- SQL Client → PostgreSQL: queries database (evidence: `src/db.ts`)
- Expiry Cleanup → SQL Client: deletes expired rows (evidence: `src/routes/internal.ts`)
- Expiry Cleanup → Runtime Config: checks cron secret (evidence: `src/routes/internal.ts`)
- Vercel Cron → Expiry Cleanup: requests cleanup (evidence: `README.md`)
