Default Alerts Feature Implementation

Overview

The Default Alerts feature automatically creates two specific, non-deletable default alerts for every new client when they are first created in the system. These alerts are immediately visible in the client's alert settings, where they can be toggled on/off but never permanently deleted.

Implementation Details

1. Database Schema

The is_default column already exists in the app.alerts table:

is_default BOOLEAN DEFAULT false

2. Default Alert Configurations

Alert 1: High CPLPV

• Name: [Default Alert] CPLPV >= 2x account average for 7d
• Description: Trigger when Cost per landing page view is doubled the account average for 7 days
• Type: cplpv
• Data Level: account
• Data Source: app.daily_metrics
• Rule: Dynamic threshold - CPLPV > 2x account average over 7 days
• Action: Assign task to Media Buyer

Alert 2: Low eROAS

• Name: [Default Alert] eROAS < 1 over 1 day
• Description: Identity any ad has an eROAS < 1 over 1 day
• Type: eroas
• Data Level: ad
• Data Source: dm_dashboard.ad_daily_dashboard
• Rule: Absolute threshold - projected_roas < 1 over 1 day
• Action: Assign task to Media Buyer

3. Backend Implementation

Files Modified:

1. services/default_alerts.py (New file)

   • create_default_alerts_for_client(): Creates default alerts for new clients
   • get_default_alerts_for_client(): Retrieves default alerts for a client
   • is_default_alert(): Checks if an alert is a default alert
   • calculate_next_check(): Calculates next check time based on frequency

2. services/client.py

   • Updated create_client() to call default alerts creation after client creation

3. crud/crud_user.py

   • Updated create_client() to call default alerts creation after client creation

4. services/alerts.py

   • Updated delete_alert_service() to return 403 Forbidden for default alerts

4. API Changes

DELETE /api/v1/alerts/{alert_id}

• Before: Could delete any alert
• After: Returns 403 Forbidden with message "Cannot delete a default alert." for default alerts

5. Frontend Implementation

Files Already Implemented:

1. pages/alerts.tsx
   • ✅ Default alert badges: Shows [Default] badge for default alerts
   • ✅ Disabled delete buttons: Delete button is hidden for default alerts (!alert.is_default)
   • ✅ Toggle functionality: Enable/disable switch remains functional

6. Integration Points

Client Creation Flow:

1. Super Admin Client Creation (/api/v1/client POST)

   • Creates client via services/client.py
   • Calls create_default_alerts_for_client()
   • Creates client alert settings

2. User Registration with Client (/api/v1/auth/signup POST)

   • Creates client via crud/crud_user.py
   • Calls create_default_alerts_for_client()
   • Creates client alert settings

7. Error Handling

• Default alerts creation failure does not prevent client creation
• Errors are logged but do not fail the entire process
• Graceful fallback if default alerts service is unavailable

8. Testing

Test Script: test_default_alerts.py

The test script verifies:

1. ✅ Client creation
2. ✅ Default alerts creation
3. ✅ Client alert settings creation
4. ✅ Default alert identification
5. ✅ Deletion prevention
6. ✅ Cleanup

Manual Testing Steps:

1. Create New Client:

   curl -X POST /api/v1/client \
     -H "Authorization: Bearer <token>" \
     -d '{"name": "Test Client"}'

2. Verify Default Alerts:

   curl -X GET /api/v1/alerts/client/{client_id}/settings \
     -H "Authorization: Bearer <token>"

3. Test Deletion Prevention:

   curl -X DELETE /api/v1/alerts/{default_alert_id}?client_id={client_id} \
     -H "Authorization: Bearer <token>"
   # Should return 403 Forbidden

9. Configuration

Default Alert Settings:

• Frequency: Daily at 5:00 AM (America/Los_Angeles timezone)
• Priority: Medium
• Assignee: Media Buyer role
• Task Creation: Enabled
• Initial State: Enabled

Customization:

Default alerts can be customized by:

• Toggling on/off in client alert settings
• Modifying thresholds through custom_config
• Changing assignees through action_config

10. Monitoring

Logging:

• Default alerts creation: INFO level
• Creation failures: ERROR level
• Deletion attempts: DEBUG level

Metrics to Monitor:

• Default alerts creation success rate
• Default alerts deletion attempts
• Client creation with/without default alerts

Security Considerations

1. Permission Checks: Only super admins can create clients
2. Default Alert Protection: Cannot be deleted via API
3. Client Isolation: Default alerts are client-specific
4. Audit Trail: All actions are logged

Future Enhancements

1. Custom Default Alerts: Allow per-client default alert templates
2. Bulk Operations: Enable/disable all default alerts at once
3. Analytics: Track default alert effectiveness
4. Migration: Tool to add default alerts to existing clients

Troubleshooting

Common Issues:

1. Default alerts not created:

   • Check database connection
   • Verify client creation succeeded
   • Check logs for errors

2. Cannot delete alert:

   • Verify alert is marked as is_default = true
   • Check API response for 403 status

3. Frontend not showing badges:

   • Verify is_default field in API response
   • Check frontend component rendering logic

Debug Commands:

-- Check default alerts for a client
SELECT * FROM app.alerts WHERE client_id = 'client-uuid' AND is_default = true;

-- Check client alert settings
SELECT * FROM app.client_alert_settings WHERE client_id = 'client-uuid';

-- Verify alert protection
SELECT id, name, is_default FROM app.alerts WHERE is_default = true;