orion/docs/implementation/admin-notification-system.md

Admin Notification System

Overview

The admin notification system provides real-time alerts and notifications to platform administrators for important events, errors, and system status updates.

Components

Backend

Database Models

Located in models/database/admin.py:

• AdminNotification: Stores individual notifications

  • type: Notification type (import_failure, order_sync_failure, etc.)
  • priority: low, normal, high, critical
  • title, message: Content
  • is_read, read_at, read_by_user_id: Read tracking
  • action_required, action_url: Optional action link
  • notification_metadata: JSON for additional context

• PlatformAlert: Stores platform-wide alerts

  • alert_type: security, performance, capacity, integration, etc.
  • severity: info, warning, error, critical
  • affected_stores, affected_systems: Scope tracking
  • occurrence_count, first_occurred_at, last_occurred_at: Deduplication
  • is_resolved, resolved_at, resolution_notes: Resolution tracking

Service Layer

Located in app/services/admin_notification_service.py:

from app.services.admin_notification_service import (
    admin_notification_service,
    platform_alert_service,
    NotificationType,
    Priority,
    AlertType,
    Severity,
)

AdminNotificationService methods:

Method	Description
create_notification()	Create a new notification
get_notifications()	List notifications with filters
get_recent_notifications()	Get recent unread for header dropdown
get_unread_count()	Count unread notifications
mark_as_read()	Mark single notification read
mark_all_as_read()	Mark all as read
delete_notification()	Delete a notification

Convenience methods for common scenarios:

Method	Use Case
notify_import_failure()	Product/order import failed
notify_order_sync_failure()	Letzshop sync failed
notify_order_exception()	Order has unmatched products
notify_critical_error()	System critical error
notify_store_issue()	Store-related problem
notify_security_alert()	Security event detected

PlatformAlertService methods:

Method	Description
create_alert()	Create a new platform alert
get_alerts()	List alerts with filters
resolve_alert()	Mark alert as resolved
get_statistics()	Get alert counts and stats
create_or_increment_alert()	Deduplicate recurring alerts

API Endpoints

Located in app/api/v1/admin/notifications.py:

Notifications:

• GET /api/v1/admin/notifications - List with filters
• POST /api/v1/admin/notifications - Create (manual)
• GET /api/v1/admin/notifications/recent - For header dropdown
• GET /api/v1/admin/notifications/unread-count - Badge count
• PUT /api/v1/admin/notifications/{id}/read - Mark read
• PUT /api/v1/admin/notifications/mark-all-read - Mark all read
• DELETE /api/v1/admin/notifications/{id} - Delete

Platform Alerts:

• GET /api/v1/admin/notifications/alerts - List with filters
• POST /api/v1/admin/notifications/alerts - Create (manual)
• PUT /api/v1/admin/notifications/alerts/{id}/resolve - Resolve
• GET /api/v1/admin/notifications/alerts/stats - Statistics

Frontend

Header Dropdown

Located in app/templates/admin/partials/header.html:

• Real-time notification bell with unread count badge
• Polls for new notifications every 60 seconds
• Quick actions: mark as read, view all
• Priority-based color coding

Notifications Page

Located in app/templates/admin/notifications.html with static/admin/js/notifications.js:

• Full notifications management interface
• Two tabs: Notifications and Platform Alerts
• Statistics cards (unread, active alerts, critical, resolved today)
• Filtering by priority, type, read status
• Bulk operations (mark all read)
• Alert resolution workflow

Automatic Triggers

Notifications are automatically created in these scenarios:

Import Failures

Product Import (app/tasks/background_tasks.py):

• When a product import job fails completely
• When import completes with 5+ errors

Historical Order Import (app/tasks/letzshop_tasks.py):

• When Letzshop API returns an error
• When import fails with an unexpected exception

Example Usage

from app.services.admin_notification_service import admin_notification_service

# In a background task or service
admin_notification_service.notify_import_failure(
    db=db,
    store_name="Acme Corp",
    job_id=123,
    error_message="CSV parsing failed: invalid column format",
    store_id=5,
)
db.commit()

Priority Levels

Priority	When to Use	Badge Color
critical	System down, data loss risk	Red
high	Import/sync failures, action needed	Orange
normal	Informational alerts	Blue
low	Minor issues, suggestions	Gray

Architecture

┌─────────────────┐     ┌──────────────────────┐
│  Background     │────▶│  Notification        │
│  Tasks          │     │  Service             │
└─────────────────┘     └──────────┬───────────┘
                                   │
┌─────────────────┐                ▼
│  API Endpoints  │◀───────────────┤
└─────────────────┘                │
                                   ▼
┌─────────────────┐     ┌──────────────────────┐
│  Header         │◀────│  Database            │
│  Dropdown       │     │  (admin_notifications│
└─────────────────┘     │   platform_alerts)   │
         │              └──────────────────────┘
         ▼
┌─────────────────┐
│  Notifications  │
│  Page           │
└─────────────────┘

Future Enhancements

• Email notifications for critical alerts
• Webhook integration for external systems
• Customizable notification preferences per admin
• Scheduled notification digests