# Notification & Alert Microservice - Final Comprehensive Specification

## Document Overview
This is the **single source of truth** for building a multi-tenant B2B notification platform. It combines the best features from all planning documents and provides a complete specification for implementation.

**Version**: 2.0  
**Last Updated**: 2025-12-03  
**Status**: Ready for Implementation

---

## Table of Contents
1. [Project Overview](#1-project-overview)
2. [Architecture](#2-architecture)
3. [Core Concepts & Terminology](#3-core-concepts--terminology)
4. [Data Models](#4-data-models)
5. [REST API Endpoints](#5-rest-api-endpoints)
6. [Authentication & Authorization](#6-authentication--authorization)
7. [Event Flow & Processing](#7-event-flow--processing)
8. [Module Structure](#8-module-structure)
9. [Background Jobs & Queues](#9-background-jobs--queues)
10. [Services](#10-services)
11. [Security Implementation](#11-security-implementation)
12. [Reliability & Edge Cases](#12-reliability--edge-cases)
13. [Performance Optimizations](#13-performance-optimizations)
14. [Billing & Quota Management](#14-billing--quota-management)
15. [Webhooks](#15-webhooks)
16. [Mobile SDK](#16-mobile-sdk)
17. [White-Label Features](#17-white-label-features)
18. [Logging & Monitoring](#18-logging--monitoring)
19. [Testing Strategy](#19-testing-strategy)
20. [Configuration](#20-configuration)
21. [Deployment Considerations](#21-deployment-considerations)
22. [Implementation Priority](#22-implementation-priority)

---

## 1. Project Overview

### 1.1 Purpose
Provide a **SaaS multi-tenant B2B notification platform** that allows multiple client applications (projects) to:
- Register and manage their own notification infrastructure
- Send events from their applications via API (with API key authentication)
- Configure custom rules and alerts for their users
- Deliver real-time notifications to mobile users via Pusher + push fallback
- Manage their own user base with role-based access control
- Track usage, manage quotas, and handle billing
- White-label the platform with custom branding

### 1.2 Goals
- **Multi-tenant architecture** with complete data isolation
- **Self-service project registration** and API key management
- **Per-project billing** and usage tracking
- **Scalable** to handle multiple high-volume clients
- **White-label capability** for client branding
- **Secure API authentication** per project (API key + secret)
- **Real-time audible alerts** with project-specific sounds
- **Mobile SDK** for easy client integration
- **Webhook support** for delivery confirmations
- **Developer portal** with comprehensive documentation

### 1.3 Target Users
1. **Platform Admins**: Manage all projects, billing, platform health
2. **Project Admins**: Manage their project's rules, users, roles, settings
3. **End Users**: Mobile app users who receive notifications
4. **External Applications**: Client backends that send events via API

---

## 2. Architecture

### 2.1 High-Level Components
- **Platform API**: Multi-tenant REST API with project isolation
- **Project Management Service**: Project registration, API keys, billing, quotas
- **Event Ingestion Layer**: Per-project event validation, routing, and quota checks
- **Rule Engine**: Project-scoped rule evaluation with DSL parser
- **Notification Delivery Service**: Pusher (real-time) + Push notifications (FCM/APNs fallback)
- **Platform Admin Panel**: Super admin dashboard for platform management
- **Client Admin Panel**: Per-project admin dashboard (white-labeled)
- **Mobile SDK**: Drop-in SDK for iOS/Android integration
- **Message Broker**: Redis Streams with project-based channels
- **Metrics & Analytics**: Per-project usage, delivery rates, performance tracking
- **Webhook Service**: Delivery of events to client webhooks
- **Billing Service**: Stripe integration for subscription management

### 2.2 Technology Stack

#### Backend Core
- **Framework**: NestJS (TypeScript)
- **Database**: MySQL with TypeORM
- **Cache/Message Broker**: Redis (Streams for events, cache for sessions, project-scoped keys)
- **Queue System**: BullMQ (for background jobs and retries, project-scoped queues)
- **Real-time**: Pusher (for server-side notification triggering, per-project credentials)
- **Authentication**: 
  - JWT with Passport.js (for admin/user access)
  - API Key + Secret (for external applications)
- **Validation**: class-validator, class-transformer
- **Logging**: Winston (with project context)
- **API Documentation**: Swagger/OpenAPI

#### External Services
- **Push Notifications**: FCM (Android), APNs (iOS) - fallback mechanism
- **File Storage**: S3/CDN for sound assets (project-scoped folders)
- **Billing**: Stripe for subscription management
- **Security**: Helmet, CORS, Rate limiting (per-project)

#### Additional Components
- **API Gateway**: Rate limiting, routing per project
- **Tenant Management**: Project isolation middleware
- **Usage Tracking**: Metrics collection per project
- **SDK Generator**: Auto-generate client libraries

### 2.3 Deployment Architecture
- **Horizontal scaling** of API servers
- **Dedicated Redis instances** per tier (free/paid) or shared with namespacing
- **Database read replicas** for query optimization
- **CDN** for sound assets
- **Queue workers** per project (enterprise) or shared with project context
- **Regional deployments** for global clients

---

## 3. Core Concepts & Terminology

### 3.1 Projects (Tenants)
- **Project**: A registered client application with isolated resources (users, rules, notifications, etc.)
- **API Key + Secret**: Per-project authentication credentials for external applications
- **Namespace**: Logical isolation boundary for all resources (database, Redis, storage)
- **Quota**: Per-project limits (events/month, notifications/month, users, rules, sounds)
- **Plan**: Subscription tier (free, starter, professional, enterprise)
- **Webhook**: Optional callback URL for delivery confirmations and events

### 3.2 Isolation Model
- **Database**: `projectId` column on all entities with foreign key constraints
- **Redis**: Namespaced keys (`project:{projectId}:*`) for cache, streams, rate limits
- **Pusher**: Per-project app instances or namespaced channels (`project-{projectId}-user-{userId}`)
- **Storage**: Project-scoped folders for sound assets (`sounds/{projectId}/`)
- **Queues**: Project context included in all job data

### 3.3 Authentication Levels
1. **Platform Level**: Super admin access (manages all projects, billing, platform health)
2. **Project Level**: Project admin access (manages their project's rules, users, roles)
3. **End User Level**: Mobile app users (receive notifications, authenticate via JWT)
4. **API Level**: Server-to-server (project's backend → platform API via API key + secret)

### 3.4 Core Entities
- **Event**: An incoming activity (pending transaction, balance update, etc.) emitted by an external application
- **Rule**: Admin-configurable condition (e.g., `event.type=='pending_tx' && event.amount > 10000`) - scoped to a project
- **Notification**: A message derived from an Event that is sent to users (via Pusher + optional push) - scoped to a project
- **Role**: User role (MD, Finance, Ops, Admin, Support, etc.) - scoped to a project
- **Transfer Bucket**: Account/ledger that funds transfers; rules reference its balance - scoped to a project
- **Webview Action**: Notification action that opens a URL within the app; address bar is editable

---

## 4. Data Models

### 4.1 Project Entity
```typescript
{
  id: UUID (VARCHAR(36))
  name: VARCHAR(255)
  slug: VARCHAR(100) (unique, URL-safe)
  
  // API Authentication
  apiKey: VARCHAR(64) (unique, indexed, format: pk_{env}_{random})
  apiSecret: VARCHAR(128) (hashed with bcrypt)
  
  // Status & Plan
  status: ENUM ('active', 'suspended', 'trial', 'cancelled', 'inactive')
  plan: ENUM ('free', 'starter', 'professional', 'enterprise')
  
  // Branding (White-Label)
  logoUrl: VARCHAR(500)
  brandColor: VARCHAR(7) (#HEX)
  customDomain: VARCHAR(255) (nullable)
  
  // Configuration
  webhookUrl: VARCHAR(500) (nullable)
  webhookSecret: VARCHAR(128) (nullable, for HMAC signature)
  pusherConfig: JSON {
    appId: string,
    key: string,
    secret: string,
    cluster: string
  }
  settings: JSON {
    defaultSound: string,
    rateLimitPerMinute: number,
    alertSuppressionWindow: { count: number, seconds: number }
  }
  
  // Quotas & Usage
  quotaEventsPerMonth: INT
  quotaNotificationsPerMonth: INT
  quotaUsers: INT
  quotaRules: INT
  quotaSounds: INT
  currentUsage: JSON {
    eventsThisMonth: number,
    notificationsThisMonth: number,
    activeUsers: number,
    lastResetAt: DATETIME
  }
  
  // Billing
  billingEmail: VARCHAR(255)
  stripeCustomerId: VARCHAR(100) (nullable)
  subscriptionId: VARCHAR(100) (nullable)
  
  // Metadata
  ownerId: UUID (foreign key to PlatformAdmin, nullable)
  description: TEXT
  createdAt: DATETIME
  updatedAt: DATETIME
  lastEventAt: DATETIME (nullable)
  
  INDEX on slug, apiKey, status, plan
}
```

### 4.2 ProjectApiKey Entity (Alternative: Multiple API Keys per Project)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  name: VARCHAR(255) (e.g., "Production Server", "Staging", "Webhook Service")
  key: VARCHAR(64) (unique, indexed, format: pk_{env}_{random})
  secret: VARCHAR(128) (hashed with bcrypt)
  permissions: JSON ['events:write', 'users:manage', 'notifications:read']
  status: ENUM ('active', 'revoked')
  lastUsedAt: DATETIME (nullable)
  expiresAt: DATETIME (nullable)
  ipWhitelist: JSON (array of IPs, nullable, enterprise only)
  createdBy: UUID (foreign key to User)
  createdAt: DATETIME
  
  INDEX on (projectId, status)
  UNIQUE INDEX on (key)
}
```

### 4.3 User Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  
  // Authentication
  email: VARCHAR(255) (unique within project)
  phone: VARCHAR(20) (unique within project)
  password: VARCHAR(255) (hashed with bcrypt, cost factor 12)
  
  // Profile
  fullName: VARCHAR(255)
  roles: JSON (array of strings, project-scoped roles)
  status: ENUM ('pending', 'active', 'disabled', 'unverified')
  
  // External Integration
  externalUserId: VARCHAR(255) (nullable, client's user ID for mapping)
  metadata: JSON (custom fields from client)
  
  // Notification Settings
  pushTokens: JSON { fcm: string, apns: string }
  pusherChannels: JSON (array of subscribed channels - cached in Redis)
  soundEnabled: TINYINT(1) (default true)
  
  createdAt: DATETIME
  updatedAt: DATETIME
  lastLoginAt: DATETIME (nullable)
  
  INDEX on projectId, email, phone, status, externalUserId
  UNIQUE constraint on (projectId, email)
  UNIQUE constraint on (projectId, phone)
  UNIQUE constraint on (projectId, externalUserId) where externalUserId is not null
}
```

### 4.4 Role Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  name: VARCHAR(100) (unique within project)
  permissions: JSON (array of strings)
  description: TEXT
  createdAt: DATETIME
  updatedAt: DATETIME
  
  INDEX on projectId, name
  UNIQUE constraint on (projectId, name)
}
```

### 4.5 Rule Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  name: VARCHAR(255)
  description: TEXT
  condition: TEXT (DSL expression, e.g., "event.type=='pending_tx' && event.amount > 10000")
  targetRoles: JSON (array of strings, project-scoped roles)
  sound: VARCHAR(255) (filename)
  priority: INT (higher = more important)
  active: TINYINT(1) (boolean)
  createdBy: UUID (foreign key to User)
  createdAt: DATETIME
  updatedAt: DATETIME
  
  INDEX on projectId, active, priority, createdBy
}
```

### 4.6 Event Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  type: VARCHAR(100) (indexed, e.g., 'pending_transaction', 'transfer_bucket_update')
  payload: JSON (event-specific data)
  source: VARCHAR(100) (e.g., 'transactions_service', 'webhook')
  
  // Client Tracking (for deduplication)
  clientEventId: VARCHAR(255) (nullable, client's event ID)
  clientTimestamp: DATETIME (nullable)
  
  receivedAt: DATETIME
  processedAt: DATETIME (nullable)
  
  INDEX on projectId, type, receivedAt
  UNIQUE INDEX on (projectId, clientEventId) where clientEventId is not null
}
```

Example pending_transaction payload:
```json
{
  "txId": "TX_123",
  "userId": "U_44",
  "userName": "Sarah Chinny",
  "amount": 5000,
  "currency": "NGN",
  "status": "pending",
  "meta": { "billType": "electricity" }
}
```

### 4.7 Notification Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  ruleId: UUID (foreign key to Rule)
  eventId: UUID (foreign key to Event)
  recipients: JSON (array of user UUIDs)
  title: VARCHAR(255)
  message: TEXT
  sound: VARCHAR(255) (filename)
  action: JSON {
    type: "open_webview",
    url: "string",
    editableAddressBar: true
  }
  delivered: TINYINT(1) (boolean)
  pusherEventSent: TINYINT(1) (boolean)
  acknowledgedBy: JSON (array of user UUIDs)
  
  // Delivery Tracking
  deliveryAttempts: INT (default 0)
  lastDeliveryAttempt: DATETIME (nullable)
  deliveryError: TEXT (nullable)
  
  createdAt: DATETIME
  deliveredAt: DATETIME (nullable)
  
  INDEX on projectId, ruleId, eventId, delivered, createdAt
}
```

### 4.8 AuditLog Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project, nullable for system-level logs)
  action: VARCHAR(100) (e.g., 'user.created', 'rule.updated', 'notification.sent')
  userId: UUID (nullable)
  resourceType: VARCHAR(50) (e.g., 'User', 'Rule', 'Notification')
  resourceId: UUID
  metadata: JSON
  ipAddress: VARCHAR(45)
  userAgent: TEXT
  timestamp: DATETIME
  
  INDEX on projectId, userId, resourceType, timestamp
}
```

### 4.9 TransferBucket Entity (Project-Scoped)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  name: VARCHAR(255)
  currentBalance: DECIMAL(19,4)
  threshold: DECIMAL(19,4)
  currency: VARCHAR(3)
  updatedAt: DATETIME
  
  INDEX on projectId, name
}
```

### 4.10 UsageMetrics Entity (Project Usage Tracking)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  period: DATE (YYYY-MM-DD for daily, YYYY-MM-01 for monthly)
  periodType: ENUM ('daily', 'monthly')
  
  eventsReceived: INT
  notificationsSent: INT
  notificationsDelivered: INT
  notificationsFailed: INT
  activeUsers: INT
  apiCalls: INT
  storageUsedBytes: BIGINT
  
  createdAt: DATETIME
  
  UNIQUE INDEX on (projectId, period, periodType)
}
```

### 4.11 PlatformAdmin Entity (Platform Management)
```typescript
{
  id: UUID (VARCHAR(36))
  email: VARCHAR(255) (unique)
  password: VARCHAR(255) (hashed with bcrypt)
  name: VARCHAR(255)
  role: ENUM ('super_admin', 'support', 'billing')
  status: ENUM ('active', 'disabled')
  lastLoginAt: DATETIME (nullable)
  createdAt: DATETIME
  updatedAt: DATETIME
}
```

### 4.12 WebhookLog Entity (Webhook Delivery Tracking)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  eventType: VARCHAR(100) (e.g., 'notification.delivered', 'quota.warning')
  payload: JSON
  responseStatus: INT (nullable)
  responseBody: TEXT (nullable)
  attemptNumber: INT
  success: TINYINT(1)
  error: TEXT (nullable)
  createdAt: DATETIME
  
  INDEX on projectId, createdAt, success
}
```

### 4.13 Sound Entity (Project-Scoped Sound Assets)
```typescript
{
  id: UUID (VARCHAR(36))
  projectId: UUID (foreign key to Project)
  name: VARCHAR(255)
  filename: VARCHAR(255)
  url: VARCHAR(500) (CDN URL)
  fileSize: BIGINT (bytes)
  mimeType: VARCHAR(50) (e.g., 'audio/mpeg', 'audio/ogg')
  duration: INT (seconds, nullable)
  createdAt: DATETIME
  updatedAt: DATETIME
  
  INDEX on projectId, name
}
```

---

## 5. REST API Endpoints

### 5.1 Platform Management Endpoints (Super Admin Only)
- `POST /api/v1/platform/projects` - Create new project
- `GET /api/v1/platform/projects` - List all projects (with pagination, filters)
- `GET /api/v1/platform/projects/:id` - Get project details
- `PUT /api/v1/platform/projects/:id` - Update project
- `DELETE /api/v1/platform/projects/:id` - Delete/suspend project
- `POST /api/v1/platform/projects/:id/regenerate-api-key` - Regenerate API key
- `GET /api/v1/platform/projects/:id/stats` - Get project statistics
- `GET /api/v1/platform/metrics` - Platform-wide metrics
- `POST /api/v1/platform/admins` - Create platform admin
- `GET /api/v1/platform/usage` - Usage analytics across all projects

### 5.2 Project Management Endpoints (Project Admin)
- `GET /api/v1/projects/me` - Get current project details
- `PUT /api/v1/projects/me` - Update project settings
- `POST /api/v1/projects/me/api-keys` - Generate new API key (if using ProjectApiKey entity)
- `GET /api/v1/projects/me/api-keys` - List API keys
- `DELETE /api/v1/projects/me/api-keys/:id` - Revoke API key
- `PUT /api/v1/projects/me/branding` - Update branding (logo, color, domain)
- `PUT /api/v1/projects/me/webhook` - Configure webhook URL and secret
- `GET /api/v1/projects/me/usage` - Get usage metrics and quotas
- `GET /api/v1/projects/me/billing` - Billing information and subscription

### 5.3 Event Ingestion Endpoints (API Key Auth)
**Option A: Path-based scoping (Grok approach)**
- `POST /api/v1/projects/:projectId/events` - Send event (requires API key header)
- `POST /api/v1/projects/:projectId/events/batch` - Send multiple events
- `GET /api/v1/projects/:projectId/events/:id` - Get event status

**Option B: Context-based scoping (Unified/Claude approach)**
- `POST /api/v1/events` - Send event (API key in header automatically scopes to project)
- `POST /api/v1/events/batch` - Send multiple events
- `GET /api/v1/events/:id` - Get event status

**Recommendation**: Use Option B (context-based) for cleaner API, but support both for flexibility.

### 5.4 Authentication Endpoints

#### User Authentication (Project-Scoped)
- `POST /api/v1/auth/register` - User registration (sets status to 'pending', requires project context)
- `POST /api/v1/auth/login` - Login with JWT token generation (project-scoped)
- `POST /api/v1/auth/refresh` - Refresh token endpoint
- `POST /api/v1/auth/logout` - Logout

#### Platform Admin Authentication
- `POST /api/v1/platform/auth/login` - Platform admin login
- `POST /api/v1/platform/auth/refresh` - Refresh token

### 5.5 User Management Endpoints (Project-Scoped)
- `POST /api/v1/users` - Create user (API key or admin, supports externalUserId)
- `GET /api/v1/users` - List users (project-scoped, with pagination and filters)
- `GET /api/v1/users/:id` - Get user details
- `PUT /api/v1/users/:id` - Update user
- `DELETE /api/v1/users/:id` - Delete user (soft delete)
- `POST /api/v1/users/sync` - Bulk sync users from client system
- `GET /api/v1/users/pending` - List pending users (Admin only)
- `POST /api/v1/users/:id/approve` - Approve user and assign roles
- `GET /api/v1/users/me` - Get current user profile
- `PUT /api/v1/users/me` - Update profile
- `PUT /api/v1/users/me/push-tokens` - Update push tokens
- `GET /api/v1/users/me/pusher-auth` - Generate Pusher auth signature for private channels

### 5.6 Rules Management Endpoints (Project-Scoped)
- `POST /api/v1/rules` - Create rule (Admin/RuleManager only)
- `GET /api/v1/rules` - List rules (with pagination and filters)
- `GET /api/v1/rules/:id` - Get single rule
- `PUT /api/v1/rules/:id` - Update rule
- `DELETE /api/v1/rules/:id` - Delete rule
- `POST /api/v1/rules/:id/test` - Test rule against sample event

### 5.7 Notifications Endpoints (Project-Scoped)
- `GET /api/v1/notifications` - Get user's notifications (with pagination, filters)
- `GET /api/v1/notifications/:id` - Get notification details
- `PUT /api/v1/notifications/:id/acknowledge` - Mark notification as acknowledged
- `POST /api/v1/notifications/:id/webview-action` - Log webview open action
- `GET /api/v1/notifications/unread-count` - Get unread notification count
- `GET /api/v1/notifications/stats` - Notification statistics (delivery rates, etc.)
- `DELETE /api/v1/notifications/:id` - Soft delete notification

### 5.8 Roles Management Endpoints (Project-Scoped)
- `POST /api/v1/roles` - Create role (Admin only)
- `GET /api/v1/roles` - List all roles
- `GET /api/v1/roles/:id` - Get role details
- `PUT /api/v1/roles/:id` - Update role
- `DELETE /api/v1/roles/:id` - Delete role

### 5.9 Audit & Analytics Endpoints (Project-Scoped)
- `GET /api/v1/audit` - Query audit logs (with filters: date, user, action, resourceType)
- `GET /api/v1/audit/export` - Export audit logs as CSV
- `GET /api/v1/analytics/delivery-rates` - Notification delivery analytics
- `GET /api/v1/analytics/user-engagement` - User engagement metrics

### 5.10 Transfer Buckets Endpoints (Project-Scoped)
- `GET /api/v1/transfer-buckets` - List buckets
- `GET /api/v1/transfer-buckets/:id` - Get bucket details
- `PUT /api/v1/transfer-buckets/:id/threshold` - Update threshold (Admin only)

### 5.11 Sound Management Endpoints (Project-Scoped)
- `POST /api/v1/sounds` - Upload sound (Admin only, file upload)
- `GET /api/v1/sounds` - List sounds
- `GET /api/v1/sounds/:id` - Get sound details
- `DELETE /api/v1/sounds/:id` - Delete sound (Admin only)

### 5.12 Health & Status Endpoints
- `GET /health` - Basic health check
- `GET /api/v1/status` - Detailed system status (Pusher connection, Redis, MySQL, queue health)
- `GET /api/v1/projects/me/status` - Project-specific status

---

## 6. Authentication & Authorization

### 6.1 API Key Authentication (Server-to-Server)

#### Option A: Single API Key per Project (Simpler)
Headers required:
```
X-API-Key: pk_live_abc123
X-API-Secret: sk_live_xyz789
Content-Type: application/json
```

#### Option B: Multiple API Keys per Project (More Flexible)
Headers required:
```
X-API-Key: pk_live_abc123
X-API-Secret: sk_live_xyz789
Content-Type: application/json
```

**Recommendation**: Start with Option A, add Option B (ProjectApiKey entity) later if needed.

Validation flow:
1. Extract API key and secret from headers
2. Hash the secret and query Project (or ProjectApiKey) table
3. Verify secret hash matches
4. Check project status (must be 'active')
5. Check permissions (if using ProjectApiKey)
6. Check quotas (events/month, rate limits)
7. Attach projectId to request context
8. Apply rate limits based on project plan

### 6.2 JWT Authentication (Admin/User)

#### Platform Admin JWT
```json
{
  "sub": "admin_id",
  "email": "admin@platform.com",
  "role": "super_admin",
  "type": "platform_admin",
  "iat": 1234567890,
  "exp": 1234567890
}
```

#### Project Admin/User JWT
```json
{
  "sub": "user_id",
  "projectId": "project_id",
  "email": "user@example.com",
  "roles": ["admin", "finance"],
  "type": "user",
  "iat": 1234567890,
  "exp": 1234567890
}
```

### 6.3 Tenant Isolation Middleware
Every request automatically filters by `projectId`:
- API key requests: projectId from API key lookup
- JWT requests: projectId from token payload
- All database queries: automatically include projectId filter
- All Redis keys: prefixed with `project:{projectId}:`

### 6.4 Guards
- **ApiKeyGuard**: Validates API key + secret, sets project context
- **JwtAuthGuard**: Validates JWT token, extracts project context
- **RolesGuard**: Checks user roles against required roles (within project)
- **ProjectGuard**: Ensures project exists and is active
- **PlatformAdminGuard**: Validates platform admin access

---

## 7. Event Flow & Processing

### 7.1 Client Application → Platform

```typescript
// Client's backend sends event
POST /api/v1/events
Headers: {
  "X-API-Key": "pk_live_abc123",
  "X-API-Secret": "sk_live_xyz789"
}
Body: {
  "type": "pending_transaction",
  "clientEventId": "tx_client_12345", // Optional deduplication
  "payload": {
    "userId": "user_44", // Client's user ID (maps to externalUserId)
    "amount": 5000,
    "currency": "NGN",
    "meta": {}
  },
  "timestamp": "2025-12-03T10:30:00Z"
}
```

### 7.2 Platform Processing Flow

1. **Authentication**: Validate API key + secret → resolve projectId
2. **Quota Check**: Verify project hasn't exceeded events/month quota
3. **Rate Limit Check**: Check per-minute rate limits
4. **Deduplication**: Check if clientEventId already processed (if provided)
5. **Validation**: Validate event schema and payload
6. **Storage**: Store event with projectId in database
7. **Streaming**: Publish to Redis Streams: `project:{projectId}:events`
8. **Background Processing**: Queue event for processing
9. **Rule Evaluation**: 
   - Fetch all active rules for the project
   - Evaluate event against each rule using RuleEngineService
   - For matched rules, determine recipients by role (within project)
10. **Notification Creation**: Create Notification records with projectId
11. **Delivery**:
    - If Pusher channel subscribed: trigger via Pusher using project's credentials
    - Else: queue for push notification (FCM/APNs)
12. **Webhook**: Send webhook to client (if configured)
13. **Metrics**: Update usage metrics (eventsReceived, notificationsSent)
14. **Audit**: Log all actions

### 7.3 Notification Delivery Flow

1. **Check User Status**: Verify user is active and has required role
2. **Check Pusher Subscription**: Query Redis for active Pusher channel
3. **Deliver via Pusher**: If subscribed, trigger notification using project's Pusher credentials
4. **Queue Push Notification**: If offline, queue for FCM/APNs
5. **Update Status**: Mark notification as delivered
6. **Webhook**: Send delivery confirmation webhook (if configured)
7. **Retry Logic**: If delivery fails, retry with exponential backoff

---

## 8. Module Structure

```
src/
├── modules/
│   ├── platform/              # Platform management (super admin)
│   │   ├── projects/
│   │   ├── admins/
│   │   ├── metrics/
│   │   └── billing/
│   ├── projects/              # Project CRUD and settings
│   ├── api-keys/              # API key management (if using ProjectApiKey)
│   ├── auth/                  # JWT and API key authentication
│   ├── users/                 # User management (project-scoped)
│   ├── roles/                 # Role management (project-scoped)
│   ├── rules/                 # Rule CRUD and RuleEngineService
│   ├── events/                # Event ingestion and processing
│   ├── notifications/         # Notification creation and delivery
│   ├── transfer-buckets/      # Bucket management (project-scoped)
│   ├── sounds/                # Sound upload and management
│   ├── audit/                 # Audit logging (project-scoped)
│   ├── usage/                 # Usage tracking and metrics
│   ├── webhooks/              # Webhook delivery service
│   └── analytics/             # Analytics and reporting
├── common/
│   ├── guards/
│   │   ├── api-key.guard.ts
│   │   ├── jwt-auth.guard.ts
│   │   ├── roles.guard.ts
│   │   ├── project.guard.ts
│   │   └── platform-admin.guard.ts
│   ├── decorators/
│   │   ├── current-user.decorator.ts
│   │   ├── current-project.decorator.ts
│   │   ├── roles.decorator.ts
│   │   └── public.decorator.ts
│   ├── middleware/
│   │   └── tenant-context.middleware.ts
│   ├── interceptors/
│   │   ├── project-context.interceptor.ts
│   │   ├── quota-check.interceptor.ts
│   │   └── logging.interceptor.ts
│   ├── filters/
│   │   └── global-exception.filter.ts
│   ├── pipes/
│   │   └── validation.pipe.ts
│   └── services/
│       └── project-context.service.ts
├── config/
├── database/
│   ├── entities/
│   └── migrations/
└── main.ts
```

---

## 9. Background Jobs & Queues (BullMQ)

All queues include project context in job data:

1. **event-processing-queue** - Process incoming events against rules (project-scoped)
2. **notification-delivery-queue** - Deliver notifications with retry (project-scoped)
3. **push-notification-queue** - Send push notifications (FCM/APNs, project-scoped)
4. **bucket-monitoring-queue** - Periodic check of transfer bucket balances (project-scoped)
5. **alert-suppression-queue** - Handle alert storm suppression (project-scoped)
6. **webhook-delivery-queue** - Deliver webhooks to clients (project-scoped)
7. **usage-metrics-queue** - Update usage metrics (project-scoped)

---

## 10. Services

### 10.1 RuleEngineService
- Parse and evaluate condition expressions safely
- Use `expr-eval` or `json-logic-js` library
- Support operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`
- Access event properties: `event.type`, `event.amount`, `event.payload.status`
- Prevent code injection with sandboxed evaluation

### 10.2 NotificationDeliveryService
- Check user Pusher channel subscription (query Redis, project-scoped)
- If subscribed: trigger via Pusher using project's Pusher credentials
- If offline: queue for push notification (BullMQ queue)
- Update notification.delivered status
- Handle retries with exponential backoff

### 10.3 PusherService
- Get Pusher client for project (from project.pusherConfig)
- Cache Pusher clients per project
- Trigger notifications on project-specific channels
- Batch trigger for multiple users
- Handle errors and retries

### 10.4 PushNotificationService
- Integration with Firebase Cloud Messaging (FCM) for Android
- Integration with Apple Push Notification Service (APNs) for iOS
- Fallback when Pusher unavailable
- Support project-specific FCM/APNs credentials (enterprise)

### 10.5 SoundManagementService
- Upload sound files to S3/CDN (project-scoped folders)
- Generate signed URLs with TTL
- Validate audio formats (mp3, ogg, wav)
- Enforce file size limits per plan

### 10.6 QuotaService
- Check project quotas (events, notifications, users, etc.)
- Update usage metrics
- Enforce hard limits (reject requests)
- Send quota warning emails (at 80%)
- Reset monthly quotas

### 10.7 WebhookService
- Deliver webhooks to client webhookUrl
- Generate HMAC signature using webhookSecret
- Retry with exponential backoff
- Log all webhook attempts
- Handle timeouts and errors

### 10.8 UsageTrackingService
- Track events received per project
- Track notifications sent per project
- Track active users per project
- Generate daily and monthly metrics
- Update UsageMetrics entity

---

## 11. Security Implementation

1. **Helmet** for HTTP headers security
2. **CORS** configuration for allowed origins
3. **Rate limiting** using `@nestjs/throttler` (per-project rate limits)
4. **Password hashing** with bcrypt (cost factor 12)
5. **API Key Authentication**:
   - API keys and secrets stored as hashed values
   - Validate on event ingestion endpoints
   - Automatically scope requests to project
   - Support IP whitelisting (enterprise)
6. **Input validation** using class-validator on all DTOs
7. **SQL injection prevention** via TypeORM parameterized queries
8. **XSS protection** by sanitizing inputs
9. **Role-based guards** on all sensitive endpoints
10. **JWT tokens** with short-lived access tokens and refresh tokens
11. **Project isolation** - ensure all queries are scoped to project
12. **TLS** for all traffic (HTTPS and WSS)
13. **Webhook security** - HMAC signature verification
14. **Audit logging** for all sensitive operations

---

## 12. Reliability & Edge Cases

### 12.1 Delivery Guarantees
- Use durable message broker + worker retries (exponential backoff)
- Notification status: pending -> sent -> acked -> failed
- At-least-once delivery semantics

### 12.2 Offline Users
- Queue notifications; deliver via Push (FCM/APNs) for backgrounded users
- On next connection, provide API to fetch missed notifications
- Mark notifications as delivered when Pusher confirms

### 12.3 Throttling & Deduplication
- Deduplicate events by clientEventId (if provided)
- If multiple rules fire for same event for same user: merge into single notification (preferred)
- Per-project rate limiting

### 12.4 Alert Storms
- Implement "alert suppression window" (configurable per project)
- If rule triggers > N times in M seconds for same scope, suppress or batch
- Configurable in project.settings

### 12.5 Bad Sound URLs / Missing Assets
- Fallback to default sound in Notification record
- Log missing asset
- Use project.defaultSound from project.settings

### 12.6 Quota Exceeded
- Soft limit: warning at 80% usage (email + webhook)
- Hard limit: reject requests at 100% quota
- Grace period before suspension
- Auto-upgrade prompts

---

## 13. Performance Optimizations

- **MySQL indexing**: Composite indexes including projectId on all frequently queried fields
- **Redis caching**: Project-scoped cache keys for active users, rules, Pusher subscriptions
- **Connection pooling**: Optimize MySQL and Redis connection pools
- **Batch processing**: Batch Pusher triggers, database inserts, notification delivery
- **Query optimization**: Use projectId index in all queries
- **CDN**: Serve sound assets from CDN with caching
- **Read replicas**: Use database read replicas for analytics queries

---

## 14. Billing & Quota Management

### 14.1 Plan Tiers
```typescript
{
  free: {
    eventsPerMonth: 1000,
    notificationsPerMonth: 5000,
    users: 100,
    rules: 5,
    sounds: 3,
    webhook: false,
    customDomain: false,
    price: 0
  },
  starter: {
    eventsPerMonth: 50000,
    notificationsPerMonth: 100000,
    users: 1000,
    rules: 25,
    sounds: 10,
    webhook: true,
    customDomain: false,
    price: 49 // USD/month
  },
  professional: {
    eventsPerMonth: 500000,
    notificationsPerMonth: 1000000,
    users: 10000,
    rules: 100,
    sounds: 50,
    webhook: true,
    customDomain: true,
    price: 199
  },
  enterprise: {
    eventsPerMonth: "unlimited",
    notificationsPerMonth: "unlimited",
    users: "unlimited",
    rules: "unlimited",
    sounds: "unlimited",
    webhook: true,
    customDomain: true,
    dedicatedSupport: true,
    sla: true,
    price: "custom"
  }
}
```

### 14.2 Usage Enforcement
- Real-time quota checks on event ingestion
- Soft limit: warning at 80% usage (email + webhook)
- Hard limit: reject requests at 100%
- Email notifications to billing contact
- Grace period before suspension

### 14.3 Billing Integration
- Stripe for subscription management
- Monthly billing cycle
- Overage charges for exceeded quotas (configurable)
- Webhook for payment failures → suspend project
- Invoice generation

---

## 15. Webhooks

### 15.1 Webhook Events
```typescript
{
  "event": "notification.delivered",
  "projectId": "project_123",
  "timestamp": "2025-12-03T10:30:00Z",
  "data": {
    "notificationId": "notif_456",
    "userId": "user_44",
    "eventId": "event_789",
    "status": "delivered",
    "deliveredAt": "2025-12-03T10:30:05Z"
  },
  "signature": "sha256=..." // HMAC signature for verification
}
```

### 15.2 Event Types
- `notification.delivered`
- `notification.failed`
- `notification.acknowledged`
- `user.registered`
- `quota.warning` (80% usage)
- `quota.exceeded`
- `project.suspended`
- `project.activated`

### 15.3 Webhook Security
- HMAC signature using webhookSecret
- Retry logic with exponential backoff
- Timeout configuration (default 30s)
- IP whitelisting option (enterprise)

---

## 16. Mobile SDK

### 16.1 SDK Features
- Easy initialization with API key
- User registration/authentication
- Pusher channel subscription
- Notification reception and display
- Sound playback
- Webview integration
- Acknowledgment callbacks
- Offline queue management

### 16.2 SDK Usage Example (React Native)
```javascript
import NotificationSDK from '@your-platform/notification-sdk';

// Initialize
const sdk = NotificationSDK.init({
  apiKey: 'pk_live_abc123',
  projectId: 'project_123'
});

// Register user
await sdk.users.register({
  email: 'user@example.com',
  externalUserId: 'user_44',
  roles: ['user']
});

// Listen for notifications
sdk.notifications.onReceived((notification) => {
  sdk.sounds.play(notification.sound);
  showInAppBanner(notification);
});

// Acknowledge
sdk.notifications.acknowledge(notificationId);
```

### 16.3 SDK Platforms
- iOS (Swift)
- Android (Kotlin/Java)
- React Native
- Flutter

---

## 17. White-Label Features

### 17.1 Branding Support
- Upload project logo
- Custom primary color
- Custom domain (CNAME: admin.clientdomain.com → platform)
- Email templates with project branding
- Customizable notification templates

### 17.2 Admin Panel Customization
- Project-specific admin panel URL
- Custom domain support (enterprise)
- Branded email notifications
- Custom notification templates

---

## 18. Logging & Monitoring

### 18.1 Logging
- Use Winston for structured logging
- Log levels: error, warn, info, debug
- Include correlation IDs and project context
- Audit all authentication attempts, rule changes, notification deliveries
- Retention policy: logs for 90 days in hot store, archived beyond

### 18.2 Monitoring
- Per-project metrics dashboards
- Alerting for quota breaches
- Delivery rate monitoring
- API latency per project
- Error tracking with project context
- Platform-wide health monitoring

---

## 19. Testing Strategy

- **Unit tests**: Services, guards, decorators (with project context mocks)
- **Integration tests**: Controllers, database operations (with project isolation)
- **E2E tests**: Critical flows (auth, rule evaluation, notification delivery)
- **Project isolation tests**: Verify data doesn't leak between projects
- **Mock external services**: FCM, APNs, Redis, Pusher, Stripe

---

## 20. Configuration

Use `@nestjs/config` for:
- Database connection (MySQL)
- Redis connection (cache and streams)
- JWT secrets and expiration
- Pusher configuration (global or per-project)
- FCM/APNs credentials (global or per-project)
- Rate limiting thresholds (per plan)
- Alert suppression windows
- Audit log retention policy
- CDN/S3 configuration for sound files
- Stripe API keys
- Webhook timeout and retry settings

---

## 21. Deployment Considerations

- Docker containerization with multi-stage build
- Health check endpoint: `GET /health`
- Graceful shutdown handling
- Environment-based configuration
- Separate worker processes for queue consumers
- Horizontal scaling support
- Database migration strategy
- Zero-downtime deployments

---

## 22. Implementation Priority

### Phase 1: Core Multi-Tenant Foundation (Weeks 1-2)
1. Project setup with TypeORM + Redis
2. Project entity and platform admin auth
3. API key authentication system (single key per project)
4. Tenant isolation middleware and guards
5. Basic event ingestion (API key auth)
6. Project context service

### Phase 2: Notification Engine (Weeks 3-4)
7. Multi-tenant rules engine
8. Project-scoped users and roles
9. Notification creation and delivery
10. Pusher integration (project-specific credentials)
11. Basic admin panel authentication (project-scoped)

### Phase 3: Core Features (Weeks 5-6)
12. Event processing and rule evaluation
13. Notification delivery (Pusher + push fallback)
14. Transfer buckets and monitoring
15. Sound management
16. Audit logging

### Phase 4: Platform Features (Weeks 7-8)
17. Usage tracking and quotas
18. Quota enforcement
19. Platform admin dashboard
20. Project management endpoints

### Phase 5: Advanced Features (Weeks 9-10)
21. Webhook delivery system
22. Billing integration (Stripe)
23. Analytics and reporting
24. White-label branding

### Phase 6: SDK & Polish (Weeks 11-12)
25. Mobile SDK (iOS/Android)
26. Developer portal
27. Comprehensive documentation
28. Performance optimization
29. Security audit
30. Load testing

---

## Key Implementation Notes

1. **All entities must include `projectId`** - Foundation of multi-tenancy
2. **All queries must be project-scoped** - Use base repository or query builder
3. **API key authentication** - External apps use API key + secret, automatically sets project context
4. **JWT tokens include project context** - User tokens include projectId
5. **Pusher credentials are project-specific** - Each project has its own Pusher config
6. **Rate limiting is per-project** - Use project-scoped Redis keys
7. **All endpoints (except platform management) are project-scoped**
8. **Project isolation testing** - Critical to test data doesn't leak between projects
9. **Cache keys are project-scoped** - Use `project:{projectId}:*` pattern
10. **Queue jobs include project context** - All background jobs must include projectId

---

## API Endpoint Scoping Options

**Recommended Approach**: Context-based scoping (cleaner API)
- API key in header automatically sets project context
- All endpoints are project-scoped by context
- No need for `/projects/:projectId/` prefix in most endpoints

**Alternative Approach**: Path-based scoping (more explicit)
- Use `/api/v1/projects/:projectId/` prefix for project-scoped endpoints
- More explicit but verbose
- Can support both for flexibility

---

## Success Metrics

Track per project:
- Event ingestion rate
- Notification delivery rate
- Average delivery latency
- User engagement (acknowledgment rate)
- API error rate
- Webhook success rate
- Quota utilization

Platform-wide:
- Total projects
- Monthly recurring revenue (MRR)
- Churn rate
- Average events per project
- Support ticket volume
- System uptime

---

**This specification is complete and ready for implementation. All features from Claude, Grok, Unified Specification, and Development Plan have been integrated.**