# md-emran-hossain/email-automation-engine architecture

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

- Interactive diagram: https://gitdiagram.com/md-emran-hossain/email-automation-engine
- Repository: https://github.com/md-emran-hossain/email-automation-engine

## Overview

Email Automation Engine is a multi-tenant platform for authoring event-driven email journeys and running them asynchronously. Users manage tenants, contacts, tags, templates, triggers, steps, and conditions in the web app; the API exposes these operations and execution summaries. Events start workflow execution, where workers handle branching, delays, email, and webhooks, while SES tracking events return through the API and queue. The README documents these product capabilities; worker-to-queue dispatch details are represented only at the documented level because worker handler source was not sampled.

Main entry points: [`apps/web/src/lib/api.ts`](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/lib/api.ts) (API client), [`apps/worker/src/handlers`](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/worker/src/handlers) (Queue workers), [`apps/api/src/modules/automation-event/interface/http/controllers`](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/automation-event/interface/http/controllers) (Event intake), [`apps/api/src/modules/automation-event/application/services/automation-event.service.ts`](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/automation-event/application/services/automation-event.service.ts) (Trigger matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_builder["Journey builder"]
  node_contactui["Contact management<br/>[Contacts.tsx]"]
  node_templateui["Template management<br/>[EmailTemplates.tsx]"]
  node_settingsui["Tenant settings<br/>[Settings.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["Management API"]
  node_iam["Identity and tenants"]
  node_workflowapi["Workflow endpoints"]
  node_workflowservices["Workflow services"]
  node_contactsapi["Contact endpoints"]
  node_contactservices["Contact services"]
  node_emailapi["Template endpoints"]
  node_emailservices["Email services"]
  node_eventapi["Event intake"]
  node_executionapi["Execution summaries"]
  node_eventservice["Trigger matching"]
end

subgraph group_runtime["Automation runtime"]
  node_worker["Queue workers"]
  node_emailworker["Email delivery"]
  node_branchworker["Conditional branching"]
  node_delayworker["Delayed steps"]
  node_webhookworker["Webhook delivery"]
  node_trackingworker["Tracking events"]
end

subgraph group_messaging["Queue contracts"]
  node_queuecontracts["Queue messages"]
end

subgraph group_integrations["External services"]
  node_database[("PostgreSQL")]
  node_sqs["AWS SQS"]
  node_ses["AWS SES"]
end

node_user(("Tenant user"))
node_externalapp(("Connected application"))
node_webhookservice(("Webhook target"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_builder
node_builder -->|"requests API"| node_apiclient
node_contactui -->|"requests API"| node_apiclient
node_templateui -->|"requests API"| node_apiclient
node_settingsui -->|"requests API"| node_apiclient
node_apiclient -->|"manages journeys"| node_workflowapi
node_apiclient -->|"manages contacts"| node_contactsapi
node_apiclient -->|"manages templates"| node_emailapi
node_apiclient -->|"manages access"| node_iam
node_workflowapi -->|"invokes"| node_workflowservices
node_contactsapi -->|"invokes"| node_contactservices
node_emailapi -->|"invokes"| node_emailservices
node_workflowapi -->|"persists workflow data"| node_database
node_contactservices -->|"persists contact data"| node_database
node_emailservices -->|"persists templates"| node_database
node_iam -->|"persists identity data"| node_database
node_externalapp -->|"posts event"| node_eventapi
node_eventapi -->|"processes event"| node_eventservice
node_eventservice -->|"queues automation"| node_sqs
node_eventservice -->|"reads trigger data"| node_database
node_sqs -->|"dispatches messages"| node_worker
node_worker -->|"dispatches email steps"| node_emailworker
node_worker -->|"dispatches splits"| node_branchworker
node_worker -->|"dispatches waiting steps"| node_delayworker
node_worker -->|"dispatches webhooks"| node_webhookworker
node_emailworker -->|"sends email"| node_ses
node_webhookworker -->|"calls webhook"| node_webhookservice
node_ses -->|"posts tracking event"| node_eventapi
node_eventapi -->|"resolves message"| node_emailservices
node_eventapi -->|"queues tracking"| node_sqs
node_sqs -->|"dispatches tracking"| node_trackingworker
node_trackingworker -->|"records events"| node_database
node_executionapi -->|"reads execution history"| node_database
node_apiclient -->|"reads summaries"| node_executionapi
node_worker -->|"updates execution state"| node_database
node_worker -->|"uses message contracts"| node_queuecontracts
node_eventservice -->|"creates event messages"| node_queuecontracts

click node_webapp "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/App.tsx"
click node_builder "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/workflow/WorkflowBuilder.tsx"
click node_contactui "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/contacts/Contacts.tsx"
click node_templateui "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/email-templates/EmailTemplates.tsx"
click node_settingsui "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/settings/Settings.tsx"
click node_apiclient "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/lib/api.ts"
click node_iam "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/iam"
click node_workflowapi "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/workflow/interface/workflow.controller.ts"
click node_workflowservices "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/workflow/application/services"
click node_contactsapi "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/contact/interface/http/controllers/contact.controller.ts"
click node_contactservices "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/contact/application/services"
click node_emailapi "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/email/interface/http/controllers/email-template.controller.ts"
click node_emailservices "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/email/application/services"
click node_eventapi "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/automation-event/interface/http/controllers"
click node_executionapi "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/contact-workflow/interface/http/controllers/execution-summary.controller.ts"
click node_eventservice "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/automation-event/application/services/automation-event.service.ts"
click node_worker "https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/worker/src/handlers"
click node_emailworker "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/send-workflow-email.handler.ts"
click node_branchworker "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/conditional-split.handler.ts"
click node_delayworker "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/watch-workflow-steps.handler.ts"
click node_webhookworker "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/call-webhook.handler.ts"
click node_trackingworker "https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/process-email-tracking-event.handler.ts"
click node_queuecontracts "https://github.com/md-emran-hossain/email-automation-engine/tree/main/packages/shared/src/queue"

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_webapp,node_builder,node_contactui,node_templateui,node_settingsui,node_apiclient,node_user toneBlue
class node_iam,node_workflowapi,node_workflowservices,node_contactsapi,node_contactservices,node_emailapi,node_emailservices,node_eventapi,node_executionapi,node_eventservice toneAmber
class node_worker,node_emailworker,node_branchworker,node_delayworker,node_webhookworker,node_trackingworker,node_webhookservice toneMint
class node_queuecontracts toneRose
class node_database,node_sqs,node_ses,node_externalapp toneIndigo
```

## Components

### Web application

- [Web app routes](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Journey builder](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/workflow/WorkflowBuilder.tsx): `apps/web/src/pages/workflow/WorkflowBuilder.tsx`
- [Contact management](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/contacts/Contacts.tsx): `apps/web/src/pages/contacts/Contacts.tsx`
- [Template management](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/email-templates/EmailTemplates.tsx): `apps/web/src/pages/email-templates/EmailTemplates.tsx`
- [Tenant settings](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/pages/settings/Settings.tsx): `apps/web/src/pages/settings/Settings.tsx`
- [API client](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Management API

- [Identity and tenants](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/iam): `apps/api/src/modules/iam`
- [Workflow endpoints](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/workflow/interface/workflow.controller.ts): `apps/api/src/modules/workflow/interface/workflow.controller.ts`
- [Workflow services](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/workflow/application/services): `apps/api/src/modules/workflow/application/services`
- [Contact endpoints](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/contact/interface/http/controllers/contact.controller.ts): `apps/api/src/modules/contact/interface/http/controllers/contact.controller.ts`
- [Contact services](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/contact/application/services): `apps/api/src/modules/contact/application/services`
- [Template endpoints](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/email/interface/http/controllers/email-template.controller.ts): `apps/api/src/modules/email/interface/http/controllers/email-template.controller.ts`
- [Email services](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/email/application/services): `apps/api/src/modules/email/application/services`
- [Event intake](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/api/src/modules/automation-event/interface/http/controllers): `apps/api/src/modules/automation-event/interface/http/controllers`
- [Execution summaries](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/contact-workflow/interface/http/controllers/execution-summary.controller.ts): `apps/api/src/modules/contact-workflow/interface/http/controllers/execution-summary.controller.ts`
- [Trigger matching](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/api/src/modules/automation-event/application/services/automation-event.service.ts): `apps/api/src/modules/automation-event/application/services/automation-event.service.ts`

### Automation runtime

- [Queue workers](https://github.com/md-emran-hossain/email-automation-engine/tree/main/apps/worker/src/handlers): `apps/worker/src/handlers`
- [Email delivery](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/send-workflow-email.handler.ts): `apps/worker/src/handlers/send-workflow-email.handler.ts`
- [Conditional branching](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/conditional-split.handler.ts): `apps/worker/src/handlers/conditional-split.handler.ts`
- [Delayed steps](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/watch-workflow-steps.handler.ts): `apps/worker/src/handlers/watch-workflow-steps.handler.ts`
- [Webhook delivery](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/call-webhook.handler.ts): `apps/worker/src/handlers/call-webhook.handler.ts`
- [Tracking events](https://github.com/md-emran-hossain/email-automation-engine/blob/main/apps/worker/src/handlers/process-email-tracking-event.handler.ts): `apps/worker/src/handlers/process-email-tracking-event.handler.ts`

### Queue contracts

- [Queue messages](https://github.com/md-emran-hossain/email-automation-engine/tree/main/packages/shared/src/queue): `packages/shared/src/queue`

### External services

- **PostgreSQL**
- **AWS SQS**
- **AWS SES**

### Other components

- **Tenant user**
- **Connected application**
- **Webhook target**

## Connections

- Tenant user → Web app routes: uses
- Web app routes → Journey builder: routes to
- Journey builder → API client: requests API
- Contact management → API client: requests API
- Template management → API client: requests API
- Tenant settings → API client: requests API
- API client → Workflow endpoints: manages journeys
- API client → Contact endpoints: manages contacts
- API client → Template endpoints: manages templates
- API client → Identity and tenants: manages access
- Workflow endpoints → Workflow services: invokes
- Contact endpoints → Contact services: invokes
- Template endpoints → Email services: invokes
- Workflow endpoints → PostgreSQL: persists workflow data
- Contact services → PostgreSQL: persists contact data
- Email services → PostgreSQL: persists templates
- Identity and tenants → PostgreSQL: persists identity data
- Connected application → Event intake: posts event
- Event intake → Trigger matching: processes event
- Trigger matching → AWS SQS: queues automation
- Trigger matching → PostgreSQL: reads trigger data
- AWS SQS → Queue workers: dispatches messages
- Queue workers → Email delivery: dispatches email steps
- Queue workers → Conditional branching: dispatches splits
- Queue workers → Delayed steps: dispatches waiting steps
- Queue workers → Webhook delivery: dispatches webhooks
- Email delivery → AWS SES: sends email
- Webhook delivery → Webhook target: calls webhook
- AWS SES → Event intake: posts tracking event
- Event intake → Email services: resolves message
- Event intake → AWS SQS: queues tracking
- AWS SQS → Tracking events: dispatches tracking
- Tracking events → PostgreSQL: records events
- Execution summaries → PostgreSQL: reads execution history
- API client → Execution summaries: reads summaries
- Queue workers → PostgreSQL: updates execution state
- Queue workers → Queue messages: uses message contracts
- Trigger matching → Queue messages: creates event messages