# proverbiallemon/emdash-inbox architecture

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

- Interactive diagram: https://gitdiagram.com/proverbiallemon/emdash-inbox
- Repository: https://github.com/proverbiallemon/emdash-inbox
- Video tour (about a minute): https://gitdiagram.com/proverbiallemon/emdash-inbox/video

## Overview

Emdash Inbox is an EmDash admin mailbox for site email: operators browse conversations, manage message state, compose or reply, and track delivery. Inbound email is authenticated and parsed into mailbox records; outbound sends are journaled before provider delivery so recovery can project accepted sends without resending. The UI also exposes private attachment handling and bundle operations, while native MCP provides a tool interface to mailbox actions. The sampled excerpts show key route and client behavior; some UI and bundle wiring is inferred only where documented or directly evidenced.

Main entry points: [`src/index.ts`](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/index.ts) (Plugin routes), [`src/lib/inboxMcpHandlers.ts`](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/inboxMcpHandlers.ts) (MCP handlers), [`src/lib/composeOps.ts`](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/composeOps.ts) (Compose operations), [`src/admin.tsx`](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/admin.tsx) (Admin entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Admin mailbox"]
  node_admin["Admin entry<br/>[admin.tsx]"]
  node_inboxui["Inbox views"]
  node_threadui["Thread views"]
  node_composeui["Compose editor<br/>[ComposeView.tsx]"]
  node_attachclient["Attachment client"]
  node_bundleui["Bundle inbox<br/>[BundleInbox.tsx]"]
end

subgraph group_api["Plugin interfaces"]
  node_plugin["Plugin routes<br/>[index.ts]"]
  node_mcp["MCP handlers"]
  node_native["Native MCP setup<br/>[nativeMcp.ts]"]
end

subgraph group_mail["Mail lifecycle"]
  node_inbound["Inbound admission<br/>[index.ts]"]
  node_mime["MIME parser<br/>[mimeParser.ts]"]
  node_composeops["Compose operations<br/>[composeOps.ts]"]
  node_delivery["Delivery provider"]
end

subgraph group_state["Mailbox state"]
  node_mailbox[("Mailbox store<br/>[mailboxStore.ts]")]
  node_journal[("Delivery journal<br/>[deliveryJournal.ts]")]
  node_attachments[("Attachment storage<br/>[attachments.ts]")]
end

subgraph group_automation["Tools and operations"]
  node_bundleclient["Bundle operation client<br/>[bundleClient.ts]"]
  node_bundleops["Bundle operations"]
  node_bundlestore[("Bundle state<br/>[bundleStore.ts]")]
end

node_operator(("Mailbox operator"))
node_cfemail["Email Sending binding"]
node_sidecar["Inbound sidecar"]
node_r2[("Private R2 bucket")]
node_mcpclient(("MCP client"))

node_operator -->|"opens"| node_admin
node_admin -->|"renders"| node_inboxui
node_admin -->|"opens compose"| node_composeui
node_inboxui -->|"requests mailbox"| node_plugin
node_threadui -->|"requests thread"| node_plugin
node_composeui -->|"saves and sends"| node_plugin
node_composeui -->|"uploads files"| node_attachclient
node_attachclient -->|"posts attachment requests"| node_plugin
node_plugin -->|"reads and mutates"| node_mailbox
node_plugin -->|"dispatches compose"| node_composeops
node_plugin -->|"dispatches inbound"| node_inbound
node_plugin -->|"records and reconciles"| node_journal
node_sidecar -->|"posts raw MIME"| node_plugin
node_inbound -->|"parses message"| node_mime
node_inbound -->|"stores inbound files"| node_attachments
node_inbound -->|"admits message"| node_mailbox
node_composeops -->|"records attempt"| node_journal
node_composeops -->|"requests delivery"| node_delivery
node_delivery -->|"sends email"| node_cfemail
node_attachments -->|"stores private files"| node_r2
node_plugin -->|"handles file routes"| node_attachments
node_native -->|"registers tools"| node_mcp
node_mcpclient -->|"calls tools"| node_native
node_mcp -->|"reads and mutates"| node_mailbox
node_mcp -->|"dispatches compose"| node_composeops
node_mcp -->|"manages delivery recovery"| node_journal
node_bundleui -->|"starts operations"| node_bundleclient
node_bundleclient -->|"posts operation requests"| node_plugin
node_plugin -->|"dispatches bundle routes"| node_bundleops
node_bundleops -->|"reads and writes"| node_bundlestore

click node_admin "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/admin.tsx"
click node_inboxui "https://github.com/proverbiallemon/emdash-inbox/tree/main/src/components"
click node_threadui "https://github.com/proverbiallemon/emdash-inbox/tree/main/src/components"
click node_composeui "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/components/ComposeView.tsx"
click node_attachclient "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/attachmentClient.ts"
click node_plugin "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/index.ts"
click node_mcp "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/inboxMcpHandlers.ts"
click node_native "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/nativeMcp.ts"
click node_inbound "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/index.ts"
click node_mime "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/mimeParser.ts"
click node_composeops "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/composeOps.ts"
click node_delivery "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/providerDelivery.ts"
click node_mailbox "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/mailboxStore.ts"
click node_journal "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/deliveryJournal.ts"
click node_attachments "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/attachments.ts"
click node_bundleui "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/daylight/BundleInbox.tsx"
click node_bundleclient "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/daylight/bundleClient.ts"
click node_bundleops "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/bundleOperations.ts"
click node_bundlestore "https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/bundleStore.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_admin,node_inboxui,node_threadui,node_composeui,node_attachclient,node_bundleui,node_mcpclient toneBlue
class node_plugin,node_mcp,node_native,node_r2 toneAmber
class node_inbound,node_mime,node_composeops,node_delivery toneMint
class node_mailbox,node_journal,node_attachments toneRose
class node_bundleclient,node_bundleops,node_bundlestore,node_operator,node_cfemail,node_sidecar toneIndigo
```

## Components

### Admin mailbox

- [Admin entry](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/admin.tsx): `src/admin.tsx`
- [Inbox views](https://github.com/proverbiallemon/emdash-inbox/tree/main/src/components): `src/components`
- [Thread views](https://github.com/proverbiallemon/emdash-inbox/tree/main/src/components): `src/components`
- [Compose editor](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/components/ComposeView.tsx): `src/components/ComposeView.tsx`
- [Attachment client](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/attachmentClient.ts): `src/lib/attachmentClient.ts`
- [Bundle inbox](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/daylight/BundleInbox.tsx): `src/daylight/BundleInbox.tsx`

### Plugin interfaces

- [Plugin routes](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/index.ts): `src/index.ts`
- [MCP handlers](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/inboxMcpHandlers.ts): `src/lib/inboxMcpHandlers.ts`
- [Native MCP setup](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/nativeMcp.ts): `src/lib/nativeMcp.ts`

### Mail lifecycle

- [Inbound admission](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/index.ts): `src/index.ts`
- [MIME parser](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/mimeParser.ts): `src/lib/mimeParser.ts`
- [Compose operations](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/composeOps.ts): `src/lib/composeOps.ts`
- [Delivery provider](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/providerDelivery.ts): `src/lib/providerDelivery.ts`

### Mailbox state

- [Mailbox store](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/mailboxStore.ts): `src/lib/mailboxStore.ts`
- [Delivery journal](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/deliveryJournal.ts): `src/lib/deliveryJournal.ts`
- [Attachment storage](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/attachments.ts): `src/lib/attachments.ts`

### Tools and operations

- [Bundle operation client](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/daylight/bundleClient.ts): `src/daylight/bundleClient.ts`
- [Bundle operations](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/bundleOperations.ts): `src/lib/bundleOperations.ts`
- [Bundle state](https://github.com/proverbiallemon/emdash-inbox/blob/main/src/lib/bundleStore.ts): `src/lib/bundleStore.ts`

### Other components

- **Mailbox operator**
- **Email Sending binding**
- **Inbound sidecar**
- **Private R2 bucket**
- **MCP client**

## Connections

- Mailbox operator → Admin entry: opens
- Admin entry → Inbox views: renders
- Admin entry → Compose editor: opens compose
- Inbox views → Plugin routes: requests mailbox
- Thread views → Plugin routes: requests thread
- Compose editor → Plugin routes: saves and sends
- Compose editor → Attachment client: uploads files
- Attachment client → Plugin routes: posts attachment requests
- Plugin routes → Mailbox store: reads and mutates
- Plugin routes → Compose operations: dispatches compose
- Plugin routes → Inbound admission: dispatches inbound
- Plugin routes → Delivery journal: records and reconciles
- Inbound sidecar → Plugin routes: posts raw MIME
- Inbound admission → MIME parser: parses message
- Inbound admission → Attachment storage: stores inbound files
- Inbound admission → Mailbox store: admits message
- Compose operations → Delivery journal: records attempt
- Compose operations → Delivery provider: requests delivery
- Delivery provider → Email Sending binding: sends email
- Attachment storage → Private R2 bucket: stores private files
- Plugin routes → Attachment storage: handles file routes
- Native MCP setup → MCP handlers: registers tools
- MCP client → Native MCP setup: calls tools
- MCP handlers → Mailbox store: reads and mutates
- MCP handlers → Compose operations: dispatches compose
- MCP handlers → Delivery journal: manages delivery recovery
- Bundle inbox → Bundle operation client: starts operations
- Bundle operation client → Plugin routes: posts operation requests
- Plugin routes → Bundle operations: dispatches bundle routes
- Bundle operations → Bundle state: reads and writes