Architecture Overview

Architecture Overview

Message Center consists of three independent services that work together to provide a complete SMS campaign management platform. Understanding the topology is essential before planning a deployment.

Service Topology

Browser / API clients
        │
        ▼
┌─────────────────────┐
│   Message Center    │  Next.js BFF (core_admin)
│   Port 3000         │  Multi-tenant admin UI + API gateway
│                     │  Owns: users, workspaces, memberships,
│                     │  campaigns shadow, sender names, audit
└─────┬───────────────┘
      │  mTLS (undici Agent)
      │  Bearer JWT (service account)
      ▼
┌─────────────────────┐
│   SMS Gateway Proxy │  Transport layer
│   Ports 8088/8089   │  mTLS termination, auth, routing
└─────┬───────────────┘
      │  mTLS
      ▼
┌─────────────────────┐
│   Core              │  Stateless SMS dispatcher
│   Port 8080/8092    │  Owns: jobs, delivery tracking,
│                     │  SMPP connections, Aerospike
└─────────────────────┘

Data stores (separate from the above):
┌─────────────────────┐
│   MongoDB           │  Message Center's own cluster
│   Port 27017        │  11 collections, 9 migrations
└─────────────────────┘
┌─────────────────────┐
│   Aerospike         │  Optional (Core-side)
│                     │  Recipient caching and dedup
└─────────────────────┘
┌─────────────────────┐
│   Grafana           │  Optional monitoring embed
│                     │  Embedded as iframe in /monitoring
└─────────────────────┘

Service Roles

Message Center (core_admin)

• What it is: A Next.js 14 application acting as both the admin UI and the BFF (Backend For Frontend).
• What it owns: All tenant data — users, workspaces, memberships, campaign shadows, sender names, audit logs.
• What it does NOT own: Job scheduling, SMPP connections, delivery reports — those belong to Core.
• How it communicates with Core: Via mTLS HTTP using a single service account JWT (never user JWTs).

Proxy

• What it is: The transport gateway between Message Center and Core.
• Role: mTLS termination, service authentication, request routing.
• Important: Message Center authenticates to Proxy with BFF_PROXY_EMAIL/BFF_PROXY_PASSWORD, obtaining a JWT that is cached in process memory.

Core

• What it is: A stateless SMS dispatch microservice.
• What it knows: Jobs (campaigns), SMPP links, delivery reports, Aerospike recipients.
• What it does NOT know: Users, workspaces, tenants, RBAC — these are BFF concerns only.

Two-Tier Authentication

Message Center operates on two completely separate authentication planes:

End-user credentials never reach Core. Core sees only the service account — it has no concept of "who created this campaign."

Network Ports

MongoDB Ownership

Message Center uses its own dedicated MongoDB cluster — it does not share a database with Core or Proxy. The database contains 11 collections managed through 9 migrations. See MongoDB & Migrations for the full schema.

Deployment Models

Next Steps

• Prerequisites — hardware and software requirements
• Installation — step-by-step installation guide
• mTLS Certificates — certificate setup