# idinging/freemail architecture

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

- Interactive diagram: https://gitdiagram.com/idinging/freemail
- Repository: https://github.com/idinging/freemail

## Overview

Freemail is a temporary-email service with a browser UI and a Cloudflare Worker backend. The main workflow is: a user signs in, creates or selects a mailbox, then reads incoming mail; the Worker parses each inbound message, optionally forwards it, stores its raw EML and metadata, and serves mailbox and message APIs. Sending is a separate, optional branch routed by sender domain to configured providers. The graph uses the sampled frontend, API, authentication, and inbound-handler code plus README-documented capabilities; unsampled subsystem links are omitted where caller ownership is not established.

Main entry points: [`src/server.js`](https://github.com/idinging/freemail/blob/master/src/server.js) (Worker entry), [`src/api/index.js`](https://github.com/idinging/freemail/blob/master/src/api/index.js) (API dispatcher), [`src/email/handler.js`](https://github.com/idinging/freemail/blob/master/src/email/handler.js) (Inbound handler), [`src/db/index.js`](https://github.com/idinging/freemail/blob/master/src/db/index.js) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_browser_app["Mailbox interface<br/>[app.js]"]
  node_client_router["View routing<br/>[app-router.js]"]
  node_client_storage[("Browser cache<br/>[storage.js]")]
end

subgraph group_worker["Worker and API"]
  node_worker_entry["Worker entry<br/>[server.js]"]
  node_auth_routes["Login routes<br/>[auth.js]"]
  node_auth_middleware["Auth middleware<br/>[app.js]"]
  node_api_routes["API routes<br/>[api.js]"]
  node_api_dispatch["API dispatcher<br/>[index.js]"]
  node_mailbox_api["Mailbox APIs<br/>[mailboxes.js]"]
  node_email_api["Email APIs<br/>[emails.js]"]
  node_send_api["Send API<br/>[send.js]"]
  node_admin_api["User administration<br/>[users.js]"]
end

subgraph group_mail["Email processing"]
  node_inbound_handler["Inbound handler<br/>[handler.js]"]
  node_email_parser["Parsing and codes<br/>[parser.js]"]
  node_email_forwarder["Forwarding rules<br/>[forwarder.js]"]
end

subgraph group_data["Persistence"]
  node_db_layer["Database access<br/>[index.js]"]
end

subgraph group_outbound["Outbound providers"]
  node_provider_router["Provider routing<br/>[index.js]"]
end

node_visitor(("Mailbox user"))
node_inbound_service{{"Email routing"}}
node_d1_store[("D1 database")]
node_r2_store[("R2 EML store")]
node_resend{{"Resend"}}
node_sendflare{{"SendFlare"}}
node_cyberpersons{{"Cyberpersons"}}

node_visitor -->|"uses"| node_browser_app
node_browser_app -->|"requests APIs"| node_worker_entry
node_browser_app -->|"caches data"| node_client_storage
node_client_router -->|"switches views"| node_browser_app
node_worker_entry -->|"mounts routes"| node_auth_routes
node_worker_entry -->|"protects API"| node_auth_middleware
node_worker_entry -->|"mounts routes"| node_api_routes
node_worker_entry -->|"dispatches email events"| node_inbound_handler
node_api_routes -->|"dispatches requests"| node_api_dispatch
node_auth_routes -->|"reads/writes users"| node_db_layer
node_api_dispatch -->|"dispatches mailbox APIs"| node_mailbox_api
node_api_dispatch -->|"dispatches email APIs"| node_email_api
node_api_dispatch -->|"dispatches send API"| node_send_api
node_api_dispatch -->|"dispatches user APIs"| node_admin_api
node_mailbox_api -->|"reads/writes mailboxes"| node_db_layer
node_email_api -->|"reads email metadata"| node_db_layer
node_inbound_service -->|"delivers messages"| node_worker_entry
node_inbound_handler -->|"parses message"| node_email_parser
node_inbound_handler -->|"applies forwarding"| node_email_forwarder
node_inbound_handler -->|"writes message metadata"| node_db_layer
node_inbound_handler -->|"stores raw EML"| node_r2_store
node_db_layer -->|"reads/writes records"| node_d1_store
node_send_api -->|"routes outbound mail"| node_provider_router
node_provider_router -.->|"sends via"| node_resend
node_provider_router -.->|"sends via"| node_sendflare
node_provider_router -.->|"sends via"| node_cyberpersons

click node_browser_app "https://github.com/idinging/freemail/blob/master/public/js/app.js"
click node_client_router "https://github.com/idinging/freemail/blob/master/public/js/app-router.js"
click node_client_storage "https://github.com/idinging/freemail/blob/master/public/js/storage.js"
click node_worker_entry "https://github.com/idinging/freemail/blob/master/src/server.js"
click node_auth_routes "https://github.com/idinging/freemail/blob/master/src/routes/auth.js"
click node_auth_middleware "https://github.com/idinging/freemail/blob/master/src/middleware/app.js"
click node_api_routes "https://github.com/idinging/freemail/blob/master/src/routes/api.js"
click node_api_dispatch "https://github.com/idinging/freemail/blob/master/src/api/index.js"
click node_mailbox_api "https://github.com/idinging/freemail/blob/master/src/api/mailboxes.js"
click node_email_api "https://github.com/idinging/freemail/blob/master/src/api/emails.js"
click node_send_api "https://github.com/idinging/freemail/blob/master/src/api/send.js"
click node_admin_api "https://github.com/idinging/freemail/blob/master/src/api/users.js"
click node_inbound_handler "https://github.com/idinging/freemail/blob/master/src/email/handler.js"
click node_email_parser "https://github.com/idinging/freemail/blob/master/src/email/parser.js"
click node_email_forwarder "https://github.com/idinging/freemail/blob/master/src/email/forwarder.js"
click node_db_layer "https://github.com/idinging/freemail/blob/master/src/db/index.js"
click node_provider_router "https://github.com/idinging/freemail/blob/master/src/email/providers/index.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_browser_app,node_client_router,node_client_storage,node_visitor toneBlue
class node_worker_entry,node_auth_routes,node_auth_middleware,node_api_routes,node_api_dispatch,node_mailbox_api,node_email_api,node_send_api,node_admin_api,node_d1_store,node_r2_store toneAmber
class node_inbound_handler,node_email_parser,node_email_forwarder toneMint
class node_db_layer toneRose
class node_provider_router,node_inbound_service,node_resend,node_sendflare,node_cyberpersons toneIndigo
```

## Components

### Browser experience

- [Mailbox interface](https://github.com/idinging/freemail/blob/master/public/js/app.js): `public/js/app.js`
- [View routing](https://github.com/idinging/freemail/blob/master/public/js/app-router.js): `public/js/app-router.js`
- [Browser cache](https://github.com/idinging/freemail/blob/master/public/js/storage.js): `public/js/storage.js`

### Worker and API

- [Worker entry](https://github.com/idinging/freemail/blob/master/src/server.js): `src/server.js`
- [Login routes](https://github.com/idinging/freemail/blob/master/src/routes/auth.js): `src/routes/auth.js`
- [Auth middleware](https://github.com/idinging/freemail/blob/master/src/middleware/app.js): `src/middleware/app.js`
- [API routes](https://github.com/idinging/freemail/blob/master/src/routes/api.js): `src/routes/api.js`
- [API dispatcher](https://github.com/idinging/freemail/blob/master/src/api/index.js): `src/api/index.js`
- [Mailbox APIs](https://github.com/idinging/freemail/blob/master/src/api/mailboxes.js): `src/api/mailboxes.js`
- [Email APIs](https://github.com/idinging/freemail/blob/master/src/api/emails.js): `src/api/emails.js`
- [Send API](https://github.com/idinging/freemail/blob/master/src/api/send.js): `src/api/send.js`
- [User administration](https://github.com/idinging/freemail/blob/master/src/api/users.js): `src/api/users.js`

### Email processing

- [Inbound handler](https://github.com/idinging/freemail/blob/master/src/email/handler.js): `src/email/handler.js`
- [Parsing and codes](https://github.com/idinging/freemail/blob/master/src/email/parser.js): `src/email/parser.js`
- [Forwarding rules](https://github.com/idinging/freemail/blob/master/src/email/forwarder.js): `src/email/forwarder.js`

### Persistence

- [Database access](https://github.com/idinging/freemail/blob/master/src/db/index.js): `src/db/index.js`

### Outbound providers

- [Provider routing](https://github.com/idinging/freemail/blob/master/src/email/providers/index.js): `src/email/providers/index.js`

### Other components

- **Mailbox user**
- **Email routing**
- **D1 database**
- **R2 EML store**
- **Resend**
- **SendFlare**
- **Cyberpersons**

## Connections

- Mailbox user → Mailbox interface: uses
- Mailbox interface → Worker entry: requests APIs
- Mailbox interface → Browser cache: caches data
- View routing → Mailbox interface: switches views
- Worker entry → Login routes: mounts routes
- Worker entry → Auth middleware: protects API
- Worker entry → API routes: mounts routes
- Worker entry → Inbound handler: dispatches email events
- API routes → API dispatcher: dispatches requests
- Login routes → Database access: reads/writes users
- API dispatcher → Mailbox APIs: dispatches mailbox APIs
- API dispatcher → Email APIs: dispatches email APIs
- API dispatcher → Send API: dispatches send API
- API dispatcher → User administration: dispatches user APIs
- Mailbox APIs → Database access: reads/writes mailboxes
- Email APIs → Database access: reads email metadata
- Email routing → Worker entry: delivers messages
- Inbound handler → Parsing and codes: parses message
- Inbound handler → Forwarding rules: applies forwarding
- Inbound handler → Database access: writes message metadata
- Inbound handler → R2 EML store: stores raw EML
- Database access → D1 database: reads/writes records
- Send API → Provider routing: routes outbound mail
- Provider routing → Resend: sends via
- Provider routing → SendFlare: sends via
- Provider routing → Cyberpersons: sends via