# ruanlopes1350/hermes-api architecture

> Architecture diagram of the GitHub repository ruanlopes1350/hermes-api, 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/ruanlopes1350/hermes-api
- Repository: https://github.com/ruanlopes1350/hermes-api

## Overview

Hermes is a multi-service transactional email gateway with an administrative REST API and asynchronous delivery workers. Client apps submit emails using service-scoped API keys; the API records and queues work, and workers render and send messages through configured SMTP. Administrators manage services, credentials, users, templates, settings, and dashboard views. The README also documents SSE updates, automated key rotation with signed webhooks, Google OAuth2, and worker scaling. Some subsystem links follow README architecture because their implementation was not sampled.

Main entry points: [`src/repository`](https://github.com/ruanlopes1350/hermes-api/tree/main/src/repository) (Repositories), [`src/server.ts`](https://github.com/ruanlopes1350/hermes-api/blob/main/src/server.ts) (Express API), [`src/queue/emailWorker.ts`](https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/emailWorker.ts) (Email Worker), [`src/controller/userController.ts`](https://github.com/ruanlopes1350/hermes-api/blob/main/src/controller/userController.ts) (User Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Access"]
  node_server["Express API<br/>[server.ts]"]
  node_user_routes["User Routes<br/>[userRoutes.ts]"]
  node_email_routes["Email Routes<br/>[emailRoutes.ts]"]
  node_service_routes["Service Routes<br/>[serviceRoutes.ts]"]
  node_template_routes["Template Routes<br/>[templateRoutes.ts]"]
  node_user_controller["User Controller<br/>[userController.ts]"]
  node_email_controller["Email Controller<br/>[emailController.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_email["Email Delivery"]
  node_email_service["Email Service<br/>[emailService.ts]"]
  node_email_queue["Email Queue<br/>[emailQueue.ts]"]
  node_email_worker["Email Worker<br/>[emailWorker.ts]"]
  node_template_service["Template Service<br/>[templateService.ts]"]
  node_render["Template Rendering<br/>[renderTemplate.ts]"]
end

subgraph group_admin["Administration"]
  node_admin_services["Admin Services"]
  node_dashboard["Dashboard"]
  node_settings["Settings<br/>[settingsService.ts]"]
  node_notifications["Notifications"]
end

subgraph group_runtime["Workers and Events"]
  node_stream["Live Streams<br/>[streamService.ts]"]
  node_presence["Presence Events<br/>[presenceService.ts]"]
  node_session_stream["Session Events"]
  node_system_worker["System Worker<br/>[systemWorker.ts]"]
  node_scaler["Worker Scaler<br/>[scaler.ts]"]
end

subgraph group_state["Persistence and Integrations"]
  node_repositories["Repositories"]
  node_schema["Database Schema<br/>[schema.ts]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_client(("Client Apps"))
node_admin_user(("Admin Users"))
node_smtp["SMTP Server"]
node_webhook["Webhook Endpoint"]
node_google["Google OAuth2"]
node_docker["Docker Runtime"]

node_client -->|"submits requests"| node_server
node_admin_user -->|"uses dashboard API"| node_server
node_server -->|"mounts routes"| node_user_routes
node_server -->|"mounts routes"| node_email_routes
node_server -->|"mounts routes"| node_service_routes
node_server -->|"mounts routes"| node_template_routes
node_server -->|"delegates authentication"| node_auth
node_user_routes -->|"dispatches requests"| node_user_controller
node_email_routes -->|"dispatches requests"| node_email_controller
node_user_controller -->|"calls user operations"| node_admin_services
node_email_controller -->|"calls email operations"| node_email_service
node_service_routes -->|"dispatches service operations"| node_admin_services
node_template_routes -->|"dispatches template operations"| node_template_service
node_email_service -->|"persists email records"| node_repositories
node_email_service -->|"enqueues delivery jobs"| node_email_queue
node_email_queue -->|"stores jobs"| node_redis
node_email_worker -->|"consumes jobs"| node_email_queue
node_email_worker -->|"uses templates"| node_template_service
node_template_service -->|"renders messages"| node_render
node_email_worker -->|"sends email"| node_smtp
node_email_worker -->|"updates delivery records"| node_repositories
node_repositories -->|"reads and writes"| node_postgres
node_repositories -->|"uses table definitions"| node_schema
node_admin_services -->|"reads and writes"| node_repositories
node_dashboard -->|"reads metrics"| node_repositories
node_settings -->|"reads and writes"| node_repositories
node_notifications -->|"reads and writes"| node_repositories
node_user_controller -->|"serves email streams"| node_stream
node_user_controller -->|"serves presence events"| node_presence
node_user_controller -->|"serves session events"| node_session_stream
node_session_stream -->|"subscribes to events"| node_redis
node_system_worker -->|"schedules rotation jobs"| node_redis
node_system_worker -->|"checks and updates credentials"| node_postgres
node_system_worker -->|"sends signed rotation notice"| node_webhook
node_email_worker -.->|"uses OAuth2 sending"| node_google
node_scaler -.->|"adjusts worker replicas"| node_docker

click node_server "https://github.com/ruanlopes1350/hermes-api/blob/main/src/server.ts"
click node_user_routes "https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/userRoutes.ts"
click node_email_routes "https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/emailRoutes.ts"
click node_service_routes "https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/serviceRoutes.ts"
click node_template_routes "https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/templateRoutes.ts"
click node_user_controller "https://github.com/ruanlopes1350/hermes-api/blob/main/src/controller/userController.ts"
click node_email_controller "https://github.com/ruanlopes1350/hermes-api/blob/main/src/controller/emailController.ts"
click node_auth "https://github.com/ruanlopes1350/hermes-api/blob/main/src/utils/auth.ts"
click node_email_service "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/emailService.ts"
click node_email_queue "https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/emailQueue.ts"
click node_email_worker "https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/emailWorker.ts"
click node_template_service "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/templateService.ts"
click node_render "https://github.com/ruanlopes1350/hermes-api/blob/main/src/utils/renderTemplate.ts"
click node_admin_services "https://github.com/ruanlopes1350/hermes-api/tree/main/src/service"
click node_dashboard "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/dashboardService.ts"
click node_settings "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/settingsService.ts"
click node_notifications "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/notificationService.ts"
click node_stream "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/streamService.ts"
click node_presence "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/presenceService.ts"
click node_session_stream "https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/sessionStreamService.ts"
click node_system_worker "https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/systemWorker.ts"
click node_scaler "https://github.com/ruanlopes1350/hermes-api/blob/main/src/scaler.ts"
click node_repositories "https://github.com/ruanlopes1350/hermes-api/tree/main/src/repository"
click node_schema "https://github.com/ruanlopes1350/hermes-api/blob/main/src/config/db/schema.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_server,node_user_routes,node_email_routes,node_service_routes,node_template_routes,node_user_controller,node_email_controller,node_auth,node_client,node_admin_user toneBlue
class node_email_service,node_email_queue,node_email_worker,node_template_service,node_render toneAmber
class node_admin_services,node_dashboard,node_settings,node_notifications,node_smtp,node_webhook toneMint
class node_stream,node_presence,node_session_stream,node_system_worker,node_scaler toneRose
class node_repositories,node_schema,node_postgres,node_redis,node_google,node_docker toneIndigo
```

## Components

### API and Access

- [Express API](https://github.com/ruanlopes1350/hermes-api/blob/main/src/server.ts): `src/server.ts`
- [User Routes](https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/userRoutes.ts): `src/routes/userRoutes.ts`
- [Email Routes](https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/emailRoutes.ts): `src/routes/emailRoutes.ts`
- [Service Routes](https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/serviceRoutes.ts): `src/routes/serviceRoutes.ts`
- [Template Routes](https://github.com/ruanlopes1350/hermes-api/blob/main/src/routes/templateRoutes.ts): `src/routes/templateRoutes.ts`
- [User Controller](https://github.com/ruanlopes1350/hermes-api/blob/main/src/controller/userController.ts): `src/controller/userController.ts`
- [Email Controller](https://github.com/ruanlopes1350/hermes-api/blob/main/src/controller/emailController.ts): `src/controller/emailController.ts`
- [Authentication](https://github.com/ruanlopes1350/hermes-api/blob/main/src/utils/auth.ts): `src/utils/auth.ts`

### Email Delivery

- [Email Service](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/emailService.ts): `src/service/emailService.ts`
- [Email Queue](https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/emailQueue.ts): `src/queue/emailQueue.ts`
- [Email Worker](https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/emailWorker.ts): `src/queue/emailWorker.ts`
- [Template Service](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/templateService.ts): `src/service/templateService.ts`
- [Template Rendering](https://github.com/ruanlopes1350/hermes-api/blob/main/src/utils/renderTemplate.ts): `src/utils/renderTemplate.ts`

### Administration

- [Admin Services](https://github.com/ruanlopes1350/hermes-api/tree/main/src/service): `src/service`
- [Dashboard](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/dashboardService.ts): `src/service/dashboardService.ts`
- [Settings](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/settingsService.ts): `src/service/settingsService.ts`
- [Notifications](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/notificationService.ts): `src/service/notificationService.ts`

### Workers and Events

- [Live Streams](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/streamService.ts): `src/service/streamService.ts`
- [Presence Events](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/presenceService.ts): `src/service/presenceService.ts`
- [Session Events](https://github.com/ruanlopes1350/hermes-api/blob/main/src/service/sessionStreamService.ts): `src/service/sessionStreamService.ts`
- [System Worker](https://github.com/ruanlopes1350/hermes-api/blob/main/src/queue/systemWorker.ts): `src/queue/systemWorker.ts`
- [Worker Scaler](https://github.com/ruanlopes1350/hermes-api/blob/main/src/scaler.ts): `src/scaler.ts`

### Persistence and Integrations

- [Repositories](https://github.com/ruanlopes1350/hermes-api/tree/main/src/repository): `src/repository`
- [Database Schema](https://github.com/ruanlopes1350/hermes-api/blob/main/src/config/db/schema.ts): `src/config/db/schema.ts`
- **PostgreSQL**
- **Redis**

### Other components

- **Client Apps**
- **Admin Users**
- **SMTP Server**
- **Webhook Endpoint**
- **Google OAuth2**
- **Docker Runtime**

## Connections

- Client Apps → Express API: submits requests
- Admin Users → Express API: uses dashboard API
- Express API → User Routes: mounts routes
- Express API → Email Routes: mounts routes
- Express API → Service Routes: mounts routes
- Express API → Template Routes: mounts routes
- Express API → Authentication: delegates authentication
- User Routes → User Controller: dispatches requests
- Email Routes → Email Controller: dispatches requests
- User Controller → Admin Services: calls user operations
- Email Controller → Email Service: calls email operations
- Service Routes → Admin Services: dispatches service operations
- Template Routes → Template Service: dispatches template operations
- Email Service → Repositories: persists email records
- Email Service → Email Queue: enqueues delivery jobs
- Email Queue → Redis: stores jobs
- Email Worker → Email Queue: consumes jobs
- Email Worker → Template Service: uses templates
- Template Service → Template Rendering: renders messages
- Email Worker → SMTP Server: sends email
- Email Worker → Repositories: updates delivery records
- Repositories → PostgreSQL: reads and writes
- Repositories → Database Schema: uses table definitions
- Admin Services → Repositories: reads and writes
- Dashboard → Repositories: reads metrics
- Settings → Repositories: reads and writes
- Notifications → Repositories: reads and writes
- User Controller → Live Streams: serves email streams
- User Controller → Presence Events: serves presence events
- User Controller → Session Events: serves session events
- Session Events → Redis: subscribes to events
- System Worker → Redis: schedules rotation jobs
- System Worker → PostgreSQL: checks and updates credentials
- System Worker → Webhook Endpoint: sends signed rotation notice
- Email Worker → Google OAuth2: uses OAuth2 sending
- Worker Scaler → Docker Runtime: adjusts worker replicas