# kayo2970/mailer architecture

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

## Overview

Mailer is a local-first mail-merge and email dispatch app. The user configures an account, composes a message and recipient list, previews and schedules or queues individualized messages, then monitors delivery and history. Images and attachments are embedded or stored locally; a background worker sends through configured SMTP or direct delivery. The graph reflects documented workflows and indexed imports; some implementation details are unsampled, so uncertain connections are omitted.

Main entry points: [`src/lib/email-service.ts`](https://github.com/kayo2970/mailer/blob/main/src/lib/email-service.ts) (Mail engine and worker), [`src/components/compose-tab.tsx`](https://github.com/kayo2970/mailer/blob/main/src/components/compose-tab.tsx) (Compose screen), [`src/app/page.tsx`](https://github.com/kayo2970/mailer/blob/main/src/app/page.tsx) (App shell), [`src/app/api/send/route.ts`](https://github.com/kayo2970/mailer/blob/main/src/app/api/send/route.ts) (Send endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["App shell<br/>[page.tsx]"]
  node_terms["Terms gate<br/>[terms-gate.tsx]"]
  node_settings_ui["Settings screen<br/>[settings-tab.tsx]"]
  node_queue_history_ui["Queue and history<br/>[log-list.tsx]"]
end

subgraph group_compose["Composition"]
  node_compose_ui["Compose screen<br/>[compose-tab.tsx]"]
  node_editor["Message editor<br/>[rich-editor.tsx]"]
  node_recipient_parser["Recipient parsing<br/>[mail-merge.ts]"]
  node_compose_helpers["Compose helpers<br/>[compose-editor.ts]"]
  node_attachment_rules["Attachment handling"]
  node_image_picker["Image library UI<br/>[image-library.tsx]"]
  node_inline_images["Inline image refs<br/>[inline-images.ts]"]
end

subgraph group_server["API and dispatch"]
  node_browser_api["Browser API client<br/>[client.ts]"]
  node_api_guard["Local request guard<br/>[api.ts]"]
  node_send_api["Send endpoint<br/>[route.ts]"]
  node_api_routes["Other API routes"]
end

subgraph group_data["Local data"]
  node_image_service["Image library service<br/>[images.ts]"]
  node_file_storage["Upload file storage<br/>[file-storage.ts]"]
  node_json_store[("JSON collections<br/>[store.ts]")]
end

subgraph group_delivery["Delivery"]
  node_mail_engine["Mail engine and worker<br/>[email-service.ts]"]
  node_direct_transport["Direct SMTP transport"]
  node_social_png["Social image generation<br/>[social-png.ts]"]
end

node_user(("Local user"))
node_smtp{{"SMTP mail server"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_compose_ui
node_app -->|"renders"| node_settings_ui
node_app -->|"renders"| node_queue_history_ui
node_app -->|"shows"| node_terms
node_compose_ui -->|"parses recipients"| node_recipient_parser
node_compose_ui -->|"uses"| node_editor
node_compose_ui -->|"uses"| node_compose_helpers
node_compose_ui -->|"checks attachments"| node_attachment_rules
node_compose_ui -->|"opens picker"| node_image_picker
node_editor -->|"formats image refs"| node_inline_images
node_image_picker -->|"inserts image refs"| node_inline_images
node_compose_ui -->|"submits requests"| node_browser_api
node_settings_ui -->|"saves settings"| node_browser_api
node_queue_history_ui -->|"loads queue"| node_browser_api
node_browser_api -.->|"calls API"| node_send_api
node_browser_api -->|"calls API"| node_api_routes
node_send_api -->|"guards request"| node_api_guard
node_api_routes -->|"guards requests"| node_api_guard
node_send_api -->|"validates addresses"| node_recipient_parser
node_send_api -->|"checks size limit"| node_attachment_rules
node_send_api -->|"enqueues batch"| node_mail_engine
node_api_routes -->|"handles settings and logs"| node_mail_engine
node_api_routes -->|"handles images"| node_image_service
node_mail_engine -->|"reads and writes"| node_json_store
node_image_service -->|"stores metadata"| node_json_store
node_image_service -->|"reads and writes files"| node_file_storage
node_mail_engine -->|"uses when selected"| node_direct_transport
node_mail_engine -->|"delivers messages"| node_smtp
node_direct_transport -.->|"delivers directly"| node_smtp
node_mail_engine -->|"loads inline images"| node_image_service
node_mail_engine -->|"builds image refs"| node_inline_images
node_mail_engine -->|"adds social images"| node_social_png
node_mail_engine -.->|"updates queue and history"| node_queue_history_ui

click node_app "https://github.com/kayo2970/mailer/blob/main/src/app/page.tsx"
click node_terms "https://github.com/kayo2970/mailer/blob/main/src/components/terms-gate.tsx"
click node_compose_ui "https://github.com/kayo2970/mailer/blob/main/src/components/compose-tab.tsx"
click node_editor "https://github.com/kayo2970/mailer/blob/main/src/components/rich-editor.tsx"
click node_recipient_parser "https://github.com/kayo2970/mailer/blob/main/src/lib/mail-merge.ts"
click node_compose_helpers "https://github.com/kayo2970/mailer/blob/main/src/lib/compose-editor.ts"
click node_attachment_rules "https://github.com/kayo2970/mailer/blob/main/src/lib/email-attachments.ts"
click node_image_picker "https://github.com/kayo2970/mailer/blob/main/src/components/image-library.tsx"
click node_inline_images "https://github.com/kayo2970/mailer/blob/main/src/lib/inline-images.ts"
click node_browser_api "https://github.com/kayo2970/mailer/blob/main/src/lib/client.ts"
click node_api_guard "https://github.com/kayo2970/mailer/blob/main/src/lib/api.ts"
click node_send_api "https://github.com/kayo2970/mailer/blob/main/src/app/api/send/route.ts"
click node_api_routes "https://github.com/kayo2970/mailer/tree/main/src/app/api"
click node_settings_ui "https://github.com/kayo2970/mailer/blob/main/src/components/settings-tab.tsx"
click node_queue_history_ui "https://github.com/kayo2970/mailer/blob/main/src/components/log-list.tsx"
click node_mail_engine "https://github.com/kayo2970/mailer/blob/main/src/lib/email-service.ts"
click node_direct_transport "https://github.com/kayo2970/mailer/blob/main/src/lib/direct-smtp-transport.ts"
click node_image_service "https://github.com/kayo2970/mailer/blob/main/src/lib/images.ts"
click node_file_storage "https://github.com/kayo2970/mailer/blob/main/src/lib/file-storage.ts"
click node_social_png "https://github.com/kayo2970/mailer/blob/main/src/lib/social-png.ts"
click node_json_store "https://github.com/kayo2970/mailer/blob/main/src/lib/store.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_terms,node_settings_ui,node_queue_history_ui,node_user toneBlue
class node_compose_ui,node_editor,node_recipient_parser,node_compose_helpers,node_attachment_rules,node_image_picker,node_inline_images toneAmber
class node_browser_api,node_api_guard,node_send_api,node_api_routes,node_smtp toneMint
class node_image_service,node_file_storage,node_json_store toneRose
class node_mail_engine,node_direct_transport,node_social_png toneIndigo
```

## Components

### User interface

- [App shell](https://github.com/kayo2970/mailer/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Terms gate](https://github.com/kayo2970/mailer/blob/main/src/components/terms-gate.tsx): `src/components/terms-gate.tsx`
- [Settings screen](https://github.com/kayo2970/mailer/blob/main/src/components/settings-tab.tsx): `src/components/settings-tab.tsx`
- [Queue and history](https://github.com/kayo2970/mailer/blob/main/src/components/log-list.tsx): `src/components/log-list.tsx`

### Composition

- [Compose screen](https://github.com/kayo2970/mailer/blob/main/src/components/compose-tab.tsx): `src/components/compose-tab.tsx`
- [Message editor](https://github.com/kayo2970/mailer/blob/main/src/components/rich-editor.tsx): `src/components/rich-editor.tsx`
- [Recipient parsing](https://github.com/kayo2970/mailer/blob/main/src/lib/mail-merge.ts): `src/lib/mail-merge.ts`
- [Compose helpers](https://github.com/kayo2970/mailer/blob/main/src/lib/compose-editor.ts): `src/lib/compose-editor.ts`
- [Attachment handling](https://github.com/kayo2970/mailer/blob/main/src/lib/email-attachments.ts): `src/lib/email-attachments.ts`
- [Image library UI](https://github.com/kayo2970/mailer/blob/main/src/components/image-library.tsx): `src/components/image-library.tsx`
- [Inline image refs](https://github.com/kayo2970/mailer/blob/main/src/lib/inline-images.ts): `src/lib/inline-images.ts`

### API and dispatch

- [Browser API client](https://github.com/kayo2970/mailer/blob/main/src/lib/client.ts): `src/lib/client.ts`
- [Local request guard](https://github.com/kayo2970/mailer/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Send endpoint](https://github.com/kayo2970/mailer/blob/main/src/app/api/send/route.ts): `src/app/api/send/route.ts`
- [Other API routes](https://github.com/kayo2970/mailer/tree/main/src/app/api): `src/app/api`

### Local data

- [Image library service](https://github.com/kayo2970/mailer/blob/main/src/lib/images.ts): `src/lib/images.ts`
- [Upload file storage](https://github.com/kayo2970/mailer/blob/main/src/lib/file-storage.ts): `src/lib/file-storage.ts`
- [JSON collections](https://github.com/kayo2970/mailer/blob/main/src/lib/store.ts): `src/lib/store.ts`

### Delivery

- [Mail engine and worker](https://github.com/kayo2970/mailer/blob/main/src/lib/email-service.ts): `src/lib/email-service.ts`
- [Direct SMTP transport](https://github.com/kayo2970/mailer/blob/main/src/lib/direct-smtp-transport.ts): `src/lib/direct-smtp-transport.ts`
- [Social image generation](https://github.com/kayo2970/mailer/blob/main/src/lib/social-png.ts): `src/lib/social-png.ts`

### Other components

- **Local user**
- **SMTP mail server**

## Connections

- Local user → App shell: uses
- App shell → Compose screen: renders (evidence: `src/app/page.tsx`)
- App shell → Settings screen: renders (evidence: `src/app/page.tsx`)
- App shell → Queue and history: renders (evidence: `src/app/page.tsx`)
- App shell → Terms gate: shows (evidence: `src/app/page.tsx`)
- Compose screen → Recipient parsing: parses recipients (evidence: `src/components/compose-tab.tsx`)
- Compose screen → Message editor: uses (evidence: `src/components/compose-tab.tsx`)
- Compose screen → Compose helpers: uses (evidence: `src/components/compose-tab.tsx`)
- Compose screen → Attachment handling: checks attachments (evidence: `src/components/compose-tab.tsx`)
- Compose screen → Image library UI: opens picker (evidence: `src/components/compose-tab.tsx`)
- Message editor → Inline image refs: formats image refs (evidence: `src/components/rich-editor.tsx`)
- Image library UI → Inline image refs: inserts image refs (evidence: `src/components/image-library.tsx`)
- Compose screen → Browser API client: submits requests (evidence: `src/components/compose-tab.tsx`)
- Settings screen → Browser API client: saves settings (evidence: `src/components/settings-tab.tsx`)
- Queue and history → Browser API client: loads queue (evidence: `src/components/log-list.tsx`)
- Browser API client → Send endpoint: calls API
- Browser API client → Other API routes: calls API (evidence: `src/lib/client.ts`)
- Send endpoint → Local request guard: guards request (evidence: `src/app/api/send/route.ts`)
- Other API routes → Local request guard: guards requests (evidence: `src/app/api/settings/route.ts`)
- Send endpoint → Recipient parsing: validates addresses (evidence: `src/app/api/send/route.ts`)
- Send endpoint → Attachment handling: checks size limit (evidence: `src/app/api/send/route.ts`)
- Send endpoint → Mail engine and worker: enqueues batch (evidence: `src/app/api/send/route.ts`)
- Other API routes → Mail engine and worker: handles settings and logs (evidence: `src/app/api/settings/route.ts`)
- Other API routes → Image library service: handles images (evidence: `src/app/api/images/route.ts`)
- Mail engine and worker → JSON collections: reads and writes (evidence: `src/lib/email-service.ts`)
- Image library service → JSON collections: stores metadata (evidence: `src/lib/images.ts`)
- Image library service → Upload file storage: reads and writes files (evidence: `src/lib/images.ts`)
- Mail engine and worker → Direct SMTP transport: uses when selected (evidence: `src/lib/email-service.ts`)
- Mail engine and worker → SMTP mail server: delivers messages
- Direct SMTP transport → SMTP mail server: delivers directly
- Mail engine and worker → Image library service: loads inline images (evidence: `src/lib/email-service.ts`)
- Mail engine and worker → Inline image refs: builds image refs (evidence: `src/lib/email-service.ts`)
- Mail engine and worker → Social image generation: adds social images (evidence: `src/lib/email-service.ts`)
- Mail engine and worker → Queue and history: updates queue and history
