ruanlopes1350/hermes-api

How ruanlopes1350/hermes-api works

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: repository Repositories · server.ts Express API · emailWorker.ts Email Worker · userController.ts User Controller

Components 32

API and Access

Express API src/server.ts
User Routes src/routes/userRoutes.ts
Email Routes src/routes/emailRoutes.ts
Service Routes src/routes/serviceRoutes.ts
Template Routes src/routes/templateRoutes.ts
User Controller src/controller/userController.ts
Email Controller src/controller/emailController.ts
Authentication src/utils/auth.ts

Email Delivery

Email Service src/service/emailService.ts
Email Queue src/queue/emailQueue.ts
Email Worker src/queue/emailWorker.ts
Template Service src/service/templateService.ts
Template Rendering src/utils/renderTemplate.ts

Administration

Admin Services src/service
Dashboard src/service/dashboardService.ts
Settings src/service/settingsService.ts
Notifications src/service/notificationService.ts

Workers and Events

Live Streams src/service/streamService.ts
Presence Events src/service/presenceService.ts
Session Events src/service/sessionStreamService.ts
System Worker src/queue/systemWorker.ts
Worker Scaler src/scaler.ts

Persistence and Integrations

Repositories src/repository
Database Schema src/config/db/schema.ts
PostgreSQL
Redis

Other components

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

Connections 36

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

More TypeScript diagrams: transcendence42/ft_transcendence · typesense/showcase-conversational-search-pg-essays · uxname/litefront · uzhao/claude-proxy-vscode · vtex/shoreline

Drawn by GitDiagram on September 25, 2026 from the repository's file tree, README and source files. Read as Markdown ·