# rahmon-tech/emailsystem architecture

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

- Interactive diagram: https://gitdiagram.com/rahmon-tech/emailsystem
- Repository: https://github.com/rahmon-tech/emailsystem

## Overview

EmailBlast is a self-hosted campaign platform. Teams compose standard or image-first messages, import recipients, configure senders and providers, then schedule or launch campaigns. The worker prepares campaigns and processes durable deliveries through provider-aware routing, safety limits, and pacing; provider events reconcile outcomes for Activity and tracking. The graph preserves documented experiment and operational capabilities. Source excerpts and the README support the shown relationships; unsampled subsystems are included where the tree and README establish them, with uncertain links omitted.

Main entry points: [`packages/core/src/engine.ts`](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/engine.ts) (Delivery engine), [`packages/core/src/campaigns.ts`](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/campaigns.ts) (Campaign lifecycle), [`packages/db/src/index.ts`](https://github.com/rahmon-tech/emailsystem/blob/main/packages/db/src/index.ts) (PostgreSQL), [`apps/web/app/api/[...path]/route.ts`](https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/app/api/%5B...path%5D/route.ts) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_compose["Campaign composer<br/>[blast.tsx]"]
  node_image["Image campaign<br/>[image-blast.tsx]"]
  node_activity["Activity console<br/>[activity.tsx]"]
  node_webapi["HTTP API<br/>[route.ts]"]
end

subgraph group_campaign["Campaign management"]
  node_campaigns["Campaign lifecycle<br/>[campaigns.ts]"]
  node_imports["Recipient imports<br/>[imports.ts]"]
  node_render["Email rendering<br/>[index.ts]"]
end

subgraph group_delivery["Delivery runtime"]
  node_worker["Queue worker<br/>[main.ts]"]
  node_engine["Delivery engine<br/>[engine.ts]"]
  node_dispatch["Pacing dispatcher<br/>[dispatcher.ts]"]
  node_events["Event reconciliation<br/>[events.ts]"]
  node_tracking["Click tracking<br/>[tracking.ts]"]
end

subgraph group_controls["Safety and experiments"]
  node_safety["Safety governor<br/>[safety.ts]"]
  node_experiments["Delivery experiments<br/>[experiments.ts]"]
  node_evidence["Experiment evidence"]
end

subgraph group_integrations["Providers and state"]
  node_provideradmin["Provider management<br/>[providers.ts]"]
  node_catalog["Provider adapters<br/>[index.ts]"]
  node_webhooks["Provider webhooks<br/>[webhooks.ts]"]
  node_db[("PostgreSQL<br/>[index.ts]")]
  node_redis[("Redis coordination<br/>[redis.ts]")]
end

node_team(("Campaign team"))
node_provider["Email providers"]
node_recipient(("Email recipient"))

node_team -->|"composes"| node_compose
node_team -->|"composes"| node_image
node_compose -.->|"submits"| node_webapi
node_image -.->|"submits"| node_webapi
node_webapi -->|"routes campaign requests"| node_campaigns
node_campaigns -->|"uses recipient lists"| node_imports
node_campaigns -->|"renders message"| node_render
node_campaigns -->|"persists campaign state"| node_db
node_worker -->|"prepares campaign"| node_campaigns
node_worker -->|"processes deliveries"| node_engine
node_worker -->|"reconciles events"| node_events
node_engine -->|"records attempts"| node_db
node_engine -->|"acquires pacing"| node_dispatch
node_engine -->|"checks safety"| node_safety
node_engine -.->|"applies experiment pacing"| node_experiments
node_engine -->|"appends outcome evidence"| node_evidence
node_engine -.->|"sends through adapter"| node_catalog
node_provideradmin -->|"tests provider"| node_catalog
node_provideradmin -->|"stores connection"| node_db
node_provider -.->|"posts delivery events"| node_webhooks
node_webhooks -.->|"normalizes events"| node_events
node_events -.->|"updates delivery state"| node_db
node_safety -->|"coordinates limits"| node_redis
node_activity -.->|"requests status"| node_webapi
node_webapi -->|"serves lifecycle actions"| node_campaigns
node_recipient -.->|"follows tracked link"| node_tracking
node_tracking -.->|"records aggregate activity"| node_db
node_experiments -->|"stores run state"| node_db
node_experiments -->|"uses evidence base"| node_evidence

click node_compose "https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/blast.tsx"
click node_image "https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/image-blast.tsx"
click node_activity "https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/activity.tsx"
click node_webapi "https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/app/api/%5B...path%5D/route.ts"
click node_campaigns "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/campaigns.ts"
click node_imports "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/imports.ts"
click node_render "https://github.com/rahmon-tech/emailsystem/blob/main/packages/email-renderer/src/index.ts"
click node_worker "https://github.com/rahmon-tech/emailsystem/blob/main/apps/worker/main.ts"
click node_engine "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/engine.ts"
click node_dispatch "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/dispatcher.ts"
click node_events "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/events.ts"
click node_tracking "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/tracking.ts"
click node_safety "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/safety.ts"
click node_experiments "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/experiments.ts"
click node_evidence "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/experiment-evidence.ts"
click node_provideradmin "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/providers.ts"
click node_catalog "https://github.com/rahmon-tech/emailsystem/blob/main/packages/providers/src/index.ts"
click node_webhooks "https://github.com/rahmon-tech/emailsystem/blob/main/packages/providers/src/webhooks.ts"
click node_db "https://github.com/rahmon-tech/emailsystem/blob/main/packages/db/src/index.ts"
click node_redis "https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/redis.ts"

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_compose,node_image,node_activity,node_webapi toneBlue
class node_campaigns,node_imports,node_render toneAmber
class node_worker,node_engine,node_dispatch,node_events,node_tracking toneMint
class node_safety,node_experiments,node_evidence toneRose
class node_provideradmin,node_catalog,node_webhooks,node_db,node_redis,node_team,node_provider,node_recipient toneIndigo
```

## Components

### Web experience

- [Campaign composer](https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/blast.tsx): `apps/web/components/blast.tsx`
- [Image campaign](https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/image-blast.tsx): `apps/web/components/image-blast.tsx`
- [Activity console](https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/components/activity.tsx): `apps/web/components/activity.tsx`
- [HTTP API](https://github.com/rahmon-tech/emailsystem/blob/main/apps/web/app/api/%5B...path%5D/route.ts): `apps/web/app/api/[...path]/route.ts`

### Campaign management

- [Campaign lifecycle](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/campaigns.ts): `packages/core/src/campaigns.ts`
- [Recipient imports](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/imports.ts): `packages/core/src/imports.ts`
- [Email rendering](https://github.com/rahmon-tech/emailsystem/blob/main/packages/email-renderer/src/index.ts): `packages/email-renderer/src/index.ts`

### Delivery runtime

- [Queue worker](https://github.com/rahmon-tech/emailsystem/blob/main/apps/worker/main.ts): `apps/worker/main.ts`
- [Delivery engine](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/engine.ts): `packages/core/src/engine.ts`
- [Pacing dispatcher](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/dispatcher.ts): `packages/core/src/dispatcher.ts`
- [Event reconciliation](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/events.ts): `packages/core/src/events.ts`
- [Click tracking](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/tracking.ts): `packages/core/src/tracking.ts`

### Safety and experiments

- [Safety governor](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/safety.ts): `packages/core/src/safety.ts`
- [Delivery experiments](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/experiments.ts): `packages/core/src/experiments.ts`
- [Experiment evidence](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/experiment-evidence.ts): `packages/core/src/experiment-evidence.ts`

### Providers and state

- [Provider management](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/providers.ts): `packages/core/src/providers.ts`
- [Provider adapters](https://github.com/rahmon-tech/emailsystem/blob/main/packages/providers/src/index.ts): `packages/providers/src/index.ts`
- [Provider webhooks](https://github.com/rahmon-tech/emailsystem/blob/main/packages/providers/src/webhooks.ts): `packages/providers/src/webhooks.ts`
- [PostgreSQL](https://github.com/rahmon-tech/emailsystem/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`
- [Redis coordination](https://github.com/rahmon-tech/emailsystem/blob/main/packages/core/src/redis.ts): `packages/core/src/redis.ts`

### Other components

- **Campaign team**
- **Email providers**
- **Email recipient**

## Connections

- Campaign team → Campaign composer: composes
- Campaign team → Image campaign: composes
- Campaign composer → HTTP API: submits
- Image campaign → HTTP API: submits
- HTTP API → Campaign lifecycle: routes campaign requests (evidence: `apps/web/app/api/[...path]/route.ts`)
- Campaign lifecycle → Recipient imports: uses recipient lists (evidence: `packages/core/src/campaigns.ts`)
- Campaign lifecycle → Email rendering: renders message (evidence: `packages/core/src/campaigns.ts`)
- Campaign lifecycle → PostgreSQL: persists campaign state (evidence: `packages/core/src/campaigns.ts`)
- Queue worker → Campaign lifecycle: prepares campaign (evidence: `apps/worker/main.ts`)
- Queue worker → Delivery engine: processes deliveries (evidence: `apps/worker/main.ts`)
- Queue worker → Event reconciliation: reconciles events (evidence: `apps/worker/main.ts`)
- Delivery engine → PostgreSQL: records attempts (evidence: `packages/core/src/engine.ts`)
- Delivery engine → Pacing dispatcher: acquires pacing (evidence: `packages/core/src/engine.ts`)
- Delivery engine → Safety governor: checks safety (evidence: `packages/core/src/engine.ts`)
- Delivery engine → Delivery experiments: applies experiment pacing (evidence: `packages/core/src/engine.ts`)
- Delivery engine → Experiment evidence: appends outcome evidence (evidence: `packages/core/src/engine.ts`)
- Delivery engine → Provider adapters: sends through adapter
- Provider management → Provider adapters: tests provider (evidence: `packages/core/src/providers.ts`)
- Provider management → PostgreSQL: stores connection (evidence: `packages/core/src/providers.ts`)
- Email providers → Provider webhooks: posts delivery events
- Provider webhooks → Event reconciliation: normalizes events
- Event reconciliation → PostgreSQL: updates delivery state
- Safety governor → Redis coordination: coordinates limits (evidence: `packages/core/src/safety.ts`)
- Activity console → HTTP API: requests status
- HTTP API → Campaign lifecycle: serves lifecycle actions (evidence: `apps/web/app/api/[...path]/route.ts`)
- Email recipient → Click tracking: follows tracked link
- Click tracking → PostgreSQL: records aggregate activity
- Delivery experiments → PostgreSQL: stores run state (evidence: `packages/core/src/experiments.ts`)
- Delivery experiments → Experiment evidence: uses evidence base (evidence: `packages/core/src/experiments.ts`)
