CRM & Marketing Platform Specification
Version: 2.0 Date: December 2024 Status: Draft
Table of Contents
- Executive Summary
- Goals & Non-Goals
- Architecture Overview
- Core Concepts
- Identity Resolution
- Activity Timeline
- Engagement Scoring
- Segmentation
- Campaign Management
- Marketing Automation
- Social Integration
- Event Promotion
- Event Integration
- API Design
- Data Model Summary
- Security & Privacy
- Performance Requirements
- Rollout Plan
1. Executive Summary
What is the CRM & Marketing Platform?
A unified customer intelligence and marketing platform that:
- Aggregates customer data from SCL (membership), TeeTime (golf), and Messaging (communications)
- Enables smart segmentation using cross-service data
- Automates marketing campaigns and customer journeys
- Publishes content to social media platforms
- Promotes events and tournaments across all channels
The Four Pillars
┌─────────────────────────────────────────────────────────────────────────────┐
│ CRM & MARKETING PLATFORM │
├─────────────────┬─────────────────┬─────────────────┬─────────────────────┤
│ CUSTOMER │ MARKETING │ CAMPAIGN │ SOCIAL │
│ INTELLIGENCE │ AUTOMATION │ MANAGER │ INTEGRATION │
├─────────────────┼─────────────────┼─────────────────┼─────────────────────┤
│ • Unified │ • Journeys │ • Segments │ • FB/IG/Twitter │
│ Profiles │ • Triggers │ • Targeting │ • Event Promotion │
│ • Timeline │ • Scheduling │ • A/B Testing │ • Content Calendar │
│ • Scoring │ • Sequences │ • Analytics │ • Engagement │
└─────────────────┴─────────────────┴─────────────────┴─────────────────────┘
Why Build It?
| Current Problem | Platform Solution |
|---|---|
| Member in SCL ≠ Player in TeeTime ≠ Contact in Messaging | Unified CustomerProfile with identity resolution |
| Staff manually cross-reference systems | Single API/UI for 360° view |
| No way to identify at-risk members | Engagement scoring + churn prediction |
| Basic segmentation on Contact data only | Smart segments using cross-service data |
| Manual campaign creation and sends | Automated journeys and triggers |
| Separate tools for social media | Integrated social publisher |
| Manual tournament promotion | Auto-promotion to all channels |
Key Design Decision: Service Boundaries
| Service | Responsibility | Owns |
|---|---|---|
| CRM/Marketing Platform | WHO, WHAT, WHEN, WHERE | Profiles, Segments, Campaigns, Automation, Social |
| Messaging Service | HOW (delivery) | Templates, Multi-channel delivery, Consent, Providers |
| SCL Service | Membership data | Members, Tiers, Payments → publishes events |
| TeeTime Service | Golf data | Players, Bookings, Tournaments → publishes events |
Consent Management: Messaging service owns consent (GDPR/POPIA compliance). CRM denormalizes opt-in flags for query convenience but does NOT manage consent.
2. Goals & Non-Goals
Goals
| # | Goal | Priority | Phase |
|---|---|---|---|
| G1 | Unified customer profile across all services | P0 | 1 |
| G2 | Identity resolution with multi-key matching | P0 | 1 |
| G3 | Activity timeline aggregation | P0 | 2 |
| G4 | Smart segmentation (cross-service data) | P0 | 3 |
| G5 | Campaign manager (create, schedule, target) | P1 | 3 |
| G6 | Customer notes and tags | P1 | 2 |
| G7 | Engagement scoring | P1 | 7 |
| G8 | Marketing automation (journeys, triggers) | P2 | 4 |
| G9 | Social integration (FB, IG, Twitter) | P2 | 5 |
| G10 | Event/tournament promotion | P2 | 5 |
| G11 | Churn risk prediction | P2 | 7 |
| G12 | A/B testing | P3 | 4 |
| G13 | Content calendar | P3 | 5 |
Non-Goals
| # | Non-Goal | Reason |
|---|---|---|
| NG1 | Replace SCL for membership management | SCL remains source of truth |
| NG2 | Replace TeeTime for bookings | TeeTime remains source of truth |
| NG3 | Send messages directly | Messaging service handles delivery |
| NG4 | Process payments | SCL Billing handles payments |
| NG5 | Manage consent | Messaging owns consent (legal compliance) |
| NG6 | Real-time sync (under 100ms) | Near real-time (seconds) is sufficient |
| NG7 | Social inbox/DM management | Future scope |
3. Architecture Overview
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL CLIENTS │
│ (Admin UI, Mobile App, Staff Portal, Club Dashboard) │
└─────────────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CRM & MARKETING PLATFORM │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ REST/ │ │ Identity │ │ Campaign │ │ Social │ │
│ │ GraphQL │ │ Resolution │ │ Orchestrator│ │ Publisher │ │
│ │ API │ │ Engine │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Activity │ │ Engagement │ │ Journey │ │ Event │ │
│ │ Timeline │ │ Scoring │ │ Engine │ │ Promoter │ │
│ │ Aggregator │ │ Engine │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ CRM Database │ │
│ │ (PostgreSQL) │ │
│ └───────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Messaging │ │ Social APIs │ │ SCL / TeeTime │
│ Service │ │ (FB, IG, X) │ │ (Events) │
│ ───────────── │ │ │ │ │
│ Delivery │ │ Publishing │ │ DomainOutbox │
│ Consent │ │ Engagement │ │ │
└───────────────┘ └───────────────┘ └───────────────┘
Technology Stack
| Component | Technology | Rationale |
|---|---|---|
| API | NestJS + GraphQL | Consistent with existing services |
| Database | PostgreSQL | Consistent with existing services |
| ORM | Prisma | Consistent with existing services |
| Event Transport | Redis + BullMQ | Already in use, sufficient for v1 |
| Cache | Redis | Fast profile lookups |
| Search | PostgreSQL FTS (v1), Elasticsearch (v2) | Start simple, scale later |
| Social APIs | Official SDKs | Facebook, Instagram, Twitter |
| Job Scheduling | BullMQ + cron | Campaign scheduling |
4. Core Concepts
CustomerProfile
The central entity representing a single customer across all systems.
interface CustomerProfile {
id: string; // CRM's own UUID
tenantId: string; // Multi-tenant isolation
// Identity Keys (at least one required)
authUserId?: string; // IDP user ID (strongest link)
email?: string; // Normalized email
phoneNumber?: string; // E.164 phone
// Cross-Service Links
sclMemberId?: number; // SCL.Member.id
teetimePlayerId?: string; // TeeTime.Player.id
messagingContactId?: string; // Messaging.Contact.id
// External IDs
externalIds: {
mcaV1ZaId?: string; // MCA v1 ZA ID
mcaV1UkId?: string; // MCA v1 UK ID
golfRsaId?: string; // GolfRSA ID
};
// Denormalized Profile
firstName?: string;
lastName?: string;
displayName?: string;
// CRM Data
status: CustomerStatus;
lifecycleStage: LifecycleStage;
tags: string[];
// Computed Scores
engagementScore?: number; // 0-100
churnRiskScore?: number; // 0-100
lifetimeValue?: number; // Cents
// Activity Metrics (denormalized)
lastActivityAt?: Date;
activityCount30d: number;
bookingCount30d: number;
// Golf Data (from TeeTime)
handicap?: number;
homeClubId?: string;
// Membership Data (from SCL)
membershipTier?: string;
membershipStatus?: string;
// Marketing Consent (synced from Messaging - READ ONLY)
emailOptIn: boolean;
smsOptIn: boolean;
pushOptIn: boolean;
whatsappOptIn: boolean;
}
Activity
A single interaction or event in the customer's timeline.
interface Activity {
id: string;
customerId: string;
type: ActivityType; // e.g., TEETIME_BOOKED, MESSAGE_SENT
category: ActivityCategory; // e.g., BOOKING, COMMUNICATION
channel?: string; // e.g., SMS, EMAIL, IN_PERSON
title: string; // Human-readable summary
description?: string;
metadata?: object;
sourceService: string; // scl, teetime, messaging
sourceId?: string; // Original record ID
occurredAt: Date;
}
Campaign
A marketing campaign targeting a segment.
interface Campaign {
id: string;
tenantId: string;
clubId?: string;
name: string;
type: CampaignType; // ONE_TIME, RECURRING, TRIGGERED, JOURNEY
status: CampaignStatus; // DRAFT, SCHEDULED, ACTIVE, PAUSED, COMPLETED
// Targeting
segmentId?: string;
// Channels
channels: Channel[]; // EMAIL, SMS, PUSH, SOCIAL
// Schedule
scheduledAt?: Date;
timezone?: string;
// Stats
sentCount: number;
openRate?: number;
clickRate?: number;
}
5. Identity Resolution
The Challenge
A single person may exist as:
- Member in SCL (joined via membership signup)
- Player in TeeTime (booked as a guest)
- Contact in Messaging (received a campaign)
We need to determine: Are these the same person?
Resolution Strategy
┌─────────────────────────────────────────────────────────────────┐
│ IDENTITY RESOLUTION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Incoming Event (e.g., member.created) │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ 1. Extract identifiers │ │
│ │ - authUserId (if present) │ │
│ │ - email (normalized) │ │
│ │ - phoneNumber (E.164) │ │
│ └───────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ 2. Match by authUserId (exact) │◄─── Strongest │
│ └───────────────────┬───────────────────┘ │
│ │ No match? │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ 3. Match by email (normalized) │◄─── Strong │
│ └───────────────────┬───────────────────┘ │
│ │ No match? │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ 4. Match by phone (E.164) │◄─── Moderate │
│ └───────────────────┬───────────────────┘ │
│ │ No match? │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ 5. Create new CustomerProfile │ │
│ └───────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Match Confidence
| Match Type | Confidence | Action |
|---|---|---|
| authUserId exact | 100% | Auto-link |
| email exact | 95% | Auto-link |
| phone exact | 85% | Auto-link |
| email + phone | 99% | Auto-link |
| name fuzzy + email domain | 60% | Flag for review |
6. Activity Timeline
Event Sources
| Source Service | Events | Category |
|---|---|---|
| SCL | member.created, member.updated, tier.changed, payment.received | MEMBERSHIP, FINANCIAL |
| TeeTime | teetime.booked, teetime.completed, handicap.updated, competition.entered | BOOKING, GOLF |
| Messaging | message.sent, message.delivered, email.opened, email.clicked | COMMUNICATION, ENGAGEMENT |
| CRM | note.added, tag.changed, profile.merged, campaign.sent | SUPPORT, MARKETING, SYSTEM |
Activity Categories
enum ActivityCategory {
MEMBERSHIP // Tier changes, signup, cancellation
BOOKING // Tee times, facility bookings
COMMUNICATION // Messages sent/received
ENGAGEMENT // Opens, clicks, responses
FINANCIAL // Payments, invoices
GOLF // Handicap, competitions, scores
MARKETING // Campaign interactions
SUPPORT // Notes, tickets
SOCIAL // Social media interactions
SYSTEM // Merges, imports, syncs
}
7. Engagement Scoring
Score Components
| Component | Weight | Data Source | Calculation |
|---|---|---|---|
| Recency | 30% | Last activity | Days since last interaction |
| Frequency | 25% | Activity count | Activities per month |
| Monetary | 20% | SCL payments | Total spend / LTV |
| Breadth | 15% | Channel usage | Unique channels engaged |
| Depth | 10% | Engagement | Open rate, click rate |
Churn Risk Factors
| Risk Factor | Weight | Indicator |
|---|---|---|
| Activity decline | 35% | 50%+ drop in activity |
| Payment issues | 25% | Failed payments, overdue |
| Engagement drop | 20% | Stopped opening emails |
| Tier downgrade | 10% | Recent tier reduction |
| Complaints | 10% | Support tickets, negative feedback |
8. Segmentation
Key Design: CRM Owns Segmentation
CRM defines segments using rich cross-service data. Messaging executes delivery.
CRM Messaging
┌─────────────────────┐ ┌─────────────────────┐
│ CustomerSegment │ │ Segment (simplified)│
│ ─────────────────── │ sync │ ─────────────────── │
│ Rules using: │ ──────────────▶│ Contact membership │
│ - SCL tier │ │ only (for delivery) │
│ - TeeTime bookings │ │ │
│ - CRM engagement │ │ │
│ - Messaging consent │ │ │
└─────────────────────┘ └─────────────────────┘
Segment Types
| Type | Description | Example |
|---|---|---|
| Static | Manual membership | "VIP List", "Board Members" |
| Dynamic | Rule-based, auto-computed | "Active members with handicap < 10" |
| Smart | ML-powered | "Likely to churn in 30 days" |
Dynamic Segment Rules
Segments can use data from ALL services:
const activeGolferSegment = {
name: "Active Golfers - Low Handicap",
rules: [
// From SCL
{ field: "membershipStatus", operator: "eq", value: "ACTIVE" },
{ field: "membershipTier", operator: "in", value: ["Gold", "Platinum"] },
// From TeeTime (denormalized)
{ field: "handicap", operator: "lt", value: 15 },
{ field: "bookingCount30d", operator: "gte", value: 2 },
// From CRM
{ field: "engagementScore", operator: "gte", value: 50 },
// From Messaging (denormalized consent)
{ field: "emailOptIn", operator: "eq", value: true }
],
combinator: "AND"
};
9. Campaign Management
Campaign Types
| Type | Description | Use Case |
|---|---|---|
| ONE_TIME | Single send | Tournament announcement |
| RECURRING | Scheduled repeats | Weekly newsletter |
| TRIGGERED | Event-based | Booking confirmation |
| JOURNEY | Multi-step sequence | Onboarding series |
Campaign Workflow
┌─────────────────────────────────────────────────────────────────┐
│ CAMPAIGN LIFECYCLE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ DRAFT ──▶ SCHEDULED ──▶ ACTIVE ──▶ COMPLETED │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ PAUSED ─────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Edit Edit/Cancel Resume/Cancel │
│ │
└─────────────────────────────────────────────────────────────────┘
Campaign Creation Flow
// 1. Create campaign
const campaign = await createCampaign({
name: "Summer Tournament 2024",
type: "ONE_TIME",
segmentId: "active-golfers-segment-id",
channels: ["EMAIL", "SMS", "FACEBOOK"],
scheduledAt: "2024-06-01T09:00:00Z",
timezone: "Africa/Johannesburg"
});
// 2. Configure channel content
await setCampaignContent(campaign.id, {
email: { templateId: "tournament-invite-email" },
sms: { templateId: "tournament-invite-sms" },
social: {
content: "Join us for the Summer Tournament 2024!",
mediaUrls: ["https://..."],
platforms: ["FACEBOOK", "INSTAGRAM"]
}
});
// 3. Schedule sends
await scheduleCampaign(campaign.id);
// → Creates jobs in BullMQ
// → Email/SMS → Messaging Service
// → Social → Social Publisher
10. Marketing Automation
Journey Builder
Multi-step automated sequences triggered by events or schedules.
┌─────────────────────────────────────────────────────────────────┐
│ NEW MEMBER ONBOARDING JOURNEY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [TRIGGER: member.created] │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ SEND Welcome │ │
│ │ Email │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ WAIT 3 days │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ YES ┌─────────────────┐ │
│ │ CONDITION: │───────────▶│ SEND Tips Email │ │
│ │ Opened welcome? │ └─────────────────┘ │
│ └────────┬────────┘ │
│ │ NO │
│ ▼ │
│ ┌─────────────────┐ │
│ │ SEND SMS │ │
│ │ Reminder │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ WAIT 7 days │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ END │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Event Triggers
| Trigger Event | Source | Possible Actions |
|---|---|---|
| member.created | SCL | Welcome sequence |
| teetime.booked | TeeTime | Booking confirmation |
| teetime.completed | TeeTime | Review request |
| handicap.updated | TeeTime | Congratulations message |
| payment.failed | SCL | Payment reminder |
| engagement.dropped | CRM | Win-back campaign |
| competition.published | TeeTime | Tournament promotion |
Journey Step Types
| Type | Description | Configuration |
|---|---|---|
| SEND | Send message | channel, templateId |
| WAIT | Delay next step | duration (e.g., "3 days") |
| CONDITION | Branch based on criteria | condition, nextStepYes, nextStepNo |
| SPLIT | A/B test | variants[], splitPercentage |
| END | Terminate journey | - |
11. Social Integration
Supported Platforms
| Platform | API | Features |
|---|---|---|
| Graph API | Pages, Posts, Events | |
| Graph API (via FB) | Business posts, Stories | |
| Twitter/X | API v2 | Tweets, Media |
| Marketing API | Company pages (future) |
Social Connection Flow
┌─────────────────────────────────────────────────────────────────┐
│ SOCIAL CONNECTION OAUTH FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Club Admin CRM Platform Facebook │
│ │ │ │ │
│ │ 1. Click "Connect FB" │ │ │
│ │─────────────────────────▶│ │ │
│ │ │ │ │
│ │ │ 2. Redirect to OAuth │ │
│ │◀─────────────────────────│───────────────────────▶│ │
│ │ │ │ │
│ │ 3. Authorize app │ │ │
│ │──────────────────────────────────────────────────▶│ │
│ │ │ │ │
│ │ 4. Callback with token │ │ │
│ │◀─────────────────────────│◀───────────────────────│ │
│ │ │ │ │
│ │ │ 5. Store encrypted │ │
│ │ │ token │ │
│ │ │─────────┐ │ │
│ │ │ │ │ │
│ │ │◀────────┘ │ │
│ │ │ │ │
│ │ 6. Connection saved │ │ │
│ │◀─────────────────────────│ │ │
│ │
└─────────────────────────────────────────────────────────────────┘
Social Post Publishing
interface SocialPost {
id: string;
tenantId: string;
connectionId: string; // Which social account
campaignId?: string; // Optional campaign link
content: string; // Post text
mediaUrls: string[]; // Images/videos
linkUrl?: string; // Link preview
status: SocialPostStatus; // DRAFT, SCHEDULED, PUBLISHED
scheduledAt?: Date;
publishedAt?: Date;
platformPostId?: string; // ID returned by platform
// Engagement metrics (synced)
likes: number;
comments: number;
shares: number;
reach: number;
}
12. Event Promotion
Auto-Promotion for Tournaments
When a competition is published in TeeTime, CRM can automatically:
- Create campaign targeting relevant segment
- Generate content from competition details
- Schedule posts across all channels
- Send reminders as event approaches
┌─────────────────────────────────────────────────────────────────┐
│ EVENT PROMOTION WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ TeeTime CRM Platform │
│ │ │ │
│ │ competition.published │ │
│ │──────────────────────────────▶│ │
│ │ │ │
│ │ │ Check auto-promote │
│ │ │ settings for club │
│ │ │─────────┐ │
│ │ │ │ │
│ │ │◀────────┘ │
│ │ │ │
│ │ │ If enabled: │
│ │ │ │
│ │ │ 1. Create campaign │
│ │ │ 2. Build segment │
│ │ │ 3. Generate content │
│ │ │ 4. Schedule: │
│ │ │ - Email blast │
│ │ │ - Social posts │
│ │ │ - SMS reminder │
│ │ │ │
└─────────────────────────────────────────────────────────────────┘
EventPromotion Configuration
interface EventPromotion {
id: string;
tenantId: string;
clubId: string;
// Source
sourceType: 'COMPETITION' | 'CLUB_EVENT';
sourceId: string; // TeeTime competition ID
// Settings
autoPromote: boolean;
channels: Channel[]; // EMAIL, SMS, FACEBOOK, INSTAGRAM
// Timing
announceAt: Date; // Initial announcement
reminderDays: number[]; // Days before: [7, 3, 1]
// Targeting
segmentId?: string; // Custom segment
targetRadius?: number; // km from club for geo
// Content
emailTemplateId?: string;
smsTemplateId?: string;
socialContent?: string;
}
13. Event Integration
Event Transport
Phase 1: Redis + BullMQ (existing infrastructure)
Events Consumed
| Source | Event | CRM Action |
|---|---|---|
| SCL | member.created | Create/link profile, activity |
| SCL | member.updated | Update profile, activity |
| SCL | tier.changed | Update tier, activity, rescore |
| SCL | payment.received | Update LTV, activity |
| TeeTime | player.created | Create/link profile, activity |
| TeeTime | teetime.booked | Activity, update frequency |
| TeeTime | teetime.completed | Activity, trigger review |
| TeeTime | competition.published | Auto-promote (if enabled) |
| TeeTime | handicap.updated | Activity, update handicap |
| Messaging | message.sent | Activity |
| Messaging | message.delivered | Activity |
| Messaging | email.opened | Activity, engagement |
| Messaging | email.clicked | Activity, engagement |
| Messaging | contactPreference.updated | Update opt-in flags |
Events Produced
| Event | Trigger | Consumers |
|---|---|---|
| crm.profile.created | New profile | Analytics |
| crm.profile.merged | Duplicate merge | Messaging (update contact) |
| crm.segment.membership.changed | Segment refresh | Messaging (sync) |
| crm.campaign.scheduled | Campaign created | Job scheduler |
| crm.campaign.sent | Campaign executed | Analytics |
| crm.churn.risk.high | Risk score > 80 | Alerting |
14. API Design
REST Endpoints Summary
# Customer Profiles
GET /api/v1/customers
GET /api/v1/customers/:id
GET /api/v1/customers/resolve
POST /api/v1/customers
PATCH /api/v1/customers/:id
POST /api/v1/customers/:id/merge
# Activity Timeline
GET /api/v1/customers/:id/activities
POST /api/v1/customers/:id/activities
# Notes
GET /api/v1/customers/:id/notes
POST /api/v1/customers/:id/notes
# Segments
GET /api/v1/segments
POST /api/v1/segments
GET /api/v1/segments/:id/members
POST /api/v1/segments/:id/refresh
POST /api/v1/segments/:id/sync-to-messaging
# Campaigns
GET /api/v1/campaigns
POST /api/v1/campaigns
GET /api/v1/campaigns/:id
PATCH /api/v1/campaigns/:id
POST /api/v1/campaigns/:id/schedule
POST /api/v1/campaigns/:id/pause
POST /api/v1/campaigns/:id/resume
# Journeys
GET /api/v1/journeys
POST /api/v1/journeys
GET /api/v1/journeys/:id/steps
POST /api/v1/journeys/:id/activate
# Social
GET /api/v1/social/connections
POST /api/v1/social/connections/connect
DELETE /api/v1/social/connections/:id
GET /api/v1/social/posts
POST /api/v1/social/posts
POST /api/v1/social/posts/:id/publish
# Event Promotion
GET /api/v1/promotions
POST /api/v1/promotions
PATCH /api/v1/promotions/:id
# Analytics
GET /api/v1/analytics/engagement
GET /api/v1/analytics/campaigns
GET /api/v1/analytics/social
15. Data Model Summary
See Data Model for complete Prisma schema.
Core Tables
| Table | Purpose |
|---|---|
| CustomerProfile | Unified customer record |
| IdentityAlias | Additional emails/phones |
| Activity | Timeline events |
| CustomerNote | Staff notes |
| CustomerSegment | Segment definitions |
| CustomerSegmentMembership | Segment membership |
Campaign Tables
| Table | Purpose |
|---|---|
| Campaign | Campaign definitions |
| CampaignInteraction | Engagement tracking |
| Journey | Multi-step automation |
| JourneyStep | Individual journey steps |
| JourneyEnrollment | Customer journey progress |
Social Tables
| Table | Purpose |
|---|---|
| SocialConnection | OAuth connections |
| SocialPost | Scheduled/published posts |
| EventPromotion | Auto-promotion config |
Sync & Audit Tables
| Table | Purpose |
|---|---|
| SyncLog | Event processing audit |
| CrmAuditLog | CRM changes audit |
| DuplicateCandidate | Potential duplicates |
16. Security & Privacy
Multi-Tenancy
- All queries filtered by
tenantId - Row-level security enforced
- No cross-tenant data leakage
Authentication & Authorization
- API authenticated via existing IDP tokens
- Role-based access:
crm:read- View profiles, timelinecrm:write- Add notes, tagscrm:campaigns- Manage campaignscrm:social- Manage social connectionscrm:admin- Merge profiles, manage segments
Social Token Security
- OAuth tokens encrypted at rest
- Refresh tokens stored separately
- Token expiry monitored and auto-refreshed
Data Privacy
- Consent flags synced from Messaging (read-only)
- GDPR right-to-erasure supported
- PII encrypted at rest
- Audit log for all data access
17. Performance Requirements
| Metric | Target |
|---|---|
| Profile lookup | under 100ms p99 |
| Timeline query | under 500ms p99 |
| Segment refresh | under 30 seconds for 10k members |
| Campaign scheduling | under 5 seconds |
| Social post publish | under 10 seconds |
| Event processing | under 5 seconds |
18. Rollout Plan
Phase 1: Foundation (MVP)
- Database schema and migrations
- Identity resolution service
- Profile CRUD API
- Basic event consumption
Phase 2: Timeline & Notes
- Activity model and API
- SCL/TeeTime/Messaging event integration
- Customer notes
Phase 3: Marketing Core
- Segment management (CRM-owned)
- Segment sync to Messaging
- Campaign manager
- Basic scheduling
Phase 4: Automation
- Journey builder
- Event triggers
- A/B testing
Phase 5: Social Integration
- Social connections (OAuth)
- Social publisher
- Event promotion
- Content calendar
Phase 6: Backfill
- MCA v1 ZA migration
- MCA v1 UK migration
- Data reconciliation
Phase 7: Intelligence
- Engagement scoring
- Churn prediction
- Analytics dashboard
Appendix A: Glossary
| Term | Definition |
|---|---|
| CustomerProfile | Unified record representing a single customer |
| Identity Resolution | Process of matching records across services |
| Activity | Single event in customer timeline |
| Campaign | Marketing communication to a segment |
| Journey | Multi-step automated sequence |
| Segment | Group of customers sharing characteristics |