Notifications

{
  "overview": "# Notifications Service Documentation\n\nThe **notifications** service in the Vivified platform is designed to manage and dispatch notifications while ensuring compliance with HIPAA standards. This service is crucial for maintaining communication within the platform, orchestrating notifications, and managing the lifecycle of notification events.\n\n## Key Responsibilities\n\n- **Accept Notification Requests**: The service accepts requests to send notifications and publishes canonical events for further processing.\n- **Subscribe and Manage Events**: It subscribes to `NotificationSent` events and maintains an inbox.\n- **Expose Settings**: Provides simple settings that are currently in-memory but are designed to be pluggable with Redis/Postgres in the future.\n- **Metrics and Auditing**: Emits Prometheus metrics for monitoring and audit events for compliance and traceability.\n\n## Architecture\n\n```mermaid\ngraph TD;\n    A[NotificationRequest] -->|Publish Event| B[MessagingService];\n    B --> C[PolicyEngine];\n    C --> D[AuditService];\n    B --> E[NotificationSent Event];\n    E --> F[InboxItem Management];\n    D --> G[Prometheus Metrics];\n```\n\n!!! note\n    This service is a proof of concept and currently uses in-memory storage for settings and inbox items. Future enhancements will include integration with Redis or Postgres.\n",
  "api": "# API Reference\n\nThe notifications service currently does not expose a REST API directly but interacts through event-driven mechanisms and internal service calls. Below are the primary data models utilized:\n\n## NotificationRequest\n- `notification_id`: Unique identifier for the notification.\n- `title`: Optional title of the notification.\n- `body`: Main content of the notification.\n- `priority`: Priority level of the notification (`low`, `normal`, `high`, `critical`).\n- `channel`: Optional communication channel.\n- `targets`: List of target recipients.\n- `metadata`: Additional metadata.\n\n## NotificationSent\n- `event_type`: Type of the event, default is `NotificationSent`.\n- `notification_id`: Identifier for the sent notification.\n- `plugin`: The plugin used to send the notification.\n- `timestamp`: Time the notification was sent.\n- `status`: Current status of the notification (`queued`, `sent`, `partial`, `failed`).\n- `details`: Additional details about the notification event.\n\n## Example Event Subscription\n=== \"Python\"\n    ```python\n    from core.messaging.service import MessagingService\n    \n    def handle_notification_sent(event):\n        # Process notification sent event\n        print(f\"Notification {event.notification_id} sent with status {event.status}\")\n    \n    messaging_service = MessagingService()\n    messaging_service.subscribe(\"NotificationSent\", handle_notification_sent)\n    ```\n\n=== \"curl\"\n    ```bash\n    curl -X POST \\\n      http://localhost:8080/events/subscribe \\\n      -H \"Content-Type: application/json\" \\\n      -d '{\"event_type\": \"NotificationSent\", \"callback_url\": \"http://myservice/handle\"}'\n    ```\n",
  "config": "# Configuration Guide\n\nThe following table outlines the configuration options available for the notifications service:\n\n| Configuration Option     | Description                                      | Default Value |\n|--------------------------|--------------------------------------------------|---------------|\n| `inbox_storage`          | Determines the type of storage for the inbox     | `in-memory`   |\n| `metrics_enabled`        | Enables or disables Prometheus metrics emission  | `true`        |\n| `audit_level`            | Sets the level of audit logging                  | `normal`      |\n| `default_notification_channel` | Default channel for sending notifications | `email`       |\n\n!!! warning\n    Ensure that configuration changes adhere to HIPAA compliance standards, especially when dealing with sensitive data.\n\n## Security Considerations\n\n- **Data Encryption**: All notifications containing PHI (Protected Health Information) must be encrypted in transit and at rest.\n- **Access Control**: Ensure that only authorized personnel have access to the configuration and the ability to send notifications.\n- **Audit Logs**: Maintain comprehensive audit logs of all notification events to comply with HIPAA regulations.\n",
  "examples": "# Usage Examples\n\n## Sending a Notification\n\n=== \"Python\"\n```python\nfrom core.messaging.service import MessagingService\nfrom .models import NotificationRequest, NotificationPriority\n\n# Create a notification request\nnotification = NotificationRequest(\n    notification_id=\"12345\",\n    title=\"Urgent Update\",\n    body=\"Please review the latest policy changes.\",\n    priority=NotificationPriority.high,\n    targets=[\"user1@example.com\", \"user2@example.com\"]\n)\n\n# Send the notification\nmessaging_service = MessagingService()\nmessaging_service.publish_event(\"NotificationRequest\", notification.dict())\n```\n\n=== \"curl\"\n```bash\ncurl -X POST \\\n  http://localhost:8080/notifications/send \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"notification_id\": \"12345\",\n        \"title\": \"Urgent Update\",\n        \"body\": \"Please review the latest policy changes.\",\n        \"priority\": \"high\",\n        \"targets\": [\"user1@example.com\", \"user2@example.com\"]\n      }'\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Notifications not being sent**\n   - Verify if the messaging service is correctly configured and active.\n   - Check logs for any errors related to policy engine decisions.\n\n2. **High latency in notification delivery**\n   - Review Prometheus metrics to identify bottlenecks.\n   - Consider increasing resources or optimizing the notification processing logic.\n\n### Logs and Debugging\n\n- Check the logs generated by the AuditService for any anomalies or unauthorized access attempts.\n\n!!! tip\n    Regularly review and optimize the notification processing logic to handle high loads efficiently and maintain HIPAA compliance."
}