# aney2000/10_min_mail architecture

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

- Interactive diagram: https://gitdiagram.com/aney2000/10_min_mail
- Repository: https://github.com/aney2000/10_min_mail

## Overview

10 Minute Mail is a local disposable-email service. A browser requests a mailbox through the web app, then connects to its live inbox; an external sender delivers mail over SMTP. The SMTP handler parses and submits messages to the shared service, which stores them and publishes delivery events for WebSocket broadcast. Mailboxes expire after ten minutes, with a periodic sweep reclaiming expired data. The README and sampled source support these principal paths; links for unsampled route and startup details rely on README statements.

Main entry points: [`src/ten_min_mail/service.py`](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/service.py) (Mailbox Service), [`src/ten_min_mail/smtp.py`](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/smtp.py) (SMTP Receiver), [`src/ten_min_mail/api.py`](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/api.py) (HTTP API), [`src/ten_min_mail/websocket.py`](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/websocket.py) (Live Inbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Clients"]
  node_web_ui["Web UI<br/>[app.js]"]
end

subgraph group_delivery["Delivery"]
  node_http_api["HTTP API<br/>[api.py]"]
  node_smtp_receiver["SMTP Receiver<br/>[smtp.py]"]
  node_parser["Mail Parser<br/>[mail_parsing.py]"]
  node_websocket["Live Inbox<br/>[websocket.py]"]
end

subgraph group_core["Application Core"]
  node_service["Mailbox Service<br/>[service.py]"]
  node_address_generator["Address Generator"]
  node_domain["Domain Rules<br/>[domain.py]"]
  node_clock["Clock<br/>[clock.py]"]
  node_repository["SQLite Repository<br/>[repository.py]"]
  node_events["Event Publisher<br/>[events.py]"]
end

subgraph group_runtime["Runtime"]
  node_mail_store[("Mailbox Data<br/>[repository.py]")]
  node_housekeeping["Expiry Sweeper<br/>[housekeeping.py]"]
  node_config["Environment Config<br/>[config.py]"]
  node_entrypoint["Application Entry<br/>[__main__.py]"]
end

node_browser(("Browser"))
node_sender(("Mail Sender"))

node_browser -->|"uses"| node_web_ui
node_web_ui -->|"requests mailboxes"| node_http_api
node_browser -->|"opens inbox"| node_websocket
node_sender -->|"sends mail"| node_smtp_receiver
node_http_api -->|"routes use cases"| node_service
node_smtp_receiver -->|"parses message"| node_parser
node_smtp_receiver -->|"delivers message"| node_service
node_service -->|"generates addresses"| node_address_generator
node_service -->|"persists mail"| node_repository
node_repository -->|"reads and writes"| node_mail_store
node_service -->|"gets current time"| node_clock
node_service -->|"applies rules"| node_domain
node_service -->|"publishes delivery"| node_events
node_events -->|"notifies subscriber"| node_websocket
node_websocket -->|"sends live frame"| node_browser
node_housekeeping -->|"purges expired"| node_service
node_entrypoint -->|"starts application"| node_http_api
node_entrypoint -->|"loads settings"| node_config

click node_web_ui "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/static/app.js"
click node_http_api "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/api.py"
click node_smtp_receiver "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/smtp.py"
click node_parser "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/mail_parsing.py"
click node_service "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/service.py"
click node_address_generator "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/address_generator.py"
click node_domain "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/domain.py"
click node_clock "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/clock.py"
click node_repository "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/repository.py"
click node_mail_store "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/repository.py"
click node_events "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/events.py"
click node_websocket "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/websocket.py"
click node_housekeeping "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/housekeeping.py"
click node_config "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/config.py"
click node_entrypoint "https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/__main__.py"

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_web_ui,node_browser toneBlue
class node_http_api,node_smtp_receiver,node_parser,node_websocket toneAmber
class node_service,node_address_generator,node_domain,node_clock,node_repository,node_events toneMint
class node_mail_store,node_housekeeping,node_config,node_entrypoint toneRose
class node_sender toneIndigo
```

## Components

### Clients

- [Web UI](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/static/app.js): `src/ten_min_mail/static/app.js`

### Delivery

- [HTTP API](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/api.py): `src/ten_min_mail/api.py`
- [SMTP Receiver](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/smtp.py): `src/ten_min_mail/smtp.py`
- [Mail Parser](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/mail_parsing.py): `src/ten_min_mail/mail_parsing.py`
- [Live Inbox](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/websocket.py): `src/ten_min_mail/websocket.py`

### Application Core

- [Mailbox Service](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/service.py): `src/ten_min_mail/service.py`
- [Address Generator](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/address_generator.py): `src/ten_min_mail/address_generator.py`
- [Domain Rules](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/domain.py): `src/ten_min_mail/domain.py`
- [Clock](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/clock.py): `src/ten_min_mail/clock.py`
- [SQLite Repository](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/repository.py): `src/ten_min_mail/repository.py`
- [Event Publisher](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/events.py): `src/ten_min_mail/events.py`

### Runtime

- [Mailbox Data](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/repository.py): `src/ten_min_mail/repository.py`
- [Expiry Sweeper](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/housekeeping.py): `src/ten_min_mail/housekeeping.py`
- [Environment Config](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/config.py): `src/ten_min_mail/config.py`
- [Application Entry](https://github.com/aney2000/10_min_mail/blob/master/src/ten_min_mail/__main__.py): `src/ten_min_mail/__main__.py`

### Other components

- **Browser**
- **Mail Sender**

## Connections

- Browser → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP API: requests mailboxes (evidence: `README.md`)
- Browser → Live Inbox: opens inbox (evidence: `README.md`)
- Mail Sender → SMTP Receiver: sends mail (evidence: `README.md`)
- HTTP API → Mailbox Service: routes use cases (evidence: `src/ten_min_mail/api.py`)
- SMTP Receiver → Mail Parser: parses message (evidence: `src/ten_min_mail/smtp.py`)
- SMTP Receiver → Mailbox Service: delivers message (evidence: `src/ten_min_mail/smtp.py`)
- Mailbox Service → Address Generator: generates addresses (evidence: `src/ten_min_mail/service.py`)
- Mailbox Service → SQLite Repository: persists mail (evidence: `src/ten_min_mail/service.py`)
- SQLite Repository → Mailbox Data: reads and writes (evidence: `src/ten_min_mail/repository.py`)
- Mailbox Service → Clock: gets current time (evidence: `src/ten_min_mail/service.py`)
- Mailbox Service → Domain Rules: applies rules (evidence: `README.md`)
- Mailbox Service → Event Publisher: publishes delivery (evidence: `src/ten_min_mail/service.py`)
- Event Publisher → Live Inbox: notifies subscriber (evidence: `README.md`)
- Live Inbox → Browser: sends live frame (evidence: `README.md`)
- Expiry Sweeper → Mailbox Service: purges expired (evidence: `README.md`)
- Application Entry → HTTP API: starts application (evidence: `README.md`)
- Application Entry → Environment Config: loads settings (evidence: `src/ten_min_mail/__main__.py`)