# tsujit74/email-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/tsujit74/email-scheduler
- Repository: https://github.com/tsujit74/email-scheduler

## Overview

Outbox lets users authenticate, build campaigns and recipient lists, schedule paced email delivery, then monitor campaign and email outcomes. The graph follows the documented browser-to-API-to-queue-to-worker flow and the sampled controller, service, repository, and worker calls. Campaign orchestration, queue implementation, and some frontend wiring are represented only at their exact enclosing paths because their source was not sampled; those links follow README documentation where noted.

Main entry points: [`backend/src/services/emailService.ts`](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailService.ts) (Recipient scheduling), [`backend/src/services/emailWorker.ts`](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailWorker.ts) (Email worker), [`backend/src/app.ts`](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/app.ts) (Express API), [`frontend/lib/api.ts`](https://github.com/tsujit74/email-scheduler/blob/main/frontend/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_compose["Campaign composer<br/>[page.tsx]"]
  node_recipient_upload["Recipient upload"]
  node_dashboard["Email dashboard<br/>[page.tsx]"]
  node_email_detail["Email details<br/>[page.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["Express API<br/>[app.ts]"]
  node_auth_routes["Google auth routes<br/>[authRoutes.ts]"]
  node_campaign_controller["Campaign endpoints"]
  node_email_controller["Email endpoints<br/>[emailController.ts]"]
end

subgraph group_campaign["Campaign management"]
  node_campaign_service["Campaign orchestration<br/>[campaignService.ts]"]
  node_email_service["Recipient scheduling<br/>[emailService.ts]"]
  node_schedule_calc["Schedule calculation<br/>[emailScheduling.ts]"]
end

subgraph group_delivery["Email delivery"]
  node_queue_service["Job scheduling"]
  node_worker["Email worker<br/>[emailWorker.ts]"]
  node_rate_limit["Hourly rate limit<br/>[rateLimit.ts]"]
  node_sender["SMTP sender<br/>[emailSender.ts]"]
end

subgraph group_infra["Persistence and integrations"]
  node_campaign_repo["Campaign repository"]
  node_email_repo["Email repository<br/>[emailRepository.ts]"]
  node_postgres[("PostgreSQL")]
  node_redis_queue["BullMQ jobs<br/>[queue.ts]"]
  node_smtp["Ethereal SMTP"]
  node_redis[("Redis<br/>[redis.ts]")]
end

node_user(("Campaign user"))

node_user -->|"creates campaign"| node_compose
node_user -->|"provides recipients"| node_recipient_upload
node_user -->|"monitors delivery"| node_dashboard
node_dashboard -->|"opens email"| node_email_detail
node_compose -->|"submits campaign"| node_frontend_api
node_recipient_upload -->|"supplies recipients"| node_compose
node_dashboard -->|"requests status"| node_frontend_api
node_email_detail -->|"requests details"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_api_app
node_api_app -->|"dispatches auth"| node_auth_routes
node_api_app -->|"dispatches campaigns"| node_campaign_controller
node_api_app -->|"dispatches email APIs"| node_email_controller
node_auth_routes -->|"stores sessions"| node_redis
node_campaign_controller -->|"calls"| node_campaign_service
node_email_controller -->|"calls"| node_email_service
node_campaign_service -->|"persists campaigns"| node_campaign_repo
node_email_service -->|"loads campaign"| node_campaign_repo
node_email_service -->|"creates and reads emails"| node_email_repo
node_email_service -->|"calculates send times"| node_schedule_calc
node_campaign_repo -->|"reads and writes"| node_postgres
node_email_repo -->|"reads and writes"| node_postgres
node_email_service -->|"enqueues emails"| node_queue_service
node_queue_service -->|"stores delayed jobs"| node_redis_queue
node_worker -->|"consumes and reschedules"| node_redis_queue
node_worker -->|"checks and updates status"| node_postgres
node_worker -->|"checks sending limit"| node_rate_limit
node_rate_limit -->|"increments counters"| node_redis
node_worker -->|"sends eligible email"| node_sender
node_sender -->|"delivers message"| node_smtp

click node_compose "https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/compose/page.tsx"
click node_recipient_upload "https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/components/compose/RecipientFileUpload.tsx"
click node_dashboard "https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/dashboard/page.tsx"
click node_email_detail "https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/dashboard/emails/%5Bid%5D/page.tsx"
click node_frontend_api "https://github.com/tsujit74/email-scheduler/blob/main/frontend/lib/api.ts"
click node_api_app "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/routes/authRoutes.ts"
click node_campaign_controller "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/controllers/campaignController.ts"
click node_email_controller "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/controllers/emailController.ts"
click node_campaign_service "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/campaignService.ts"
click node_email_service "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailService.ts"
click node_schedule_calc "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/utils/emailScheduling.ts"
click node_campaign_repo "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/repositories/campaignRepository.ts"
click node_email_repo "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/repositories/emailRepository.ts"
click node_queue_service "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailQueueService.ts"
click node_redis_queue "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/config/queue.ts"
click node_worker "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailWorker.ts"
click node_rate_limit "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/rateLimit.ts"
click node_sender "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailSender.ts"
click node_redis "https://github.com/tsujit74/email-scheduler/blob/main/backend/src/config/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_recipient_upload,node_dashboard,node_email_detail,node_frontend_api,node_user toneBlue
class node_api_app,node_auth_routes,node_campaign_controller,node_email_controller toneAmber
class node_campaign_service,node_email_service,node_schedule_calc toneMint
class node_queue_service,node_worker,node_rate_limit,node_sender toneRose
class node_campaign_repo,node_email_repo,node_postgres,node_redis_queue,node_smtp,node_redis toneIndigo
```

## Components

### User interface

- [Campaign composer](https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/compose/page.tsx): `frontend/app/compose/page.tsx`
- [Recipient upload](https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/components/compose/RecipientFileUpload.tsx): `frontend/app/components/compose/RecipientFileUpload.tsx`
- [Email dashboard](https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Email details](https://github.com/tsujit74/email-scheduler/blob/main/frontend/app/dashboard/emails/%5Bid%5D/page.tsx): `frontend/app/dashboard/emails/[id]/page.tsx`
- [API client](https://github.com/tsujit74/email-scheduler/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and identity

- [Express API](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Google auth routes](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/routes/authRoutes.ts): `backend/src/routes/authRoutes.ts`
- [Campaign endpoints](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/controllers/campaignController.ts): `backend/src/controllers/campaignController.ts`
- [Email endpoints](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/controllers/emailController.ts): `backend/src/controllers/emailController.ts`

### Campaign management

- [Campaign orchestration](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/campaignService.ts): `backend/src/services/campaignService.ts`
- [Recipient scheduling](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailService.ts): `backend/src/services/emailService.ts`
- [Schedule calculation](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/utils/emailScheduling.ts): `backend/src/utils/emailScheduling.ts`

### Email delivery

- [Job scheduling](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailQueueService.ts): `backend/src/services/emailQueueService.ts`
- [Email worker](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailWorker.ts): `backend/src/services/emailWorker.ts`
- [Hourly rate limit](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/rateLimit.ts): `backend/src/services/rateLimit.ts`
- [SMTP sender](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/services/emailSender.ts): `backend/src/services/emailSender.ts`

### Persistence and integrations

- [Campaign repository](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/repositories/campaignRepository.ts): `backend/src/repositories/campaignRepository.ts`
- [Email repository](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/repositories/emailRepository.ts): `backend/src/repositories/emailRepository.ts`
- **PostgreSQL**
- [BullMQ jobs](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/config/queue.ts): `backend/src/config/queue.ts`
- **Ethereal SMTP**
- [Redis](https://github.com/tsujit74/email-scheduler/blob/main/backend/src/config/redis.ts): `backend/src/config/redis.ts`

### Other components

- **Campaign user**

## Connections

- Campaign user → Campaign composer: creates campaign
- Campaign user → Recipient upload: provides recipients
- Campaign user → Email dashboard: monitors delivery
- Email dashboard → Email details: opens email
- Campaign composer → API client: submits campaign
- Recipient upload → Campaign composer: supplies recipients
- Email dashboard → API client: requests status
- Email details → API client: requests details
- API client → Express API: HTTP requests
- Express API → Google auth routes: dispatches auth
- Express API → Campaign endpoints: dispatches campaigns
- Express API → Email endpoints: dispatches email APIs
- Google auth routes → Redis: stores sessions
- Campaign endpoints → Campaign orchestration: calls
- Email endpoints → Recipient scheduling: calls
- Campaign orchestration → Campaign repository: persists campaigns
- Recipient scheduling → Campaign repository: loads campaign
- Recipient scheduling → Email repository: creates and reads emails
- Recipient scheduling → Schedule calculation: calculates send times
- Campaign repository → PostgreSQL: reads and writes
- Email repository → PostgreSQL: reads and writes
- Recipient scheduling → Job scheduling: enqueues emails
- Job scheduling → BullMQ jobs: stores delayed jobs
- Email worker → BullMQ jobs: consumes and reschedules
- Email worker → PostgreSQL: checks and updates status
- Email worker → Hourly rate limit: checks sending limit
- Hourly rate limit → Redis: increments counters
- Email worker → SMTP sender: sends eligible email
- SMTP sender → Ethereal SMTP: delivers message