# Notification Service — Detailed Design

| Field | Value |
|-------|-------|
| Document ID | DD-NOTIF-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |

---

## 1. Service Overview

The Notification Service sends email and SMS notifications for individual orders using Jinja2-based templates with Japanese language content.

---

## 2. API Endpoints

### 2.1 POST /api/v1/notifications/email — Send Email

Sends email notification for a **SINGLE** order. No bulk email capability. Rate limited to 10 per second.

**Request:**
```json
{
    "order_id": 1,
    "to_email": "tanaka@example.co.jp",
    "template_name": "ORDER_CONFIRMATION",
    "template_data": {"order_id": 1, "customer_name": "田中太郎", "total_amount": 179600, "currency": "JPY", "item_count": 2}
}
```

### 2.2 POST /api/v1/notifications/sms — Send SMS

Same pattern. Single order per call.

### 2.3 GET /api/v1/notifications/{notification_id}

### 2.4 GET /api/v1/notifications/order/{order_id}

Returns all notifications for an order (may be multiple — confirmation, shipped, etc.).

---

## 3. Data Model

```mermaid
erDiagram
    notification_templates {
        int id PK
        string name UK "ORDER_CONFIRMATION|ORDER_SHIPPED|ORDER_CANCELLED"
        string subject_template
        text body_template "Jinja2 format"
        enum channel "EMAIL|SMS"
        string language "ja"
    }
    notifications {
        int id PK
        int order_id "NOT unique - multiple per order"
        enum channel "EMAIL|SMS"
        string template_name
        string recipient
        string subject
        text body
        enum status "PENDING|SENT|FAILED"
        datetime sent_at
        datetime created_at
    }
```

> **Schema Note:** `order_id` is NOT unique — an order can have multiple notifications (confirmation, shipped, cancelled). However, there is **no batch_id column** for tracking grouped notification sends.

---

## 4. Template System

### 4.1 Default Templates (Japanese)

| Name | Subject | Channel |
|------|---------|---------|
| ORDER_CONFIRMATION | ご注文確認 — 注文番号 #{{ order_id }} | EMAIL |
| ORDER_SHIPPED | 発送のお知らせ — 注文番号 #{{ order_id }} | EMAIL |
| ORDER_CANCELLED | ご注文キャンセルのお知らせ — 注文番号 #{{ order_id }} | EMAIL |

### 4.2 Template Rendering

Templates use Jinja2 syntax. Variables are passed via `template_data` in the API request. Rendering happens **per-notification** — there is no batch template rendering optimization.

---

## 5. Notification Flow

```mermaid
sequenceDiagram
    participant OS as Order Service
    participant NS as Notification Service
    participant DB as Notification DB

    OS->>NS: POST /api/v1/notifications/email
    Note over NS: Lookup template by name
    Note over NS: Render subject + body (Jinja2)
    NS->>DB: INSERT notification (status: SENT)
    Note over NS: Mock email send (log)
    NS-->>OS: 201 Created
```

---

## 6. Rate Limiting

| Parameter | Value |
|-----------|-------|
| Max rate | **10 notifications per second** |
| Scope | Global (all channels combined) |
| Enforcement | Application-level |
| Queuing | **None — no queue exists** |

> **Bulk Impact:** Processing 10,000 order notifications at 10/second rate limit = minimum **1,000 seconds (~17 minutes)**. This rate limit is a significant bottleneck for any future bulk operation.

---

## 7. Current Limitations

| ID | Limitation | Severity |
|----|-----------|----------|
| DD-NTF-LIM-001 | **Single order notification per API call.** No bulk notification endpoint. Each notification requires a separate HTTP request. | High |
| DD-NTF-LIM-002 | **No batch email/SMS sending capability.** Cannot send notifications to multiple recipients in a single call. | High |
| DD-NTF-LIM-003 | **Rate limit of 10/second creates severe bottleneck for bulk operations.** 10,000 notifications would take ~17 minutes. | High |
| DD-NTF-LIM-004 | **No batch template rendering optimization.** Templates are rendered one-by-one per notification. | Medium |
| DD-NTF-LIM-005 | **No queue-based async sending.** All notifications are sent synchronously within the HTTP request. Adding async/queue processing would require architectural changes. | High |
| DD-NTF-LIM-006 | **No batch_id for grouped notifications.** Cannot correlate which notifications belong to the same bulk import batch. | Medium |