Home / Manual Onboarding

UnifiedBeez Backend Architecture - Visual Diagrams

Screenshot-Ready Miro Board Diagrams | Zoom & Pan Enabled

100%
Step 0: User Journey Step 1: Plan Selection Step 2: Business Info Step 3: Team Setup Step 4: AI Assistant Step 5: Channel Integration Step 6: Channel Config Step 7: Web Chat Step 8: Automation Templates
DIAGRAM 1: USER JOURNEY & DATA FLOW
How Onboarding Maps to Backend Services - STEP 0: Sign Up & Verification
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Sign Up

  • Email input
  • Password creation
  • OR OAuth (Google/Apple/Microsoft)
  • Privacy policy consent checkbox

2. Email Verification

  • 6-digit OTP sent to email
  • OTP input field
  • Expiry: 10 minutes
  • Resend option available

3. Phone Verification

  • Phone number input
  • SMS OTP via Twilio
  • 6-digit verification code
  • International format support

4. Basic Info

  • Full name input
  • Phone number confirmation
  • Profile initialization
  • Account activation

5. Password Reset (Forgot Password)

  • Click "Forgot Password" link
  • Enter email address
  • Receive reset link via email
  • Click link → New password form
  • Set new password
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

🔐 Authentication Service

API Endpoints:
• POST /auth/signup
• POST /auth/verify-email
• POST /auth/login
Features:
• OAuth handlers (Google, Apple, Microsoft)
• Password hashing (bcrypt)
• JWT token generation
• Session creation

📧 Email Service

Features:
• OTP generation (6-digit)
• Email dispatch via Sendy + AWS SES
• Template: verification-email
• Expiry: 10 minutes
Integration:
• Sendy (self-hosted) + AWS SES
• Rate limit: 10 emails/minute per user

📱 SMS Service (Twilio)

Features:
• SMS OTP via Twilio API
• Phone number verification
• International support
API Call:
POST /2010-04-01/Accounts/{AccountSid}/Messages.json
Rate Limit:
100 SMS/sec

🔑 Password Reset Service

API Endpoints:
• POST /auth/forgot-password
• POST /auth/reset-password
• POST /auth/verify-reset-token
Features:
• Generate secure reset tokens (UUID)
• Send reset link via Sendy + AWS SES
• Token expiry (1 hour)
• One-time use tokens
• Rate limiting (5 requests/hour per email)
Security:
• Token hashing (SHA-256)
• IP address logging
• Email verification before reset
• Automatic token cleanup after use
Email Template:
• Subject: "Reset Your UnifiedBeez Password"
• Reset link: {FRONTEND_URL}/reset-password?token={TOKEN}
• Expiry warning: "This link expires in 1 hour"
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Service:
• NestJS Auth Service

Configuration:
• Tasks: 2-10
• CPU: 2 vCPU
• RAM: 4GB
• Port: 3000

RDS RDS PostgreSQL

Configuration:
• Multi-AZ
• db.t4g.medium
• 100GB storage

Table:
• users

Port: 5432

ElastiCache ElastiCache Redis

Purpose:
• Session store
• OTP cache
• Rate limiting

Type:
• cache.t4g.micro
• Multi-AZ (2 nodes: Primary + Replica)

Port: 6379

Secrets Manager Secrets Manager

Stored:
• OAuth secrets
• Twilio creds
• Sendy + AWS SES credentials
• JWT secret

Encryption:
• KMS encrypted

CloudWatch CloudWatch Logs

Log Groups:
• /aws/ecs/unifiedbeez-auth-service (all auth events)
• /aws/rds/postgresql/unifiedbeez-db (query logs)

Retention: 30 days (cost optimization)
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: users
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Unique user identifier
email
VARCHAR(255)
UNIQUE, NOT NULL
User email (encrypted)
phone
VARCHAR(20)
UNIQUE, NULLABLE
User phone (encrypted)
passwordHash
VARCHAR(255)
NOT NULL
Bcrypt hashed password
emailVerified
BOOLEAN
DEFAULT false
Email verification status
phoneVerified
BOOLEAN
DEFAULT false
Phone verification status
oauthProvider
VARCHAR(50)
NULLABLE
google|apple|microsoft
createdAt
TIMESTAMP
DEFAULT NOW()
Account creation time
consentTimestamp
TIMESTAMP
NOT NULL
GDPR: Consent recorded
consentIpAddress
VARCHAR(45)
NOT NULL
GDPR: IP when consented
privacyPolicyVersion
VARCHAR(10)
NOT NULL
GDPR: Policy version

🔑 Indexes

• idx_email ON users(email)
• idx_oauth ON users(oauthProvider, oauthId)

🔐 Encryption

• email: AES-256 (at rest via RDS encryption)
• phone: AES-256 (at rest via RDS encryption)
• passwordHash: bcrypt with salt rounds = 10
TABLE: password_reset_tokens
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Token record identifier
userId
INTEGER
FK → users(id)
User requesting password reset
token
VARCHAR(255)
UNIQUE, NOT NULL
SHA-256 hashed reset token
expiresAt
TIMESTAMP
NOT NULL
1 hour from creation
used
BOOLEAN
DEFAULT false
One-time use flag
usedAt
TIMESTAMP
NULLABLE
When token was consumed
ipAddress
VARCHAR(45)
NOT NULL
Request origin (security audit)
userAgent
TEXT
NULLABLE
Browser/device info
createdAt
TIMESTAMP
DEFAULT NOW()
Token generation time

🔑 Password Reset Token Features

Security Measures:
• Tokens are hashed with SHA-256 before storage
• 1-hour expiration window
• One-time use only (marked as used after consumption)
• Rate limiting: 5 reset requests per hour per email
• IP address logging for security audits

Cleanup Strategy:
• Expired tokens deleted daily via Lambda cron job
• Used tokens deleted after 7 days
• Prevents table bloat
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ GDPR CHECKPOINT #1

Privacy Policy Consent Collected What: User must check "I agree to Privacy Policy & Terms" before signup
When: Before account creation
How: Checkbox + timestamp + IP address recorded
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Public Privacy Policy" (Line 1596-1689)
Database Storage:
→ users.consentTimestamp
→ users.consentIpAddress
→ users.privacyPolicyVersion

✅ GDPR CHECKPOINT #2

Article 7: Conditions for Consent Requirement: Consent must be freely given, specific, informed, unambiguous

Our Implementation:
• Freely Given: User can choose not to sign up
• Specific: Clear what data is collected
• Informed: Privacy policy link provided
• Unambiguous: Active checkbox, not pre-checked
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Legal Requirements" (Line 269-288)

✅ GDPR CHECKPOINT #3

Audit Log Created (10-Year Retention) What: Every signup attempt logged (success or failure)

Audit Log Entry Example: 
{
  eventType: "USER_SIGNUP",
  userId: 123,
  email: "user@example.com",
  ipAddress: "192.168.1.1",
  timestamp: "2025-10-21T10:30:00Z",
  consentGiven: true,
  privacyPolicyVersion: "v1.0"
}
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Layer 4: Audit & Monitoring" (Line 720-808)
Storage: PostgreSQL table "gdpr_audit_logs"
Retention: 10 years (regulatory requirement)

📝 NOTE: This is STEP 0 (Sign Up & Verification) only

The complete diagram continues with:

  • STEP 1: Plan Selection & Payment (Billing Service + Stripe)
  • STEP 2: Business Information (Organization Service + S3 file uploads)
  • STEP 3: Team Setup (Team Management Service)
  • STEP 4: AI Assistant Creation (AI Service + OpenAI)
  • STEP 5: Channel Integration (Channel Service + WhatsApp/Twilio/etc.)
  • STEP 6: Channel Configuration (Per-channel settings)
  • STEP 7: Web Chat Setup (Widget configuration)
  • STEP 8: Automation Templates (Automation Service)

Each step follows this exact 5-lane swim lane structure.

STEP 1: PLAN SELECTION & PAYMENT
Billing Service + Stripe Integration + Organization Setup
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Select Plan

  • Individual: £19/month
  • Business: £99/month
  • Premium: £299/month
  • Organisation: £499/month

2. Add-Ons Selection (Optional)

  • Click "Add-on available" on plan card
  • Browse add-on marketplace
  • Select add-ons with quantity
  • View add-on checkout summary
  • Add to cart or skip
Available Add-ons:
• Seats (£7/month each, up to 50)
• AI Assistant (£25/month, unlimited)
• Twilio WhatsApp Channel (£25/month, 3 per 5k msgs)
• Twilio Message Pack (£20/month, 1k msgs)
• Twilio Voice Call (£20/month, 2 numbers)
• Multi-language AI (£10/month, 5 languages)
• Priority Support (£25/month)
• White-Label Portal (£99/month, 5 portals)
• Reseller/Agency Portal (£149/month)
• CRM/Calendar Sync (£20/month)
• Ecommerce Pack (£25/month, 50/period)

3. Billing Cycle

  • Monthly billing
  • Yearly (15% discount)
  • 30-day free trial
  • View price breakdown

4. Payment

  • Enter card details
  • Billing address
  • Stripe checkout
  • Confirm purchase
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

💳 Billing Service

API Endpoints:
• POST /billing/plans
• GET /billing/plans/:id
• POST /billing/subscribe
• POST /billing/addons
Features:
• Plan configuration
• Pricing calculation
• 15% yearly discount
• 30-day trial handling
• Add-on management
Business Logic:
• Individual: 1 seat, 10k credits
• Business: 3 seats, 2 AI bots
• Premium: 30 seats, unlimited AI
• Organisation: 50 seats, all features

💰 Stripe Integration

Stripe API Calls:
• POST /v1/customers
• POST /v1/subscriptions
• POST /v1/payment_methods
• POST /v1/invoices
Webhooks Received:
• customer.subscription.created
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.payment_failed
• customer.subscription.deleted
Security:
• No PCI data stored locally
• Tokenized payment methods
• HTTPS only
• Webhook signing secret

🛒 Add-on Marketplace Service

API Endpoints:
• GET /addons - List all available add-ons
• GET /addons/:id - Get add-on details
• POST /addons/purchase - Purchase add-ons
• GET /addons/my-addons - User's active add-ons
• DELETE /addons/:id - Cancel add-on
• PATCH /addons/:id/quantity - Update quantity
Features:
• Add-on catalog management
• Plan-specific add-on availability
• Quantity validation (min/max limits)
• Real-time price calculation
• Add-on checkout summary
• Stripe subscription item creation
• Usage tracking and limits enforcement
Add-on Types:
Seats: £7/month each (max 50)
AI Assistant: £25/month (unlimited)
WhatsApp Channel: £25/month (3 per 5k msgs)
Message Pack: £20/month (1k msgs)
Voice Call: £20/month (2 numbers)
Multi-language AI: £10/month (5 languages)
Priority Support: £25/month
White-Label Portal: £99/month (5 portals)
Reseller Portal: £149/month
CRM Sync: £20/month
Ecommerce Pack: £25/month (50/period)
Business Logic:
• Validate add-on compatibility with plan
• Enforce quantity limits per add-on
• Calculate prorated charges
• Apply VAT (if applicable)
• Create Stripe subscription items
• Update organization feature flags
• Send confirmation emails

🏢 Organization Service

Features:
• Organization creation
• Plan limits enforcement
• Feature flags setup
• Seat allocation
API Endpoints:
• POST /organizations
• PATCH /organizations/:id/plan
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Service:
• Billing Service

Configuration:
• Tasks: 2-5
• CPU: 2 vCPU
• RAM: 4GB
• Port: 3000

RDS RDS PostgreSQL

Tables:
• organizations
• subscriptions
• payment_methods
• invoices

Encryption:
• At rest (KMS)
• Port: 5432

S3 S3 Bucket

Purpose:
• Invoice PDFs
• Receipt storage

Bucket:
• unifiedbeez-invoices-prod

Versioning: ON

Lambda Lambda

Function:
• Stripe webhook handler

Trigger:
• API Gateway POST
• /webhooks/stripe

Timeout: 30s

Secrets Manager Secrets Manager

Stored Secrets:
• Stripe API Key (sk_live_...)
• Stripe Webhook Signing Secret
• Encryption: KMS encrypted
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: organizations
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Organization identifier
ownerId
INTEGER
FK → users(id)
Organization owner
planTier
VARCHAR(50)
NOT NULL
individual|business|premium|organisation
billingCycle
VARCHAR(20)
NOT NULL
monthly|yearly
planStartDate
TIMESTAMP
NOT NULL
Plan activation date
trialEndsAt
TIMESTAMP
NULLABLE
30 days from signup
createdAt
TIMESTAMP
DEFAULT NOW()
Organization creation time
TABLE: subscriptions
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Subscription identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
stripeSubscriptionId
VARCHAR(255)
NOT NULL
Stripe subscription ID
stripeCustomerId
VARCHAR(255)
NOT NULL
Stripe customer ID
status
VARCHAR(50)
NOT NULL
active|trial|cancelled|past_due
currentPeriodStart
TIMESTAMP
NOT NULL
Billing period start
currentPeriodEnd
TIMESTAMP
NOT NULL
Billing period end
addOns
JSONB
NULLABLE
{seats: 5, aiAssistants: 2}
createdAt
TIMESTAMP
DEFAULT NOW()
Subscription creation time
TABLE: payment_methods
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Payment method identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
stripePaymentMethodId
VARCHAR(255)
NOT NULL
Tokenized (from Stripe)
last4
VARCHAR(4)
NOT NULL
Last 4 card digits
brand
VARCHAR(20)
NOT NULL
visa|mastercard|amex
expiryMonth
INTEGER
NOT NULL
Card expiry month
expiryYear
INTEGER
NOT NULL
Card expiry year
isDefault
BOOLEAN
DEFAULT false
Default payment method flag
TABLE: addon_definitions
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Add-on catalog identifier
name
VARCHAR(100)
NOT NULL, UNIQUE
Add-on name (e.g., "Seats")
slug
VARCHAR(100)
NOT NULL, UNIQUE
URL-friendly identifier
description
TEXT
NOT NULL
Add-on description text
category
VARCHAR(50)
NOT NULL
capacity|feature|channel|support
pricePerUnit
DECIMAL(10,2)
NOT NULL
Price in GBP (e.g., 7.00)
stripePriceId
VARCHAR(255)
NOT NULL
Stripe Price ID for billing
billingInterval
VARCHAR(20)
NOT NULL
month|year
minQuantity
INTEGER
DEFAULT 1
Minimum purchase quantity
maxQuantity
INTEGER
NULLABLE
Maximum allowed (NULL=unlimited)
usageLimit
INTEGER
NULLABLE
Per-period usage limit
usageLimitType
VARCHAR(50)
NULLABLE
messages|calls|seats|languages
availableForPlans
VARCHAR[]
NOT NULL
['business','premium','organisation']
isActive
BOOLEAN
DEFAULT true
Availability status
displayOrder
INTEGER
DEFAULT 0
Sort order in marketplace
iconUrl
VARCHAR(255)
NULLABLE
Add-on icon/image URL
createdAt
TIMESTAMP
DEFAULT NOW()
Catalog entry creation time
updatedAt
TIMESTAMP
DEFAULT NOW()
Last updated timestamp
TABLE: organization_addons
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Organization add-on record ID
organizationId
INTEGER
FK → organizations(id)
Owning organization
addonId
INTEGER
FK → addon_definitions(id)
Purchased add-on type
quantity
INTEGER
NOT NULL, DEFAULT 1
Number of units purchased
stripeSubscriptionItemId
VARCHAR(255)
NOT NULL
Stripe subscription item ID
status
VARCHAR(50)
NOT NULL
active|cancelled|paused
currentPeriodStart
TIMESTAMP
NOT NULL
Billing period start
currentPeriodEnd
TIMESTAMP
NOT NULL
Billing period end
usageCount
INTEGER
DEFAULT 0
Current period usage tracker
purchasedAt
TIMESTAMP
DEFAULT NOW()
Initial purchase timestamp
cancelledAt
TIMESTAMP
NULLABLE
Cancellation timestamp
updatedAt
TIMESTAMP
DEFAULT NOW()
Last modification time
TABLE: addon_usage_logs
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Usage log entry ID
organizationAddonId
INTEGER
FK → organization_addons(id)
Related add-on subscription
usageType
VARCHAR(50)
NOT NULL
message|call|seat|language
usageAmount
INTEGER
NOT NULL, DEFAULT 1
Units consumed
metadata
JSONB
NULLABLE
Additional usage context
timestamp
TIMESTAMP
DEFAULT NOW()
Usage occurrence time
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ No PCI Data Stored Locally

Stripe Tokenization What: Credit card details never touch our servers
How: Stripe.js tokenizes card on client-side
Stored: Only stripePaymentMethodId (token) + last4 digits
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Public Privacy Policy - Billing" (Line 1678)

✅ Billing Email Confirmation

User Receives Confirmation Content Includes:
• Plan selected
• Price breakdown
• How to cancel
• Refund policy
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Legal Requirements" (Line 269)

✅ Audit Log

Events Logged • PLAN_SELECTED
• PAYMENT_INITIATED
• PAYMENT_COMPLETED
• SUBSCRIPTION_CREATED
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "GdprAuditLog Table" (Line 729)
Retention: 10 years (regulatory requirement)
STEP 2: BUSINESS INFORMATION & KNOWLEDGE BASE
Organization Service + File Upload + Knowledge Base Processing + AI Enhancement
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Business Name & Industry

  • Enter business name
  • Select industry (E-commerce, Healthcare, etc.)
  • Business description (500 chars)
  • AI enhancement option

2. Upload Logo

  • Upload company logo
  • Max size: 5MB
  • Formats: PNG, JPG, SVG
  • Auto CDN distribution

3. Business Objectives

  • Select objectives (multi-select)
  • Sales, Support, Retention
  • Lead Generation, Customer Service
  • Custom objectives

4. Knowledge Base Upload

  • Upload PDFs, DOCX files
  • Add website URLs for scraping
  • Upload images with text (OCR)
  • Max 10MB per file
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

🏢 Organization Service

API Endpoints:
• PATCH /organizations/:id/business-info
• POST /organizations/:id/logo
• PATCH /organizations/:id/objectives
Features:
• Business profile creation
• Industry classification
• Objectives configuration
• Logo URL management

📁 File Upload Service

Features:
• S3 multipart upload
• File validation (type, size 10MB)
• Virus scanning (ClamAV)
• CloudFront CDN distribution
API Endpoints:
• POST /files/upload
• GET /files/:id
• DELETE /files/:id

📚 Knowledge Base Service

Processing Pipeline:
• PDF → text extraction
• OCR for images (AWS Textract)
• Website scraping (Puppeteer)
• Text chunking for vector DB
• Embedding generation (OpenAI)
• pgvector storage
API Endpoints:
• POST /knowledge-base/upload
• POST /knowledge-base/scrape-url
• GET /knowledge-base/status/:id

✨ AI Enhancement Service

Features:
• "Enhance with Beebot" for business description
• OpenAI API call for text improvement
• Grammar and clarity enhancement
• Professional tone optimization
API Endpoints:
• POST /ai/enhance-description
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Services:
• Knowledge Base Processing Service
• File Upload Service

Configuration:
• Tasks: 3-10
• CPU: 4 vCPU
• RAM: 8GB

S3 S3 Buckets

Buckets:
• unifiedbeez-knowledge-base/
• unifiedbeez-logos/
• unifiedbeez-documents/

Features:
• Versioning enabled
• Lifecycle policies (30 days)

CloudFront CloudFront

Purpose:
• Logo CDN distribution
• File CDN caching

Configuration:
• Origin: S3 buckets
• Cache TTL: 24 hours

Lambda Lambda

Functions:
• Document processing trigger
• S3 event handler

Trigger:
• S3 PUT events
• Timeout: 5 minutes

Textract Textract

Purpose:
• OCR for scanned documents
• Image text extraction

API:
• DetectDocumentText
• AnalyzeDocument

SQS SQS Queue

Queue:
• document-processing-queue

Purpose:
• Async document processing
• Visibility timeout: 5 min
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: organizations (Updated Columns)
Column Name
Type
Constraints
Purpose
businessName
VARCHAR(255)
NOT NULL
Company/Business name
industry
VARCHAR(100)
NOT NULL
E-commerce, Healthcare, etc.
logoUrl
TEXT
NULLABLE
S3 CDN path to logo
businessDescription
TEXT
NULLABLE
500 char description (AI enhanced)
objectives
JSONB
NULLABLE
["sales", "support", "retention"]
TABLE: knowledge_base
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Knowledge base entry identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
fileName
VARCHAR(255)
NOT NULL
Original file name
fileType
VARCHAR(50)
NOT NULL
pdf|docx|url|image
s3Key
TEXT
NOT NULL
S3 object key
fileSize
BIGINT
NOT NULL
File size in bytes
processingStatus
VARCHAR(50)
NOT NULL
pending|processing|completed|error
extractedText
TEXT
NULLABLE
Full-text searchable content
embedding
VECTOR(1536)
NULLABLE
OpenAI embeddings for RAG
uploadedAt
TIMESTAMP
DEFAULT NOW()
Upload timestamp
processedAt
TIMESTAMP
NULLABLE
Processing completion time
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ File Upload Consent

Website Scraping = Data Processing Article 6: Lawful Basis for Processing
Consent Required: User must consent to website scraping and content extraction
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 6: Lawful Basis for Processing

✅ Data Retention Policy

Knowledge Base Retention Policy: 30 days after account deletion
S3 Versioning: 30-day recovery window
Permanent Deletion: After 30 days
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data Retention" (Line 1678)

✅ Encryption at Rest

S3 SSE-KMS Encryption Method: AWS KMS managed keys
Coverage: All uploaded files
Key Rotation: Automatic annual rotation
→ CONSOLIDATED_ARCHITECTURE.md
   Decision #12: Security & IAM
   Decision #6: File Storage
STEP 3: TEAM & ROLE SETUP
Team Management Service + Role-Based Access Control + Invitation System
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Invite Team Members

  • Enter email addresses (comma-separated bulk)
  • Assign roles per member
  • Add custom message (optional)
  • Send invitations

2. Assign Roles

  • Owner (full access)
  • Admin (manage settings)
  • Support (handle messages)
  • Designer, Tech (specific permissions)

3. Track Invitations

  • View pending invitations
  • Resend invitation emails
  • Cancel pending invites
  • 24-hour expiry timer

4. Manage Team

  • Remove team members
  • Change member roles
  • View team activity
  • Manage permissions
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

👥 Team Management Service

API Endpoints:
• POST /teams/invite
• POST /teams/invite/bulk
• GET /teams/:orgId/members
• DELETE /teams/members/:id
• PATCH /teams/members/:id/role
Features:
• Team member invitation API
• Role-based access control (RBAC)
• Invitation token generation
• Bulk invite processing

📧 Email Service

Features:
• Send invitation emails (Sendy + AWS SES)
• Invitation acceptance tracking
• Reminder emails (if not accepted)
• Email templates with branding
Email Content:
• Organization name
• Inviter name and role
• Acceptance link (with token)
• Privacy policy link (GDPR)

🔐 Authorization Service

RBAC Features:
• Role permissions matrix
• Feature access control
• API endpoint permissions
• Resource-level permissions
Role Permissions:
• Owner: All permissions
• Admin: Manage settings, team
• Support: Handle messages only
• Custom roles: Granular control
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Service:
• Team Management Service

Configuration:
• Tasks: 2-5
• CPU: 2 vCPU
• RAM: 4GB

RDS RDS PostgreSQL

Tables:
• team_members
• invitations
• roles

Port: 5432

ElastiCache ElastiCache Redis

Purpose:
• Invitation token cache
• 24-hour TTL

Key Pattern:
• invite:{token}
• Port: 6379

SES Sendy + AWS SES

Purpose:
• Invitation email delivery
• Reminder emails

Rate Limit:
• 50 emails/second

Lambda Lambda

Function:
• Invitation expiry cleanup

Schedule:
• Cron: Every 24 hours
• CloudWatch Events
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: team_members
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Team member identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
userId
INTEGER
FK → users(id)
Linked user account
role
VARCHAR(50)
NOT NULL
owner|admin|support|designer|tech
permissions
JSONB
NULLABLE
Granular permissions array
invitedBy
INTEGER
FK → users(id)
Who sent the invitation
joinedAt
TIMESTAMP
DEFAULT NOW()
Team join timestamp
status
VARCHAR(50)
NOT NULL
active|removed
TABLE: invitations
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Invitation identifier
organizationId
INTEGER
FK → organizations(id)
Target organization
email
VARCHAR(255)
NOT NULL
Invitee email address
role
VARCHAR(50)
NOT NULL
Assigned role
token
VARCHAR(255)
UNIQUE, NOT NULL
Secure invitation token (UUID)
invitedBy
INTEGER
FK → users(id)
Inviter user ID
status
VARCHAR(50)
NOT NULL
pending|accepted|expired|cancelled
expiresAt
TIMESTAMP
NOT NULL
24 hours from creation
createdAt
TIMESTAMP
DEFAULT NOW()
Invitation creation time
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ Team Member Email Collection Consent

Data We Collect Email addresses of team members
Purpose: Team collaboration and access control
Legal Basis: Legitimate interest (business operations)
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data We Collect" (Line 1610)

✅ Privacy Policy in Invitation Email

Invitation Email Must Include: • Organization name
• Privacy policy link
• Right to decline invitation
• Data processing information
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Public Privacy Policy" (Line 1596)

✅ Right to Decline Invitation

GDPR Consent Principle Invitee Rights:
• Can decline invitation
• Can request email removal
• No automatic opt-in
• Clear unsubscribe option
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 7: Consent Requirements
STEP 4: AI ASSISTANT CREATION
AI Configuration Service + OpenAI Integration + Multi-AI Management
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Name Your AI

  • Enter AI assistant name
  • Default: "Beebot"
  • Custom names allowed
  • Name character limit: 50

2. Select AI Model

  • GPT-4 (recommended)
  • GPT-3.5 Turbo
  • Claude 3 (optional)
  • Custom model parameters

3. Configure Personality

  • Tone: Professional, Friendly, Casual
  • Response length preference
  • Language support
  • Custom instructions

4. Create Assistant

  • Review configuration
  • Test AI responses
  • Save and activate
  • Create multiple assistants (plan limits)
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

🤖 AI Configuration Service

API Endpoints:
• POST /ai-assistants
• GET /ai-assistants/:orgId
• PATCH /ai-assistants/:id
• DELETE /ai-assistants/:id
• POST /ai-assistants/:id/test
Features:
• AI assistant creation
• Configuration management
• Plan limit enforcement
• Multi-AI support

✨ OpenAI Integration Service

OpenAI API Calls:
• POST /v1/chat/completions
• POST /v1/embeddings
• POST /v1/assistants
• POST /v1/threads
Features:
• GPT-4 / GPT-3.5 support
• System prompts management
• Temperature & token control
• Streaming responses

📋 Prompt Engineering Service

Features:
• System prompt generation
• Knowledge base injection
• Personality customization
• Context management
Prompt Structure:
• Business context
• Knowledge base context
• Tone & personality
• Response guidelines
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Service:
• AI Configuration Service

Configuration:
• Tasks: 3-10
• CPU: 2 vCPU
• RAM: 4GB

RDS RDS PostgreSQL

Tables:
• ai_assistants
• ai_configurations
• conversation_history

Port: 5432

ElastiCache ElastiCache Redis

Purpose:
• AI config cache
• Conversation context cache

TTL:
• Config: 1 hour
• Context: 24 hours

Secrets Manager Secrets Manager

Stored:
• OpenAI API Key
• Claude API Key (optional)

Encryption:
• KMS encrypted
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: ai_assistants
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
AI assistant identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
name
VARCHAR(50)
NOT NULL
AI assistant name (e.g., "Beebot")
model
VARCHAR(50)
NOT NULL
gpt-4|gpt-3.5-turbo|claude-3
systemPrompt
TEXT
NOT NULL
AI instructions and personality
tone
VARCHAR(50)
NOT NULL
professional|friendly|casual
temperature
DECIMAL(3,2)
DEFAULT 0.7
AI creativity (0.0 - 1.0)
maxTokens
INTEGER
DEFAULT 500
Max response length
languages
JSONB
NULLABLE
["en", "es", "fr"]
isActive
BOOLEAN
DEFAULT true
Active status
createdAt
TIMESTAMP
DEFAULT NOW()
Creation timestamp
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ AI Conversation Data Processing

Article 6: Lawful Basis Data Processed:
• User messages to AI
• AI responses
• Conversation context

Legal Basis: Legitimate interest (service provision)
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 6: Lawful Basis for Processing

✅ OpenAI Data Processing Agreement

Third-Party Processor Agreement Required: DPA with OpenAI
Data Retention: 30 days (OpenAI policy)
No Training: API data not used for training
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Third-Party Processors"

✅ Conversation History Retention

Data Retention Policy Retention: 90 days (configurable)
User Rights: Right to access, delete
Auto-deletion: After retention period
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data Retention" (Line 1678)
STEP 5: CHANNEL INTEGRATION
Multi-Channel Connection Service + WhatsApp + Instagram + Facebook + Email + Telegram + LinkedIn + Shopify + PayPal + Calendly + Zoom + Stripe + SMS
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Select Channels

  • Messaging: WhatsApp, Telegram, SMS
  • Social: Instagram, Facebook, LinkedIn
  • Email: Gmail, Outlook, SMTP
  • E-commerce: Shopify, PayPal, Stripe
  • Productivity: Calendly, Zoom
  • Web: Web Chat Widget

2. Authenticate Channel

  • OAuth: Facebook, Instagram, LinkedIn, Google, Outlook, Shopify, Zoom, Calendly
  • API Keys: WhatsApp, Telegram, Stripe, PayPal
  • SMTP/IMAP: Generic Email
  • Twilio: Account SID & Auth Token
  • Grant required permissions

3. Verify Connection

  • Test webhook delivery
  • Verify message sending
  • Check permissions
  • Connection status: Active

4. Assign AI Assistant

  • Select which AI per channel
  • Multi-AI support
  • Channel-specific settings
  • Save configuration
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

📱 Channel Connection Service

API Endpoints:
• POST /channels/connect
• GET /channels/:orgId
• DELETE /channels/:id
• POST /channels/:id/verify
• PATCH /channels/:id/config
Features:
• OAuth flow management
• Webhook setup & verification
• Connection health monitoring
• Multi-channel orchestration

💬 WhatsApp Business Service

Integration:
• WhatsApp Business API
• Send/Receive messages
• Media handling (images, docs)
• Message templates (pre-approved)
Webhooks:
• POST /webhooks/whatsapp
• Message received events
• Delivery status updates
• Read receipts

📘 Facebook/Instagram Service

Integration:
• Facebook Messenger API
• Instagram Messaging API
• OAuth 2.0 authentication
• Page/Account linking
Features:
• Send/Receive DMs
• Story replies
• Comment handling
• Media attachments

📞 Twilio SMS Service

Integration:
• Twilio Programmable SMS
• Send/Receive SMS
• Phone number provisioning
• International SMS support
Webhooks:
• POST /webhooks/twilio
• Inbound message events
• Delivery callbacks
• Status updates

📧 Email Integration Service

Integrations:
• Google Workspace (Gmail) - OAuth 2.0
• Microsoft Outlook/365 - OAuth 2.0
• Generic Email - SMTP/IMAP
• Bi-directional sync (send & receive)
Features:
• Email thread management
• Auto-reply detection
• Attachment handling
• HTML email parsing
• Spam filtering integration
API Endpoints:
• POST /channels/email/google/connect
• POST /channels/email/outlook/connect
• POST /channels/email/smtp/connect
• GET /channels/email/:id/inbox
• POST /channels/email/:id/send

✈️ Telegram Bot Service

Integration:
• Telegram Bot API
• Bot token authentication
• Send/Receive messages
• Media support (photos, docs, voice)
• Inline keyboards & commands
Webhooks:
• POST /webhooks/telegram
• Message updates
• Callback query events
• File uploads
API Endpoints:
• POST /channels/telegram/connect
• POST /channels/telegram/:id/send
• GET /channels/telegram/:id/info

💼 LinkedIn Messaging Service

Integration:
• LinkedIn Messaging API
• OAuth 2.0 authentication
• Direct message handling
• Company page messaging
• Connection request management
Features:
• Send/Receive InMail
• Conversation threading
• Profile data enrichment
• Rate limiting (API quotas)
API Endpoints:
• POST /channels/linkedin/connect
• GET /channels/linkedin/:id/conversations
• POST /channels/linkedin/:id/send

🛍️ Shopify Integration Service

Integration:
• Shopify Admin API
• OAuth 2.0 authentication
• Order notifications
• Customer message handling
• Product inquiry automation
Features:
• Order status updates
• Abandoned cart notifications
• Customer support messaging
• Shipping tracking updates
• Refund/return handling
Webhooks:
• POST /webhooks/shopify
• orders/create
• orders/updated
• customers/create

💳 Stripe Integration Service

Integration:
• Stripe API
• Payment event notifications
• Customer communication channel
• Dispute management messaging
Features:
• Payment confirmation messages
• Failed payment alerts
• Subscription renewal reminders
• Invoice notifications
Webhooks:
• POST /webhooks/stripe
• payment_intent.succeeded
• payment_intent.failed
• invoice.paid

💰 PayPal Integration Service

Integration:
• PayPal REST API
• OAuth 2.0 authentication
• Payment notifications
• Dispute messaging automation
Features:
• Payment received notifications
• Refund status updates
• Chargeback alerts
• Customer payment inquiries
Webhooks:
• POST /webhooks/paypal
• PAYMENT.SALE.COMPLETED
• PAYMENT.SALE.REFUNDED
• CUSTOMER.DISPUTE.CREATED

📅 Calendly Integration Service

Integration:
• Calendly API v2
• OAuth 2.0 authentication
• Appointment booking notifications
• Calendar event messaging
Features:
• Booking confirmation messages
• Reminder notifications
• Cancellation/reschedule alerts
• Pre-meeting instructions
• Follow-up automation
Webhooks:
• POST /webhooks/calendly
• invitee.created
• invitee.canceled
• event_type.activated

🎥 Zoom Integration Service

Integration:
• Zoom API
• OAuth 2.0 authentication
• Meeting notifications
• Webinar messaging automation
Features:
• Meeting scheduled notifications
• Join link distribution
• Meeting reminders
• Recording available alerts
• Participant follow-ups
Webhooks:
• POST /webhooks/zoom
• meeting.started
• meeting.ended
• recording.completed
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Services:
• Channel Connection Service
• Messaging: WhatsApp, Telegram, SMS
• Social: Facebook, Instagram, LinkedIn
• Email: Gmail, Outlook, SMTP
• E-commerce: Shopify, Stripe, PayPal
• Productivity: Calendly, Zoom

Configuration:
• Tasks: 10-30 (auto-scaling)
• CPU: 2 vCPU
• RAM: 4GB

API Gateway API Gateway

Purpose:
• Webhook endpoints
• Rate limiting
• Request validation

Endpoints:
• /webhooks/whatsapp
• /webhooks/facebook
• /webhooks/twilio
• /webhooks/telegram
• /webhooks/linkedin
• /webhooks/shopify
• /webhooks/stripe
• /webhooks/paypal
• /webhooks/calendly
• /webhooks/zoom

RDS RDS PostgreSQL

Tables:
• channels
• channel_credentials
• messages
• webhooks_log

Port: 5432

ElastiCache ElastiCache Redis

Purpose:
• OAuth token cache
• Message queue (Redis Streams)
• Rate limit tracking

TTL: Token: 1 hour

SQS SQS Queue

Queues:
• inbound-messages-queue
• outbound-messages-queue

Purpose:
• Message processing buffer
• Async webhook handling

Secrets Manager Secrets Manager

Stored:
• WhatsApp API tokens
• Facebook/Instagram App secrets
• Twilio Auth Token
• Telegram Bot tokens
• LinkedIn OAuth secrets
• Google Workspace OAuth credentials
• Microsoft Outlook OAuth credentials
• SMTP/IMAP credentials
• Shopify App credentials
• Stripe API keys
• PayPal API credentials
• Calendly OAuth secrets
• Zoom OAuth secrets
• OAuth client secrets (all providers)
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: channels
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Channel identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
channelType
VARCHAR(50)
NOT NULL
whatsapp|facebook|instagram|sms|telegram|linkedin|email_gmail|email_outlook|email_smtp|shopify|stripe|paypal|calendly|zoom|webchat
channelName
VARCHAR(255)
NOT NULL
User-friendly name
externalId
VARCHAR(255)
NULLABLE
WhatsApp Business ID, FB Page ID, Telegram Bot ID, LinkedIn Profile ID, Shopify Store ID, etc.
aiAssistantId
INTEGER
FK → ai_assistants(id)
Assigned AI assistant
status
VARCHAR(50)
NOT NULL
active|inactive|pending|error
webhookUrl
TEXT
NULLABLE
Webhook callback URL
configuration
JSONB
NULLABLE
Channel-specific settings
connectedAt
TIMESTAMP
DEFAULT NOW()
Connection timestamp
TABLE: channel_credentials
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Credential identifier
channelId
INTEGER
FK → channels(id)
Linked channel
credentialType
VARCHAR(50)
NOT NULL
oauth_token|api_key|access_token
encryptedValue
TEXT
NOT NULL
AES-256 encrypted credential
expiresAt
TIMESTAMP
NULLABLE
OAuth token expiry
refreshToken
TEXT
NULLABLE
OAuth refresh token (encrypted)
createdAt
TIMESTAMP
DEFAULT NOW()
Credential creation time
📋 CHANNEL CONFIGURATION JSONB SCHEMAS

📧 Email Channels (Gmail, Outlook, SMTP)

{
  "provider": "gmail|outlook|smtp",
  "emailAddress": "support@company.com",
  "displayName": "Company Support",
  "signature": "HTML email signature",
  "autoReply": {
    "enabled": true,
    "template": "Thank you for contacting us...",
    "businessHoursOnly": true
  },
  "threading": {
    "enabled": true,
    "maxThreadDepth": 10
  },
  "filters": {
    "spamFiltering": true,
    "blockedDomains": ["spam.com"],
    "requiredSubjectKeywords": []
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "encryption": "tls"
  }
}

✈️ Telegram Bot

{
  "botUsername": "@companybot",
  "welcomeMessage": "Welcome! How can I help you?",
  "commands": [
    {"command": "/start", "description": "Start conversation"},
    {"command": "/help", "description": "Get help"}
  ],
  "inlineKeyboard": {
    "enabled": true,
    "buttons": [
      {"text": "Contact Support", "callback_data": "support"}
    ]
  },
  "mediaHandling": {
    "allowPhotos": true,
    "allowDocuments": true,
    "maxFileSize": 20971520
  }
}

💼 LinkedIn Messaging

{
  "profileId": "urn:li:person:xxxxx",
  "companyPageId": "urn:li:organization:xxxxx",
  "autoAcceptConnections": false,
  "welcomeMessage": "Thanks for connecting!",
  "rateLimits": {
    "maxMessagesPerDay": 100,
    "maxConnectionRequestsPerWeek": 100
  },
  "profileEnrichment": {
    "fetchJobTitle": true,
    "fetchCompany": true
  }
}

🛍️ Shopify + 💳 Stripe + 💰 PayPal

// Shopify
{
  "shopDomain": "mystore.myshopify.com",
  "notifications": {
    "orderCreated": {"enabled": true, "template": "Order confirmed"},
    "orderShipped": {"enabled": true, "includeTracking": true},
    "abandonedCart": {"enabled": true, "delayMinutes": 60}
  }
}

// Stripe
{
  "accountId": "acct_xxxxx",
  "notifications": {
    "paymentSucceeded": {"enabled": true},
    "paymentFailed": {"enabled": true, "alertTeam": true},
    "subscriptionRenewal": {"daysBeforeRenewal": 7}
  }
}

// PayPal
{
  "merchantId": "merchant_xxxxx",
  "environment": "live|sandbox",
  "notifications": {
    "paymentCompleted": {"enabled": true},
    "disputeCreated": {"alertTeam": true}
  }
}

📅 Calendly + 🎥 Zoom

// Calendly
{
  "organizationUri": "https://api.calendly.com/organizations/xxxxx",
  "notifications": {
    "bookingConfirmed": {
      "enabled": true,
      "sendReminders": true,
      "reminderMinutesBefore": [1440, 60]
    }
  }
}

// Zoom
{
  "accountId": "xxxxx",
  "notifications": {
    "meetingScheduled": {"enabled": true, "includeJoinLink": true},
    "recordingAvailable": {"enabled": true, "expiryDays": 30},
    "meetingReminder": {"minutesBefore": [60, 15]}
  },
  "meetingDefaults": {
    "autoRecording": "cloud",
    "waitingRoom": true
  }
}
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ Third-Party Data Processors

Article 28: Data Processing Agreements Processors:
• Meta (WhatsApp, Facebook, Instagram)
• Twilio (SMS)
• Telegram (Bot API)
• LinkedIn (Messaging API)
• Google (Workspace/Gmail)
• Microsoft (Outlook/365)
• Shopify (E-commerce)
• Stripe (Payments)
• PayPal (Payments)
• Calendly (Scheduling)
• Zoom (Meetings)

Requirements:
• DPA signed with each processor
• GDPR-compliant data handling
• EU data residency options where available
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 28: Processor Requirements

✅ Customer Message Data

Data Minimization Principle Data Collected:
• Customer messages (minimal)
• Sender ID / Phone number
• Message metadata

Purpose: Provide customer support service
Retention: 90 days (configurable)
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data Minimization"

✅ Encrypted Credentials Storage

Security Measure: Article 32 Encryption:
• OAuth tokens: AES-256 encrypted
• API keys: AWS Secrets Manager (KMS)
• At-rest encryption for all credentials

Access Control: IAM role-based
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 32: Security of Processing
STEP 6: PER-CHANNEL AI CONFIGURATION
AI Assistant Selection + Follow-Up Triggers + Escalation Rules + BeeBot Nudges + AI Behavior Settings + Access Permissions
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Select AI Assistant & Industry Type

  • Choose AI Assistant (SupportBot, Professional, Detailed, Receptionist)
  • Select Industry Type (Tech Support/SaaS, E-commerce, etc.)
  • Enable Smart Suggestions by BeeBot (AI recommendations)

2. Configure Escalation Rules

  • Escalate after (5) unanswered messages
  • Escalate on keyword (Fire, Emergency, Police)
  • Escalate after no reply in (10 minutes)
  • Select backup escalation contact (All team members)

3. Setup Follow-Up Triggers

  • Enable Follow-Up (toggle on/off)
  • Delay Before Follow-Up (<10 Sec)
  • Follow-Up Content Type (Sales/Support/Custom)
  • Smart Suggestions: Use recommended settings

4. AI Behavior Settings (Timing)

  • AI reply delay (5 Mins)
  • Working Days (Monday - Friday)
  • Select timezone (UTC+1:00)
  • Opening Hours (09:00 AM) & Closing Hours (06:00 PM)

5. Access Permissions

  • Select team members with channel access
  • Assign roles (Admin, Manager, Agent, Viewer)
  • Set "All Team Members" for shared access
  • Configure per-channel permissions

6. Review & Save Configuration

  • Review all AI configuration settings
  • Test AI behavior per channel
  • Apply configuration to selected channels
  • Monitor AI performance & adjust settings
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

⚙️ Channel Configuration Service

API Endpoints:
• PATCH /channels/:id/config
• POST /channels/:id/templates
• GET /channels/:id/config
• POST /channels/:id/test-config
Features:
• Business hours management
• Template storage & retrieval
• Configuration validation
• Real-time config updates

⏰ Business Hours Service

Features:
• Timezone conversion
• Holiday calendar management
• Working hours validation
• Real-time availability check
API Endpoints:
• GET /business-hours/is-available
• POST /business-hours/holidays

📝 Template Management Service

Features:
• Template CRUD operations
• Variable replacement {name}
• Multi-language support
• Template versioning
Template Types:
• Greeting templates
• After-hours templates
• FAQ templates
• Escalation templates

🔄 Follow-Up Automation Service

Features:
• Automated follow-up triggers
• Delay before follow-up (configurable)
• Follow-up content type (Sales/Support/Custom)
• Smart Suggestions by BeeBot
• Multi-step follow-up sequences
Trigger Conditions:
• Customer initiated conversation
• No response from customer (X hours)
• Conversation marked as pending
• Keyword-based triggers
• Business hours aware
API Endpoints:
• POST /channels/:id/follow-up-rules
• GET /channels/:id/follow-up-rules
• PATCH /follow-up-rules/:ruleId
• POST /follow-up-rules/:ruleId/trigger
• GET /follow-ups/pending

⚠️ Escalation Rules Service

Escalation Triggers:
• After X unanswered messages (configurable: 3, 5, 10)
• After no reply in X time (10min, 30min, 1hr, 24hr)
• Keyword detection (Fire, Emergency, Police, etc.)
• Customer sentiment analysis (angry, frustrated)
• VIP customer detection
Escalation Actions:
• Assign to specific team member
• Assign to inbox (all team members)
• Select backup escalation contact
• Send notification (email/SMS/Slack)
• Auto-tag conversation as "Escalated"
API Endpoints:
• POST /channels/:id/escalation-rules
• GET /channels/:id/escalation-rules
• PATCH /escalation-rules/:ruleId
• POST /conversations/:id/escalate
• GET /escalations/active

💡 BeeBot Nudges (Smart Suggestions)

Recommendation Engine:
• AI-powered settings recommendations
• Based on My Plan (Individual/Business/Premium/Organisation)
• Based on Business Type (Tech Support, SaaS, E-commerce)
• Industry best practices database
• A/B testing optimization suggestions
Smart Suggestions:
• Optimal AI reply delay (5sec, 10sec, 30sec)
• Recommended working days/hours
• Escalation thresholds (unanswered messages count)
• Follow-up timing (24 hours for support, 48 hours for sales)
• Tone profile recommendations (Professional, Friendly, Technical)
API Endpoints:
• GET /channels/:id/smart-suggestions
• POST /channels/:id/apply-suggestion
• GET /suggestions/templates/:industry
• POST /feedback/suggestion/:id

🔐 Access Permissions Service

Features:
• Per-channel access control
• Role-based permissions (Admin, Manager, Agent, Viewer)
• Team member assignment to channels
• "All Team Members" option for shared access
• Permission inheritance from organization roles
Permission Levels:
• Admin: Full config + conversation access
• Manager: View config + manage conversations
• Agent: Respond to conversations only
• Viewer: Read-only access
API Endpoints:
• POST /channels/:id/permissions
• GET /channels/:id/permissions
• PATCH /channels/:id/permissions/:userId
• DELETE /channels/:id/permissions/:userId
• GET /users/:id/accessible-channels
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Services:
• Channel Configuration Service
• Follow-Up Automation Service
• Escalation Rules Service
• BeeBot Nudges Service
• Access Permissions Service

Configuration:
• Tasks: 2-8 (per service)
• CPU: 1 vCPU
• RAM: 2GB

RDS RDS PostgreSQL

Tables:
• channel_configurations
• response_templates
• business_hours
• follow_up_rules
• escalation_rules
• channel_permissions

Port: 5432

ElastiCache ElastiCache Redis

Purpose:
• Config cache
• Template cache

TTL:
• 30 minutes (hot reload)
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: channel_configurations
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Configuration identifier
channelId
INTEGER
FK → channels(id)
Linked channel
businessHours
JSONB
NOT NULL
{monday: "9-17", timezone: "UTC"}
autoGreeting
BOOLEAN
DEFAULT true
Send auto greeting
greetingTemplateId
INTEGER
FK → response_templates(id)
Greeting template
afterHoursTemplateId
INTEGER
FK → response_templates(id)
After-hours template
maxResponseLength
INTEGER
DEFAULT 500
Character limit per message
escalationRules
JSONB
NULLABLE
Escalation trigger conditions
TABLE: follow_up_rules
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Follow-up rule identifier
channelId
INTEGER
FK → channels(id)
Linked channel
organizationId
INTEGER
FK → organizations(id)
Owner organization
isEnabled
BOOLEAN
DEFAULT false
Toggle follow-up on/off
delayHours
INTEGER
DEFAULT 24
Hours before follow-up (24, 48, 72)
contentType
VARCHAR(50)
NOT NULL
sales|support|custom
followUpMessage
TEXT
NOT NULL
Follow-up message template
triggerConditions
JSONB
NOT NULL
{"noCustomerReply": true, "keywords": []}
businessHoursOnly
BOOLEAN
DEFAULT true
Only send during business hours
maxFollowUps
INTEGER
DEFAULT 2
Max follow-ups per conversation
createdAt
TIMESTAMP
DEFAULT NOW()
Rule creation timestamp
TABLE: escalation_rules
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Escalation rule identifier
channelId
INTEGER
FK → channels(id)
Linked channel
organizationId
INTEGER
FK → organizations(id)
Owner organization
isEnabled
BOOLEAN
DEFAULT true
Toggle escalation on/off
unansweredMessageCount
INTEGER
DEFAULT 5
Escalate after X unanswered (3, 5, 10)
noReplyMinutes
INTEGER
DEFAULT 10
Escalate after X minutes (10, 30, 60, 1440)
keywordTriggers
TEXT[]
DEFAULT ARRAY[]::TEXT[]
["fire", "emergency", "police", "urgent"]
sentimentTrigger
BOOLEAN
DEFAULT false
Escalate on negative sentiment
assignToUserId
INTEGER
FK → users(id), NULLABLE
Specific team member to assign
assignToInbox
BOOLEAN
DEFAULT false
Assign to all team members
backupEscalationUserId
INTEGER
FK → users(id), NULLABLE
Backup contact if primary unavailable
notificationChannels
TEXT[]
DEFAULT ARRAY['email']::TEXT[]
["email", "sms", "slack"]
createdAt
TIMESTAMP
DEFAULT NOW()
Rule creation timestamp
TABLE: channel_permissions
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Permission identifier
channelId
INTEGER
FK → channels(id)
Linked channel
userId
INTEGER
FK → users(id)
Team member with access
permissionLevel
VARCHAR(20)
NOT NULL
admin|manager|agent|viewer
canViewConfig
BOOLEAN
DEFAULT false
Can view channel configuration
canEditConfig
BOOLEAN
DEFAULT false
Can edit channel configuration
canViewConversations
BOOLEAN
DEFAULT true
Can view conversations
canReply
BOOLEAN
DEFAULT true
Can reply to conversations
grantedAt
TIMESTAMP
DEFAULT NOW()
Permission grant timestamp
grantedBy
INTEGER
FK → users(id)
User who granted permission
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ Template Data Processing

User-Generated Templates Data: Message templates may contain placeholders like {customer_name}
Processing: Variables replaced with actual customer data at runtime
GDPR: Minimal personal data usage
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data Minimization"

✅ Configuration Data Storage

Settings Not Personal Data Stored: Business hours, templates, AI behavior
Classification: Non-personal business configuration
Retention: Lifetime of organization account
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "What We Collect"

✅ Customer Data in Variables

Runtime Variable Replacement Variables: {name}, {email}, {order_id}
Storage: Not stored in templates (runtime only)
Compliance: Data minimization principle
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 5: Data Processing Principles
STEP 7: WEB CHAT SETUP
Widget Configuration + Embed Code Generation + Branding + Domain Allowlist Security (XSS Protection) + Chat Customization
User Actions
Backend Services
AWS Infrastructure
Data Storage
GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

1. Customize Widget

  • Widget position (bottom-right/left)
  • Brand colors & theme
  • Welcome message text
  • Avatar/logo upload

2. Configure Behavior

  • Auto-open settings
  • Show/hide on mobile
  • Proactive messages
  • Typing indicators

3. Generate Embed Code

  • Copy JavaScript snippet
  • Installation instructions
  • Widget ID assignment (unique UUID)

4. Domain Allowlist Security 🔒

  • Add authorized domains: example.com
  • Wildcard subdomains: *.example.com
  • Test domain verification before go-live
  • Security: Blocks XSS attacks & widget hijacking
  • Monitor: View blocked unauthorized attempts

5. Install & Test

  • Paste code in website <head> or <body>
  • Test widget appearance on allowed domain
  • Verify AI responses work correctly
  • Check security: Try loading from unauthorized domain (should block)
  • Go live
↓
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

💬 Widget Configuration Service

API Endpoints:
• POST /widgets
• PATCH /widgets/:id
• GET /widgets/:id/embed-code
• POST /widgets/:id/preview
Features:
• Widget customization
• Embed code generation
• Domain validation
• Real-time preview

🌐 Widget SDK Service

Features:
• JavaScript SDK hosting
• WebSocket connections
• Real-time messaging
• Message encryption (TLS)
SDK Endpoints:
• /sdk/widget.js (CDN)
• wss://chat.unifiedbeez.com
• POST /api/v1/widget/messages

🎨 Branding Service

Features:
• Custom CSS injection
• Logo/avatar management
• Color theme validation
• Preview generation
Customizable Elements:
• Primary/secondary colors
• Font family
• Border radius
• Widget size

🔒 Domain Allowlist Security Service [CRITICAL]

XSS Protection Features:
• Domain whitelist validation (CORS)
• Referrer header verification
• Origin header validation
• Wildcard subdomain support (*.example.com)
• Real-time domain verification on widget load
• Automatic blocking of unauthorized domains
Security Workflow:
1. Widget Load Request:
  → Extract Origin/Referer header
  → Query allowlist: SELECT * FROM widget_domains WHERE widgetId = ? AND domain = ?
  → If NOT FOUND → Return 403 Forbidden + Log attempt
  → If FOUND → Serve widget.js with CORS headers

2. WebSocket Connection:
  → Validate Origin header against allowlist
  → Reject connection if domain not whitelisted

3. API Requests:
  → Verify widgetId + domain combination
  → Rate limiting per domain (1000 req/min)
Threat Prevention:
• XSS Attack: Prevents malicious sites from embedding widget
• Widget Hijacking: Blocks unauthorized domain usage
• Data Theft: Prevents conversation data leakage
• Brand Abuse: Stops widget use on competitor sites
• DDoS via Widget: Rate limits per allowed domain
API Endpoints:
• POST /widgets/:id/domains (Add domain to allowlist)
• GET /widgets/:id/domains (List allowed domains)
• DELETE /widgets/:id/domains/:domainId (Remove domain)
• POST /widgets/:id/domains/verify (Test domain access)
• GET /widgets/:id/blocked-attempts (Security logs)
⚠️ Security Implementation:
Middleware (NestJS Guard):
@UseGuards(DomainAllowlistGuard)
Applied to ALL widget SDK endpoints

Response Headers:
• Access-Control-Allow-Origin: https://example.com
• Content-Security-Policy: frame-ancestors 'self' https://example.com
• X-Frame-Options: ALLOW-FROM https://example.com

🏷️ Label Management Service

Features:
• Create custom labels per organization
• Apply multiple labels to conversations
• Filter conversations by labels
• Label auto-assignment via rules
• AI-suggested labels based on content
• Bulk label operations
• Label analytics (most used, trending)
Label Categories:
• Sales: Hot Lead, Follow-up Required, Closed Won, Closed Lost
• Support: Bug, Feature Request, Question, Escalated, Resolved
• Priority: Urgent, High Priority, Normal, Low Priority
• Status: Open, In Progress, Waiting on Customer, Completed
• Channel: WhatsApp, Email, Instagram, Facebook
• Custom: User-defined labels with colors
API Endpoints:
Label Management:
• POST /labels - Create new label
• GET /labels - List all organization labels
• GET /labels/:id - Get label details
• PATCH /labels/:id - Update label
• DELETE /labels/:id - Delete label

Label Assignment:
• POST /conversations/:id/labels - Apply label to conversation
• DELETE /conversations/:id/labels/:labelId - Remove label
• GET /conversations/:id/labels - Get conversation labels
• POST /conversations/bulk-label - Apply label to multiple conversations

Label Filtering:
• GET /conversations?labelIds=1,2,3 - Filter by labels
• GET /labels/:id/conversations - Get all conversations with label
• GET /labels/stats - Label usage statistics
Auto-Labeling Rules:
• Keyword-based: "refund" → Apply "Billing" label
• Sentiment-based: Negative sentiment → Apply "Escalated" label
• Channel-based: WhatsApp messages → Apply "WhatsApp" label
• AI-powered: OpenAI categorization → Suggest relevant labels
• Time-based: No response >24hrs → Apply "Stale" label
Bulk Operations:
• Apply label to filtered conversations
• Remove label from multiple conversations
• Replace labels (remove old, apply new)
• Export labeled conversations (CSV, Excel)
• Scheduled label cleanup (remove unused labels)
↓
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

CloudFront CloudFront

Purpose:
• Widget SDK distribution
• Global CDN delivery

File:
• /sdk/widget.js
• Cache: 24 hours

ECS ECS Fargate

Services:
• Widget API Service
• WebSocket Server

Configuration:
• Tasks: 5-50 (auto-scaling)
• CPU: 1 vCPU
• RAM: 2GB

RDS RDS PostgreSQL

Tables:
• widgets
• widget_domains [SECURITY]
• widget_blocked_attempts [AUDIT]
• conversation_labels [NEW]
• conversation_label_assignments [NEW]
• widget_sessions
• chat_messages

Port: 5432

S3 S3 Bucket

Bucket:
• unifiedbeez-widget-assets

Stored:
• Custom avatars/logos
• widget.js SDK file

ElastiCache ElastiCache Redis

Purpose:
• WebSocket session store
• Real-time message queue

TTL: Session: 24 hours
↓
🗄️ SWIM LANE 4: DATA STORAGE (PostgreSQL Schema)
TABLE: widgets
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Widget identifier
organizationId
INTEGER
FK → organizations(id)
Linked organization
widgetId
VARCHAR(255)
UNIQUE, NOT NULL
Public widget ID (UUID)
widgetName
VARCHAR(255)
NOT NULL
User-friendly name
position
VARCHAR(50)
DEFAULT 'bottom-right'
bottom-right|bottom-left
primaryColor
VARCHAR(7)
NOT NULL
Hex color (e.g., #1A4D2E)
welcomeMessage
TEXT
NOT NULL
Initial greeting text
avatarUrl
TEXT
NULLABLE
S3 CDN path to avatar
allowedDomains
JSONB
NOT NULL
["example.com", "*.example.com"]
aiAssistantId
INTEGER
FK → ai_assistants(id)
Assigned AI for webchat
isActive
BOOLEAN
DEFAULT true
Widget active status
createdAt
TIMESTAMP
DEFAULT NOW()
Creation timestamp
🔒 TABLE: widget_domains (CRITICAL SECURITY)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Domain entry identifier
widgetId
INTEGER
FK → widgets(id)
Linked widget
domain
VARCHAR(255)
NOT NULL, INDEX
example.com or *.example.com
domainType
VARCHAR(20)
NOT NULL
exact|wildcard
isActive
BOOLEAN
DEFAULT true
Enable/disable domain without deleting
addedBy
INTEGER
FK → users(id)
User who added this domain
addedAt
TIMESTAMP
DEFAULT NOW()
When domain was whitelisted
lastVerifiedAt
TIMESTAMP
NULLABLE
Last successful widget load from this domain
verificationCount
INTEGER
DEFAULT 0
Total successful loads (usage tracking)
⚠️ Security Index:
CREATE UNIQUE INDEX idx_widget_domain ON widget_domains(widgetId, domain);
Ensures fast O(1) domain lookups for every widget load request
🚨 TABLE: widget_blocked_attempts (SECURITY AUDIT LOG)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Log entry identifier
widgetId
INTEGER
FK → widgets(id)
Widget that rejected request
blockedDomain
VARCHAR(255)
NOT NULL, INDEX
Unauthorized domain that attempted access
requestType
VARCHAR(50)
NOT NULL
widget_load|websocket|api_call
ipAddress
VARCHAR(45)
NOT NULL
Source IP (IPv4 or IPv6)
userAgent
TEXT
NULLABLE
Browser/bot user agent string
refererHeader
TEXT
NULLABLE
HTTP Referer header (full URL)
blockedAt
TIMESTAMP
DEFAULT NOW(), INDEX
When attempt was blocked
⚠️ Security Monitoring:
• Alert if same domain blocked >10 times in 1 hour (potential attack)
• Alert if multiple IPs blocked for same widgetId (DDoS attempt)
• Retention: 90 days (GDPR compliant, security incident investigation)
• Dashboard: Show top 10 blocked domains per widget for security awareness
🏷️ TABLE: conversation_labels (Conversation Organization)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Label identifier
organizationId
INTEGER
FK → organizations(id)
Owning organization
name
VARCHAR(100)
NOT NULL
Label name (e.g., "Sales", "Support", "Bug")
color
VARCHAR(7)
NOT NULL
Hex color for UI (e.g., #FF5733)
description
TEXT
NULLABLE
Label purpose/description
category
VARCHAR(50)
DEFAULT 'general'
sales|support|billing|technical|general|custom
isActive
BOOLEAN
DEFAULT true
Enable/disable without deleting
displayOrder
INTEGER
DEFAULT 0
Sort order in UI
createdBy
INTEGER
FK → users(id)
User who created label
createdAt
TIMESTAMP
DEFAULT NOW()
Label creation timestamp
updatedAt
TIMESTAMP
DEFAULT NOW()
Last modification timestamp
💡 Usage Examples:
• Sales Labels: "Hot Lead", "Follow-up Required", "Closed Won", "Closed Lost"
• Support Labels: "Bug", "Feature Request", "Question", "Escalated", "Resolved"
• Priority Labels: "Urgent", "High Priority", "Normal", "Low Priority"
• Status Labels: "Open", "In Progress", "Waiting on Customer", "Completed"
• Channel Labels: "WhatsApp", "Email", "Instagram", "Facebook" (channel type tags)
🔗 TABLE: conversation_label_assignments (Junction Table)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Assignment identifier
conversationId
INTEGER
FK → conversations(id)
Conversation being labeled
labelId
INTEGER
FK → conversation_labels(id)
Applied label
assignedBy
INTEGER
FK → users(id)
User who applied label
assignedAt
TIMESTAMP
DEFAULT NOW()
When label was applied
source
VARCHAR(50)
DEFAULT 'manual'
manual|auto|ai_suggested|rule_based
🔍 Unique Constraint:
CREATE UNIQUE INDEX idx_conversation_label ON conversation_label_assignments(conversationId, labelId);
Prevents duplicate labels on same conversation

📊 Performance Index:
CREATE INDEX idx_conversation_labels_lookup ON conversation_label_assignments(conversationId);
Fast lookup of all labels for a conversation (O(log n))
↓
🛡️ SWIM LANE 5: GDPR COMPLIANCE REFERENCES

✅ Cookie Consent Banner

ePrivacy Directive Compliance Required: Widget must show cookie consent banner
Stored: Session cookies for chat functionality
User Control: Accept/Reject cookies
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Cookie Policy"

✅ Website Visitor Data

Data Minimization Collected:
• Session ID (ephemeral)
• Messages sent to widget
• No tracking beyond chat

Retention: 90 days
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Section: "Data We Collect"

✅ Embed Code Security

Domain Allowlist Protection Security:
• Only allowed domains can load widget
• CORS validation
• TLS encryption (HTTPS only)
• Prevents unauthorized usage
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Article 32: Security of Processing
STEP 8: AUTOMATION TEMPLATES
Automation Library + Template Selection + Rule Configuration + Trigger Setup
👤 User Actions
⚙️ Backend Services
☁️ AWS Infrastructure
🗄️ Data Storage
🛡️ GDPR Compliance
👤 SWIM LANE 1: USER ACTIONS

📚 Browse Templates

User explores automation library

  • View pre-built automation templates
  • Filter by category (Sales, Support, Marketing)
  • Search templates by keyword
  • Preview template workflow

✅ Select Automation

User chooses template to activate

  • Click "Use This Template"
  • Review automation description
  • Check required channels/integrations
  • View example triggers & actions

⚙️ Configure Triggers

User customizes automation conditions

  • Set trigger type (Time, Event, Keyword)
  • Define conditions (IF/THEN rules)
  • Configure action parameters
  • Assign AI assistant to execute

🚀 Activate Automation

User enables and tests automation

  • Name the automation
  • Enable/disable toggle
  • Test automation with sample data
  • Save and deploy to production
⚙️ SWIM LANE 2: BACKEND SERVICES TRIGGERED

📚 Automation Library Service

API Endpoints:
• GET /automations/templates
• GET /automations/templates/:id
• GET /automations/categories
• POST /automations/search
• GET /automations/templates/by-industry/:industry [NEW]
• GET /automations/industries [NEW]
Responsibilities:
• Serve pre-built templates
• Category management
• Template versioning
• Search & filtering
• Industry-specific filtering [NEW]
• Featured/recommended templates per industry [NEW]
Industry Categories:
• E-commerce: Abandoned cart recovery, Order confirmation, Shipping updates
• Healthcare: Appointment reminders, Test result notifications, Follow-up care
• Education: Course enrollment, Assignment reminders, Grade notifications
• Real Estate: Property inquiries, Viewing schedules, Offer notifications
• SaaS/Tech: Trial expiry, Feature announcements, Usage alerts
• Finance: Payment reminders, Account alerts, Fraud notifications
• Hospitality: Booking confirmations, Check-in reminders, Guest feedback
• General: Universal templates applicable to any industry
Dependencies:
• PostgreSQL (automation_templates, industry_categories, template_industry_mapping) [UPDATED]
• ElastiCache (template caching)
• S3 (template icons/assets)

⚙️ Automation Configuration Service

API Endpoints:
• POST /automations/create
• PATCH /automations/:id
• DELETE /automations/:id
• POST /automations/:id/test
Responsibilities:
• Create user automations
• Configure triggers & actions
• Validate rule logic
• Enable/disable automations
Validation:
• Check channel availability
• Verify AI assistant exists
• Validate trigger conditions
• Test action parameters

⚡ Rule Execution Service

API Endpoints:
• POST /rules/evaluate
• POST /rules/execute
• GET /rules/history
• GET /rules/:id/logs
Responsibilities:
• Evaluate trigger conditions
• Execute automation actions
• Log execution results
• Handle errors & retries
Integration:
• Python FastAPI Rules Engine
• NestJS Event Bridge
• SQS for async execution
• CloudWatch for monitoring

🔔 Event Trigger Service

Event Sources:
• Time-based (Cron schedules)
• Event-based (New message, Tag added)
• Keyword-based (Message contains X)
• Condition-based (Business hours, Sentiment)
Responsibilities:
• Monitor trigger conditions
• Emit events to SQS
• Rate limiting & throttling
• Duplicate prevention
Processing:
• Real-time event detection
• Batch processing (scheduled)
• Retry failed triggers
• Dead-letter queue handling

📊 Analytics & Reporting Service

API Endpoints:
• GET /automations/:id/analytics
• GET /automations/performance
• GET /automations/execution-logs
• POST /automations/reports/export
Metrics:
• Execution count (success/failure)
• Average execution time
• Trigger frequency
• Cost per automation (API calls)
Storage:
• CloudWatch Logs (execution logs)
• PostgreSQL (aggregated metrics)
• S3 (historical exports)
• ElastiCache (real-time counters)
☁️ SWIM LANE 3: AWS INFRASTRUCTURE USED

ECS ECS Fargate

Backend Services Containers

  • Automation Library Service (NestJS)
  • Configuration Service (NestJS)
  • Rule Execution Service (Python FastAPI)
  • Event Trigger Service (NestJS)
  • Auto-scaling: 2-10 tasks

RDS RDS PostgreSQL

Database Tables

  • automation_templates (pre-built library)
  • user_automations (custom configurations)
  • automation_triggers (conditions)
  • automation_actions (workflows)
  • execution_logs (history)

SQS SQS

Event Processing Queues

  • automation-trigger-queue (trigger events)
  • automation-execution-queue (actions)
  • automation-dlq (failed executions)
  • Visibility timeout: 5 minutes
  • Max retries: 3 attempts

Lambda Lambda Functions

Scheduled & Event-Driven Tasks

  • cron-trigger-checker (every 1 minute)
  • event-processor (SQS consumer)
  • rule-evaluator (condition checking)
  • automation-executor (action runner)
  • Runtime: Node.js 18.x, Python 3.11

ElastiCache ElastiCache Redis

Caching & Rate Limiting

  • automation_templates:* (library cache)
  • active_automations:org_id (quick lookup)
  • trigger_count:automation_id (rate limits)
  • execution_lock:automation_id (prevent duplicates)
  • TTL: Templates 1 hour, Locks 5 minutes

CloudWatch CloudWatch

Monitoring & Logging

  • Log Group: /aws/ecs/automation-services
  • Metrics: ExecutionCount, FailureRate, Latency
  • Alarms: FailureRate > 5%, Latency > 10s
  • EventBridge: Cron schedules, Event rules
  • Retention: 30 days

S3 S3

Template Assets & Exports

  • unifiedbeez-automation-templates/ (icons, previews)
  • unifiedbeez-automation-exports/ (analytics CSVs)
  • Lifecycle: Delete exports after 90 days
  • Encryption: SSE-S3 (AES-256)
  • CloudFront CDN for template assets

Secrets Manager Secrets Manager

External API Keys

  • automation/openai-api-key (AI execution)
  • automation/sendy-aws-ses-credentials (email actions)
  • automation/twilio-credentials (SMS actions)
  • automation/slack-webhook (notification actions)
  • Auto-rotation: Every 90 days
🗄️ SWIM LANE 4: DATA STORAGE & SCHEMAS
TABLE: automation_templates
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Template identifier
name
VARCHAR(200)
NOT NULL, UNIQUE
"Auto-assign to Sales", "After-hours Response"
category
VARCHAR(50)
NOT NULL
sales|support|marketing|operations
description
TEXT
NOT NULL
Template explanation for users
triggerType
VARCHAR(50)
NOT NULL
time|event|keyword|condition
triggerConfig
JSONB
NOT NULL
{"cron": "0 9 * * *"} or {"event": "message.received"}
actionType
VARCHAR(50)
NOT NULL
send_message|assign_tag|transfer_chat|create_ticket
actionConfig
JSONB
NOT NULL
{"message": "Thanks for contacting us!", "delay": 60}
iconUrl
VARCHAR(500)
NULLABLE
S3 URL for template icon
popularity
INTEGER
DEFAULT 0
Usage count (for sorting)
isActive
BOOLEAN
DEFAULT true
Show/hide template
createdAt
TIMESTAMP
DEFAULT NOW()
Template creation date
🏢 TABLE: industry_categories (Industry Classification)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Industry identifier
name
VARCHAR(100)
NOT NULL, UNIQUE
Industry name (e.g., "E-commerce", "Healthcare")
slug
VARCHAR(100)
NOT NULL, UNIQUE
URL-friendly identifier (e.g., "ecommerce", "healthcare")
description
TEXT
NOT NULL
Industry description for users
iconUrl
VARCHAR(500)
NULLABLE
S3 URL for industry icon
displayOrder
INTEGER
DEFAULT 0
Sort order in UI
isActive
BOOLEAN
DEFAULT true
Show/hide industry category
templateCount
INTEGER
DEFAULT 0
Number of templates in this industry (cached)
createdAt
TIMESTAMP
DEFAULT NOW()
Category creation date
updatedAt
TIMESTAMP
DEFAULT NOW()
Last modification date
📋 Sample Industries:
• E-commerce: Online retail, marketplace platforms, dropshipping
• Healthcare: Clinics, hospitals, telehealth, pharmacies
• Education: Schools, universities, online courses, tutoring
• Real Estate: Agencies, property management, rentals
• SaaS/Tech: Software companies, tech startups, IT services
• Finance: Banks, fintech, insurance, accounting
• Hospitality: Hotels, restaurants, travel agencies
• General: Applicable to any industry
🔗 TABLE: template_industry_mapping (Junction Table)
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Mapping identifier
templateId
INTEGER
FK → automation_templates(id)
Automation template
industryId
INTEGER
FK → industry_categories(id)
Industry category
isFeatured
BOOLEAN
DEFAULT false
Featured/recommended template for this industry
relevanceScore
INTEGER
DEFAULT 50
Relevance score (0-100) for sorting
createdAt
TIMESTAMP
DEFAULT NOW()
Mapping creation date
🔍 Unique Constraint:
CREATE UNIQUE INDEX idx_template_industry ON template_industry_mapping(templateId, industryId);
Prevents duplicate industry assignments to same template

📊 Performance Index:
CREATE INDEX idx_industry_templates_lookup ON template_industry_mapping(industryId, relevanceScore DESC);
Fast lookup of templates by industry with relevance sorting (O(log n))

💡 Example Usage:
• Template "Abandoned Cart Recovery" → Mapped to "E-commerce" (relevanceScore: 95, isFeatured: true)
• Template "Appointment Reminder" → Mapped to "Healthcare" (relevanceScore: 90), "Education" (relevanceScore: 70)
• Template "Welcome Message" → Mapped to "General" (relevanceScore: 80) - applies to all industries
TABLE: user_automations
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
User automation identifier
organizationId
INTEGER
FK → organizations.id
Which organization owns this
templateId
INTEGER
FK → automation_templates.id
Based on which template
name
VARCHAR(200)
NOT NULL
User-defined name
isEnabled
BOOLEAN
DEFAULT true
Active/paused toggle
triggerConfig
JSONB
NOT NULL
Customized trigger conditions
actionConfig
JSONB
NOT NULL
Customized action parameters
assignedAiAssistantId
INTEGER
FK → ai_assistants.id
Which AI executes this automation
channelFilter
JSONB
NULLABLE
["whatsapp", "webchat"] or null for all
executionCount
INTEGER
DEFAULT 0
Total times executed
lastExecutedAt
TIMESTAMP
NULLABLE
Last run timestamp
createdBy
INTEGER
FK → users.id
Team member who created it
createdAt
TIMESTAMP
DEFAULT NOW()
Creation date
updatedAt
TIMESTAMP
DEFAULT NOW()
Last modification date
TABLE: automation_execution_logs
Column Name
Type
Constraints
Purpose
id
SERIAL
PRIMARY KEY
Log entry identifier
automationId
INTEGER
FK → user_automations.id
Which automation ran
triggeredBy
VARCHAR(100)
NOT NULL
cron|event|manual
triggerData
JSONB
NULLABLE
Event payload that triggered execution
status
VARCHAR(50)
NOT NULL
success|failed|retrying
result
JSONB
NULLABLE
Action execution results
errorMessage
TEXT
NULLABLE
Error details if failed
executionTime
INTEGER
NOT NULL
Duration in milliseconds
retryCount
INTEGER
DEFAULT 0
Number of retry attempts
executedAt
TIMESTAMP
DEFAULT NOW()
When automation ran
🔍 Database Relationships
Foreign Keys:
• user_automations.templateId → automation_templates.id
• user_automations.organizationId → organizations.id
• user_automations.assignedAiAssistantId → ai_assistants.id
• user_automations.createdBy → users.id
• automation_execution_logs.automationId → user_automations.id

Indexes for Performance:
• automation_templates: (category, isActive, popularity DESC)
• user_automations: (organizationId, isEnabled)
• user_automations: (assignedAiAssistantId)
• automation_execution_logs: (automationId, executedAt DESC)
• automation_execution_logs: (status, executedAt DESC)

Data Retention:
• automation_templates: Permanent (until archived)
• user_automations: Permanent (soft delete)
• automation_execution_logs: 90 days (auto-archive to S3)
🛡️ SWIM LANE 5: GDPR COMPLIANCE

✅ Article 6: Lawful Basis

Legitimate Interest Data Collected:
• Automation configurations (trigger/action settings)
• Execution logs (performance metrics)
• Template usage statistics

Purpose: Service improvement & automation execution
Retention: Configs permanent, Logs 90 days
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 78-125: Article 6 Compliance

✅ Article 13: Right to Information

Transparency Requirements User Notifications:
• "This automation will process customer messages"
• "Execution logs stored for 90 days"
• "You can disable or delete automations anytime"
• Link to automation data policy
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 568-623: Article 13 Implementation

✅ Article 15: Right of Access

Data Export Capabilities User Can Download:
• All automation configurations (JSON export)
• Execution history (CSV export)
• Template usage analytics
• API: GET /user/data/automations
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 624-673: Article 15 Data Access

✅ Article 17: Right to Erasure

Deletion Capabilities User Can Delete:
• Individual automations (immediate deletion)
• All execution logs (cascade delete)
• Template usage history

Organization Deletion:
• All automations deleted when org deleted
• Execution logs purged from database
• S3 exports removed (lifecycle policy)
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 674-728: Article 17 Right to Erasure

✅ Article 22: Automated Decision-Making

Human Oversight Required Safeguards:
• User explicitly creates & enables automations
• Can disable/modify automations anytime
• All actions logged & reviewable
• Human can override AI decisions

No Profiling:
• Automations execute rule-based logic only
• No automated legal/financial decisions
• Transparent trigger/action configurations
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 905-976: Article 22 Automated Decisions

✅ Article 28: Data Processors

Third-Party Integrations Processors Used:
• OpenAI (AI-generated responses in actions)
• Sendy + AWS SES (email notification actions)
• Twilio (SMS notification actions)
• Slack (webhook notification actions)

DPA Status:
• All processors have signed DPAs
• GDPR-compliant data handling
• EU data residency where applicable
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 977-1014: Article 28 Processors

✅ Article 32: Security Measures

Technical & Organizational Security Encryption:
• TLS 1.3 for all API communications
• At-rest encryption (RDS, S3)
• Secrets Manager for API keys

Access Control:
• RBAC for automation management
• Audit logs for all modifications
• Rate limiting on execution endpoints

Monitoring:
• CloudWatch alarms for failures
• Execution logs for audit trails
• Dead-letter queue for failed jobs
→ COMPLETE_GDPR_COMPLIANCE_GUIDE.md
   Line 1015-1088: Article 32 Security
🛡️ Automation-Specific GDPR Considerations
Data Minimization (Article 5):
• Only log necessary execution metadata
• Don't store full message content in logs
• Aggregate metrics instead of raw data

Purpose Limitation (Article 5):
• Execution logs used ONLY for debugging & analytics
• Not shared with third parties
• Not used for profiling or marketing

Storage Limitation (Article 5):
• Execution logs auto-deleted after 90 days
• S3 lifecycle policy enforces retention
• User can request earlier deletion

User Control & Transparency:
• Clear UI showing what automation does
• Easy enable/disable toggle
• Real-time execution logs visible to user
• Export all automation data on request
↑