# tud8951/cloud-mail architecture

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

## Overview

Cloud Mail is a Cloudflare Workers-based email service with a Vue client. Users sign in, manage email accounts, read received messages and attachments, compose and send mail, and use administrative features such as user/role management, settings, and analytics. The client routes pages through request modules to the Worker API; backend services apply business rules and use D1, KV, and R2 or external providers. The README documents major capabilities, while sampled source confirms selected service calls and dependencies; unsampled links are omitted or marked unverified.

Main entry points: [`mail-worker/src/email/email.js`](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/email/email.js) (Inbound mail), [`mail-worker/src/service/email-service.js`](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/email-service.js) (Email operations), [`mail-worker/src/service/account-service.js`](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/account-service.js) (Email accounts), [`mail-worker/src/service/user-service.js`](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/user-service.js) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Vue client"]
  node_client_app["Client shell<br/>[main.js]"]
  node_client_routes["Page routing<br/>[index.js]"]
  node_mailbox_views["Mailbox views<br/>[index.vue]"]
  node_compose_view["Compose mail<br/>[index.vue]"]
  node_admin_views["Admin views<br/>[index.vue]"]
  node_analytics_view["Analytics view<br/>[index.vue]"]
  node_client_requests["API requests<br/>[email.js]"]
end

subgraph group_backend["Worker application"]
  node_worker_entry["Worker entry<br/>[index.js]"]
  node_api_routes["API endpoints"]
  node_security["Identity and permissions"]
end

subgraph group_domain["Mail domain services"]
  node_email_processing["Inbound mail<br/>[email.js]"]
  node_email_service["Email operations<br/>[email-service.js]"]
  node_account_service["Email accounts<br/>[account-service.js]"]
  node_user_service["User management<br/>[user-service.js]"]
  node_role_service["Roles and limits<br/>[role-service.js]"]
  node_oauth_service["OAuth login<br/>[oauth-service.js]"]
  node_settings_service["Site settings<br/>[setting-service.js]"]
  node_analytics_service["Mail analytics"]
  node_attachment_service["Attachments<br/>[att-service.js]"]
end

subgraph group_platform["Storage and integrations"]
  node_d1[("D1 database")]
  node_kv[("Cloudflare KV")]
  node_r2[("Cloudflare R2")]
  node_resend["Resend"]
  node_telegram["Telegram or mail forward"]
  node_workers_ai["Workers AI"]
  node_turnstile["Turnstile"]
  node_oauth_provider["Linux.do OAuth"]
end

node_mail_user(("Mail user"))

node_mail_user -->|"uses"| node_client_app
node_client_app -->|"loads routes"| node_client_routes
node_mail_user -->|"manages mail"| node_mailbox_views
node_mail_user -->|"composes mail"| node_compose_view
node_mail_user -->|"administers"| node_admin_views
node_mail_user -->|"views analytics"| node_analytics_view
node_mailbox_views -.->|"requests mail"| node_client_requests
node_compose_view -.->|"submits mail"| node_client_requests
node_admin_views -.->|"requests admin"| node_client_requests
node_analytics_view -.->|"requests metrics"| node_client_requests
node_client_requests -.->|"calls API"| node_api_routes
node_api_routes -.->|"registered by"| node_worker_entry
node_worker_entry -->|"dispatches inbound"| node_email_processing
node_email_processing -->|"stores received mail"| node_email_service
node_email_processing -->|"resolves accounts"| node_account_service
node_email_processing -->|"reads settings"| node_settings_service
node_email_processing -->|"handles attachments"| node_attachment_service
node_email_processing -->|"forwards notifications"| node_telegram
node_email_processing -->|"identifies codes"| node_workers_ai
node_email_service -->|"sends mail"| node_resend
node_email_service -->|"saves attachments"| node_attachment_service
node_email_service -->|"queries accounts"| node_account_service
node_email_service -->|"checks recipients"| node_role_service
node_account_service -->|"checks user"| node_user_service
node_account_service -->|"deletes mail"| node_email_service
node_user_service -->|"loads account counts"| node_account_service
node_user_service -->|"loads mail counts"| node_email_service
node_user_service -->|"loads permissions"| node_role_service
node_oauth_service -->|"looks up user"| node_user_service
node_oauth_service -->|"exchanges OAuth"| node_oauth_provider
node_settings_service -->|"stores background"| node_r2
node_settings_service -->|"caches settings"| node_kv
node_worker_entry -->|"loads analytics"| node_analytics_service
node_email_processing -.->|"stores mail data"| node_d1
node_email_service -.->|"reads and writes"| node_d1
node_account_service -.->|"reads and writes"| node_d1
node_role_service -.->|"reads and writes"| node_d1
node_oauth_service -.->|"reads and writes"| node_d1
node_mail_user -.->|"verification"| node_turnstile

click node_client_app "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/main.js"
click node_client_routes "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/router/index.js"
click node_mailbox_views "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/email/index.vue"
click node_compose_view "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/layout/write/index.vue"
click node_admin_views "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/user/index.vue"
click node_analytics_view "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/analysis/index.vue"
click node_client_requests "https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/request/email.js"
click node_worker_entry "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/index.js"
click node_api_routes "https://github.com/tud8951/cloud-mail/tree/main/mail-worker/src/api"
click node_security "https://github.com/tud8951/cloud-mail/tree/main/mail-worker/src/security"
click node_email_processing "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/email/email.js"
click node_email_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/email-service.js"
click node_account_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/account-service.js"
click node_user_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/user-service.js"
click node_role_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/role-service.js"
click node_oauth_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/oauth-service.js"
click node_settings_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/setting-service.js"
click node_analytics_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/analysis-service.js"
click node_attachment_service "https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/att-service.js"

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_client_app,node_client_routes,node_mailbox_views,node_compose_view,node_admin_views,node_analytics_view,node_client_requests,node_mail_user toneBlue
class node_worker_entry,node_api_routes,node_security toneAmber
class node_email_processing,node_email_service,node_account_service,node_user_service,node_role_service,node_oauth_service,node_settings_service,node_analytics_service,node_attachment_service toneMint
class node_d1,node_kv,node_r2,node_resend,node_telegram,node_workers_ai,node_turnstile,node_oauth_provider toneRose
```

## Components

### Vue client

- [Client shell](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/main.js): `mail-vue/src/main.js`
- [Page routing](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/router/index.js): `mail-vue/src/router/index.js`
- [Mailbox views](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/email/index.vue): `mail-vue/src/views/email/index.vue`
- [Compose mail](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/layout/write/index.vue): `mail-vue/src/layout/write/index.vue`
- [Admin views](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/user/index.vue): `mail-vue/src/views/user/index.vue`
- [Analytics view](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/views/analysis/index.vue): `mail-vue/src/views/analysis/index.vue`
- [API requests](https://github.com/tud8951/cloud-mail/blob/main/mail-vue/src/request/email.js): `mail-vue/src/request/email.js`

### Worker application

- [Worker entry](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/index.js): `mail-worker/src/index.js`
- [API endpoints](https://github.com/tud8951/cloud-mail/tree/main/mail-worker/src/api): `mail-worker/src/api`
- [Identity and permissions](https://github.com/tud8951/cloud-mail/tree/main/mail-worker/src/security): `mail-worker/src/security`

### Mail domain services

- [Inbound mail](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/email/email.js): `mail-worker/src/email/email.js`
- [Email operations](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/email-service.js): `mail-worker/src/service/email-service.js`
- [Email accounts](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/account-service.js): `mail-worker/src/service/account-service.js`
- [User management](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/user-service.js): `mail-worker/src/service/user-service.js`
- [Roles and limits](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/role-service.js): `mail-worker/src/service/role-service.js`
- [OAuth login](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/oauth-service.js): `mail-worker/src/service/oauth-service.js`
- [Site settings](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/setting-service.js): `mail-worker/src/service/setting-service.js`
- [Mail analytics](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/analysis-service.js): `mail-worker/src/service/analysis-service.js`
- [Attachments](https://github.com/tud8951/cloud-mail/blob/main/mail-worker/src/service/att-service.js): `mail-worker/src/service/att-service.js`

### Storage and integrations

- **D1 database**
- **Cloudflare KV**
- **Cloudflare R2**
- **Resend**
- **Telegram or mail forward**
- **Workers AI**
- **Turnstile**
- **Linux.do OAuth**

### Other components

- **Mail user**

## Connections

- Mail user → Client shell: uses (evidence: `README.md`)
- Client shell → Page routing: loads routes (evidence: `mail-vue/src/main.js`)
- Mail user → Mailbox views: manages mail (evidence: `README.md`)
- Mail user → Compose mail: composes mail (evidence: `README.md`)
- Mail user → Admin views: administers (evidence: `README.md`)
- Mail user → Analytics view: views analytics (evidence: `README.md`)
- Mailbox views → API requests: requests mail
- Compose mail → API requests: submits mail
- Admin views → API requests: requests admin
- Analytics view → API requests: requests metrics
- API requests → API endpoints: calls API
- API endpoints → Worker entry: registered by
- Worker entry → Inbound mail: dispatches inbound (evidence: `mail-worker/src/index.js`)
- Inbound mail → Email operations: stores received mail (evidence: `mail-worker/src/email/email.js`)
- Inbound mail → Email accounts: resolves accounts (evidence: `mail-worker/src/email/email.js`)
- Inbound mail → Site settings: reads settings (evidence: `mail-worker/src/email/email.js`)
- Inbound mail → Attachments: handles attachments (evidence: `mail-worker/src/email/email.js`)
- Inbound mail → Telegram or mail forward: forwards notifications (evidence: `mail-worker/src/email/email.js`)
- Inbound mail → Workers AI: identifies codes (evidence: `mail-worker/src/email/email.js`)
- Email operations → Resend: sends mail (evidence: `mail-worker/src/service/email-service.js`)
- Email operations → Attachments: saves attachments (evidence: `mail-worker/src/service/email-service.js`)
- Email operations → Email accounts: queries accounts (evidence: `mail-worker/src/service/email-service.js`)
- Email operations → Roles and limits: checks recipients (evidence: `mail-worker/src/service/email-service.js`)
- Email accounts → User management: checks user (evidence: `mail-worker/src/service/account-service.js`)
- Email accounts → Email operations: deletes mail (evidence: `mail-worker/src/service/account-service.js`)
- User management → Email accounts: loads account counts (evidence: `mail-worker/src/service/user-service.js`)
- User management → Email operations: loads mail counts (evidence: `mail-worker/src/service/user-service.js`)
- User management → Roles and limits: loads permissions (evidence: `mail-worker/src/service/user-service.js`)
- OAuth login → User management: looks up user (evidence: `mail-worker/src/service/oauth-service.js`)
- OAuth login → Linux.do OAuth: exchanges OAuth (evidence: `mail-worker/src/service/oauth-service.js`)
- Site settings → Cloudflare R2: stores background (evidence: `mail-worker/src/service/setting-service.js`)
- Site settings → Cloudflare KV: caches settings (evidence: `mail-worker/src/service/setting-service.js`)
- Worker entry → Mail analytics: loads analytics (evidence: `mail-worker/src/index.js`)
- Inbound mail → D1 database: stores mail data
- Email operations → D1 database: reads and writes
- Email accounts → D1 database: reads and writes
- Roles and limits → D1 database: reads and writes
- OAuth login → D1 database: reads and writes
- Mail user → Turnstile: verification
