# hong-a-debug/hgmail architecture

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

- Interactive diagram: https://gitdiagram.com/hong-a-debug/hgmail
- Repository: https://github.com/hong-a-debug/hgmail

## Overview

This Cloudflare Workers email system receives and filters inbound mail, stores messages and attachments, and serves a role-aware web inbox. Users can register, sign in, read and delete mail, and compose or reply; administrators additionally manage settings and registration codes. The main runtime entry point coordinates these workflows with parsing, authentication, storage, attachment handling, and Resend. The README documents PWA/mailto support and automatic replies. Some route and UI details are unsampled, so those connections are shown only where documentation supports them.

Main entry points: [`src/index.ts`](https://github.com/hong-a-debug/hgmail/blob/main/src/index.ts) (Worker routes), [`src/admin.ts`](https://github.com/hong-a-debug/hgmail/blob/main/src/admin.ts) (Admin settings), [`src/attachment.ts`](https://github.com/hong-a-debug/hgmail/blob/main/src/attachment.ts) (Attachment handling), [`src/template.html`](https://github.com/hong-a-debug/hgmail/blob/main/src/template.html) (Inbox and PWA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Worker runtime"]
  node_worker["Worker routes<br/>[index.ts]"]
  node_web_ui["Inbox and PWA<br/>[template.html]"]
end

subgraph group_mail["Mail handling"]
  node_parser["Mail parser and filter<br/>[email-parser.ts]"]
  node_postal_mime["PostalMime"]
  node_attachments["Attachment handling<br/>[attachment.ts]"]
  node_resend_client["Resend client<br/>[resend-client.ts]"]
end

subgraph group_accounts["Accounts and administration"]
  node_auth["Users and sessions<br/>[auth.ts]"]
  node_admin["Admin settings<br/>[admin.ts]"]
  node_hashing["SHA-256 utility<br/>[utils.ts]"]
end

subgraph group_storage["Storage and delivery"]
  node_email_kv[("Email KV")]
  node_user_kv[("User KV")]
  node_r2[("Attachment R2")]
  node_resend["Resend service"]
end

node_sender(("Incoming sender"))
node_user(("Inbox user"))
node_email_routing["Email Routing"]

node_sender -->|"sends mail"| node_email_routing
node_email_routing -->|"routes mail"| node_worker
node_user -->|"uses inbox"| node_web_ui
node_web_ui -->|"calls API"| node_worker
node_worker -->|"parses mail"| node_parser
node_parser -->|"parses MIME"| node_postal_mime
node_worker -->|"stores mail"| node_email_kv
node_worker -->|"saves attachments"| node_attachments
node_attachments -->|"reads and writes"| node_r2
node_worker -->|"manages sessions"| node_auth
node_auth -->|"reads and writes"| node_user_kv
node_worker -->|"handles settings"| node_admin
node_admin -->|"stores settings"| node_user_kv
node_admin -->|"hashes codes"| node_hashing
node_worker -->|"sends mail"| node_resend_client
node_resend_client -->|"submits messages"| node_resend
node_worker -->|"deletes mail"| node_email_kv
node_worker -->|"deletes attachments"| node_attachments

click node_worker "https://github.com/hong-a-debug/hgmail/blob/main/src/index.ts"
click node_web_ui "https://github.com/hong-a-debug/hgmail/blob/main/src/template.html"
click node_parser "https://github.com/hong-a-debug/hgmail/blob/main/src/email-parser.ts"
click node_attachments "https://github.com/hong-a-debug/hgmail/blob/main/src/attachment.ts"
click node_auth "https://github.com/hong-a-debug/hgmail/blob/main/src/auth.ts"
click node_admin "https://github.com/hong-a-debug/hgmail/blob/main/src/admin.ts"
click node_hashing "https://github.com/hong-a-debug/hgmail/blob/main/src/utils.ts"
click node_resend_client "https://github.com/hong-a-debug/hgmail/blob/main/src/resend-client.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_worker,node_web_ui,node_user toneBlue
class node_parser,node_postal_mime,node_attachments,node_resend_client toneAmber
class node_auth,node_admin,node_hashing toneMint
class node_email_kv,node_user_kv,node_r2,node_resend toneRose
class node_sender,node_email_routing toneIndigo
```

## Components

### Worker runtime

- [Worker routes](https://github.com/hong-a-debug/hgmail/blob/main/src/index.ts): `src/index.ts`
- [Inbox and PWA](https://github.com/hong-a-debug/hgmail/blob/main/src/template.html): `src/template.html`

### Mail handling

- [Mail parser and filter](https://github.com/hong-a-debug/hgmail/blob/main/src/email-parser.ts): `src/email-parser.ts`
- **PostalMime**
- [Attachment handling](https://github.com/hong-a-debug/hgmail/blob/main/src/attachment.ts): `src/attachment.ts`
- [Resend client](https://github.com/hong-a-debug/hgmail/blob/main/src/resend-client.ts): `src/resend-client.ts`

### Accounts and administration

- [Users and sessions](https://github.com/hong-a-debug/hgmail/blob/main/src/auth.ts): `src/auth.ts`
- [Admin settings](https://github.com/hong-a-debug/hgmail/blob/main/src/admin.ts): `src/admin.ts`
- [SHA-256 utility](https://github.com/hong-a-debug/hgmail/blob/main/src/utils.ts): `src/utils.ts`

### Storage and delivery

- **Email KV**
- **User KV**
- **Attachment R2**
- **Resend service**

### Other components

- **Incoming sender**
- **Inbox user**
- **Email Routing**

## Connections

- Incoming sender → Email Routing: sends mail (evidence: `README.md`)
- Email Routing → Worker routes: routes mail (evidence: `README.md`)
- Inbox user → Inbox and PWA: uses inbox (evidence: `README.md`)
- Inbox and PWA → Worker routes: calls API (evidence: `README.md`)
- Worker routes → Mail parser and filter: parses mail (evidence: `src/index.ts`)
- Mail parser and filter → PostalMime: parses MIME (evidence: `src/email-parser.ts`)
- Worker routes → Email KV: stores mail (evidence: `src/index.ts`)
- Worker routes → Attachment handling: saves attachments (evidence: `src/index.ts`)
- Attachment handling → Attachment R2: reads and writes (evidence: `src/attachment.ts`)
- Worker routes → Users and sessions: manages sessions (evidence: `src/index.ts`)
- Users and sessions → User KV: reads and writes (evidence: `src/auth.ts`)
- Worker routes → Admin settings: handles settings (evidence: `src/index.ts`)
- Admin settings → User KV: stores settings (evidence: `src/admin.ts`)
- Admin settings → SHA-256 utility: hashes codes (evidence: `src/admin.ts`)
- Worker routes → Resend client: sends mail (evidence: `src/index.ts`)
- Resend client → Resend service: submits messages (evidence: `src/resend-client.ts`)
- Worker routes → Email KV: deletes mail (evidence: `src/index.ts`)
- Worker routes → Attachment handling: deletes attachments (evidence: `src/index.ts`)
