Skip to content

Latest commit

 

History

History
319 lines (263 loc) · 11.3 KB

notification_service.md

File metadata and controls

319 lines (263 loc) · 11.3 KB

Notification Service

Overview

The Notification Service is a minimal multi-channel notification system for the trading platform. It provides basic notification tracking with mock implementations for local development. The service runs on port 8005 and integrates with the platform through Kafka messaging and gateway routing.

Service Architecture

Core Components

  • FastAPI Application: Simple REST API on port 8005
  • NotificationSender: Mock notification delivery with logging
  • In-Memory Storage: Temporary notification status tracking
  • Gateway Integration: Kafka-based notification requests through gateway

Current Implementation Status

  • ✅ Basic Infrastructure: FastAPI app with health check
  • ✅ Mock Notifications: Email, SMS, Slack simulation with logging
  • ✅ Status Tracking: In-memory notification status storage
  • ✅ Gateway Integration: Kafka-based request handling through gateway
  • ❌ Real Delivery: No actual email/SMS/push delivery implemented

Implemented Endpoints

The service currently implements 2 direct endpoints:

1. Health Check

GET /health

Response: Service status and health information

2. Notification Status

GET /status/{notification_id}

Purpose: Get status of a previously sent notification Response: Status, timestamp, and delivery channels

Gateway Integration (Primary Interface)

The notification service is primarily accessed through the gateway (port 8000) via Kafka messaging:

Available Through Gateway (Port 8000)

POST /api/notifications/send
GET /api/notifications/status/{notification_id}
GET /api/notifications/history
POST /api/notifications/subscribe

Gateway → Service Flow

  1. Client Request → Gateway (8000)
  2. Gateway → Kafka Topic (notification.send.request)
  3. Kafka Consumer → Notification Service (8005)
  4. Service → Mock delivery + status storage
  5. Response → Gateway → Client

Data Models and Request Formats

Notification Request (via Gateway)

{
  "message": "Your AAPL trade was executed at $150.25",
  "priority": "medium",
  "channels": ["email", "sms", "slack"],
  "metadata": {
    "symbol": "AAPL",
    "action": "buy",
    "price": 150.25
  }
}

Supported Channels: email, sms, slack, discord Priority Levels: low, medium, high, critical

Notification Response

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "sent_at": "2025-11-01T10:30:00Z",
  "channels_sent": ["email", "sms", "slack"]
}

Status Response (Direct Service)

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "sent_at": "2025-11-01T10:30:00.123456",
  "channels_sent": ["email", "sms"]
}

Mock Notification Implementation

Current Delivery Behavior

All notification channels are mock implementations that:

  • ✅ Log to console: Detailed logging of notification attempts
  • ✅ Store status: In-memory tracking with unique IDs
  • ✅ Simulate delivery: Immediate "sent" status for all channels
  • ❌ No actual delivery: No real emails, SMS, or push notifications sent

Supported Mock Channels

Email Simulation

# Mock email delivery
async def _send_email(self, message: str, priority: str):
    logger.info("Email sent", message=message[:50])

SMS Simulation

# Mock SMS delivery
async def _send_sms(self, message: str, priority: str):
    logger.info("SMS sent", message=message[:50])

Slack Simulation

# Mock Slack delivery
async def _send_slack(self, message: str, priority: str):
    logger.info("Slack message sent", message=message[:50])

In-Memory Status Tracking

# Stored notification status
{
  "notification_id": "uuid-string",
  "status": "sent",
  "sent_at": datetime.utcnow(),
  "channels_sent": ["email", "sms", "slack"]
}

Development Setup

Local Development

# Option 1: Direct execution
cd services/notification_service
python main.py
# Service starts on http://127.0.0.1:8005

# Option 2: From project root
cd E:\app\trading-agent
uvicorn services.notification_service.main:app --host 0.0.0.0 --port 8005 --reload

Dependencies

# Minimal dependencies
pip install fastapi uvicorn structlog

Automatic Configuration

  • ✅ Zero external dependencies: No SMTP, Twilio, or Firebase setup needed
  • ✅ Smart import handling: Works for direct execution or module usage
  • ✅ Instant startup: No initialization delays or external connections
  • ✅ Full functionality: Complete API without external service dependencies

Testing the Service

Direct Service Testing (Port 8005)

# Health check
curl http://127.0.0.1:8005/health
# Response: {"status": "healthy", "service": "notification_service"}

# Check notification status (requires existing notification_id)
curl http://127.0.0.1:8005/status/550e8400-e29b-41d4-a716-446655440000

Gateway Testing (Port 8000) - Primary Interface

# Send notification through gateway
curl -X POST http://127.0.0.1:8000/api/notifications/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Test trading alert: AAPL position opened",
    "priority": "medium",
    "channels": ["email", "sms"],
    "metadata": {"symbol": "AAPL", "action": "buy"}
  }'

# Get notification status through gateway
curl http://127.0.0.1:8000/api/notifications/status/{notification_id}

# Get notification history
curl http://127.0.0.1:8000/api/notifications/history

Expected Console Output

[INFO] Notification Service starting up
[INFO] Notification sender initialized
[INFO] Email sent message=Test trading alert: AAPL position opene
[INFO] SMS sent message=Test trading alert: AAPL position opene
[INFO] Notification sent notification_id=550e8400-e29b-41d4-a716-446655440000 channels=['email', 'sms']

Integration with Trading Platform

Service Dependencies

  • Gateway Service (8000): Routes notification requests via Kafka
  • Trading Service (8001): Sends trade execution notifications
  • Risk Service (8004): Sends risk alerts and warnings
  • Other Services: Can send system alerts through Kafka

Kafka Integration

# Kafka topics used
- "notification.send.request" - Incoming notification requests
- "notification.status.update" - Status updates (if implemented)

Data Flow

Client Request → Gateway (8000) → Kafka → Notification Service (8005) → Mock Delivery → Status Storage
                     ↓
Trading Service (8001) → Kafka → Notification Service (8005) → Mock Alerts

Architecture Position

Current Role

  • Mock Service: Provides notification infrastructure without actual delivery
  • Development Support: Enables testing notification flows without external dependencies
  • Status Tracking: Basic in-memory notification history
  • Kafka Consumer: Processes requests from other services

Service Integration Pattern

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Gateway       │    │     Kafka       │    │  Notification   │
│   (8000)        │───▶│   Message Bus   │───▶│   Service       │
│                 │    │                 │    │   (8005)        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        ▲                        ▲                        │
        │                        │                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Client       │    │   Trading       │    │   Mock          │
│   Applications  │    │   Service       │    │   Delivery      │
│                 │    │   (8001)        │    │   + Logging     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Current Limitations

Implementation Constraints

  1. No Real Delivery: All notifications are mock/logged only
  2. In-Memory Storage: Status lost on service restart
  3. Limited Channels: Only email/sms/slack simulation implemented
  4. No Templates: No message formatting or templating system
  5. No Scheduling: No delayed or scheduled notifications
  6. No Retries: No delivery retry mechanisms

Development Stage

  • ✅ Basic Infrastructure: Service framework and routing
  • ✅ Mock Implementations: Console logging for all channels
  • ✅ Status Tracking: Basic in-memory notification status
  • ✅ Gateway Integration: Kafka-based request handling
  • ❌ Real Delivery: No actual email/SMS/push implementations
  • ❌ Persistence: No database storage for notifications
  • ❌ Advanced Features: No templates, scheduling, or retries

Future Implementation Requirements

Production Readiness

  1. Real Delivery Providers:

    • SMTP for email (Gmail, SendGrid, etc.)
    • Twilio for SMS
    • Firebase for push notifications
    • Webhook delivery for integrations

  2. Data Persistence:

    • PostgreSQL/SQLite database for notification history
    • Status tracking with delivery confirmations
    • Failed delivery logging and retry mechanisms

  3. Advanced Features:

    • HTML email templates
    • Message scheduling and queuing
    • Delivery rate limiting
    • A/B testing for message formats

  4. Monitoring & Analytics:

    • Delivery success/failure rates
    • Channel performance metrics
    • User engagement tracking

Summary

The Notification Service is a basic infrastructure service that provides:

✅ Current Capabilities

  • 2 direct endpoints for health check and status lookup
  • Gateway integration with 4 proxied endpoints via Kafka
  • Mock delivery for email, SMS, and Slack channels
  • Status tracking with in-memory storage
  • Development-friendly with zero external dependencies
  • Console logging for all notification attempts

⚠️ Development Stage Features

  • Mock-only delivery: No actual notifications sent
  • In-memory storage: Status tracking without persistence
  • Basic infrastructure: Service framework ready for real implementations
  • Kafka integration: Proper message bus connectivity

❌ Not Yet Implemented

  • Real notification delivery (email, SMS, push, webhooks)
  • Database persistence for notification history
  • Message templates and formatting
  • Delivery retries and error handling
  • Scheduling and queuing systems

This service provides the notification infrastructure foundation for the trading platform, with proper integration patterns established but requiring production delivery implementations for real-world use.