feat: Implement Day 16 - SaaS Health Metrics Dashboard with retention curves and Metabase queries

- Added script to generate retention curves from subscription data (day16_DATA_generate_retention_curves.py)
- Created comprehensive SQL queries for Metabase dashboard (day16_QUERIES_metabase.md)
- Developed quick start guide for setting up the dashboard in Metabase Cloud (day16_QUICKSTART.md)
- Compiled project summary and documentation for execution readiness (day16_SUMMARY.md)
- Specified project dependencies in requirements file (day16_requirements.txt)
- Established guidelines for capturing dashboard screenshots (screenshots/README.md)

Author: raphaela-nawa

README.md

@@ -38,7 +38,7 @@ Each one ships with full code and documentation.
 | 13 | Orchestration | Alert Triage Orchestrator (Finance Compliance) | Finance/Compliance | ✅ Complete | [Day 13](./day13) |
 | 14 | Orchestration | Transport Regulatory KPIs - Automated Email Reports | Government/Public Policy | ✅ Complete | [Day 14](./day14) |
 | 15 | Orchestration | Real-Time Analytics Orchestrator - Webhook Event Processing Pipeline | SaaS / Technology | ✅ Complete | [Day 15](./day15) |
-| 16 | Dashboards | TBD | TBD | 🚧 Planned | [Day 16](./day16) |
+| 16 | Dashboards | SaaS Health Metrics Dashboard - Metabase Cloud | TBD | ✅ Complete | [Day 16](./day16) |
 | 17 | Dashboards | TBD | TBD | 🚧 Planned | [Day 17](./day17) |
 | 18 | Dashboards | TBD | TBD | 🚧 Planned | [Day 18](./day18) |
 | 19 | Dashboards | TBD | TBD | 🚧 Planned | [Day 19](./day19) |

common/prompt library/VISUALIZATION_DELIVERY_CRITERIA.md

@@ -0,0 +1,17 @@
+# Day 16: SaaS Health Metrics Dashboard - Metabase Cloud + BigQuery
+# Environment Variables
+
+## BigQuery Configuration
+DAY16_GCP_PROJECT_ID=your-project-id-here
+DAY16_BQ_DATASET=day16_saas_metrics
+DAY16_BQ_LOCATION=US
+
+## Metabase Cloud Configuration
+DAY16_METABASE_URL=https://your-instance.metabaseapp.com
+DAY16_METABASE_DASHBOARD_ID=your-dashboard-id
+
+## Data Source
+DAY16_SOURCE_DB_PATH=../day06/data/day06_saas_metrics.db
+
+## Service Account (DO NOT COMMIT THE ACTUAL KEY FILE)
+DAY16_SERVICE_ACCOUNT_KEY_PATH=./day16_metabase_key.json

day16/.env.example

@@ -0,0 +1,16 @@
+# Day 16 - Ignore sensitive files
+
+# Service account keys
+*.json
+!day16_metabase_dashboard.json
+
+# Data files (too large for git)
+data/*.csv
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Environment files
+.env

day16/.gitignore

@@ -0,0 +1,236 @@
+# Day 16: BigQuery Setup Guide
+
+## Overview
+This guide helps you upload the Day 6 SaaS metrics data to BigQuery for use with Metabase Cloud.
+
+---
+
+## Step 1: Create BigQuery Dataset
+
+### Using GCP Console:
+1. Go to [BigQuery Console](https://console.cloud.google.com/bigquery)
+2. Select your project (or create a new one)
+3. Click "Create Dataset"
+4. Use these settings:
+   - **Dataset ID**: `day16_saas_metrics`
+   - **Location**: `US` (or your preferred region)
+   - **Default table expiration**: Never
+5. Click "Create Dataset"
+
+### Using gcloud CLI:
+```bash
+# Set your project ID
+export DAY16_GCP_PROJECT_ID="your-project-id"
+
+# Create dataset
+bq mk \
+  --dataset \
+  --location=US \
+  --description="Day 16: SaaS Health Metrics for Metabase Dashboard" \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics
+```
+
+---
+
+## Step 2: Upload CSV Files to BigQuery
+
+You have 8 CSV files in `day16/data/` that need to be uploaded.
+
+### Option A: Using GCP Console (Easiest)
+
+For each CSV file, follow these steps:
+
+1. In BigQuery, select your `day16_saas_metrics` dataset
+2. Click "Create Table"
+3. Configure:
+   - **Source**: Upload
+   - **Select file**: Choose the CSV file
+   - **File format**: CSV
+   - **Table name**: Use the filename without `.csv` (e.g., `day06_dashboard_kpis`)
+   - **Schema**: Auto-detect
+   - **Advanced options** → Header rows to skip: `1`
+4. Click "Create Table"
+
+Repeat for all 8 files:
+- `day06_dashboard_kpis.csv`
+- `day06_mrr_summary.csv`
+- `day06_retention_curves.csv`
+- `day06_churn_by_cohort.csv`
+- `day06_customer_health.csv`
+- `day06_customers.csv`
+- `day06_subscriptions.csv`
+- `day06_mrr_movements.csv`
+
+### Option B: Using bq CLI (Faster for bulk upload)
+
+```bash
+# Navigate to the data directory
+cd day16/data
+
+# Set your project ID
+export DAY16_GCP_PROJECT_ID="your-project-id"
+
+# Upload all tables
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_dashboard_kpis \
+  day06_dashboard_kpis.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_mrr_summary \
+  day06_mrr_summary.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_retention_curves \
+  day06_retention_curves.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_churn_by_cohort \
+  day06_churn_by_cohort.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_customer_health \
+  day06_customer_health.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_customers \
+  day06_customers.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_subscriptions \
+  day06_subscriptions.csv
+
+bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
+  ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics.day06_mrr_movements \
+  day06_mrr_movements.csv
+```
+
+---
+
+## Step 3: Verify Upload
+
+```bash
+# List tables
+bq ls ${DAY16_GCP_PROJECT_ID}:day16_saas_metrics
+
+# Check row counts
+bq query --use_legacy_sql=false \
+  "SELECT 'dashboard_kpis' as table_name, COUNT(*) as row_count FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_dashboard_kpis\`
+   UNION ALL
+   SELECT 'mrr_summary', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_mrr_summary\`
+   UNION ALL
+   SELECT 'retention_curves', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_retention_curves\`
+   UNION ALL
+   SELECT 'churn_by_cohort', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_churn_by_cohort\`
+   UNION ALL
+   SELECT 'customer_health', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_customer_health\`
+   UNION ALL
+   SELECT 'customers', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_customers\`
+   UNION ALL
+   SELECT 'subscriptions', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_subscriptions\`
+   UNION ALL
+   SELECT 'mrr_movements', COUNT(*) FROM \`${DAY16_GCP_PROJECT_ID}.day16_saas_metrics.day06_mrr_movements\`"
+```
+
+Expected row counts:
+- `dashboard_kpis`: 1
+- `mrr_summary`: 24
+- `retention_curves`: 299
+- `churn_by_cohort`: 52
+- `customer_health`: 500
+- `customers`: 500
+- `subscriptions`: 641
+- `mrr_movements`: 24
+
+---
+
+## Step 4: Create Service Account for Metabase
+
+Metabase Cloud needs credentials to access your BigQuery data.
+
+### Create Service Account:
+```bash
+# Set variables
+export DAY16_GCP_PROJECT_ID="your-project-id"
+export DAY16_SERVICE_ACCOUNT="metabase-day16"
+
+# Create service account
+gcloud iam service-accounts create ${DAY16_SERVICE_ACCOUNT} \
+  --display-name="Metabase Day 16 Dashboard" \
+  --project=${DAY16_GCP_PROJECT_ID}
+
+# Grant BigQuery Data Viewer role
+gcloud projects add-iam-policy-binding ${DAY16_GCP_PROJECT_ID} \
+  --member="serviceAccount:${DAY16_SERVICE_ACCOUNT}@${DAY16_GCP_PROJECT_ID}.iam.gserviceaccount.com" \
+  --role="roles/bigquery.dataViewer"
+
+# Grant BigQuery Job User role (for running queries)
+gcloud projects add-iam-policy-binding ${DAY16_GCP_PROJECT_ID} \
+  --member="serviceAccount:${DAY16_SERVICE_ACCOUNT}@${DAY16_GCP_PROJECT_ID}.iam.gserviceaccount.com" \
+  --role="roles/bigquery.jobUser"
+
+# Create and download key
+gcloud iam service-accounts keys create day16_metabase_key.json \
+  --iam-account=${DAY16_SERVICE_ACCOUNT}@${DAY16_GCP_PROJECT_ID}.iam.gserviceaccount.com
+```
+
+**Save the `day16_metabase_key.json` file** - you'll need it for Metabase Cloud connection.
+
+---
+
+## Step 5: Connect Metabase Cloud to BigQuery
+
+1. Go to [Metabase Cloud](https://www.metabase.com/start/)
+2. Sign up or log in
+3. Click "Add a database"
+4. Select "BigQuery"
+5. Configure:
+   - **Display Name**: Day 16 - SaaS Health Metrics
+   - **Project ID**: Your GCP project ID
+   - **Dataset ID**: `day16_saas_metrics`
+   - **Service Account JSON**: Upload `day16_metabase_key.json`
+6. Click "Save"
+7. Click "Sync database schema now"
+
+---
+
+## Next Steps
+
+Once connected, you're ready to create dashboard cards using the SQL queries in:
+- `day16_QUERIES_metabase.md`
+
+---
+
+## Troubleshooting
+
+### "Permission denied" error:
+- Verify service account has both `bigquery.dataViewer` and `bigquery.jobUser` roles
+- Check that the service account JSON key is valid
+
+### "Dataset not found":
+- Ensure dataset ID is exactly `day16_saas_metrics`
+- Verify dataset is in the same project as your service account
+
+### "Table not found":
+- Run the verification query in Step 3 to confirm all tables uploaded successfully
+- Check table names match exactly (case-sensitive)
+
+---
+
+## Cost Considerations
+
+- **Storage**: ~1 MB total (negligible cost)
+- **Queries**: Metabase preview queries are typically <10 MB scanned
+- **Expected monthly cost**: <$1 USD (likely free tier)
+
+---
+
+## Security Notes
+
+- ⚠️ **DO NOT commit `day16_metabase_key.json` to git**
+- Add to `.gitignore`: `*.json` in day16 folder
+- Service account has read-only access (dataViewer role only)
+- Consider setting up BigQuery authorized views for production
+
+---
+
+Built for Christmas Data Advent 2025 - Day 16 (Project 4A)

day16/README.md

@@ -0,0 +1,77 @@
+"""
+Day 16: Export SaaS metrics from SQLite to CSV for BigQuery upload
+Exports all tables from Day 6 database to CSV format
+"""
+
+import sqlite3
+import pandas as pd
+import os
+from pathlib import Path
+
+# Configuration
+DAY16_SOURCE_DB = "../day06/data/day06_saas_metrics.db"
+DAY16_OUTPUT_DIR = "./data"
+
+# Tables to export
+DAY16_TABLES = [
+    "day06_dashboard_kpis",
+    "day06_mrr_summary",
+    "day06_retention_curves",
+    "day06_churn_by_cohort",
+    "day06_customer_health",
+    "day06_customers",
+    "day06_subscriptions",
+    "day06_mrr_movements"
+]
+
+def day16_export_table_to_csv(db_path: str, table_name: str, output_dir: str):
+    """Export a single table to CSV"""
+    try:
+        conn = sqlite3.connect(db_path)
+        df = pd.read_sql_query(f"SELECT * FROM {table_name}", conn)
+        conn.close()
+
+        # Save to CSV
+        output_path = os.path.join(output_dir, f"{table_name}.csv")
+        df.to_csv(output_path, index=False)
+
+        print(f"✅ Exported {table_name}: {len(df)} rows → {output_path}")
+        return True
+
+    except Exception as e:
+        print(f"❌ Error exporting {table_name}: {e}")
+        return False
+
+def day16_main():
+    """Export all tables from Day 6 database"""
+    print("=" * 60)
+    print("Day 16: Exporting SaaS Metrics to CSV for BigQuery")
+    print("=" * 60)
+
+    # Create output directory
+    Path(DAY16_OUTPUT_DIR).mkdir(parents=True, exist_ok=True)
+
+    # Check if source database exists
+    if not os.path.exists(DAY16_SOURCE_DB):
+        print(f"❌ Error: Database not found at {DAY16_SOURCE_DB}")
+        return
+
+    print(f"\n📂 Source: {DAY16_SOURCE_DB}")
+    print(f"📂 Output: {DAY16_OUTPUT_DIR}\n")
+
+    # Export each table
+    success_count = 0
+    for table in DAY16_TABLES:
+        if day16_export_table_to_csv(DAY16_SOURCE_DB, table, DAY16_OUTPUT_DIR):
+            success_count += 1
+
+    print(f"\n{'=' * 60}")
+    print(f"✅ Export complete: {success_count}/{len(DAY16_TABLES)} tables exported")
+    print(f"{'=' * 60}")
+    print("\nNext steps:")
+    print("1. Upload CSV files to BigQuery")
+    print("2. Use the SQL queries in day16_QUERIES_metabase.md")
+    print("3. Connect Metabase Cloud to BigQuery")
+
+if __name__ == "__main__":
+    day16_main()