Expand to Business Analytics: Add Customer, Sales, and KPI models

Major expansion from fraud detection to comprehensive business analytics:

DATABASE CHANGES:
- Renamed database from 'fraud_detection' to 'business_analytics'
- Renamed user from 'fraud_analyst' to 'data_analyst'
- Expanded from 20 to 39 tables across 4 business models

NEW MODELS (19 tables):
1. Customer Analytics (5 tables):
   - customer_segments, customer_lifetime_value, churn_predictions
   - customer_satisfaction, engagement_metrics

2. Sales & Revenue Analytics (6 tables):
   - product_catalog, sales_transactions, sales_targets
   - sales_performance, revenue_forecasts

3. KPI & Metrics (8 tables):
   - kpi_definitions, daily_metrics, monthly_summaries
   - trend_analysis, dashboard_snapshots
   - report_definitions, report_executions, data_quality_checks

DATA GENERATION:
- Extended generate_data.sh with 6 new steps (now 15 total)
- Added CLV calculations for all customers
- Added churn predictions based on transaction recency
- Added 30K customer satisfaction surveys
- Added 1M sales transactions linked to 24 products
- Added 90 days of daily KPI metrics
- Added 24 months of business summaries

SQL EXERCISES (3 new levels):
- Level 2: Customer Analytics (10 exercises + 3 challenges)
- Level 3: Sales & Revenue Analysis (12 exercises + 3 challenges)
- Level 4: KPI Dashboards & Metrics (12 exercises + 3 challenges)

DOCUMENTATION:
- Updated README.md with business analytics focus
- Updated QUICKSTART.md with new data generation steps
- Updated SETUP_COMPLETE.md with 39-table architecture
- Added DATA_MODELS.md with complete model specifications
- Added WHATS_NEW.md with migration guide

SEED DATA:
- Added 8 customer segments (VIP, High Value, etc.)
- Added 24 products across 5 categories
- Added 16 KPI definitions across 4 categories
- Added 8 standard report definitions

All changes maintain idempotency and backward compatibility with existing fraud detection functionality.
This commit is contained in:
Alphaeus Mote
2025-10-23 14:17:12 -04:00
parent b30733ccad
commit aa803bd3bd
14 changed files with 2762 additions and 132 deletions
+358
View File
@@ -0,0 +1,358 @@
# Business Analytics Database - Data Models
## Overview
This database supports **Data Analyst** activities including:
- Routine and semi-routine analysis
- Dashboard creation and maintenance
- Business trend identification
- Statistical analysis and pattern recognition
- Stakeholder reporting
---
## Model 1: Customer Analytics (Routine Analysis)
### Purpose
Support customer segmentation, lifetime value analysis, churn prediction, and engagement tracking.
### Tables
#### `customer_segments`
Customer classification for targeted analysis
```sql
- segment_id (PK)
- segment_name (e.g., 'High Value', 'At Risk', 'New Customer')
- segment_description
- criteria_definition (JSON)
- created_date
- updated_date
```
#### `customer_lifetime_value`
CLV calculations for business insights
```sql
- clv_id (PK)
- customer_id (FK customers)
- calculation_date
- total_revenue
- total_transactions
- average_order_value
- predicted_future_value
- clv_score
- segment_id (FK customer_segments)
```
#### `churn_predictions`
Customer retention analysis
```sql
- prediction_id (PK)
- customer_id (FK customers)
- prediction_date
- churn_probability (0-100)
- risk_level (LOW, MEDIUM, HIGH, CRITICAL)
- last_transaction_date
- days_since_last_transaction
- engagement_score
- recommended_action
```
#### `customer_satisfaction`
Satisfaction scores and feedback
```sql
- satisfaction_id (PK)
- customer_id (FK customers)
- survey_date
- nps_score (-100 to 100)
- csat_score (1-5)
- feedback_text
- category (PRODUCT, SERVICE, SUPPORT, etc.)
- sentiment (POSITIVE, NEUTRAL, NEGATIVE)
```
#### `engagement_metrics`
Customer interaction tracking
```sql
- metric_id (PK)
- customer_id (FK customers)
- metric_date
- login_count
- page_views
- time_spent_minutes
- features_used
- support_tickets_opened
- engagement_score
```
---
## Model 2: Sales & Revenue Analytics (Semi-Routine Reporting)
### Purpose
Support sales performance tracking, revenue forecasting, and product analysis.
### Tables
#### `product_catalog`
Product master data
```sql
- product_id (PK)
- product_name
- product_category
- product_subcategory
- unit_price
- cost_price
- margin_percentage
- is_active
- launch_date
- discontinued_date
```
#### `sales_transactions`
Detailed sales records (extends existing transactions)
```sql
- sale_id (PK)
- transaction_id (FK transactions)
- product_id (FK product_catalog)
- quantity
- unit_price
- discount_amount
- tax_amount
- total_amount
- sale_date
- sales_channel (ONLINE, STORE, PHONE, MOBILE_APP)
- sales_rep_id
- region
```
#### `sales_targets`
Performance goals for tracking
```sql
- target_id (PK)
- target_period (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY)
- start_date
- end_date
- product_category
- region
- target_revenue
- target_units
- target_customers
- created_by
```
#### `sales_performance`
Aggregated performance metrics
```sql
- performance_id (PK)
- period_date
- period_type (DAILY, WEEKLY, MONTHLY, QUARTERLY)
- product_id (FK product_catalog)
- region
- total_revenue
- total_units_sold
- total_transactions
- unique_customers
- average_order_value
- vs_target_percentage
```
#### `revenue_forecasts`
Predictive revenue analysis
```sql
- forecast_id (PK)
- forecast_date
- forecast_period_start
- forecast_period_end
- product_category
- region
- forecasted_revenue
- confidence_level (LOW, MEDIUM, HIGH)
- forecast_method (HISTORICAL, TREND, SEASONAL, ML)
- actual_revenue (filled after period ends)
- variance_percentage
```
---
## Model 3: Operational Metrics & KPIs (Dashboard Creation)
### Purpose
Support dashboard creation with pre-calculated KPIs and trend analysis.
### Tables
#### `kpi_definitions`
Master list of tracked KPIs
```sql
- kpi_id (PK)
- kpi_name
- kpi_description
- kpi_category (SALES, CUSTOMER, OPERATIONAL, FINANCIAL)
- calculation_formula
- target_value
- threshold_warning
- threshold_critical
- unit_of_measure
- refresh_frequency (REALTIME, HOURLY, DAILY, WEEKLY)
- is_active
```
#### `daily_metrics`
Daily operational snapshots
```sql
- metric_id (PK)
- metric_date
- kpi_id (FK kpi_definitions)
- metric_value
- vs_previous_day_percentage
- vs_previous_week_percentage
- vs_previous_month_percentage
- status (ON_TARGET, WARNING, CRITICAL)
- notes
```
#### `monthly_summaries`
Monthly aggregated data for reporting
```sql
- summary_id (PK)
- summary_month
- summary_year
- total_revenue
- total_transactions
- total_customers
- new_customers
- churned_customers
- average_transaction_value
- customer_acquisition_cost
- customer_lifetime_value
- net_promoter_score
- gross_margin_percentage
```
#### `trend_analysis`
Statistical trend tracking
```sql
- trend_id (PK)
- kpi_id (FK kpi_definitions)
- analysis_date
- period_start
- period_end
- trend_direction (UP, DOWN, FLAT)
- trend_strength (WEAK, MODERATE, STRONG)
- moving_average_7day
- moving_average_30day
- seasonality_detected
- anomalies_detected
- statistical_significance
```
#### `dashboard_snapshots`
Pre-calculated dashboard data
```sql
- snapshot_id (PK)
- dashboard_name
- snapshot_timestamp
- data_payload (JSON)
- refresh_duration_seconds
- row_count
- last_updated_by
```
---
## Model 4: Business Intelligence & Reporting
### Purpose
Support ad-hoc analysis and standard report generation.
### Tables
#### `report_definitions`
Catalog of standard reports
```sql
- report_id (PK)
- report_name
- report_description
- report_category
- sql_query_template
- parameters (JSON)
- output_format (PDF, EXCEL, CSV, HTML)
- schedule_frequency
- recipients
- is_active
```
#### `report_executions`
Report run history
```sql
- execution_id (PK)
- report_id (FK report_definitions)
- execution_timestamp
- parameters_used (JSON)
- row_count
- execution_duration_seconds
- status (SUCCESS, FAILED, TIMEOUT)
- error_message
- output_file_path
- executed_by
```
#### `data_quality_checks`
Data validation tracking
```sql
- check_id (PK)
- check_name
- table_name
- column_name
- check_type (NULL_CHECK, RANGE_CHECK, UNIQUENESS, REFERENTIAL_INTEGRITY)
- check_date
- records_checked
- records_failed
- failure_percentage
- status (PASS, FAIL, WARNING)
- remediation_notes
```
---
## Relationships to Existing Models
### Integration Points
1. **Customer Analytics** ← links to existing `customers` table
2. **Sales Transactions** ← extends existing `transactions` table
3. **Engagement Metrics** ← links to `login_sessions` and `transactions`
4. **Churn Predictions** ← analyzes `transactions` and `accounts`
5. **KPIs** ← aggregates from multiple existing tables
---
## Use Cases for Data Analyst Role
### Routine Analysis
- Daily sales reports
- Customer segment updates
- KPI dashboard refreshes
- Data quality checks
### Semi-Routine Analysis
- Monthly trend analysis
- Churn prediction updates
- Revenue forecasting
- Performance vs. targets
### Ad-Hoc Analysis
- Customer cohort analysis
- Product performance deep-dives
- Seasonal pattern identification
- Anomaly investigation
---
## Next Steps
1. ✅ Design complete
2. ⏳ Implement schema in `schema/01-create-tables.sql`
3. ⏳ Update data generation scripts
4. ⏳ Create SQL exercises for each model
5. ⏳ Update documentation
+64 -33
View File
@@ -19,7 +19,7 @@ docker-compose up -d
docker-compose ps
```
You should see both `fraud_detection_db` and `fraud_detection_ui` running.
You should see both `business_analytics_db` and `business_analytics_ui` running.
---
@@ -34,9 +34,9 @@ chmod +x scripts/setup-database.sh
```
**What this does:**
- Creates all 20+ tables
- Creates all 39 tables across 4 business models
- Sets up indexes and constraints
- Loads reference data (countries, merchant categories, etc.)
- Loads reference data (countries, merchant categories, customer segments, products, KPIs, etc.)
**Expected output:**
```
@@ -63,6 +63,9 @@ chmod +x data/generate_data.sh
- Creates 150,000 accounts
- Generates 5,000,000 transactions
- Creates fraud patterns and alerts
- Generates customer analytics (CLV, churn, satisfaction)
- Creates sales data (1M sales records)
- Generates KPI metrics (90 days of daily metrics)
**⏱️ Time estimate:**
- Fast machine (SSD, 16GB RAM): ~15 minutes
@@ -72,10 +75,16 @@ chmod +x data/generate_data.sh
**You can monitor progress:**
The script shows progress for each step:
```
[1/9] Loading geographic reference data...
[2/9] Generating Customers...
[3/9] Generating Accounts...
[1/15] Loading geographic reference data...
[2/15] Generating Customers...
[3/15] Generating Accounts...
...
[10/15] Generating Customer Lifetime Value data...
[11/15] Generating Churn Predictions...
[12/15] Generating Customer Satisfaction data...
[13/15] Generating Sales Transactions...
[14/15] Generating Daily Metrics...
[15/15] Generating Monthly Summaries...
```
---
@@ -98,7 +107,7 @@ The script shows progress for each step:
#### Option B: Command Line (psql)
```bash
docker exec -it fraud_detection_db psql -U fraud_analyst -d fraud_detection
docker exec -it business_analytics_db psql -U data_analyst -d business_analytics
```
**Quick commands:**
@@ -122,8 +131,8 @@ SELECT COUNT(*) FROM transactions;
```
Host: localhost
Port: 5432
Database: fraud_detection
Username: fraud_analyst
Database: business_analytics
Username: data_analyst
Password: SecurePass123!
```
@@ -146,43 +155,65 @@ SELECT COUNT(*) FROM customers;
-- How many transactions?
SELECT COUNT(*) FROM transactions;
-- How many fraud alerts?
SELECT COUNT(*) FROM alerts WHERE status = 'OPEN';
-- How many sales records?
SELECT COUNT(*) FROM sales_transactions;
-- How many KPIs are being tracked?
SELECT COUNT(*) FROM kpi_definitions WHERE is_active = TRUE;
```
### 2. Find High-Risk Customers
### 2. Customer Analytics: High-Value Customers
```sql
SELECT
customer_id,
first_name,
last_name,
email,
risk_score
FROM customers
WHERE risk_score > 80
ORDER BY risk_score DESC
SELECT
c.customer_id,
c.first_name,
c.last_name,
clv.clv_score,
cs.segment_name
FROM customers c
JOIN customer_lifetime_value clv ON c.customer_id = clv.customer_id
JOIN customer_segments cs ON clv.segment_id = cs.segment_id
WHERE cs.segment_name IN ('VIP', 'High Value')
ORDER BY clv.clv_score DESC
LIMIT 10;
```
### 3. View Recent Transactions
### 3. Sales Analytics: Top Products
```sql
SELECT
transaction_id,
account_id,
amount,
transaction_date,
is_flagged
FROM transactions
ORDER BY transaction_date DESC
LIMIT 20;
SELECT
p.product_name,
p.product_category,
COUNT(st.transaction_id) as sales_count,
SUM(st.total_amount) as total_revenue
FROM product_catalog p
JOIN sales_transactions st ON p.product_id = st.product_id
GROUP BY p.product_id, p.product_name, p.product_category
ORDER BY total_revenue DESC
LIMIT 10;
```
### 4. Find Flagged Transactions
### 4. KPI Dashboard: Current Status
```sql
SELECT
SELECT
kd.kpi_name,
kd.kpi_category,
dm.metric_value,
kd.target_value,
dm.status
FROM kpi_definitions kd
JOIN daily_metrics dm ON kd.kpi_id = dm.kpi_id
WHERE dm.metric_date = CURRENT_DATE
AND kd.is_active = TRUE
ORDER BY kd.kpi_category, kd.kpi_name;
```
### 5. Fraud Detection: Flagged Transactions
```sql
SELECT
t.transaction_id,
t.amount,
t.fraud_score,
+266
View File
@@ -0,0 +1,266 @@
# What's New - Business Analytics Database
## 🎯 Major Update: Aligned with Data Analyst Role
The database has been **expanded and refocused** to align with real-world **Data Analyst** responsibilities:
- ✅ Routine and semi-routine analysis
- ✅ Dashboard creation and maintenance
- ✅ Business trend identification
- ✅ Statistical analysis and pattern recognition
- ✅ Stakeholder reporting
---
## 📊 Database Renamed
**Old Name:** `fraud_detection`
**New Name:** `business_analytics`
**User Changed:** `fraud_analyst``data_analyst`
This better reflects the broader scope of business intelligence and analytics work.
---
## 🆕 New Data Models Added
### 1. Customer Analytics Model (5 Tables)
**Purpose:** Routine customer analysis and segmentation
#### New Tables:
- **`customer_segments`** - Customer classification definitions
- **`customer_lifetime_value`** - CLV calculations and tracking
- **`churn_predictions`** - Customer retention risk analysis
- **`customer_satisfaction`** - NPS, CSAT scores, and feedback
- **`engagement_metrics`** - Customer interaction tracking
**Use Cases:**
- Customer segmentation analysis
- Churn risk identification
- Lifetime value calculations
- Satisfaction trend analysis
- Engagement scoring
---
### 2. Sales & Revenue Analytics Model (6 Tables)
**Purpose:** Semi-routine sales reporting and forecasting
#### New Tables:
- **`product_catalog`** - Product master data
- **`sales_transactions`** - Detailed sales records
- **`sales_targets`** - Performance goals and targets
- **`sales_performance`** - Aggregated performance metrics
- **`revenue_forecasts`** - Revenue predictions and variance
**Use Cases:**
- Sales performance dashboards
- Product analysis
- Revenue forecasting
- Target vs. actual analysis
- Channel performance comparison
---
### 3. Operational Metrics & KPI Model (5 Tables)
**Purpose:** Dashboard creation and KPI tracking
#### New Tables:
- **`kpi_definitions`** - Master KPI catalog
- **`daily_metrics`** - Daily operational snapshots
- **`monthly_summaries`** - Monthly business summaries
- **`trend_analysis`** - Statistical trend tracking
- **`dashboard_snapshots`** - Pre-calculated dashboard data
**Use Cases:**
- Executive dashboards
- KPI monitoring
- Trend analysis
- Performance tracking
- Anomaly detection
---
### 4. Business Intelligence & Reporting Model (3 Tables)
**Purpose:** Report management and data quality
#### New Tables:
- **`report_definitions`** - Standard report catalog
- **`report_executions`** - Report run history
- **`data_quality_checks`** - Data validation tracking
**Use Cases:**
- Report scheduling
- Execution monitoring
- Data quality assurance
- Audit trails
---
## 📈 Total Database Size
### Original (Fraud Detection Only):
- **20 tables** focused on fraud investigation
### Updated (Business Analytics):
- **39 tables** covering:
- Fraud detection (original 20 tables)
- Customer analytics (5 tables)
- Sales & revenue (6 tables)
- KPIs & metrics (5 tables)
- Reporting & BI (3 tables)
---
## 🔗 Integration with Existing Data
The new models **integrate seamlessly** with existing tables:
```
customers → customer_lifetime_value
→ churn_predictions
→ customer_satisfaction
→ engagement_metrics
transactions → sales_transactions
→ sales_performance
→ revenue_forecasts
(all tables) → kpi_definitions
→ daily_metrics
→ monthly_summaries
```
---
## 💼 Data Analyst Workflows Supported
### Daily Routine Tasks
1. **Refresh dashboards** using `dashboard_snapshots`
2. **Update daily metrics** in `daily_metrics`
3. **Run data quality checks** via `data_quality_checks`
4. **Generate standard reports** from `report_definitions`
### Weekly Semi-Routine Tasks
1. **Customer segmentation** analysis using `customer_segments` and `customer_lifetime_value`
2. **Sales performance** review via `sales_performance` vs `sales_targets`
3. **Churn prediction** updates in `churn_predictions`
4. **Trend analysis** using `trend_analysis` table
### Monthly Analysis
1. **Monthly summaries** generation in `monthly_summaries`
2. **Revenue forecasting** via `revenue_forecasts`
3. **Customer satisfaction** trend analysis
4. **KPI performance** review
### Ad-Hoc Analysis
1. **Product performance** deep-dives
2. **Customer cohort** analysis
3. **Seasonal pattern** identification
4. **Anomaly investigation**
---
## 🎓 New Learning Opportunities
### For Beginners:
- Basic aggregations (SUM, AVG, COUNT)
- Simple JOINs across analytics tables
- Date-based filtering and grouping
- KPI calculations
### For Intermediate:
- Customer segmentation queries
- Sales trend analysis
- Moving averages and window functions
- Cohort analysis
### For Advanced:
- Churn prediction analysis
- Revenue forecasting validation
- Multi-dimensional analysis
- Statistical significance testing
---
## 🔄 Migration Notes
### What Changed:
- ✅ Database name: `fraud_detection``business_analytics`
- ✅ User name: `fraud_analyst``data_analyst`
- ✅ Container names updated
- ✅ All scripts updated
- ✅ 19 new tables added
### What Stayed the Same:
- ✅ All original 20 fraud detection tables
- ✅ All existing data generation logic
- ✅ All existing indexes and constraints
- ✅ Idempotent script design
- ✅ Docker setup structure
### Backward Compatibility:
- ✅ All original fraud detection exercises still work
- ✅ All original queries still valid
- ✅ No breaking changes to existing schema
---
## 📝 Next Steps
### Immediate:
1. ✅ Schema updated with 19 new tables
2. ⏳ Update data generation scripts
3. ⏳ Create SQL exercises for new models
4. ⏳ Update main documentation
### Future Enhancements:
- Add sample data for new tables
- Create dashboard query examples
- Build KPI calculation examples
- Add data quality check templates
---
## 🚀 Getting Started with New Models
### Quick Test Queries:
```sql
-- Check new tables exist
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
AND table_name IN (
'customer_segments',
'customer_lifetime_value',
'product_catalog',
'sales_transactions',
'kpi_definitions',
'daily_metrics'
);
-- View table counts
SELECT
'customer_segments' as table_name, COUNT(*) FROM customer_segments
UNION ALL
SELECT 'product_catalog', COUNT(*) FROM product_catalog
UNION ALL
SELECT 'kpi_definitions', COUNT(*) FROM kpi_definitions;
```
---
## 📚 Documentation Updates
-**DATA_MODELS.md** - Complete model documentation
-**WHATS_NEW.md** - This file
-**README.md** - Update with new scope
-**QUICKSTART.md** - Add new model examples
-**Exercises** - Create analytics-focused exercises
---
**The database is now a comprehensive Business Analytics platform suitable for Data Analyst training and real-world analysis scenarios!** 🎉