# atsh-here/genmail-vm architecture

> Architecture diagram of the GitHub repository atsh-here/genmail-vm, 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/atsh-here/genmail-vm
- Repository: https://github.com/atsh-here/genmail-vm

## Overview

genmail is a self-hosted transactional mail forwarder: SMTP mail is filtered on the VM, routed through a Cloudflare Worker, and delivered to a verified destination. Its main workflow separates SMTP ingress, recipient filtering, route resolution, MIME delivery, and logging. The repository also supports Git-driven filter and routing-data updates. The Worker and milter excerpts are partial; documented capabilities are included, while uncertain internal wiring is omitted.

Main entry points: [`worker/src/index.js`](https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js) (Worker API), [`milter/genmail_milter.py`](https://github.com/atsh-here/genmail-vm/blob/main/milter/genmail_milter.py) (Milter), [`webhook/app.py`](https://github.com/atsh-here/genmail-vm/blob/main/webhook/app.py) (Config webhook), [`.github/scripts/db-sync.py`](https://github.com/atsh-here/genmail-vm/blob/main/.github/scripts/db-sync.py) (DB sync script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["SMTP ingress"]
  node_postfix["Postfix SMTP<br/>[main.cf]"]
end

subgraph group_filtering["Filtering and config"]
  node_milter["Milter<br/>[genmail_milter.py]"]
  node_old_filter["OLD allowlist<br/>[OLD.yaml]"]
  node_mar_filter["MAR rules<br/>[MAR.yaml]"]
end

subgraph group_routing["Routing and data"]
  node_worker["Worker API<br/>[index.js]"]
  node_route_resolution["Route resolution<br/>[index.js]"]
  node_route_data["Route tables"]
  node_d1[("D1 database")]
end

subgraph group_delivery["Delivery and logging"]
  node_mime_handling["MIME parsing and rewrite<br/>[index.js]"]
  node_email_sending["Cloudflare Email Sending"]
  node_mail_log[("Mail log<br/>[mail_log.sql]")]
end

subgraph group_sync["Git-based updates"]
  node_config_webhook["Config webhook<br/>[app.py]"]
  node_github_config["Config sync workflow<br/>[genmail-config.yml]"]
  node_config_push["Config push script"]
  node_db_workflow["DB sync workflow<br/>[db-sync.yml]"]
  node_db_sync_script["DB sync script<br/>[db-sync.py]"]
  node_csv_data["Routing CSVs"]
end

node_internet_mail(("Internet mail"))
node_github(("Git repository"))
node_tunnel["Cloudflare Tunnel"]

node_internet_mail -->|"SMTP sends"| node_postfix
node_postfix -->|"dispatches mail"| node_milter
node_milter -->|"reads"| node_old_filter
node_milter -->|"reads"| node_mar_filter
node_milter -->|"requests /route"| node_worker
node_worker -->|"dispatches"| node_route_resolution
node_route_resolution -->|"queries routes"| node_d1
node_d1 -->|"returns matches"| node_route_resolution
node_worker -->|"writes decisions"| node_mail_log
node_milter -->|"sends MIME to /deliver"| node_worker
node_worker -->|"parses and rewrites"| node_mime_handling
node_mime_handling -->|"sends message"| node_email_sending
node_worker -->|"updates delivery status"| node_mail_log
node_github -->|"triggers on commit"| node_github_config
node_github_config -->|"runs"| node_config_push
node_config_push -->|"posts signed config"| node_tunnel
node_tunnel -->|"forwards request"| node_config_webhook
node_config_webhook -->|"writes config"| node_old_filter
node_config_webhook -->|"writes config"| node_mar_filter
node_github -->|"triggers on commit"| node_db_workflow
node_db_workflow -->|"runs"| node_db_sync_script
node_db_sync_script -->|"reads and posts"| node_csv_data
node_db_sync_script -->|"requests /db/sync"| node_worker
node_worker -->|"applies table state"| node_d1
node_worker -->|"returns post-apply state"| node_csv_data

click node_postfix "https://github.com/atsh-here/genmail-vm/blob/main/postfix/main.cf"
click node_milter "https://github.com/atsh-here/genmail-vm/blob/main/milter/genmail_milter.py"
click node_old_filter "https://github.com/atsh-here/genmail-vm/blob/main/config/OLD.yaml"
click node_mar_filter "https://github.com/atsh-here/genmail-vm/blob/main/config/MAR.yaml"
click node_worker "https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js"
click node_route_resolution "https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js"
click node_route_data "https://github.com/atsh-here/genmail-vm/tree/main/DB/datafiles"
click node_mime_handling "https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js"
click node_mail_log "https://github.com/atsh-here/genmail-vm/blob/main/DB/schemas/mail_log.sql"
click node_config_webhook "https://github.com/atsh-here/genmail-vm/blob/main/webhook/app.py"
click node_github_config "https://github.com/atsh-here/genmail-vm/blob/main/.github/workflows/genmail-config.yml"
click node_config_push "https://github.com/atsh-here/genmail-vm/blob/main/.github/scripts/push-all-configs.py"
click node_db_workflow "https://github.com/atsh-here/genmail-vm/blob/main/.github/workflows/db-sync.yml"
click node_db_sync_script "https://github.com/atsh-here/genmail-vm/blob/main/.github/scripts/db-sync.py"
click node_csv_data "https://github.com/atsh-here/genmail-vm/tree/main/DB/datafiles"

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_postfix toneBlue
class node_milter,node_old_filter,node_mar_filter toneAmber
class node_worker,node_route_resolution,node_route_data,node_d1 toneMint
class node_mime_handling,node_email_sending,node_mail_log toneRose
class node_config_webhook,node_github_config,node_config_push,node_db_workflow,node_db_sync_script,node_csv_data,node_internet_mail,node_github,node_tunnel toneIndigo
```

## Components

### SMTP ingress

- [Postfix SMTP](https://github.com/atsh-here/genmail-vm/blob/main/postfix/main.cf): `postfix/main.cf`

### Filtering and config

- [Milter](https://github.com/atsh-here/genmail-vm/blob/main/milter/genmail_milter.py): `milter/genmail_milter.py`
- [OLD allowlist](https://github.com/atsh-here/genmail-vm/blob/main/config/OLD.yaml): `config/OLD.yaml`
- [MAR rules](https://github.com/atsh-here/genmail-vm/blob/main/config/MAR.yaml): `config/MAR.yaml`

### Routing and data

- [Worker API](https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js): `worker/src/index.js`
- [Route resolution](https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js): `worker/src/index.js`
- [Route tables](https://github.com/atsh-here/genmail-vm/tree/main/DB/datafiles): `DB/datafiles`
- **D1 database**

### Delivery and logging

- [MIME parsing and rewrite](https://github.com/atsh-here/genmail-vm/blob/main/worker/src/index.js): `worker/src/index.js`
- **Cloudflare Email Sending**
- [Mail log](https://github.com/atsh-here/genmail-vm/blob/main/DB/schemas/mail_log.sql): `DB/schemas/mail_log.sql`

### Git-based updates

- [Config webhook](https://github.com/atsh-here/genmail-vm/blob/main/webhook/app.py): `webhook/app.py`
- [Config sync workflow](https://github.com/atsh-here/genmail-vm/blob/main/.github/workflows/genmail-config.yml): `.github/workflows/genmail-config.yml`
- [Config push script](https://github.com/atsh-here/genmail-vm/blob/main/.github/scripts/push-all-configs.py): `.github/scripts/push-all-configs.py`
- [DB sync workflow](https://github.com/atsh-here/genmail-vm/blob/main/.github/workflows/db-sync.yml): `.github/workflows/db-sync.yml`
- [DB sync script](https://github.com/atsh-here/genmail-vm/blob/main/.github/scripts/db-sync.py): `.github/scripts/db-sync.py`
- [Routing CSVs](https://github.com/atsh-here/genmail-vm/tree/main/DB/datafiles): `DB/datafiles`

### Other components

- **Internet mail**
- **Git repository**
- **Cloudflare Tunnel**

## Connections

- Internet mail → Postfix SMTP: SMTP sends
- Postfix SMTP → Milter: dispatches mail
- Milter → OLD allowlist: reads
- Milter → MAR rules: reads
- Milter → Worker API: requests /route
- Worker API → Route resolution: dispatches
- Route resolution → D1 database: queries routes
- D1 database → Route resolution: returns matches
- Worker API → Mail log: writes decisions
- Milter → Worker API: sends MIME to /deliver
- Worker API → MIME parsing and rewrite: parses and rewrites
- MIME parsing and rewrite → Cloudflare Email Sending: sends message
- Worker API → Mail log: updates delivery status
- Git repository → Config sync workflow: triggers on commit
- Config sync workflow → Config push script: runs
- Config push script → Cloudflare Tunnel: posts signed config
- Cloudflare Tunnel → Config webhook: forwards request
- Config webhook → OLD allowlist: writes config
- Config webhook → MAR rules: writes config
- Git repository → DB sync workflow: triggers on commit
- DB sync workflow → DB sync script: runs
- DB sync script → Routing CSVs: reads and posts
- DB sync script → Worker API: requests /db/sync
- Worker API → D1 database: applies table state
- Worker API → Routing CSVs: returns post-apply state