CRM & Marketing Platform Specification
Version: 2.0 Date: December 2024 Status: Draft
Documents in This Section
| Document | Sections | Description |
|---|---|---|
| Core Concepts | 4-7 | CustomerProfile, Identity Resolution, Timeline, Scoring |
| Segmentation | 8 | Dynamic segments, rules, Messaging sync |
| AI Segment Builder | 8.1 | Natural language to segment criteria via LLM |
| Campaigns | 9 | Campaign types, workflow, execution |
| Marketing Automation | 10 | Journeys, triggers, step types |
| Social Integration | 11 | OAuth, publishing, platforms |
| Event Promotion | 12 | Auto-promote tournaments and events |
| Technical | 13-17 | Event integration, API design, security, performance |
| ML Scoring | 18 | ML-powered scoring, SMART segments, feature engineering |
| AI Marketing Automation | 19 | LLM content generation, send time optimization, NL segments, journey optimization, churn interventions |
| Marketing + ML + AI Flow | 20 | Unified flow showing how marketing automation, ML scoring, and AI enhancement work together |
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 |
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 |
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 |
Service Boundaries
Key Design Decision
| 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.
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