CRM & Marketing Platform Implementation Guide

Version: 2.0 Date: December 2024

---

Documents in This Section

Document	Description
Phase 1: Foundation	Database, Identity Resolution, Basic API
Phase 2: Events	BullMQ consumers, service sync
Phase 3: Timeline	Activity timeline, customer notes
Phase 4: Marketing Core	Campaigns, segments, scheduling
Phase 5: Automation	Journey builder, event triggers
Phase 6: Social	OAuth, publisher, event promotion
Phase 7: Backfill	MCA v1 migration
Phase 8: Intelligence	Engagement scoring, churn prediction
Testing	Unit, integration, load tests
Deployment	Kubernetes, secrets

---

Overview

This guide provides step-by-step instructions for implementing the CRM & Marketing Platform. Follow the phases in order, as each builds on the previous.

---

Phase Summary

Phase	Description	Key Deliverables
1	Foundation	Database, Identity Resolution, Basic API
2	Event Integration	BullMQ consumers, SCL/TeeTime/Messaging sync
3	Timeline & Notes	Activity timeline, Customer notes
4	Marketing Core	Campaigns, Segments (CRM-owned), Scheduling
5	Marketing Automation	Journey builder, Event triggers, A/B testing
6	Social Integration	OAuth connections, Publisher, Event promotion
7	Backfill	MCA v1 ZA/UK migration
8	Intelligence	Engagement scoring, Churn prediction

---

Prerequisites

Infrastructure

• PostgreSQL database provisioned (CRM database)
• Redis available for event transport and caching
• Kubernetes namespace/deployment slots
• Infisical secrets configured

Codebase Setup

# Create library structure
mkdir -p libs/prisma/crm-client
mkdir -p libs/crm/core
mkdir -p libs/crm/events
mkdir -p libs/crm/campaigns
mkdir -p libs/crm/automation
mkdir -p libs/crm/social
mkdir -p apps/crm/crm-backend

Dependencies

{
  "dependencies": {
    "@prisma/client": "^6.x",
    "@nestjs/common": "^10.x",
    "@nestjs/bullmq": "^10.x",
    "@nestjs/schedule": "^4.x",
    "bullmq": "^5.x",
    "cron-parser": "^4.x"
  }
}

---

Project Structure

libs/
├── prisma/
│   └── crm-client/          # Prisma schema and client
│       ├── prisma/
│       │   └── schema.prisma
│       └── src/
│           └── index.ts
├── crm/
│   ├── core/                # Core services
│   │   └── src/
│   │       ├── services/
│   │       │   ├── customer-profile.service.ts
│   │       │   ├── identity-resolution.service.ts
│   │       │   └── profile-merge.service.ts
│   │       ├── repositories/
│   │       └── dto/
│   ├── events/              # Event processing
│   │   └── src/
│   │       ├── processors/
│   │       └── handlers/
│   ├── campaigns/           # Campaign management
│   │   └── src/
│   │       ├── services/
│   │       └── jobs/
│   ├── automation/          # Marketing automation
│   │   └── src/
│   │       ├── services/
│   │       └── engine/
│   └── social/              # Social integration
│       └── src/
│           ├── services/
│           └── platforms/

apps/
└── crm/
    └── crm-backend/         # NestJS application
        └── src/
            ├── app/
            │   ├── customer/
            │   ├── segment/
            │   ├── campaign/
            │   ├── journey/
            │   └── social/
            └── main.ts

---

Nx Configuration

Library Generation

# Prisma client
npx nx g @nx/node:library prisma-crm-client --directory=libs/prisma/crm-client

# Core libraries
npx nx g @nx/node:library crm-core --directory=libs/crm/core
npx nx g @nx/node:library crm-events --directory=libs/crm/events
npx nx g @nx/node:library crm-campaigns --directory=libs/crm/campaigns
npx nx g @nx/node:library crm-automation --directory=libs/crm/automation
npx nx g @nx/node:library crm-social --directory=libs/crm/social

# Backend application
npx nx g @nx/node:application crm-backend --directory=apps/crm/crm-backend

Prisma Setup

cd libs/prisma/crm-client
pnpm prisma init

---

Environment Variables

Required Secrets (Infisical)

# Database
CRM_DATABASE_URL=postgresql://user:pass@host:5432/crm

# Redis
REDIS_URL=redis://localhost:6379

# JWT (existing auth)
JWT_SECRET=your-secret

# Social APIs (Phase 6)
FACEBOOK_APP_ID=...
FACEBOOK_APP_SECRET=...
INSTAGRAM_APP_ID=...
INSTAGRAM_APP_SECRET=...
TWITTER_CLIENT_ID=...
TWITTER_CLIENT_SECRET=...

# Encryption key for social tokens
ENCRYPTION_KEY=...

---

Development Workflow

Local Development

# Start database
docker-compose up -d postgres redis

# Run migrations
cd libs/prisma/crm-client
pnpm prisma migrate dev

# Generate client
pnpm prisma generate

# Start backend
npx nx serve crm-backend

Cluster Migration Baseline (CRM Schema)

Use Infisical + a K8s port-forward to mark the baseline migration as applied in the shared scl_db crm schema.

# Port-forward the SCL database
kubectl -n scl port-forward svc/scl-database 55432:5432

# In a separate shell: inject secrets and mark baseline migration applied
infisical run --env=prod --path=/scl/backend -- sh -lc '\
export CRM_DATABASE_URL=$(node -e "const url=new URL(process.env.SCL_DATABASE_URL); url.hostname=\"127.0.0.1\"; url.port=\"55432\"; url.searchParams.set(\"schema\",\"crm\"); process.stdout.write(url.toString());"); \
pnpm exec prisma migrate resolve --schema=libs/prisma/crm-client/prisma/schema.prisma --applied 20251230_000_crm_init'

For future schema changes, generate a new migration and use pnpm exec prisma migrate deploy against the same CRM_DATABASE_URL (port-forward as needed).

Running Tests

# Unit tests
npx nx test crm-core
npx nx test crm-campaigns

# Integration tests
npx nx test crm-backend --configuration=integration

# E2E tests
npx nx e2e crm-backend-e2e

---

Related Documents

• Data Model
• API Reference
• Event Catalog