# High-Level Design

| Field | Value |
|-------|-------|
| Document ID | HLD-ECOM-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |
| Author | Suzuki Ichiro (Technical Director) |

---

## 1. Architecture Overview

The E-Commerce platform follows a microservice architecture with three independently deployable services, each owning its own database (Database-per-Service pattern).

```mermaid
graph TB
    FE[Frontend Admin Dashboard<br/>:5173] --> OS[Order Service<br/>:8000]
    FE --> PS[Payment Service<br/>:8001]
    FE --> NS[Notification Service<br/>:8002]

    OS --> OS_DB[(Order DB<br/>SQLite)]
    PS --> PS_DB[(Payment DB<br/>SQLite)]
    NS --> NS_DB[(Notification DB<br/>SQLite)]

    OS -->|POST /api/v1/payments| PS
    OS -->|POST /api/v1/notifications/email| NS
    PS -->|POST /api/v1/orders/{id}/webhook| OS
```

---

## 2. Service Registry

| Service | Port | Tech Stack | Database | Responsibility |
|---------|------|-----------|----------|----------------|
| Order Service | 8000 | Python 3.12, FastAPI, SQLAlchemy async | SQLite (order_service.db) | Order CRUD, status lifecycle, cross-service orchestration |
| Payment Service | 8001 | Python 3.12, FastAPI, SQLAlchemy async | SQLite (payment_service.db) | Payment processing, refunds, amount validation, webhooks |
| Notification Service | 8002 | Python 3.12, FastAPI, SQLAlchemy async | SQLite (notification_service.db) | Email/SMS via Jinja2 templates, delivery tracking |
| Frontend Admin Dashboard | 5173 | React 19, TypeScript, Vite, Tailwind CSS | None (stateless SPA) | Web-based admin UI, dashboards, order management |

---

## 3. Communication Patterns

All inter-service communication uses **synchronous REST over HTTP**. There is no message broker, event bus, or async communication channel.

| Pattern | Usage | Timeout |
|---------|-------|---------|
| Synchronous REST | All cross-service calls | 30s (payment), 10s (notification/webhook) |
| Webhook (REST callback) | Payment → Order status update | 10s |

---

## 4. Service Dependency Matrix

| Caller | Callee | Endpoint | Method | Pattern | Purpose |
|--------|--------|----------|--------|---------|---------|
| Order Service | Payment Service | /api/v1/payments | POST | Sync REST | Process payment on order creation |
| Order Service | Payment Service | /api/v1/payments/refund | POST | Sync REST | Refund on order cancellation |
| Order Service | Payment Service | /api/v1/payments/order/{order_id} | GET | Sync REST | Get payment for refund lookup |
| Order Service | Notification Service | /api/v1/notifications/email | POST | Sync REST | Send confirmation/shipped/cancelled email |
| Payment Service | Order Service | /api/v1/orders/{order_id}/webhook | POST | Webhook | Notify payment status change |
| Frontend | Order Service | /api/v1/orders | GET/POST/DELETE | Sync REST | Order management UI |
| Frontend | Payment Service | /api/v1/payments/order/{order_id} | GET | Sync REST | Payment details display |
| Frontend | Notification Service | /api/v1/notifications/order/{order_id} | GET | Sync REST | Notification log display |

**Dependency Direction:** Order Service is the primary orchestrator. It depends on both Payment and Notification services. Payment Service has a reverse dependency on Order Service for webhook callbacks.

---

## 5. Data Flow Diagrams

### 5.1 Order Creation Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant OS as Order Service
    participant PS as Payment Service
    participant NS as Notification Service

    C->>OS: POST /api/v1/orders
    Note over OS: Validate order data (single order)
    Note over OS: Calculate total_amount
    Note over OS: Save order (status: PENDING)
    OS->>OS: Update status → PAYMENT_PROCESSING

    OS->>PS: POST /api/v1/payments
    Note over PS: Validate amount (100 - 1,000,000 JPY)
    Note over PS: Check duplicate order_id
    Note over PS: Process payment
    PS-->>OS: 201 Created (payment details)

    OS->>OS: Update status → PAID

    OS->>NS: POST /api/v1/notifications/email
    Note over NS: Render ORDER_CONFIRMATION template
    Note over NS: Send email (mock)
    NS-->>OS: 201 Created (notification details)

    OS-->>C: 201 Created (order with items)
```

> **NOTE:** This flow processes ONE order at a time. Each step is sequential — Payment must complete before Notification is called. There is no parallel processing and no batch capability.

### 5.2 Order Cancellation Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant OS as Order Service
    participant PS as Payment Service
    participant NS as Notification Service

    C->>OS: DELETE /api/v1/orders/{id}
    Note over OS: Update status → CANCELLED

    OS->>PS: GET /api/v1/payments/order/{order_id}
    PS-->>OS: Payment details
    OS->>PS: POST /api/v1/payments/refund
    Note over PS: Process refund for single payment
    PS-->>OS: 201 Created (refund details)

    OS->>NS: POST /api/v1/notifications/email
    Note over NS: Render ORDER_CANCELLED template
    NS-->>OS: 201 Created

    OS-->>C: 200 OK (cancelled order)
```

### 5.3 Payment Webhook Flow

```mermaid
sequenceDiagram
    participant PG as Payment Gateway
    participant PS as Payment Service
    participant OS as Order Service

    PG->>PS: POST /api/v1/payments/webhook
    Note over PS: Update payment status
    PS->>OS: POST /api/v1/orders/{id}/webhook
    Note over OS: Update order status based on payment result
    OS-->>PS: 200 OK
    PS-->>PG: 200 OK
```

---

## 6. Data Architecture

### 6.1 Database-per-Service Pattern

Each service owns its database exclusively. There are **no cross-service foreign keys** and **no shared database**. Data consistency across services is maintained through eventual consistency via API calls.

| Service | Database File | Tables |
|---------|--------------|--------|
| Order Service | order_service.db | orders, order_items |
| Payment Service | payment_service.db | payments, refunds |
| Notification Service | notification_service.db | notification_templates, notifications |

### 6.2 Data Ownership

- **Order Service** owns all order and order item data. It does not store payment or notification details.
- **Payment Service** owns payment and refund records. It references `order_id` as a logical reference (not a foreign key).
- **Notification Service** owns notification records and templates. It references `order_id` as a logical reference.

---

## 7. Cross-Service Contract Summary

### 7.1 API Versioning

All APIs use version prefix `/api/v1/`. Breaking changes require a new version.

### 7.2 Error Handling

Each service returns errors in a consistent format:
```json
{
    "detail": "Error description"
}
```

HTTP status codes: 400 (validation error), 404 (not found), 422 (schema validation), 500 (internal error).

### 7.3 Timeouts

| Call | Timeout | Retry |
|------|---------|-------|
| Order → Payment | 30 seconds | No retry (fail-open) |
| Order → Notification | 10 seconds | No retry (fail-open) |
| Payment → Order webhook | 10 seconds | No retry |

> **NOTE:** There is no retry mechanism or circuit breaker. If a downstream service is unavailable, the call fails silently (logged but not retried). This is a known limitation.

---

## 8. Known Limitations and Impact Areas

### 8.1 Single-Order Processing Only

All cross-service communication handles **single orders**. The API contracts, database schemas, and business logic assume one-order-at-a-time processing.

### 8.2 Impact of Adding Bulk Operations

Adding bulk order import (e.g., CSV upload for 100–10,000 orders) would require changes across **ALL three services**:

| Service | Required Changes | Complexity |
|---------|-----------------|-----------|
| Order Service | New bulk creation endpoint, CSV parser, batch processing logic, progress tracking, `batch_id` column in orders table | High |
| Payment Service | New batch payment API, aggregated amount calculation, review of max transaction amount (1,000,000 JPY limit), batch payment grouping | High |
| Notification Service | Bulk notification API, rate limit redesign (current: 10/s), queue-based async sending, batch template rendering | Medium |
| Database (all) | Schema migrations: add batch_id columns, import history tables, batch status tracking | High |

### 8.3 Specific Bottlenecks

1. **Payment amount limit:** Maximum 1,000,000 JPY per single transaction. Bulk orders exceeding this per-order would still work, but no aggregated batch payment exists.
2. **Notification rate limit:** 10 notifications/second. Bulk importing 10,000 orders would require at minimum 1,000 seconds (~17 minutes) for notifications alone.
3. **Sequential processing:** Current order creation flow is sequential. Bulk import would need parallel or queue-based processing.
4. **No batch error handling:** If one order in a batch fails, there is no mechanism to continue processing remaining orders (partial failure handling).