Architecture

Hermes follows a microservices architecture with an API Gateway pattern.

System Overview

┌──────────────────────────────────────────┐
│           API Gateway (:5010)            │
│   api.hermes.camie.ai                    │
│   Auth · Rate Limiting · Wallet · Proxy  │
└────────┬───┬───┬───┬───┬───┬────────────┘
         │   │   │   │   │   │
    ┌────┘   │   │   │   │   └────┐
    ▼        ▼   ▼   ▼   ▼       ▼
┌──────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
│Sub-1 │ │S-2 │ │S-3 │ │S-4 │ │S-5 │ │S-6 │
│:3011 │ │5005│ │3007│ │3008│ │3005│ │3012│
│Leads │ │Enr.│ │Camp│ │Inbox│ │Infra│ │SMS │
└──────┘ └────┘ └────┘ └────┘ └────┘ └────┘
                                  │
                    ┌─────────────┤
                    ▼             ▼
              ┌──────────┐  ┌──────────┐
              │ Contabo  │  │ Namecheap│
              │   VPS    │  │ Domains  │
              └──────────┘  └──────────┘

Subsystems

Sub-1: Lead Discovery (Port 3011)

• Facebook Ads Library scraping
• Google Ads discovery
• AI-powered company & contact enrichment
• Lead list management
• Built with NestJS

Sub-2: Enrichment (Port 5005)

• Email credential storage & management
• Email validation (MX, SMTP, catch-all detection)
• Bulk CSV credential upload
• Built with Express

Sub-3: Email Campaigns (Port 3007)

• Campaign creation & scheduling
• Timezone-aware sending windows
• Automatic follow-ups
• Template variable substitution
• Built with Express + shared-auth module

Sub-4: Inbox (Port 3008)

• Unified inbox across all mailboxes
• IMAP polling for inbound messages
• Thread grouping
• Read/reply capabilities
• Built with Express

Sub-5: Infrastructure (Port 3005)

• Contabo VPS provisioning
• Domain purchase (Namecheap)
• Mail server setup (Postfix/Dovecot)
• Mailbox creation & management
• DNS record management
• Email warmup analytics (Instantly integration)
• Built with Express

Sub-6: SMS (Port 3012)

• Twilio phone number management
• SMS campaign scheduling
• Conversation threads
• Webhook handling for inbound SMS
• Built with Express

API Gateway (Port 5010)

The gateway provides:

• Dual Authentication — API keys (hermes_ prefix) and JWT tokens
• Rate Limiting — 100 req/min, 1,000 req/hr per API key
• IP Whitelisting — Optional per-key restriction
• Wallet System — Credits-based billing for infrastructure provisioning
• Request Logging — Full audit trail for API key usage
• Proxy Routing — Transparent forwarding to subsystems

Database

All subsystems share a single PostgreSQL database (project_hermes_db) with schema isolation by table naming conventions.

Background Processing

• BullMQ — Job queues for lead discovery and email sending
• node-cron — Scheduled tasks (warmup analytics sync, campaign processing)
• Redis — Queue backend and caching