# sums001/openinbox architecture

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

- Interactive diagram: https://gitdiagram.com/sums001/openinbox
- Repository: https://github.com/sums001/openinbox

## Overview

OpenInbox is a self-hosted business-email application on Cloudflare. A user opens the web client, completes setup and authentication, then manages mail and administration through the client’s same-origin API; the Worker handles API requests and scheduled or mail-related work. The README also documents inbound routing, outbound provider failover, domain/DNS setup, security, and optional attachment storage. The graph preserves these product stages, but several runtime links are documented only at a high level because their implementation files were not sampled.

Main entry points: [`src/web/App.tsx`](https://github.com/sums001/openinbox/blob/main/src/web/App.tsx) (Application shell), [`src/worker/app.ts`](https://github.com/sums001/openinbox/blob/main/src/worker/app.ts) (API router), [`src/web/lib/api.ts`](https://github.com/sums001/openinbox/blob/main/src/web/lib/api.ts) (API client), [`src/web/pages/mail`](https://github.com/sums001/openinbox/tree/main/src/web/pages/mail) (Mail client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Application shell<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_ui["Sign-in and recovery"]
end

subgraph group_mail["Mail workflows"]
  node_mail_ui["Mail client"]
  node_sanitize["Message rendering safety<br/>[sanitize.ts]"]
end

subgraph group_admin["Setup and administration"]
  node_admin_ui["Admin console"]
  node_setup_ui["Setup wizard<br/>[SetupPage.tsx]"]
  node_settings_ui["User settings"]
end

subgraph group_worker["Worker services"]
  node_worker_api["API router<br/>[app.ts]"]
  node_auth_sessions["Session security<br/>[session.ts]"]
  node_setup_service["Instance and domain setup<br/>[setup.ts]"]
  node_mail_routes["Mail API routes<br/>[mail.ts]"]
  node_compose_routes["Compose routes<br/>[compose.ts]"]
  node_inbound["Inbound processing<br/>[inbound.ts]"]
  node_send["Outbound delivery<br/>[send.ts]"]
  node_webhooks["Delivery webhooks<br/>[webhooks.ts]"]
end

subgraph group_platform["Cloudflare and storage"]
  node_db[("D1 database<br/>[db.ts]")]
  node_r2[("Attachment storage<br/>[r2.ts]")]
  node_cloudflare_api{{"Cloudflare API"}}
  node_email_routing{{"Email Routing"}}
  node_providers{{"Sending providers<br/>[index.ts]"}}
end

node_user(("Mailbox user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_auth_ui
node_webapp -->|"routes to"| node_setup_ui
node_webapp -->|"routes to"| node_mail_ui
node_webapp -->|"routes to"| node_admin_ui
node_webapp -->|"routes to"| node_settings_ui
node_mail_ui -->|"uses"| node_sanitize
node_auth_ui -.->|"requests"| node_api_client
node_mail_ui -.->|"requests"| node_api_client
node_admin_ui -.->|"requests"| node_api_client
node_setup_ui -->|"requests"| node_api_client
node_settings_ui -.->|"requests"| node_api_client
node_api_client -->|"calls API"| node_worker_api
node_worker_api -->|"loads session"| node_auth_sessions
node_worker_api -.->|"routes setup"| node_setup_service
node_worker_api -->|"routes mail"| node_mail_routes
node_worker_api -.->|"routes compose"| node_compose_routes
node_email_routing -->|"hands off mail"| node_inbound
node_inbound -.->|"stores messages"| node_db
node_send -.->|"delivers through"| node_providers
node_providers -.->|"delivers mail"| node_user
node_webhooks -->|"updates delivery state"| node_db
node_setup_service -->|"configures domains"| node_cloudflare_api
node_cloudflare_api -->|"configures routing"| node_email_routing
node_inbound -.->|"stores large attachments"| node_r2
node_worker_api -->|"uses D1"| node_db
node_user -->|"administers instance"| node_admin_ui

click node_webapp "https://github.com/sums001/openinbox/blob/main/src/web/App.tsx"
click node_api_client "https://github.com/sums001/openinbox/blob/main/src/web/lib/api.ts"
click node_auth_ui "https://github.com/sums001/openinbox/tree/main/src/web/pages/auth"
click node_mail_ui "https://github.com/sums001/openinbox/tree/main/src/web/pages/mail"
click node_sanitize "https://github.com/sums001/openinbox/blob/main/src/web/lib/sanitize.ts"
click node_admin_ui "https://github.com/sums001/openinbox/tree/main/src/web/pages/admin"
click node_setup_ui "https://github.com/sums001/openinbox/blob/main/src/web/pages/setup/SetupPage.tsx"
click node_settings_ui "https://github.com/sums001/openinbox/tree/main/src/web/pages/settings"
click node_worker_api "https://github.com/sums001/openinbox/blob/main/src/worker/app.ts"
click node_auth_sessions "https://github.com/sums001/openinbox/blob/main/src/worker/auth/session.ts"
click node_setup_service "https://github.com/sums001/openinbox/blob/main/src/worker/services/setup.ts"
click node_mail_routes "https://github.com/sums001/openinbox/blob/main/src/worker/routes/mail.ts"
click node_compose_routes "https://github.com/sums001/openinbox/blob/main/src/worker/routes/compose.ts"
click node_inbound "https://github.com/sums001/openinbox/blob/main/src/worker/services/inbound.ts"
click node_send "https://github.com/sums001/openinbox/blob/main/src/worker/services/send.ts"
click node_webhooks "https://github.com/sums001/openinbox/blob/main/src/worker/services/webhooks.ts"
click node_db "https://github.com/sums001/openinbox/blob/main/src/worker/db/db.ts"
click node_r2 "https://github.com/sums001/openinbox/blob/main/src/worker/storage/r2.ts"
click node_providers "https://github.com/sums001/openinbox/blob/main/src/worker/providers/index.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_webapp,node_api_client,node_auth_ui,node_user toneBlue
class node_mail_ui,node_sanitize toneAmber
class node_admin_ui,node_setup_ui,node_settings_ui toneMint
class node_worker_api,node_auth_sessions,node_setup_service,node_mail_routes,node_compose_routes,node_inbound,node_send,node_webhooks toneRose
class node_db,node_r2,node_cloudflare_api,node_email_routing,node_providers toneIndigo
```

## Components

### Web client

- [Application shell](https://github.com/sums001/openinbox/blob/main/src/web/App.tsx): `src/web/App.tsx`
- [API client](https://github.com/sums001/openinbox/blob/main/src/web/lib/api.ts): `src/web/lib/api.ts`
- [Sign-in and recovery](https://github.com/sums001/openinbox/tree/main/src/web/pages/auth): `src/web/pages/auth`

### Mail workflows

- [Mail client](https://github.com/sums001/openinbox/tree/main/src/web/pages/mail): `src/web/pages/mail`
- [Message rendering safety](https://github.com/sums001/openinbox/blob/main/src/web/lib/sanitize.ts): `src/web/lib/sanitize.ts`

### Setup and administration

- [Admin console](https://github.com/sums001/openinbox/tree/main/src/web/pages/admin): `src/web/pages/admin`
- [Setup wizard](https://github.com/sums001/openinbox/blob/main/src/web/pages/setup/SetupPage.tsx): `src/web/pages/setup/SetupPage.tsx`
- [User settings](https://github.com/sums001/openinbox/tree/main/src/web/pages/settings): `src/web/pages/settings`

### Worker services

- [API router](https://github.com/sums001/openinbox/blob/main/src/worker/app.ts): `src/worker/app.ts`
- [Session security](https://github.com/sums001/openinbox/blob/main/src/worker/auth/session.ts): `src/worker/auth/session.ts`
- [Instance and domain setup](https://github.com/sums001/openinbox/blob/main/src/worker/services/setup.ts): `src/worker/services/setup.ts`
- [Mail API routes](https://github.com/sums001/openinbox/blob/main/src/worker/routes/mail.ts): `src/worker/routes/mail.ts`
- [Compose routes](https://github.com/sums001/openinbox/blob/main/src/worker/routes/compose.ts): `src/worker/routes/compose.ts`
- [Inbound processing](https://github.com/sums001/openinbox/blob/main/src/worker/services/inbound.ts): `src/worker/services/inbound.ts`
- [Outbound delivery](https://github.com/sums001/openinbox/blob/main/src/worker/services/send.ts): `src/worker/services/send.ts`
- [Delivery webhooks](https://github.com/sums001/openinbox/blob/main/src/worker/services/webhooks.ts): `src/worker/services/webhooks.ts`

### Cloudflare and storage

- [D1 database](https://github.com/sums001/openinbox/blob/main/src/worker/db/db.ts): `src/worker/db/db.ts`
- [Attachment storage](https://github.com/sums001/openinbox/blob/main/src/worker/storage/r2.ts): `src/worker/storage/r2.ts`
- **Cloudflare API**
- **Email Routing**
- [Sending providers](https://github.com/sums001/openinbox/blob/main/src/worker/providers/index.ts): `src/worker/providers/index.ts`

### Other components

- **Mailbox user**

## Connections

- Mailbox user → Application shell: uses (evidence: `README.md`)
- Application shell → Sign-in and recovery: routes to (evidence: `src/web/App.tsx`)
- Application shell → Setup wizard: routes to (evidence: `src/web/App.tsx`)
- Application shell → Mail client: routes to (evidence: `src/web/App.tsx`)
- Application shell → Admin console: routes to (evidence: `src/web/App.tsx`)
- Application shell → User settings: routes to (evidence: `src/web/App.tsx`)
- Mail client → Message rendering safety: uses (evidence: `src/web/pages/mail/ThreadView.tsx`)
- Sign-in and recovery → API client: requests
- Mail client → API client: requests (evidence: `src/web/pages/mail/ThreadView.tsx`)
- Admin console → API client: requests
- Setup wizard → API client: requests (evidence: `src/web/pages/setup/SetupPage.tsx`)
- User settings → API client: requests (evidence: `src/web/pages/settings/MailboxSettings.tsx`)
- API client → API router: calls API (evidence: `src/web/lib/api.ts`)
- API router → Session security: loads session (evidence: `src/worker/app.ts`)
- API router → Instance and domain setup: routes setup
- API router → Mail API routes: routes mail (evidence: `src/worker/app.ts`)
- API router → Compose routes: routes compose (evidence: `src/worker/app.ts`)
- Email Routing → Inbound processing: hands off mail (evidence: `README.md`)
- Inbound processing → D1 database: stores messages
- Outbound delivery → Sending providers: delivers through
- Sending providers → Mailbox user: delivers mail
- Delivery webhooks → D1 database: updates delivery state (evidence: `src/worker/services/webhooks.ts`)
- Instance and domain setup → Cloudflare API: configures domains (evidence: `README.md`)
- Cloudflare API → Email Routing: configures routing (evidence: `README.md`)
- Inbound processing → Attachment storage: stores large attachments
- API router → D1 database: uses D1 (evidence: `README.md`)
- Mailbox user → Admin console: administers instance (evidence: `README.md`)
