Files

Samir Boulahtit f141cc4e6a docs: migrate module documentation to single source of truth

Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-08 23:38:37 +01:00

6.4 KiB

Raw Permalink Blame History

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

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

6.4 KiB Raw Permalink Blame History