birthday_messaging/README.md

# birthdaymessaging


Overview

The Birthday Messaging Intelligence Platform is a data-driven engagement system designed to transform static birthday campaigns into an intelligent engagement engine.

The system integrates CRM data, behavioral interaction logs, and predictive analytics to automatically identify high-value engagement opportunities, detect churn risk, and orchestrate personalized birthday messaging campaigns.

The platform evolves through three stages:

Stage	Description
Week 2	Data pipeline and engagement preparation
Week 3	Predictive intelligence and behavioral segmentation
Future	Multi-channel automation and campaign optimization

The end result is a system that predicts disengagement before it happens and activates personalized engagement campaigns.

System Architecture

The project is organized into modular components following a data pipeline → intelligence → automation architecture.

CRM Data + Clickstream Logs
            │
            ▼
     Unified Data Pipeline
            │
            ▼
    Data Cleaning & Compliance
            │
            ▼
     Engagement Intelligence
            │
            ▼
      Churn Prediction
            │
            ▼
     Predictive Segmentation
            │
            ▼
     Automation Triggers
Project Structure
birthdaymessaging/
│
├── config.yaml
├── main.py
├── README.md
│
├── data/
│   ├── raw/
│   └── processed/
│
├── docs/
│   ├── ethics.md
│   └── model-audits/
│
├── src/
│   ├── pipeline/            # Week 2 Data Engineering
│   │   ├── unified_stream.py
│   │   ├── relative_date_trigger.py
│   │   ├── rf_scoring.py
│   │   ├── list_hygiene.py
│   │   ├── ethics_flags.py
│   │   ├── deliverability_check.py
│   │   └── config_loader.py
│   │
│   ├── models/              # Week 3 Intelligence Layer
│   │   ├── engagement_scoring.py
│   │   ├── churn_classifier.py
│   │   └── send_time_optimizer.py
│   │
│   ├── segmentation/
│   │   └── predictive_segments.py
│   │
│   └── automation/
│       ├── trigger_engine.py
│       └── reactivation_triggers.yaml
Week 2: Data Engineering Pipeline

Week 2 focuses on building a clean, compliant data foundation.

Unified Data Stream

File:

src/pipeline/unified_stream.py

Functions:

Load CRM dataset

Load clickstream activity logs

Pseudonymize user identifiers

Merge datasets

Normalize timestamps (UTC)

Output:

unified_dataset.csv
Birthday Recursion Trigger

File:

relative_date_trigger.py

Implements recurring campaign triggers such as:

Birthday approaching

Pre-birthday reminder

Post-birthday follow-up

Ensures contacts re-enter the workflow annually.

Recency-Frequency Scoring

File:

rf_scoring.py

Calculates engagement indicators:

Recency index

Frequency of sessions

Session change delta

Used as an early engagement signal.

List Hygiene Automation

File:

list_hygiene.py

Improves deliverability by removing:

Invalid email domains

Disposable email services

Role-based addresses

Ethics and Compliance Layer

File:

ethics_flags.py

Detects sensitive data usage:

medical_condition

political_opinion

dietary_restrictions

Ensures compliance with GDPR principles.

Deliverability Simulation

File:

deliverability_check.py

Simulates email infrastructure readiness:

SPF validation

DKIM compatibility

DMARC enforcement

inactive contact suppression

Week 3: Engagement Intelligence Engine

Week 3 converts the pipeline into a predictive analytics platform.

Engagement Scoring Engine

File:

src/models/engagement_scoring.py

Calculates a normalized engagement score (0–100) based on:

Recency of interaction

Session frequency

Session duration

Click engagement depth

Formula:

Engagement Score =
(Recency Weight × Normalized Recency)
+ (Frequency Weight × Session Count)
+ (Engagement Depth Weight × Interaction Index)

Output classification:

Score	Tier
75–100	Highly Engaged
50–74	Stable
25–49	Declining
0–24	At Risk
Churn Risk Classification

File:

src/models/churn_classifier.py

Defines churn risk using behavioral signals.

Conditions:

No login ≥ X days
AND
Engagement score drop ≥ Y%

Risk categories:

Risk Level	Description
Low	Healthy engagement
Medium	Engagement declining
High	High probability of churn

Output fields:

churn_risk_flag
churn_probability_score
risk_class
Predictive Segmentation

File:

src/segmentation/predictive_segments.py

Creates behavioral marketing segments using:

Lifecycle Stage
Engagement Tier
Birthday Proximity
Churn Risk Overlay

Example segment:

At-Risk + Birthday Approaching
Send-Time Optimization

File:

src/models/send_time_optimizer.py

Analyzes historical open patterns and determines optimal send windows.

Outputs:

optimal_send_hour
optimal_send_day
Automation Triggers

File:

src/automation/reactivation_triggers.yaml

Defines campaign orchestration rules.

Example:

IF churn_risk_flag = True
AND birthday_within_30_days = True

THEN send reminder email
WAIT 24h
IF unopened → send SMS
Model Governance & Ethics

Documentation:

docs/model-audits/week3-bias-review.md
docs/ethics.md

Audits include:

Geographic bias

Age-based performance variance

False-positive churn classification

Transparency measures include clear documentation of automated decision logic.

Running the Pipeline

Run the full pipeline:

python main.py

Pipeline order:

Week 2:
Data Merge
Birthday Triggers
RF Scoring
List Hygiene
Ethics Checks
Deliverability Simulation

Week 3:
Engagement Scoring
Churn Classification
Predictive Segmentation
Send-Time Optimization

Final dataset:

data/processed/final_intelligence_output.csv
Success Criteria

The system is considered operational when:

Engagement scores generated for all active users

Churn risk classification validated

Predictive segments documented

Reactivation triggers tested

Send-time optimization operational

Ethics documentation updated

Bias audit completed

Outcome

At completion, the platform functions as an Engagement Intelligence Engine.

Capabilities include:

Predicting disengagement

Prioritizing high-value users

Automating reactivation campaigns

Personalizing birthday marketing

Ensuring ethical data usage

The platform transforms traditional birthday messaging into a behaviorally intelligent engagement strategy.