Skip to main content

🏗️ Ulmexa SaaS Architecture

Ulmexa is designed as a 3-tier SaaS platform that integrates Digital Marketing Services (Email, SMS, Hosting) with a scalable cloud backend.
This architecture ensures security, scalability, and maintainability while supporting future growth.

🔹 Overview​

Ulmexa follows the classic 3-tier architecture:

  1. Presentation Layer (Frontend) – user-facing interface (web app & dashboard).
  2. Application Layer (Backend/API) – business logic, campaign engine, queue workers.
  3. Infrastructure Layer (Data & Services) – databases, message queues, external providers (Mail, SMS, OpenStack).

🖥️ 1. Presentation Layer (Frontend)​

  • Framework: Angular + Docusaurus (for docs site).
  • Purpose:
    • Provides the user dashboard for managing campaigns, domains, VPS instances, and subscriptions.
    • Handles authentication (via Keycloak).
    • Connects to the backend via REST APIs.

✅ Key Components

  • Campaign creation & scheduling UI
  • Project & client management
  • VPS management interface
  • Subscription & billing UI
  • Documentation portal (Docusaurus)

⚙️ 2. Application Layer (Backend/API)​

  • Framework: Spring Boot (Java).
  • Pattern: Modular microservice-like structure within a monolithic backend.
  • Responsibilities:
    • Expose REST APIs for frontend
    • Implement business logic (campaign scheduling, billing, subscription management)
    • Manage integrations with providers (Mailcow, OpenStack, SMS gateways)
    • Handle queue-based email sending with retries

✅ Key Services

  • Campaign Service

    • Queues emails via RabbitMQ
    • Injects tracking pixels
    • Handles retries & DLQs

  • Mail Provider Service

    • Integrates with Mailcow API for domain/mailbox management
    • Stores SMTP credentials per user

  • VPS/Hosting Service

    • Uses OpenStack4j to manage instances, floating IPs, volumes, images
    • Maps subscription to allocated resources

  • Subscription & Billing Service

    • Validates active plans
    • Suspends overdue VPSs after grace period
    • Issues invoices

  • Authentication & Authorization

    • Delegated to Keycloak IAM
    • Supports per-user projects and team members

🗄️ 3. Infrastructure Layer (Data & Services)​

This tier provides persistence, message queues, and external services.

✅ Components

  • Database: PostgreSQL

    • Stores users, projects, campaigns, subscriptions, VPS metadata

  • Message Broker: RabbitMQ

    • Queues email send jobs
    • Implements retry + dead-letter queues
    • Supports scheduled sends with TTL

  • Mail Server: Mailcow

    • Provides domain & mailbox management
    • Sends campaigns via per-mailbox SMTP

  • Cloud Infrastructure: OpenStack

    • Manages VPS lifecycle (create, suspend, resume, delete)
    • Isolates resources per customer project
    • Integrated with Keycloak for identity mapping

  • Authentication: Keycloak

    • Central IAM for users and admins
    • Maps OpenStack projects to SaaS users

  • Storage: Object storage (OpenStack Swift / S3-compatible)

    • Stores campaign assets, images, attachments

🔄 Data Flow Example​

  1. A user logs in via Keycloak.
  2. User creates a campaign → backend validates subscription.
  3. Backend pushes emails into RabbitMQ queues.
  4. Workers consume queue messages → send via Mailcow SMTP.
  5. Tracking pixel logs events back to backend.
  6. If emails fail → retries via RabbitMQ DLQ.
  7. Reports/analytics are stored in PostgreSQL.

📐 Architecture Diagram​

Ulmexa Architecture