Global Event Notification System

The Event Notification System is the central infrastructure for real-time notifications in the xynap Platform. It connects backend events with the frontend and supports multiple channels (in-app, email, Telegram, browser push, speech output).

Architecture

┌──────────────┐     emit_event()     ┌──────────────┐
│   Backend    │ ──────────────────→   │  Event Bus   │
│  (Service)   │                       │  (Pub/Sub)   │
└──────────────┘                       └──────┬───────┘
                                              │
                         ┌────────────────────┼─────────────────────┐
                         ▼                    ▼                     ▼
                   ┌───────────┐      ┌──────────────┐    ┌──────────────┐
                   │ Workflow   │      │  WebSocket   │    │  Dispatcher  │
                   │  Engine    │      │  Broadcast   │    │ (Email/TG)   │
                   └───────────┘      └──────┬───────┘    └──────────────┘
                                             │
                                      ┌──────┴───────┐
                                      │   Frontend   │
                                      │ EventStream  │
                                      └──────┬───────┘
                                             │
                        ┌────────────────────┼────────────────────┐
                        ▼                    ▼                    ▼
                  ┌───────────┐     ┌──────────────┐    ┌──────────────┐
                  │ Bell +    │     │ Call Notifier │    │   Browser    │
                  │ Badge +   │     │ (Modal +     │    │ Notification │
                  │ Dropdown  │     │  Speech)     │    │   (Desktop)  │
                  └───────────┘     └──────────────┘    └──────────────┘

Channels

Channel	Description	Trigger
app	In-app notification (DB + UI)	create_notification()
email	Email via SMTP	Dispatcher
telegram	Telegram Bot API	Dispatcher
browser	Desktop notification (Web Push)	Frontend on notification.created
speech	Speech output (Web Speech API)	Frontend on call.incoming

Event Types

System Events

Event	Payload	Description
notification.created	uuid, title, body, category, severity, ...	New in-app notification
call.incoming	caller_id, did_number, customer, ...	Incoming call (SIP)
mail.new_message	folder, message	New email
mail.folder_update	folder	Mail folder changed
support.session.created	session_code, channel	New support request
file.uploaded	path, name	File uploaded

Backend: Creating Notifications

from app.core.notifications.service import create_notification

notif = await create_notification(
    db, user_id=42,
    title="New customer created",
    body="Customer 'Example Corp' was successfully created.",
    category="crm",
    severity="success",
    icon="building",
    entity_type="customer",
    entity_id="uuid-...",
    action_url="/crm/customers/uuid-...",
)

Frontend: Receiving Events

import { useNotificationCenter } from '@/shell/composables/useNotificationCenter'

const { notifications, unreadCount, hasUnread, markRead } = useNotificationCenter()

REST API

Method	Endpoint	Description
GET	/api/v1/notifications	List notifications
GET	/api/v1/notifications/summary	Get total + unread count
PUT	/api/v1/notifications/{uuid}/read	Mark as read
POST	/api/v1/notifications/read-all	Mark all as read
DELETE	/api/v1/notifications/{uuid}	Delete notification