Vell Messaging & Communication Architecture

Date: 2025-12-13 Context: Control Tower Workload Account, Stock Controls

---

Executive Summary

This document defines the clear delineation between communication channels for Vell, ensuring: - Security communications (MFA, password reset) have highest deliverability - Transactional emails (confirmations, alerts) are separated from marketing - Marketing/bulk communications use HubSpot (not SES) to protect domain reputation - MFA delivery uses Cognito's built-in capabilities with SES/SNS

---

Communication Channel Matrix

Channel	Purpose	Provider	SES Config Set	Priority
Security	MFA codes, password reset, email verify	SES	vell-{env}-security	Highest
Transactional	Order confirmations, API notifications, system alerts	SES	vell-{env}-transactional	High
Bulk/System	System-wide announcements	SES	vell-{env}-bulk	Low
Marketing	Newsletters, drip campaigns, nurture	HubSpot	N/A (external)	External
Partner Nurture	Co-sell updates, partner communications	HubSpot	N/A (external)	External

---

Why Separate Channels?

1. Deliverability Protection

• Security emails (MFA codes) must arrive within seconds
• If marketing emails generate spam complaints, they could affect all email from your domain
• Separate SES Configuration Sets = separate reputation tracking

2. Monitoring & Alerting

• Security channel has tighter monitoring (bounce rate < 5%, complaint rate < 0.1%)
• Transactional channel has standard monitoring
• Bulk channel can tolerate higher bounce rates

3. Compliance

• Security communications have different retention requirements
• Audit trail needed for authentication events
• GDPR/privacy considerations differ by channel

---

MFA Delivery Architecture

Current State: TOTP Only

Your Cognito User Pool currently uses SOFTWARE_TOKEN_MFA (authenticator apps like Google Authenticator).

Recommended State: Multi-Factor Options

┌─────────────────────────────────────────────────────────────┐
│                     COGNITO USER POOL                       │
│                                                             │
│  MFA Options:                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │    TOTP     │  │    SMS      │  │   Email     │        │
│  │ (Preferred) │  │ (Backup)    │  │ (Verify)    │        │
│  │             │  │             │  │             │        │
│  │ Authy/GA/   │  │ SNS (End    │  │ SES via     │        │
│  │ MS Auth     │  │ User Msg)   │  │ Security    │        │
│  └─────────────┘  └─────────────┘  │ Config Set  │        │
│                          │          └──────┬──────┘        │
│                          │                 │               │
└──────────────────────────┼─────────────────┼───────────────┘
                           │                 │
                           ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│              AWS END USER MESSAGING (SNS)                   │
│  • SMS delivery for MFA codes                               │
│  • Spend limits configurable                                │
│  • Phone number validation required                         │
└─────────────────────────────────────────────────────────────┘

MFA Recommendation

Method	When to Use	Cost	Reliability
TOTP (Authenticator)	Default for all users	Free	Highest
SMS	Backup when TOTP unavailable	~$0.01/msg	Good (carrier dependent)
Email	Account recovery only	~$0.0001/msg	High

Best Practice: Prefer TOTP, offer SMS as backup, use email for account recovery only.

---

SES Configuration Details

Security Channel

Configuration Set: vell-{env}-security
Purpose: MFA codes, password reset, email verification
From Address: security@vell.ai
Monitoring:
  - Bounce rate alarm: > 5%
  - Complaint rate alarm: > 0.1%
  - Delivery latency tracking
Features:
  - VDM (Virtual Deliverability Manager) enabled
  - Guardian optimized delivery enabled
  - Suppression for bounces/complaints

Transactional Channel

Configuration Set: vell-{env}-transactional
Purpose: Order confirmations, system alerts, API notifications
From Address: noreply@vell.ai
Monitoring:
  - Bounce rate alarm: > 10%
  - Complaint rate alarm: > 0.5%
Features:
  - VDM enabled
  - Standard suppression

Bulk Channel

Configuration Set: vell-{env}-bulk
Purpose: System-wide announcements (use sparingly)
From Address: announcements@vell.ai
Monitoring:
  - Basic metrics only
Note: Prefer HubSpot for marketing. This is for rare system announcements.

---

Laravel Implementation

Mail Configuration

Update config/mail.php to support multiple mailers:

'mailers' => [
    // Security channel - MFA, password reset
    'ses-security' => [
        'transport' => 'ses',
        'configuration_set' => env('SES_SECURITY_CONFIG_SET'),
    ],

    // Transactional channel - confirmations, alerts
    'ses-transactional' => [
        'transport' => 'ses',
        'configuration_set' => env('SES_TRANSACTIONAL_CONFIG_SET'),
    ],

    // Bulk channel - system announcements (prefer HubSpot)
    'ses-bulk' => [
        'transport' => 'ses',
        'configuration_set' => env('SES_BULK_CONFIG_SET'),
    ],

    // Default (fallback to transactional)
    'ses' => [
        'transport' => 'ses',
        'configuration_set' => env('SES_TRANSACTIONAL_CONFIG_SET'),
    ],
],

Usage Examples

// Security email (password reset)
Mail::mailer('ses-security')
    ->to($user->email)
    ->send(new PasswordResetMail($token));

// Transactional email (order confirmation)
Mail::mailer('ses-transactional')
    ->to($customer->email)
    ->send(new OrderConfirmationMail($order));

// System announcement (rare)
Mail::mailer('ses-bulk')
    ->to($users)
    ->send(new SystemAnnouncementMail($announcement));

// Marketing (use HubSpot, not SES)
$hubspotService->sendMarketingEmail($contactId, $templateId);

---

HubSpot vs Kajabi Delineation

HubSpot (B2B Focus)

• Partner CRM and deal tracking
• Co-sell opportunity management
• Partner email nurture sequences
• Sales pipeline automation
• Custom property sync with Vell

Kajabi (B2C Focus)

• Front-end at app.vell.ai
• Course and content delivery
• Public marketing pages
• Consumer email campaigns
• Landing pages

Integration Points

┌─────────────────────────────────────────────────────────────┐
│                          VELL                               │
│                                                             │
│  ┌─────────────────┐           ┌─────────────────────┐     │
│  │ Partner/Co-Sell │           │ User/Customer       │     │
│  │ Data            │           │ Data                │     │
│  └────────┬────────┘           └──────────┬──────────┘     │
│           │                               │                 │
└───────────┼───────────────────────────────┼─────────────────┘
            │                               │
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│       HUBSPOT         │       │       KAJABI          │
│                       │       │                       │
│ • Partner contacts    │       │ • User accounts       │
│ • Deal pipeline       │       │ • Course enrollment   │
│ • Co-sell tracking    │       │ • Marketing funnels   │
│ • Partner nurture     │       │ • Public content      │
│ • AWS Marketplace     │       │                       │
│   custom properties   │       │                       │
└───────────────────────┘       └───────────────────────┘

---

Environment Variables

Add these to your .env file after deploying the CloudFormation stacks:

# =============================================================================
# MESSAGING CHANNEL CONFIGURATION
# =============================================================================

# SES Configuration Sets (deployed via vell-messaging-infrastructure.yaml)
SES_SECURITY_CONFIG_SET=vell-production-security
SES_TRANSACTIONAL_CONFIG_SET=vell-production-transactional
SES_BULK_CONFIG_SET=vell-production-bulk

# SNS Topics
SNS_SECURITY_TOPIC_ARN=arn:aws:sns:us-east-1:ACCOUNT:vell-production-security-notifications
SNS_TRANSACTIONAL_TOPIC_ARN=arn:aws:sns:us-east-1:ACCOUNT:vell-production-transactional-notifications
SNS_ALERTS_TOPIC_ARN=arn:aws:sns:us-east-1:ACCOUNT:vell-production-system-alerts

# Default mail configuration
MAIL_MAILER=ses-transactional
MAIL_FROM_ADDRESS=noreply@vell.ai
MAIL_FROM_NAME="Vell"

# Security-specific sender
MAIL_SECURITY_FROM_ADDRESS=security@vell.ai
MAIL_SECURITY_FROM_NAME="Vell Security"

# =============================================================================
# COGNITO MFA CONFIGURATION
# =============================================================================

# MFA is handled by Cognito User Pool
# TOTP is primary, SMS is optional backup
COGNITO_MFA_ENABLED=true
COGNITO_SMS_MFA_ENABLED=false  # Enable after SNS SMS sandbox exit

# =============================================================================
# OBSERVABILITY (Sentry Replacement)
# =============================================================================

# Disable Sentry
SENTRY_LARAVEL_DSN=
SENTRY_DSN=

# Enable CloudWatch
LOG_CHANNEL=cloudwatch
CLOUDWATCH_LOG_GROUP=/vell/production/application
CLOUDWATCH_ERROR_LOG_GROUP=/vell/production/errors

# Enable X-Ray
AWS_XRAY_ENABLED=true

---

Deployment Checklist

Pre-Deployment

• Verify SES domain is verified for vell.ai
• Verify SES is out of sandbox (or request production access)
• Confirm VPC and subnet IDs for Lambda functions
• Have ALB DNS name ready

Deploy CloudFormation Stacks

# 1. Deploy Messaging Infrastructure
aws cloudformation deploy \
  --template-file infrastructure/cloudformation/vell-messaging-infrastructure.yaml \
  --stack-name vell-production-messaging \
  --parameter-overrides EnvironmentName=production VellDomain=vell.ai \
  --capabilities CAPABILITY_NAMED_IAM

# 2. Deploy Observability (Sentry replacement)
aws cloudformation deploy \
  --template-file infrastructure/cloudformation/vell-observability.yaml \
  --stack-name vell-production-observability \
  --parameter-overrides EnvironmentName=production AlertEmail=ops@vell.ai \
  --capabilities CAPABILITY_NAMED_IAM

# 3. Deploy API Gateway
aws cloudformation deploy \
  --template-file infrastructure/cloudformation/vell-api-gateway.yaml \
  --stack-name vell-production-api-gateway \
  --parameter-overrides \
    EnvironmentName=production \
    VellDomain=app.vell.ai \
    VellAlbDnsName=your-alb-dns-name \
    VpcId=vpc-xxx \
    SubnetIds=subnet-xxx,subnet-yyy \
  --capabilities CAPABILITY_NAMED_IAM

# 4. Deploy Cognito (if not already deployed)
aws cloudformation deploy \
  --template-file app/CustomExtensions/CloudMarketplace/resources/cloudformation/vell-cognito-user-pool.yaml \
  --stack-name vell-production-cognito \
  --parameter-overrides EnvironmentName=production \
  --capabilities CAPABILITY_NAMED_IAM

Post-Deployment

• Update .env with stack outputs
• Run php artisan config:cache
• Install X-Ray daemon on EC2 instances
• Test security email delivery
• Test WebSocket connection
• Verify CloudWatch logs are flowing
• Subscribe to alert SNS topics

---

Cost Estimates

Service	Monthly Cost (Est.)	Notes
SES	~$0.10/1000 emails	Security + Transactional
SNS (Email notifications)	~$0.50/1M	Delivery status
SNS (SMS MFA)	~$0.01/message	If enabled
CloudWatch Logs	~$0.50/GB	With 90-day retention
X-Ray	~$5/1M traces	5% sampling in prod
API Gateway REST	~$3.50/1M requests
API Gateway WebSocket	~$1/1M messages	Pusher replacement
DynamoDB (WS connections)	~$0	On-demand, low volume

Total Estimate: ~$20-50/month (varies with usage)

---

Document Version: 1.0 Last Updated: 2025-12-13