# mhibrizif/zimail architecture

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

- Interactive diagram: https://gitdiagram.com/mhibrizif/zimail
- Repository: https://github.com/mhibrizif/zimail

## Overview

Zimail is a self-hosted, multi-domain email service with a browser client and REST, CLI, and MCP access. A user signs in, opens a mailbox or conversation, and can reply or compose; the mail API delegates sending and persistence to the outbound flow, while inbound provider delivery enters separately and is stored for mailbox retrieval. Supporting product stages include account/domain setup, attachments, calendar and reservation booking, meetings, and scheduled delivery. The README documents these capabilities; unsampled subsystems are represented at their enclosing source directories, without asserting internal call wiring.

Main entry points: [`src/lib/server/mail-store/index.ts`](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/mail-store/index.ts) (Mail store), [`src/routes/api/mail/+server.ts`](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/mail/%2Bserver.ts) (Mail API), [`src/routes/api/setup/+server.ts`](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/setup/%2Bserver.ts) (Setup and auth API), [`src/lib/server/outbound/outbox.ts`](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/outbound/outbox.ts) (Outbound dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_web["Mailbox and pages<br/>[+page.server.ts]"]
  node_mailapi["Mail API<br/>[+server.ts]"]
  node_threadapi["Conversation API<br/>[+server.ts]"]
end

subgraph group_mail["Mail handling"]
  node_mailstore["Mail store<br/>[index.ts]"]
  node_outbox["Outbound dispatch<br/>[outbox.ts]"]
  node_inbound["Inbound handling<br/>[inbound.ts]"]
  node_provider["Mail provider adapters<br/>[resend-provider.ts]"]
  node_attachments["Attachment handling<br/>[attachments.ts]"]
  node_scheduled["Scheduled delivery<br/>[scheduled-send.ts]"]
  node_db[("D1 mail and account data")]
  node_r2[("R2 attachments")]
end

subgraph group_identity["Accounts and domains"]
  node_authapi["Setup and auth API<br/>[+server.ts]"]
  node_auth["Authentication service<br/>[index.ts]"]
  node_domainapi["Domain API<br/>[+server.ts]"]
  node_domains["Domain service<br/>[index.ts]"]
end

subgraph group_calendar["Calendar and meetings"]
  node_calendar["Calendar and reservations"]
  node_meetings["Meetings"]
end

subgraph group_interfaces["External interfaces"]
  node_cli["CLI and MCP<br/>[main.ts]"]
  node_rest["REST API"]
end

node_user(("Mailbox user"))
node_emailservice{{"Email delivery service"}}
node_cron(("Scheduled trigger"))
node_livekit{{"LiveKit"}}
node_calendarfeeds{{"External iCal feeds"}}

node_user -->|"uses"| node_web
node_web -->|"requests mail"| node_mailapi
node_mailapi -->|"lists mailbox"| node_mailstore
node_threadapi -->|"loads and updates"| node_mailstore
node_mailapi -->|"dispatches send"| node_outbox
node_threadapi -->|"dispatches reply"| node_outbox
node_outbox -->|"sends through"| node_provider
node_provider -->|"sends mail"| node_emailservice
node_emailservice -->|"delivers mail"| node_inbound
node_inbound -->|"stores messages"| node_mailstore
node_mailstore -->|"reads and writes"| node_db
node_attachments -->|"stores files"| node_r2
node_user -->|"sets up account"| node_authapi
node_authapi -->|"creates admin and session"| node_auth
node_authapi -->|"connects domain and address"| node_domains
node_auth -->|"persists identity"| node_db
node_domainapi -->|"manages domains"| node_domains
node_domains -->|"reads and writes"| node_db
node_user -->|"uses"| node_rest
node_cli -->|"calls API"| node_rest
node_user -->|"books and manages events"| node_calendar
node_calendar -.->|"fetches feeds"| node_calendarfeeds
node_user -->|"joins meetings"| node_meetings
node_meetings -.->|"connects calls"| node_livekit
node_cron -->|"triggers delivery"| node_scheduled
node_scheduled -->|"releases queued mail"| node_provider

click node_web "https://github.com/mhibrizif/zimail/blob/main/src/routes/inbox/%2Bpage.server.ts"
click node_mailapi "https://github.com/mhibrizif/zimail/blob/main/src/routes/api/mail/%2Bserver.ts"
click node_threadapi "https://github.com/mhibrizif/zimail/blob/main/src/routes/api/mail/%5Bid%5D/%2Bserver.ts"
click node_mailstore "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/mail-store/index.ts"
click node_outbox "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/outbound/outbox.ts"
click node_inbound "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/inbound/inbound.ts"
click node_provider "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/providers/resend-provider.ts"
click node_attachments "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/attachments.ts"
click node_scheduled "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/scheduled-send.ts"
click node_authapi "https://github.com/mhibrizif/zimail/blob/main/src/routes/api/setup/%2Bserver.ts"
click node_auth "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/auth/index.ts"
click node_domainapi "https://github.com/mhibrizif/zimail/blob/main/src/routes/api/domains/%2Bserver.ts"
click node_domains "https://github.com/mhibrizif/zimail/blob/main/src/lib/server/domains/index.ts"
click node_calendar "https://github.com/mhibrizif/zimail/tree/main/src/lib/server/calendar"
click node_meetings "https://github.com/mhibrizif/zimail/tree/main/src/lib/server/meet"
click node_cli "https://github.com/mhibrizif/zimail/blob/main/cli/main.ts"
click node_rest "https://github.com/mhibrizif/zimail/tree/main/src/routes/api"

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,node_mailapi,node_threadapi,node_user toneBlue
class node_mailstore,node_outbox,node_inbound,node_provider,node_attachments,node_scheduled,node_db,node_r2 toneAmber
class node_authapi,node_auth,node_domainapi,node_domains toneMint
class node_calendar,node_meetings toneRose
class node_cli,node_rest,node_emailservice,node_cron,node_livekit,node_calendarfeeds toneIndigo
```

## Components

### Web application

- [Mailbox and pages](https://github.com/mhibrizif/zimail/blob/main/src/routes/inbox/%2Bpage.server.ts): `src/routes/inbox/+page.server.ts`
- [Mail API](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/mail/%2Bserver.ts): `src/routes/api/mail/+server.ts`
- [Conversation API](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/mail/%5Bid%5D/%2Bserver.ts): `src/routes/api/mail/[id]/+server.ts`

### Mail handling

- [Mail store](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/mail-store/index.ts): `src/lib/server/mail-store/index.ts`
- [Outbound dispatch](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/outbound/outbox.ts): `src/lib/server/outbound/outbox.ts`
- [Inbound handling](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/inbound/inbound.ts): `src/lib/server/inbound/inbound.ts`
- [Mail provider adapters](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/providers/resend-provider.ts): `src/lib/server/providers/resend-provider.ts`
- [Attachment handling](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/attachments.ts): `src/lib/server/attachments.ts`
- [Scheduled delivery](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/scheduled-send.ts): `src/lib/server/scheduled-send.ts`
- **D1 mail and account data**
- **R2 attachments**

### Accounts and domains

- [Setup and auth API](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/setup/%2Bserver.ts): `src/routes/api/setup/+server.ts`
- [Authentication service](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/auth/index.ts): `src/lib/server/auth/index.ts`
- [Domain API](https://github.com/mhibrizif/zimail/blob/main/src/routes/api/domains/%2Bserver.ts): `src/routes/api/domains/+server.ts`
- [Domain service](https://github.com/mhibrizif/zimail/blob/main/src/lib/server/domains/index.ts): `src/lib/server/domains/index.ts`

### Calendar and meetings

- [Calendar and reservations](https://github.com/mhibrizif/zimail/tree/main/src/lib/server/calendar): `src/lib/server/calendar`
- [Meetings](https://github.com/mhibrizif/zimail/tree/main/src/lib/server/meet): `src/lib/server/meet`

### External interfaces

- [CLI and MCP](https://github.com/mhibrizif/zimail/blob/main/cli/main.ts): `cli/main.ts`
- [REST API](https://github.com/mhibrizif/zimail/tree/main/src/routes/api): `src/routes/api`

### Other components

- **Mailbox user**
- **Email delivery service**
- **Scheduled trigger**
- **LiveKit**
- **External iCal feeds**

## Connections

- Mailbox user → Mailbox and pages: uses
- Mailbox and pages → Mail API: requests mail
- Mail API → Mail store: lists mailbox
- Conversation API → Mail store: loads and updates
- Mail API → Outbound dispatch: dispatches send
- Conversation API → Outbound dispatch: dispatches reply
- Outbound dispatch → Mail provider adapters: sends through
- Mail provider adapters → Email delivery service: sends mail
- Email delivery service → Inbound handling: delivers mail
- Inbound handling → Mail store: stores messages
- Mail store → D1 mail and account data: reads and writes
- Attachment handling → R2 attachments: stores files
- Mailbox user → Setup and auth API: sets up account
- Setup and auth API → Authentication service: creates admin and session
- Setup and auth API → Domain service: connects domain and address
- Authentication service → D1 mail and account data: persists identity
- Domain API → Domain service: manages domains
- Domain service → D1 mail and account data: reads and writes
- Mailbox user → REST API: uses
- CLI and MCP → REST API: calls API
- Mailbox user → Calendar and reservations: books and manages events
- Calendar and reservations → External iCal feeds: fetches feeds
- Mailbox user → Meetings: joins meetings
- Meetings → LiveKit: connects calls
- Scheduled trigger → Scheduled delivery: triggers delivery
- Scheduled delivery → Mail provider adapters: releases queued mail