# cy035/cloud-mail architecture

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

- Interactive diagram: https://gitdiagram.com/cy035/cloud-mail
- Repository: https://github.com/cy035/cloud-mail

## Overview

Cloud Mail is a Cloudflare-based multi-account email service. Users access mail and administration through a responsive Vue interface; the Worker provides account, email, attachment, permission, settings, and analytics capabilities, with D1/KV/R2 and external mail or verification integrations. The main flow is user action → frontend request → Worker API and business services → stored or delivered mail. Some UI/API wiring is documented only at product level; those relationships are marked unverified rather than inferred from filenames.

Main entry points: [`mail-worker/src/email/email.js`](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/email/email.js) (Mail processing), [`mail-worker/src/api`](https://github.com/cy035/cloud-mail/tree/main/mail-worker/src/api) (HTTP APIs), [`mail-worker/src/service/email-service.js`](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/email-service.js) (Email operations), [`mail-worker/src/entity/orm.js`](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/entity/orm.js) (D1 database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mail interface"]
  node_vue["Vue application<br/>[main.js]"]
  node_mailviews["Mail views"]
  node_adminviews["Admin views"]
  node_frontendrequests["API requests"]
end

subgraph group_worker["Worker runtime"]
  node_worker["Worker entry<br/>[index.js]"]
  node_api["HTTP APIs"]
end

subgraph group_domain["Mail capabilities"]
  node_identity["Accounts and access<br/>[account-service.js]"]
  node_email["Mail processing<br/>[email.js]"]
  node_mailservice["Email operations<br/>[email-service.js]"]
  node_attachments["Attachments<br/>[att-service.js]"]
  node_roles["Roles and permissions<br/>[role-service.js]"]
  node_analytics["Analytics"]
  node_settings["Site settings<br/>[setting-service.js]"]
end

subgraph group_platform["Data and integrations"]
  node_d1[("D1 database<br/>[orm.js]")]
  node_kv[("Cloudflare KV<br/>[setting-service.js]")]
  node_r2[("Object storage<br/>[r2-service.js]")]
  node_resend["Resend delivery<br/>[resend-service.js]"]
  node_turnstile["Turnstile"]
  node_ai["Workers AI<br/>[ai-service.js]"]
  node_telegram["Telegram push"]
  node_webhook["Webhook push<br/>[webhook-service.js]"]
end

node_user(("Mail user"))

node_user -->|"uses"| node_vue
node_vue -.->|"renders"| node_mailviews
node_vue -.->|"renders"| node_adminviews
node_mailviews -.->|"requests"| node_frontendrequests
node_adminviews -.->|"requests"| node_frontendrequests
node_frontendrequests -.->|"calls"| node_api
node_api -.->|"routes through"| node_worker
node_worker -->|"registers"| node_email
node_worker -->|"imports"| node_analytics
node_worker -->|"imports"| node_identity
node_worker -->|"imports"| node_mailservice
node_api -.->|"dispatches"| node_identity
node_api -.->|"dispatches"| node_mailservice
node_api -.->|"dispatches"| node_analytics
node_api -.->|"dispatches"| node_settings
node_api -.->|"dispatches"| node_roles
node_email -->|"uses"| node_mailservice
node_email -->|"uses"| node_identity
node_email -->|"uses"| node_settings
node_email -->|"uses"| node_attachments
node_email -->|"notifies"| node_telegram
node_email -->|"notifies"| node_webhook
node_email -->|"uses"| node_ai
node_identity -->|"queries"| node_d1
node_mailservice -->|"queries"| node_d1
node_mailservice -->|"saves files"| node_attachments
node_attachments -->|"stores objects"| node_r2
node_attachments -->|"records metadata"| node_d1
node_roles -->|"queries"| node_d1
node_settings -->|"reads settings"| node_d1
node_settings -->|"caches settings"| node_kv
node_settings -->|"manages background"| node_r2
node_mailservice -.->|"sends mail"| node_resend
node_identity -->|"verifies humans"| node_turnstile
node_email -->|"pushes received mail"| node_telegram
node_email -->|"pushes received mail"| node_webhook
node_email -->|"recognizes codes"| node_ai
node_analytics -.->|"reports data"| node_d1

click node_vue "https://github.com/cy035/cloud-mail/blob/main/mail-vue/src/main.js"
click node_mailviews "https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/views"
click node_adminviews "https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/views"
click node_frontendrequests "https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/request"
click node_worker "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/index.js"
click node_api "https://github.com/cy035/cloud-mail/tree/main/mail-worker/src/api"
click node_identity "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/account-service.js"
click node_email "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/email/email.js"
click node_mailservice "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/email-service.js"
click node_attachments "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/att-service.js"
click node_roles "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/role-service.js"
click node_analytics "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/analysis-service.js"
click node_settings "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/setting-service.js"
click node_d1 "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/entity/orm.js"
click node_kv "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/setting-service.js"
click node_r2 "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/r2-service.js"
click node_resend "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/resend-service.js"
click node_turnstile "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/turnstile-service.js"
click node_ai "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/ai-service.js"
click node_telegram "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/telegram-service.js"
click node_webhook "https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/webhook-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_vue,node_mailviews,node_adminviews,node_frontendrequests,node_user toneBlue
class node_worker,node_api toneAmber
class node_identity,node_email,node_mailservice,node_attachments,node_roles,node_analytics,node_settings toneMint
class node_d1,node_kv,node_r2,node_resend,node_turnstile,node_ai,node_telegram,node_webhook toneRose
```

## Components

### Mail interface

- [Vue application](https://github.com/cy035/cloud-mail/blob/main/mail-vue/src/main.js): `mail-vue/src/main.js`
- [Mail views](https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/views): `mail-vue/src/views`
- [Admin views](https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/views): `mail-vue/src/views`
- [API requests](https://github.com/cy035/cloud-mail/tree/main/mail-vue/src/request): `mail-vue/src/request`

### Worker runtime

- [Worker entry](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/index.js): `mail-worker/src/index.js`
- [HTTP APIs](https://github.com/cy035/cloud-mail/tree/main/mail-worker/src/api): `mail-worker/src/api`

### Mail capabilities

- [Accounts and access](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/account-service.js): `mail-worker/src/service/account-service.js`
- [Mail processing](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/email/email.js): `mail-worker/src/email/email.js`
- [Email operations](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/email-service.js): `mail-worker/src/service/email-service.js`
- [Attachments](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/att-service.js): `mail-worker/src/service/att-service.js`
- [Roles and permissions](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/role-service.js): `mail-worker/src/service/role-service.js`
- [Analytics](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/analysis-service.js): `mail-worker/src/service/analysis-service.js`
- [Site settings](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/setting-service.js): `mail-worker/src/service/setting-service.js`

### Data and integrations

- [D1 database](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/entity/orm.js): `mail-worker/src/entity/orm.js`
- [Cloudflare KV](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/setting-service.js): `mail-worker/src/service/setting-service.js`
- [Object storage](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/r2-service.js): `mail-worker/src/service/r2-service.js`
- [Resend delivery](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/resend-service.js): `mail-worker/src/service/resend-service.js`
- [Turnstile](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/turnstile-service.js): `mail-worker/src/service/turnstile-service.js`
- [Workers AI](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/ai-service.js): `mail-worker/src/service/ai-service.js`
- [Telegram push](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/telegram-service.js): `mail-worker/src/service/telegram-service.js`
- [Webhook push](https://github.com/cy035/cloud-mail/blob/main/mail-worker/src/service/webhook-service.js): `mail-worker/src/service/webhook-service.js`

### Other components

- **Mail user**

## Connections

- Mail user → Vue application: uses (evidence: `README.md`)
- Vue application → Mail views: renders
- Vue application → Admin views: renders
- Mail views → API requests: requests
- Admin views → API requests: requests
- API requests → HTTP APIs: calls
- HTTP APIs → Worker entry: routes through
- Worker entry → Mail processing: registers (evidence: `mail-worker/src/index.js`)
- Worker entry → Analytics: imports (evidence: `mail-worker/src/index.js`)
- Worker entry → Accounts and access: imports (evidence: `mail-worker/src/index.js`)
- Worker entry → Email operations: imports (evidence: `mail-worker/src/index.js`)
- HTTP APIs → Accounts and access: dispatches
- HTTP APIs → Email operations: dispatches
- HTTP APIs → Analytics: dispatches
- HTTP APIs → Site settings: dispatches
- HTTP APIs → Roles and permissions: dispatches
- Mail processing → Email operations: uses (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Accounts and access: uses (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Site settings: uses (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Attachments: uses (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Telegram push: notifies (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Webhook push: notifies (evidence: `mail-worker/src/email/email.js`)
- Mail processing → Workers AI: uses (evidence: `mail-worker/src/email/email.js`)
- Accounts and access → D1 database: queries (evidence: `mail-worker/src/service/account-service.js`)
- Email operations → D1 database: queries (evidence: `mail-worker/src/service/email-service.js`)
- Email operations → Attachments: saves files (evidence: `mail-worker/src/service/email-service.js`)
- Attachments → Object storage: stores objects (evidence: `mail-worker/src/service/att-service.js`)
- Attachments → D1 database: records metadata (evidence: `mail-worker/src/service/att-service.js`)
- Roles and permissions → D1 database: queries (evidence: `mail-worker/src/service/role-service.js`)
- Site settings → D1 database: reads settings (evidence: `mail-worker/src/service/setting-service.js`)
- Site settings → Cloudflare KV: caches settings (evidence: `mail-worker/src/service/setting-service.js`)
- Site settings → Object storage: manages background (evidence: `mail-worker/src/service/setting-service.js`)
- Email operations → Resend delivery: sends mail (evidence: `README.md`)
- Accounts and access → Turnstile: verifies humans (evidence: `mail-worker/src/service/account-service.js`)
- Mail processing → Telegram push: pushes received mail (evidence: `README.md`)
- Mail processing → Webhook push: pushes received mail (evidence: `README.md`)
- Mail processing → Workers AI: recognizes codes (evidence: `README.md`)
- Analytics → D1 database: reports data
