## 1. Introduction
# 1. Introduction
## 1.1 Purpose
This document defines the functional and business requirements for the CSV Bulk Import feature in the Order Management System of the EC site platform. The primary objective is to significantly improve operational efficiency and support the business processes of corporate customers by enabling the bulk import of large order volumes (100 to 10,000 orders) via CSV files. This requirement addresses the current limitation where orders must be created individually through the REST API or the administrative interface, which is inefficient for high-volume corporate clients. The document is intended for use by development, operations, and business stakeholders to ensure accurate implementation and alignment with business needs.
[KB-0300f3b7-a279-4396-bf18-c17f413ebe6d] [KB-049c5f42-4f53-4566-bbd6-62b438d57b92] [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1] [KB-1603dccf-0e13-426d-a4c3-527af9e69c16] [KB-161f44bf-9450-491f-b894-1fd70c185060] [KB-1ac0c309-d977-46d8-9523-c7d212164f65] [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08] [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644] [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96] [KB-6ef0a78b-63b6-493e-a7b0-76398d5a2889] [KB-94407aa3-d1ac-4455-a68c-265236fefec4] [KB-9722c127-de97-4494-bb8d-1d840efa8899] [KB-b709fa10-4f3b-445a-ae6e-4b3ecfd8ee36] [KB-b8a9eea9-db7e-4e70-9dc8-994ef3b37ab8] [KB-a575171d-af73-42ca-ab8d-5e127d21a373]
## 1.2 Scope
The scope of this document covers the requirements for implementing the CSV Bulk Import feature within the Order Management System of the EC site platform. This includes functional requirements, business rules, and system constraints relevant to the bulk import of orders for corporate clients. The document does not address other order creation methods, payment processing, or notification services except as they relate to the CSV import workflow.
## 1.3 Intended Audience
The intended audience for this document includes:
- Development Team: Responsible for implementing the CSV Bulk Import feature.
- Operations Team: Responsible for managing and supporting order processing workflows.
- Business Stakeholders: Corporate customers and internal business users who require efficient bulk order processing.
- Quality Assurance: Responsible for validating that the implemented feature meets the documented requirements.
## 1.4 Definitions, Acronyms, and Abbreviations
- CSV: Comma-Separated Values
- REST API: Representational State Transfer Application Programming Interface
- EC site: E-Commerce site
- Order Management System: The system responsible for handling the lifecycle of customer orders
## 1.5 References
- [System Limitation Table – Batch Order Creation Not Supported](#)
See:
| ID | Limitation Description | Impact Area | Severity |
|---------|----------------------------------------------------------------------------------------|--------------|------------|
| LIM-001 | **Order creation is limited to one at a time.** Batch or bulk order creation is not supported. Orders must be created individually via REST API. | Order Service | Critical |
[KB-4b179d3b-979b-4576-b74f-2dfcbcfd1443]
- [Payment Service – No Batch Payment Processing](#)
The Payment Service processes payments for individual orders only. Batch payment processing is not supported.
[KB-8ca26148-03e1-4184-a736-624e14448df9]
- [Batch Payment Constraint](#)
The maximum limit of 1,000,000 JPY applies to a single transaction. When bulk order import is implemented, each order under 1,000,000 JPY must be processed with an independent payment call. There is no endpoint for aggregated or batch payment processing. Processing 10,000 orders requires 10,000 individual payment API calls.
[KB-9bbed7ab-b122-4996-8526-88b63bb5aed3]
## 1.6 Document Organization
This document is structured according to ISO/IEC/IEEE 29148 requirements specification guidelines. Subsequent sections detail functional requirements, business rules, system constraints, and references related to the CSV Bulk Import feature.
## 2. System Architecture
# 2. System Architecture
## 2.1 Architectural Overview
The e-commerce order management platform utilizes a microservices architecture with three independently deployable services, each owning its own database (Database-per-Service pattern). The system is designed for modularity, scalability, and clear separation of responsibilities.
### High-Level Architecture
```mermaid
graph TB
FE[Frontend Admin Dashboard
:5173] --> OS[Order Service
:8000]
FE --> PS[Payment Service
:8001]
FE --> NS[Notification Service
:8002]
```
- **Frontend Admin Dashboard (Port 5173):** Stateless React SPA, directly connects to all backend services via REST API.
- **Order Service (Port 8000):** Handles order CRUD, status lifecycle, and orchestrates cross-service operations.
- **Payment Service (Port 8001):** Responsible for payment processing, refunds, and amount validation.
- **Notification Service (Port 8002):** Manages email/SMS notifications and template rendering.
All inter-service communication is synchronous REST over HTTP. There are no message brokers or asynchronous event buses in the current design. Each service is independently deployable and scalable.
[KB-9fd7847c-0564-4274-bd5a-833ba3f5f5b1] [KB-441b0dbc-517a-4b47-8da4-2ee14b968fb5] [KB-659a6dc4-ff79-4737-a729-91dd90f7c926]
---
## 2.2 Service Responsibilities and Boundaries
| Service | Responsibility | Database Schema | Team |
|----------------------|------------------------------------------------|-------------------|------------|
| Order Service | Order CRUD, status management, orchestration | orders, order_items | Team Alpha |
| Payment Service | Payment processing, refunds, validation | payments, refunds | Team Beta |
| Notification Service | Email/SMS notifications, template management | notification_templates, notifications | Team Beta |
| Frontend Admin UI | Web-based admin UI, dashboards, order management | — (stateless SPA) | Team Gamma |
- Each service owns its data and database schema exclusively.
- No cross-service foreign keys or shared databases are used.
- Data consistency is maintained through API calls (eventual consistency).
[KB-8b49c0c9-19fd-470b-9b1d-14ac73833002] [KB-95b83826-82e1-44c0-b244-29599b7d9a45] [KB-ba9cd6e8-367c-4707-a285-910e21614201]
---
## 2.3 Data Architecture
### Database-per-Service Pattern
| 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 |
- **Order Service**: Owns all order and order item data. Does not store payment or notification details.
- **Payment Service**: Owns payment and refund records. References order_id as a logical reference (not a foreign key).
- **Notification Service**: Owns notification records and templates. References order_id as a logical reference.
[KB-95b83826-82e1-44c0-b244-29599b7d9a45] [KB-c9bb8f17-858b-4e2f-96b1-4e63c8dd6520]
---
## 2.4 Communication Patterns
| Pattern | Usage | Timeout |
|-------------------------|-------------------------------|-------------------------------------------|
| Synchronous REST | All cross-service calls | 30s (payment), 10s (notification/webhook) |
| Webhook (REST callback) | Payment → Order status update | 10s |
- All inter-service communication is synchronous REST over HTTP.
- No retry or circuit breaker mechanisms are implemented; failures are logged and handled as "fail-open" (i.e., the system continues processing without retry).
- All cross-service operations are single-order only; batch or bulk operations are not supported in the current architecture.
[KB-7a51aee8-14e6-495b-9d15-8a2591bb1b3f] [KB-885427e4-337e-4fc5-8eb2-bef11353423f]
---
## 2.5 Deployment Architecture
The platform is deployed on AWS using ECS Fargate for container orchestration. Each service runs in its own ECS Fargate task within a private subnet. The frontend is deployed as a static SPA, typically served via AWS CloudFront.
- **Data Tier:** Each service uses a dedicated SQLite database file (for local/dev) or RDS PostgreSQL (for production).
- **Network Security:** Services are segmented using VPC subnets and security groups. Public endpoints are protected by AWS WAF and CloudFront.
- **Scalability:** Each service can be scaled independently by adjusting ECS task counts.
[KB-9509e5ba-9ce8-42ec-ad62-dfc12ab4f840] [KB-6288638a-39a4-41ee-9526-b7430dafc1e6] [KB-6a813ea7-ce62-4533-8c67-6225ee0cb7da]
---
## 2.6 Key Architectural Constraints
- **No batch import or bulk processing:** All APIs, data models, and business logic are designed for single-order operations only.
- **No cross-service foreign keys:** Data ownership is strictly enforced at the service boundary.
- **No asynchronous processing:** All notifications and payments are processed synchronously; failures are logged but not retried.
- **Notification rate limit:** 10 notifications/second. Importing 10,000 orders would take at least 1,000 seconds (approx. 17 minutes) if implemented.
- **No batch error handling:** If a single record fails in a batch (future enhancement), there is no mechanism to continue processing the remainder.
[KB-04a84995-0820-4319-c1582821058a] [KB-885427e4-337e-4fc5-8eb2-bef11353423f] [KB-a0851770-5672-4c15-86e0-c87bc3cf3a0d]
---
## 2.7 Known Limitations
| ID | Limitation | Impact |
|------------|----------------------------------------------------------------------------|--------------------------------------------------|
| LIM-001 | No CSV import capability. Orders are created via REST API only. | No support for bulk onboarding or migration. |
| LIM-002 | No retry/circuit breaker for downstream services. | Payment/notification failures are not retried. |
| LIM-003 | Notification rate limit (10/sec). | Bulk operations are slow or impractical. |
| LIM-004 | No batch error handling or progress tracking. | Partial failures require manual intervention. |
| LIM-005 | All cross-service operations are single-order only. | No batch APIs or bulk workflows. |
[KB-21694119-9e77-40f8-8f36-05178a328228] [KB-885427e4-337e-4fc5-8eb2-bef11353423f] [KB-a0851770-5672-4c15-86e0-c87bc3cf3a0d]
---
## 2.8 Future Architectural Considerations
- **Bulk Order Import:** Add CSV import and batch processing endpoints across all services.
- **Batch Payment Processing:** Support for grouped payments to reduce transaction overhead.
- **Queue-Based Notification:** Move from synchronous to asynchronous notification delivery to improve throughput and reliability.
- **Progress Tracking Dashboard:** Real-time monitoring of batch operations, including success/failure counts.
[KB-a0851770-5672-4c15-86e0-c87bc3cf3a0d] [KB-a77b16b9-5ab9-4af8-abaf-c66a31c33ffa] [KB-e33d4c34-aeb6-49a6-a88d-25523efffba5]
---
**End of Section 2**
## 3. Functional Design
# 3. Functional Design
This section describes the functional design of the system, including order management, payment processing, notification service integration, and CSV import requirements, as defined by the provided requirements and architectural documentation.
---
## 3.1 Order Management
### 3.1.1 Single Order Creation
- The system supports the creation of a single order per request via the API endpoint `POST /api/v1/orders/`.
- Required input includes customer information (name, email), order items (product name, quantity, unit price), and currency.
- Upon receiving a valid order request, the system calculates the total order amount as the sum of (quantity × unit price) for each item.
- The order is persisted in the database with status set to "pending" and then transitions to "processing payment" as payment is initiated.
- No bulk or batch order creation endpoint is available; all orders must be created individually.
- Pagination is supported for order listing via `GET /api/v1/orders/` with `skip` and `limit` parameters (default limit: 20).
- Order details, including items, can be retrieved by order ID using `GET /api/v1/orders/{order_id}`.
- Order status transitions are supported: pending → processing payment → paid → shipped → delivered. Cancellation is also supported, transitioning the status to "cancelled".
- Cancelling an order triggers a refund request to the Payment Service and a cancellation notification to the Notification Service.
[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] [KB-981308db-2c30-4894-ba6b-491bf40b1d24]
### 3.1.2 Order Data Model
Example response for order creation:
```json
{
"id": 1,
"customer_email": "tanaka@example.co.jp",
"customer_name": "田中太郎",
"status": "paid",
"total_amount": 183100.0,
"currency": "JPY",
"created_at": "2025-12-01T10:00:00Z",
"updated_at": "2025-12-01T10:00:01Z",
"items": [
{"id": 1, "product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0},
{"id": 2, "product_name": "マウス", "quantity": 1, "unit_price": 3500.0}
]
}
```
[KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4]
---
## 3.2 Payment Processing
### 3.2.1 Payment Service Integration
- Payments are processed for a single order at a time via `POST /api/v1/payments/`.
- Each payment request must specify `order_id`, `amount`, and `currency`.
- Amount validation: minimum 100 JPY, maximum 1,000,000 JPY per transaction.
- Duplicate payments for the same order are rejected.
- Upon successful payment, the Payment Service notifies the Order Service of the payment status via a webhook: `POST /api/v1/orders/{order_id}/webhook` with payload `{"payment_status": "completed", "transaction_id": "uuid"}`.
- There is no batch payment processing or batch webhook mechanism; each order and payment is handled individually.
- Refunds are processed via `POST /api/v1/payments/refund` with the payment ID and reason.
- Error handling includes validation errors (400), not found (404), schema validation errors (422), and internal server errors (500).
[KB-8072a75f-d61d-49b1-a859-1be86806c449] [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-49bae945-5563-437b-afa5-d95b1b74ce7e] [KB-69d55b34-e506-4b4e-a043-ef842030f397] [KB-807411b6-3c4a-43cf-beaf-94b330ac5f73]
#### Payment API Example
```json
{
"order_id": 1,
"amount": 183100.0,
"currency": "JPY"
}
```
[KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]
---
## 3.3 Notification Service
### 3.3.1 Notification Triggers and Templates
- Email and SMS notifications are sent for individual orders using templates.
- Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED.
- Templates use Jinja2-style variable substitution and support Japanese content.
- Notification delivery status is tracked (PENDING, SENT, FAILED).
- Notification history can be retrieved by notification ID or by order ID.
- Each notification is sent via a single API call; batch notification sending is not supported.
- Rate limiting applies: maximum 10 email notifications per second.
[KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] [KB-582e7673-bd66-493e-b511-017708ae9326] [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c] [KB-79349dcb-8798-40ed-b5d7-4be4dd855565]
#### Notification API Example
```json
{
"order_id": 1,
"to_email": "tanaka@example.co.jp",
"template_name": "ORDER_CONFIRMATION",
"template_data": {
"order_id": 1,
"customer_name": "田中太郎",
"total_amount": 183100,
"currency": "JPY",
"item_count": 2
}
}
```
[KB-582e7673-bd66-493e-b511-017708ae9326]
---
## 3.4 CSV Import and Bulk Operations
### 3.4.1 CSV Import Requirements
- Users can upload CSV files for bulk order creation (planned/desired feature).
- Maximum file size: 50MB. Supported encodings: UTF-8, Shift_JIS.
- CSV validation checks column structure, data types, and required fields. Errors are reported with specific row identification.
- Orders are created in bulk from validated CSV data, supporting 100 to 10,000 orders per import.
- The system displays real-time progress of the import (processed/total count) and allows partial failure handling (successful orders are retained, failed rows are downloadable).
- Bulk payment processing is not supported; each order requires an individual payment API call due to the per-transaction amount limit.
- Bulk notification sending is not supported; each confirmation email is sent per order, subject to rate limits.
- Import history is tracked, including filename, order count, success/failure counts, user, and timestamp.
- CSV template download is supported for correct formatting.
- In-progress imports can be cancelled; unprocessed orders are not created.
[KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e] [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] [KB-35c9e00d-f446-4174-be65-d214ecbff895] [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522] [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435]
#### CSV Import Functional Table
| Requirement ID | Requirement Description | Priority | Impacted Service | Acceptance Criteria |
|------------------|---------------------------------------------------------------------------------------------------------|----------|------------------|--------------------------------------------------------------|
| FR-BULK-001 | Users can upload CSV files (max 50MB; UTF-8, Shift_JIS) | P1 | Order Service | Upload succeeds if file is valid |
| FR-BULK-002 | CSV validation (columns, types, required fields); error rows reported | P1 | Order Service | Validation results displayed after upload |
| FR-BULK-003 | Bulk order creation from validated CSV (100–10,000 orders) | P1 | Order Service | 10,000 orders created within 5 minutes |
| FR-BULK-004 | Bulk payment processing for created orders (each order processed individually) | P1 | Payment Service | All payments processed; individual errors handled as partial |
| FR-BULK-005 | Bulk notification sending for imported orders (confirmation email per order) | P2 | Notification Svc | Confirmation emails sent to all customers (rate limit aware) |
| FR-BULK-006 | Real-time progress tracking of import (processed/total count) | P1 | Order Service | Progress bar updates in real time |
| FR-BULK-007 | Partial failure handling (successful orders retained; failed orders downloadable) | P1 | Order Service | Failed order list downloadable |
| FR-BULK-009 | CSV template download (correct format) | P3 | Order Service | Template CSV downloadable and usable |
| FR-BULK-010 | Cancel in-progress import (unprocessed orders not created) | P1 | Order Service | Cancelled import does not create unprocessed orders |
[KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e] [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] [KB-35c9e00d-f446-4174-be65-d214ecbff895] [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522] [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435]
---
## 3.5 Error Handling
- All API error responses follow RFC 7807 ("Problem Details for HTTP APIs").
- Common error codes: 400 (Bad Request/Validation Error), 404 (Not Found), 422 (Schema Validation Error), 500 (Internal Server Error).
- For CSV import, invalid data rows are identified and reported with error messages in Japanese.
[KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] [KB-35c9e00d-f446-4174-be65-d214ecbff895] [KB-6353c73b-fdb1-409c-9679-739f0ab68585]
---
## 3.6 Limitations
- No batch or bulk order creation endpoint exists; all orders must be created one at a time.
- No batch payment processing; each order requires an individual payment API call.
- No batch webhook or status update; each order status is updated individually.
- Bulk notification sending is not supported; each notification is sent per order, subject to rate limits.
[KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-69d55b34-e506-4b4e-a043-ef842030f397]
---
## 3.7 Cross-Service API Contracts
### 3.7.1 Order Service → Payment Service
| Field | Value |
|-----------|----------------------------------------------------|
| Caller | Order Service |
| Endpoint | POST http://localhost:8001/api/v1/payments |
| Trigger | Order creation |
| Payload | {"order_id": N, "amount": N.N, "currency": "JPY"} |
| Response | 201 with payment details |
| Timeout | 30 seconds |
| On Failure| Order status reverts to PENDING |
### 3.7.2 Payment Service → Order Service
| Field | Value |
|-----------|-------------------------------------------------------------|
| Caller | Payment Service |
| Endpoint | POST http://localhost:8000/api/v1/orders/{order_id}/webhook |
| Trigger | Payment status change |
| Payload | {"payment_status": "completed", "transaction_id": "uuid"} |
| Response | 200 OK |
| Timeout | 10 seconds |
### 3.7.3 Order Service → Notification Service
| Field | Value |
|-----------|------------------------------------------------------------------------------------|
| Caller | Order Service |
| Endpoint | POST http://localhost:8002/api/v1/notifications/email |
| Trigger | Order creation, status change, cancellation |
| Payload | {"order_id": N, "to_email": "...", "template_name": "...", "template_data": {...}} |
| Response | 201 with notification details |
| Timeout | 10 seconds |
| On Failure| Logged, order creation continues |
[KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]
---
## 3.8 Summary
The system is designed for robust, auditable, and reliable order management, payment processing, and notification delivery, with clear constraints on batch operations and explicit cross-service API contracts. All operations are performed per order, ensuring traceability and compliance with business and technical requirements.
---
**References:**
[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]
[KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]
[KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
[KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add]
[KB-981308db-2c30-4894-bb7e-8c6f68081d3]
[KB-8072a75f-d61d-49b1-a859-1be86806c449]
[KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]
[KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
[KB-69d55b34-e506-4b4e-a043-ef842030f397]
[KB-582e7673-bd66-493e-b511-017708ae9326]
[KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c]
[KB-79349dcb-8798-40ed-b5d7-4be4dd855565]
[KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e]
[KB-2d968f58-3ed8-4207-9d71-0c429c197cb4]
[KB-35c9e00d-f446-4174-be65-d214ecbff895]
[KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522]
[KB-89dddd9a-2e13-46e7-99a4-34c3fff47435]
[KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c]
[KB-2414677b-6e22-47f5-917c-2ed718d86fd4]
[KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]
[KB-6353c73b-fdb1-409c-9679-739f0ab68585]
## 4. Data Design
# 4. Data Design
## 4.1 Overview
The system employs a microservice-oriented data architecture, where each service manages its own SQLite database file. There are no cross-service foreign key constraints; all inter-service references are logical (e.g., order_id in payments is a logical reference, not a foreign key). The main services and their data domains are as follows:
| 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 |
| Frontend Admin Dashboard | None | — (stateless SPA, no database) |
[KB-923d5bdd-a9ee-4e73-b3a8-291d3f1f1aed]
## 4.2 Entity-Relationship Model
Each service maintains its own schema. The following ER diagram summarizes the relationships within and across services (logical references only):
```
erDiagram
orders {
int id PK
string customer_email
string customer_name
enum status
float total_amount
string currency
datetime created_at
datetime updated_at
}
order_items {
int id PK
int order_id FK
string product_name
int quantity
float unit_price
}
payments {
int id PK
int order_id UK "UNIQUE"
float amount
string currency
enum status
string payment_method
string transaction_id UK
datetime created_at
datetime updated_at
}
refunds {
int id PK
int payment_id FK
float amount
string reason
string status
datetime created_at
}
notification_templates {
int id PK
string name UK
string subject_template
text body_template
enum channel
string language
}
notifications {
int id PK
int order_id "NOT UNIQUE"
enum channel
string template_name
string recipient
string subject
text body
enum status
datetime sent_at
datetime created_at
}
orders ||--o{ order_items : "has"
payments ||--o{ refunds : "has"
orders ||--|| payments : "logical ref (order_id)"
orders ||--o{ notifications : "logical ref (order_id)"
```
[KB-6ef4190a-2fee-4402-adb3-fb7ae18f1d13], [KB-49954076-169a-4896-bca8-5973d8b21cdd], [KB-356ddf02-2b05-4387-a727-4296b1ab5915], [KB-449d95d0-b534-4180-b0e4-6514bc1a0191], [KB-571d4a6b-bc77-4f6e-8e3c-68f157b7745d], [KB-85db493d-f238-492f-b53c-27c0d02082ed], [KB-847fbc04-b0ee-44a8-bfc2-8e650ca31ccd]
## 4.3 Table Definitions
### 4.3.1 Order Service
#### orders Table
| Column | Type | Nullable | Default | Constraint | Notes |
|----------------|----------|----------|---------------|--------------|--------------------------|
| id | INTEGER | No | autoincrement | PRIMARY KEY | |
| customer_email | VARCHAR | No | | | |
| customer_name | VARCHAR | No | | | Japanese names supported |
| status | ENUM | No | "pending" | | OrderStatus enum |
| total_amount | FLOAT | No | | | Sum of items |
| currency | VARCHAR | No | "JPY" | | |
| created_at | DATETIME | No | now() | | UTC |
| updated_at | DATETIME | No | now() | | UTC, auto-update |
[KB-48e3a6fc-59cd-431b-890b-917289a82403], [KB-8d52e9c2-c2f3-4b9e-94a3-f560daf6d6c1], [KB-88780e57-3879-4a74-a095-f18be34b4082]
#### order_items Table
| Column | Type | Nullable | Constraint |
|--------------|---------|----------|-----------------------------------------|
| id | INTEGER | No | PRIMARY KEY |
| order_id | INTEGER | No | FOREIGN KEY → orders.id, CASCADE DELETE |
| product_name | VARCHAR | No | |
| quantity | INTEGER | No | > 0 |
| unit_price | FLOAT | No | > 0 |
Indexes: ix_orders_id on orders.id, order_items.order_id FK index.
[KB-84f4d39b-b804-49a0-b0b7-5649bdeff324], [KB-53818072-e7b5-4a95-a6f5-f6860541f1d4], [KB-3897bab0-b75b-4c45-af3c-ee53984a4466]
### 4.3.2 Payment Service
#### payments Table
| Column | Type | Nullable | Default | Constraint | Notes |
|----------------|---------|----------|------------|--------------------|--------------------------------------------|
| id | INTEGER | No | | PRIMARY KEY | |
| order_id | INTEGER | No | | UNIQUE | 1:1 relationship with orders; no batch pay |
| amount | FLOAT | No | | >= 100, <= 1,000,000| Amount in JPY |
| currency | VARCHAR | No | "JPY" | | |
| status | ENUM | No | | PaymentStatus | |
| payment_method | VARCHAR | No | "credit_card"| | |
| transaction_id | VARCHAR | No | | UNIQUE | UUID |
| created_at | DATETIME| No | now() | | |
| updated_at | DATETIME| No | now() | | |
**Constraints:**
- order_id is UNIQUE: strictly one payment per order.
- No batch_id, bulk_payment_group, or aggregated_amount columns—batch payments are not supported.
[KB-11739ab0-b209-41e4-b73e-7d7e0c4338b2], [KB-92fe4b57-1970-4ef5-a240-867f363cff01], [KB-6714d019-5f7b-40d8-8076-f17a39d4c75b], [KB-447f3c51-a447-416e-a1ea-a5ed5855eb8d], [KB-6ddb555b-8ec5-459d-8da0-8839165718e8]
#### refunds Table
| Column | Type | Nullable | Constraint |
|------------|---------|----------|------------------------|
| id | INTEGER | No | PRIMARY KEY |
| payment_id | INTEGER | No | FK → payments.id |
| amount | FLOAT | No | = payment.amount |
| reason | VARCHAR | No | |
| status | VARCHAR | No | "completed" |
| created_at | DATETIME| No | now() |
[KB-6ddb555b-8ec5-459d-8da0-8839165718e8], [KB-847fbc04-b0ee-44a8-bfc2-8e650ca31ccd]
### 4.3.3 Notification Service
#### notification_templates Table
| Column | Type | Nullable | Constraint | Notes |
|------------------|---------|----------|-----------------|-------------------|
| id | INTEGER | No | PRIMARY KEY | |
| name | VARCHAR | No | UNIQUE | |
| subject_template | VARCHAR | No | Jinja2 template | |
| body_template | TEXT | No | Jinja2 template | |
| channel | ENUM | No | EMAIL or SMS | |
| language | VARCHAR | No | Default "ja" | |
**Seed Data:**
| name | subject_template | language |
|--------------------|-------------------------------------------------------|------------|
| ORDER_CONFIRMATION | Order Confirmation — Order #{{ order_id }} | ja |
| ORDER_SHIPPED | Shipping Notice — Order #{{ order_id }} | ja |
| ORDER_CANCELLED | Order Cancellation Notice — Order #{{ order_id }} | ja |
[KB-2db8f533-b785-43d6-9795-9d49a4b8e86d], [KB-557a0ee1-9cb7-4897-8eaf-81588e825d91], [KB-6aaac46d-2614-4305-a441-1ed4d572a870], [KB-7d1f4e6a-0838-4444-9f3a-9904725382eb]
#### notifications Table
| Column | Type | Nullable | Constraint | Notes |
|---------------|----------|----------|------------------------|------------------------------|
| id | INTEGER | No | PRIMARY KEY | |
| order_id | INTEGER | No | NOT UNIQUE | Multiple notifications/order |
| channel | ENUM | No | EMAIL / SMS | |
| template_name | VARCHAR | No | | |
| recipient | VARCHAR | No | | |
| subject | VARCHAR | No | | |
| body | TEXT | No | | |
| status | ENUM | No | "pending" | |
| sent_at | DATETIME | Yes | | Time sent |
| created_at | DATETIME | No | now() | |
**Note:**
- order_id is NOT UNIQUE; multiple notifications can be sent per order.
- There is NO batch_id column; group/batch notification tracking is not supported.
[KB-333c6a90-8b2f-47ab-b3cc-d537fce54c6b], [KB-49d60049-0541-4147-bd0c-cc092d6dbbf5], [KB-571d4a6b-bc77-4f6e-8e3c-68f157b7745d]
## 4.4 Data Constraints and Limitations
### 4.4.1 Batch Operations
- The current schema does NOT support batch order import or batch payment processing.
- No batch_id, csv_source, bulk_import_group, or import_row_number columns exist in orders, payments, or notifications tables.
- Each order and payment must be created individually via API; bulk endpoints are not available.
- Batch/group notification tracking is not possible due to the absence of batch_id.
[KB-6f0beda3-71c6-49d1-afe6-4f9a90c6574d], [KB-3897bab0-b75b-4c45-af3c-ee53984a4466], [KB-65241a62-b269-4bc8-b9ed-b2f85e1cefce], [KB-447f3c51-a447-416e-a1ea-a5ed5855eb8d], [KB-92fe4b57-1970-4ef5-a240-867f363cff01]
### 4.4.2 Payment Constraints
- payments.order_id is UNIQUE, enforcing a strict 1:1 relationship between orders and payments.
- Batch payments (one payment covering multiple orders) are not supported; there is no batch_id or aggregation field.
[KB-92fe4b57-1970-4ef5-a240-867f363cff01], [KB-6714d019-5f7b-40d8-8076-f17a39d4c75b], [KB-447f3c51-a447-416e-a1ea-a5ed5855eb8d]
### 4.4.3 Notification Constraints
- notifications.order_id is not unique, allowing multiple notifications per order.
- There is no batch_id field; notifications cannot be grouped or correlated by batch.
[KB-49d60049-0541-4147-bd0c-cc092d6dbbf5], [KB-65241a62-b269-4bc8-b9ed-b2f85e1cefce]
## 4.5 Data Integrity and Security
- All databases use logical references for cross-service relationships; referential integrity is enforced within each service only.
- Sensitive fields (e.g., payment information) are subject to PCI and PHI controls, including encryption and audit logging (see security and compliance sections).
- No soft delete is implemented; deletions are hard deletes unless otherwise specified.
[KB-923d5bdd-a9ee-4e73-b3a8-291d3f1f1aed], [KB-83851ad4-bf7b-4ce1-a3a1-6ba1b4513f57]
---
**End of Section 4. Data Design**
## 5. Interface Design
# 5. Interface Design
## 5.1 Overview
The system architecture is based on a microservices model, with RESTful APIs as the primary communication mechanism between services. All service-to-service communication is synchronous REST over HTTP, with strict timeouts and no asynchronous message brokers or event buses. Each API is versioned via the URI path (e.g., `/api/v1/`), and all endpoints use JSON for request and response bodies. Security is enforced through OAuth2/OIDC with JWT tokens, and all sensitive operations require authentication and authorization. No batch or bulk operations are supported—each API call processes a single resource or transaction only. Rate limiting and error handling are consistently applied across all services. [KB-3c903362-1377-4d77-a89b-841133324242], [KB-b8d63553-10df-4d66-abf5-a55b53f12e7b], [KB-5ef5f51f-df55-4bdd-8475-6c06a2ba7705], [KB-a40a2330-365e-4221-bda5-fe6a0f595402], [KB-d54c0a5c-c6b6-4dec-ada3-8d6c59ff89eb]
## 5.2 API Endpoint Inventory
The following table summarizes the main REST API endpoints, their methods, authentication requirements, and status:
| Endpoint | Method | Service | Auth Required | PHI | Status |
|-------------------------------------------|--------|----------------------|---------------|-----|----------|
| /api/v1/orders/ | POST | Order Service | Yes | No | Live |
| /api/v1/orders/ | GET | Order Service | Yes | No | Live |
| /api/v1/orders/{order_id} | GET | Order Service | Yes | No | Live |
| /api/v1/orders/{order_id}/status | PUT | Order Service | Yes | No | Live |
| /api/v1/orders/{order_id} | DELETE | Order Service | Yes | No | Live |
| /api/v1/orders/{order_id}/webhook | POST | Order Service | Yes | No | Live |
| /api/v1/payments/ | POST | Payment Service | Yes | No | Live |
| /api/v1/payments/{payment_id} | GET | Payment Service | Yes | No | Live |
| /api/v1/payments/order/{order_id} | GET | Payment Service | Yes | No | Live |
| /api/v1/payments/refund | POST | Payment Service | Yes | No | Live |
| /api/v1/notifications/email | POST | Notification Service | Yes | No | Live |
| /api/v1/notifications/sms | POST | Notification Service | Yes | No | Live |
| /api/v1/notifications/{notification_id} | GET | Notification Service | Yes | No | Live |
| /api/v1/notifications/order/{order_id} | GET | Notification Service | Yes | No | Live |
[KB-cb409cd5-afc3-4d0c-8d30-43ef32818de6], [KB-51d28c72-f536-45dc-b33a-791b463888e9], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]
## 5.3 Resource Naming and Versioning
- All resource URLs use plural nouns and kebab-case (e.g., `/api/v1/orders`, `/api/v1/payments`).
- Versioning is implemented via the URI path (e.g., `/api/v1/`). Only major versions are included in the path.
- No trailing slashes, file extensions, or verbs in URLs.
- Maximum resource nesting depth is 2.
- All APIs must be documented using OpenAPI 3.1, with required field descriptions and example values.
[KB-3c903362-1377-4d77-a89b-841133324242], [KB-98da8276-e84b-4136-b182-1b6b56f60834], [KB-5ef5f51f-df55-4bdd-8475-6c06a2ba7705], [KB-cfecaa8c-f6f4-4d80-8886-9d059a755d68]
## 5.4 API Patterns and Constraints
- All service-to-service calls are synchronous REST over HTTP.
- Webhook mechanisms are used for payment status updates (Payment Service → Order Service).
- Each endpoint processes a single resource; no bulk/batch endpoints exist.
- Rate limits are strictly enforced (e.g., 10 notifications/sec for Notification Service).
- No retry or circuit breaker logic is implemented at the API layer.
- All requests and responses use JSON format; date/time is in ISO 8601.
- Pagination is supported for listing endpoints using `skip` and `limit` parameters (default: limit=20).
- Error responses conform to RFC 7807 Problem Details or a standard `{"detail": "Error description"}` format.
[KB-b8d63553-10df-4d66-abf5-a55b53f12e7b], [KB-6c4af247-7d5b-458c-8ea3-77545cb88bf6], [KB-5ef5f51f-df55-4bdd-8475-6c06a2ba7705], [KB-d54c0a5c-c6b6-4dec-ada3-8d6c59ff89eb], [KB-9de11552-e4f6-4e7c-99bd-16e90f5c9b11], [KB-8072a75f-d61d-49b1-a859-1be86806c449]
## 5.5 Service Dependency Matrix
| Source Service | Target Service | 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 |
[KB-6277ef6e-12da-47d4-a04d-66f27260b610], [KB-6fa3fbfa-477c-4724-b31a-742db2bf1db3], [KB-acd413e5-d98b-40de-8808-e4e255cff22b]
## 5.6 Request and Response Standards
- **Request Headers:**
- `Authorization: Bearer ` (required except for health check/token endpoints)
- `Content-Type: application/json` (if body present)
- `Accept: application/json` (optional, default)
- `X-Correlation-Id`: UUID for tracing (auto-generated if absent)
- `X-Clinic-Id`: Clinic identifier for multi-tenant context
- `If-Match`: ETag for optimistic concurrency (PUT only)
- **Response Headers:**
- `Content-Type: application/json`
- `X-Correlation-Id`: Echoed or generated
- `X-Request-Id`: Unique request identifier
- `ETag`: On GET, entity version hash for caching
- `Cache-Control`: `no-store` for PHI endpoints
- `Strict-Transport-Security`: `max-age=31536000; includeSubDomains`
- `X-Content-Type-Options`: `nosniff`
- `X-Frame-Options`: `DENY`
- `Pragma`: `no-cache` (on PHI endpoints)
- **Status Codes:**
- 200 OK: Successful GET, PUT, PATCH
- 201 Created: Successful POST
- 204 No Content: Successful DELETE
- 400 Bad Request: Validation error
- 401 Unauthorized: Missing/invalid authentication
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource does not exist
- 409 Conflict: Duplicate resource
- 422 Unprocessable Entity: Schema validation error
- 500 Internal Server Error: Unexpected error
[KB-baf87d77-4aa3-49f0-a6f6-84d180a23727], [KB-2e6dcb76-d23e-4bac-9d8d-fb951c2842a6], [KB-f57ca614-2740-43bd-9680-946abf52a290]
## 5.7 Security and Access Control
- All APIs require OAuth2/OIDC Bearer tokens (JWT) for authentication.
- JWT tokens use RS256, issued by Azure Active Directory, with a 15-minute access token lifetime.
- CORS is restricted to whitelisted origins per environment.
- CSRF protection via SameSite=Strict cookies and double-submit pattern.
- Content-Security-Policy, X-Content-Type-Options, and X-Frame-Options headers are enforced.
- Administrative and privileged access requires MFA and is logged at an enhanced level.
- Access permissions are role-based and enforced at the endpoint level.
[KB-06cbdf57-f5b7-42c6-9d15-4119f65cd34e], [KB-24ab8a1f-6394-4b40-ad6c-8720f544ac83], [KB-c5624d9a-572e-492b-8987-f94cd10aec13], [KB-8fcd87b3-58ea-4884-8f00-1ca6273b6f1d]
## 5.8 Key API Flows
### 5.8.1 Order Creation
1. **POST /api/v1/orders/**
- Creates a single order.
- Triggers Payment Service (`POST /api/v1/payments`) and Notification Service (`POST /api/v1/notifications/email`).
- No bulk/batch creation supported.
2. **POST /api/v1/payments/**
- Processes payment for a single order.
- Amount must be between 100 and 1,000,000 JPY.
- `order_id` must be unique (no duplicate payments).
3. **POST /api/v1/notifications/email**
- Sends order confirmation email.
- Rate limit: 10 notifications/sec.
[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-51d28c72-f536-45dc-b33a-791b463888e9], [KB-582e7673-bd66-493e-b511-017708ae9326]
### 5.8.2 Order Cancellation
1. **DELETE /api/v1/orders/{order_id}**
- Cancels the order.
- Triggers Payment Service refund (`POST /api/v1/payments/refund`) and sends cancellation notification.
2. **POST /api/v1/payments/refund**
- Processes refund for the associated payment.
3. **POST /api/v1/notifications/email**
- Sends order cancellation email.
[KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-cac81f88-4c41-4edf-be1c-50ab45084420]
### 5.8.3 Payment Status Update (Webhook)
- **POST /api/v1/orders/{order_id}/webhook**
- Receives payment status updates from Payment Service.
- Updates order status accordingly.
- Only single-order callbacks are supported (no batch webhooks).
[KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-f5f23d49-82ef-4a1e-8cfe-9260964d2064]
## 5.9 Notification Service
- Only single notification per request (no bulk/batch).
- Email and SMS notifications are supported.
- Rate limit: 10 notifications/sec (global, all channels).
- No queuing; excess requests are rejected.
- Templates use Jinja2 syntax and are rendered per notification.
- Notification failures are logged but do not block order processing.
[KB-51d28c72-f536-45dc-b33a-791b463888e9], [KB-9de11552-e4f6-4e7c-99bd-16e90f5c9b11], [KB-d1baa4cc-70e5-4c48-a400-9b5d02a20efd], [KB-fbda27b0-4aa2-43b4-932c-14fe81aa5b87]
## 5.10 Current Limitations
| ID | Limitation | Severity |
|----------------|-------------------------------------------------------------------------------------------------|----------|
| DD-PAY-LIM-001 | Only processes ONE order at a time. No bulk/batch payment API exists. | High |
| DD-PAY-LIM-002 | No aggregated amount calculation. Cannot combine multiple order amounts into a single payment. | High |
| DD-PAY-LIM-003 | Maximum 1,000,000 JPY per single transaction. | Medium |
| DD-PAY-LIM-004 | 1:1 payment-to-order unique constraint prevents batch payment grouping. | High |
| DD-NOTIF-LIM-001 | No bulk notification API. At 10/sec, 10,000 notifications require ~17 minutes minimum. | High |
[KB-6c4af247-7d5b-458c-8ea3-77545cb88bf6], [KB-9de11552-e4f6-4e7c-99bd-16e90f5c9b11], [KB-b14eacfd-1d32-487d-abac-85783694babf]
---
**All interface design details above are strictly based on the provided context.**
## 6. Non-Functional Requirements
# 6. Non-Functional Requirements
This section defines the non-functional requirements (NFRs) for the system, including performance, reliability, availability, security, scalability, and compliance constraints. All requirements are derived strictly from the provided context.
---
## 6.1 Performance Requirements
| ID | Category | Requirement | Target |
|---------|--------------|-------------------------------------|------------------------------|
| NFR-001 | Performance | Order creation throughput | 100 orders/minute |
| NFR-002 | Performance | Payment processing latency | < 30 seconds per transaction |
| NFR-003 | Performance | Notification delivery latency | < 5 seconds per notification |
| NFR-004 | Performance | API response time (read operations) | < 200ms P95 |
**Additional Constraints:**
- Notification Service is limited to 10 notifications/second (global rate limit, no queueing). Sending 10,000 notifications requires a minimum of 1,000 seconds (~17 minutes). This is a critical bottleneck for bulk operations. [KB-26b502e3-480e-4dfc-acfa-b73ff1febca9], [KB-49b83196-e2b5-46cd-bda8-bb1dccebc240]
- Order creation, payment, and notification steps are executed sequentially, not in parallel. Total latency is the sum of each step’s duration. [KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]
---
## 6.2 Availability and Reliability
| ID | Category | Requirement | Target |
|---------|-------------|------------------------------------|----------------|
| NFR-005 | Availability| System uptime | 99.5% |
| NFR-006 | Reliability | Data consistency across services | Eventual |
**Additional Reliability Constraints:**
- On partial failure, successful orders must be retained; failed orders are rolled back. [KB-4e0d9a2e-ec89-4115-84ca-ea7ebdd3ad41]
- Automatic retry mechanism: Up to 3 retries for eligible operations (database, external API, message queue, file upload, email sending) with exponential or fixed backoff. [KB-43991936-704b-4730-96bf-2f33e6ec643e]
- No retry or circuit breaker for cross-service calls in the current implementation; failures are logged but not retried. [KB-01305cb3-d331-4b4b-ba02-69ada467b41b], [KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]
---
## 6.3 Security
| ID | Category | Requirement | Target/Constraint |
|---------|-----------|--------------------------------------|------------------------------|
| NFR-007 | Security | API input validation | All endpoints |
| NFR-008 | Security | Notification rate limit | 10 notifications/second |
**Security Controls:**
- All endpoints must validate input (Bean Validation, custom validators). [KB-49b83196-e2b5-46cd-bda8-bb1dccebc240], [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
- PHI must never appear in error responses, logs, URLs, or query parameters. Only resource IDs (UUID) are permitted in error messages. [KB-221e6244-fcbf-434c-8aa7-a850d7be2f8d], [KB-39cb0a23-daec-4c73-8b62-7bc2b4110a12], [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
- All API calls are logged with correlation ID for traceability. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
- TLS 1.3 is required for all communications; mTLS is required for service-to-service calls. [KB-51003524-faa7-4337-a3ba-15f90a68cbb6], [KB-3a9b6fa5-5440-4f13-aa22-4bd318b46b70]
- Access control is enforced at API and field level using @PreAuthorize and PHI field filtering. [KB-359fd01d-34fc-4682-bf09-529a75cbb1f4], [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
- Audit logging for every PHI access event. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
- Session timeout is 15 minutes of inactivity. [KB-386ea7e9-da1d-43e4-9035-46f55587f121]
---
## 6.4 Scalability
- Notification Service is not capable of bulk processing; all notifications are processed one-by-one per API call. [KB-06c5403a-d177-4525-b247-1d7ae37a86b8], [KB-01305cb3-d331-4b4b-ba02-69ada467b41b]
- Maximum notification rate is 10/second (global, all channels). [KB-26b502e3-480e-4dfc-acfa-b73ff1febca9]
- No bulk import UI or batch creation form is available in the frontend. [KB-01305cb3-d331-4b4b-ba02-69ada467b41b]
---
## 6.5 Data Consistency
- Eventual consistency is acceptable for cross-service data. [KB-49b83196-e2b5-46cd-bda8-bb1dccebc240]
- On partial failure, successful orders are retained, failed orders are rolled back. [KB-4e0d9a2e-ec89-4115-84ca-ea7ebdd3ad41]
---
## 6.6 Regulatory and Compliance
- All requirements must support HIPAA Security Rule compliance, including audit logging, access controls, and PHI handling. [KB-47b0a2f1-2e5a-413c-b607-302aeceb636a], [KB-34a3b971-f4da-4b21-ad93-da173a33f837]
- All PHI access, modification, and disclosure events must be logged and retained per policy. [KB-47b0a2f1-2e5a-413c-b607-302aeceb636a]
- System must support audit log retention for up to 8 years, depending on event type. [KB-059dda76-1df0-4539-a60b-e504ba4e11ea]
---
## 6.7 Summary Table
| ID | Category | Requirement/Constraint | Target/Value |
|---------|--------------|-----------------------------------------------|-----------------------------|
| NFR-001 | Performance | Order creation throughput | 100 orders/minute |
| NFR-002 | Performance | Payment processing latency | < 30 sec/transaction |
| NFR-003 | Performance | Notification delivery latency | < 5 sec/notification |
| NFR-004 | Performance | API response time (read) | < 200ms P95 |
| NFR-005 | Availability | System uptime | 99.5% |
| NFR-006 | Reliability | Data consistency across services | Eventual |
| NFR-007 | Security | API input validation | All endpoints |
| NFR-008 | Security | Notification rate limit | 10 notifications/second |
| NFR-009 | Security | PHI never in error/log/URL | Enforced |
| NFR-010 | Security | TLS 1.3 for all communications | Required |
| NFR-011 | Security | Session timeout | 15 minutes |
| NFR-012 | Compliance | Audit log retention | Up to 8 years |
---
**References:**
[KB-49b83196-e2b5-46cd-bda8-bb1dccebc240]
[KB-26b502e3-480e-4dfc-acfa-b73ff1febca9]
[KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf]
[KB-150eb89c-77b0-415b-a547-3ed0502eec24]
[KB-01305cb3-d331-4b4b-ba02-69ada467b41b]
[KB-4e0d9a2e-ec89-4115-84ca-ea7ebdd3ad41]
[KB-43991936-704b-4730-96bf-2f33e6ec643e]
[KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]
[KB-221e6244-fcbf-434c-8aa7-a850d7be2f8d]
[KB-39cb0a23-daec-4c73-8b62-7bc2b4110a12]
[KB-359fd01d-34fc-4682-bf09-529a75cbb1f4]
[KB-51003524-faa7-4337-a3ba-15f90a68cbb6]
[KB-3a9b6fa5-5440-4f13-aa22-4bd318b46b70]
[KB-47b0a2f1-2e5a-413c-b607-302aeceb636a]
[KB-059dda76-1df0-4539-a60b-e504ba4e11ea]
[KB-386ea7e9-da1d-43e4-9035-46f55587f121]
## 7. Technology Stack
## 7. Technology Stack
The technology stack for the system is as follows:
| Layer | Technology / Tooling | Notes / Purpose |
|----------------------|------------------------------------------------|------------------------------------------------------|
| Language | TypeScript (Frontend), Python 3.12 (Backend) | TypeScript for SPA, Python for backend services |
| Frontend Framework | React 19 | SPA for admin dashboard and management UI |
| Frontend Tooling | Vite | Build tool for React |
| Styling | Tailwind CSS | Utility-first CSS framework |
| Charts | Recharts | Charting library for data visualization |
| Routing | react-router-dom v7 | Client-side routing |
| State Management | React hooks (no external library) | Local state only, no Redux or similar |
| UI Component Library | MUI (Material-UI) | UI components (forms, grids, dialogs, etc.) |
| Data Grid | MUI X Data Grid / Data Grid Pro | Advanced table/grid features |
| Date/Time Picker | MUI X Date Pickers | Date and time selection components |
| Rich Text Editor | TipTap / Draft.js | Rich text input (where required) |
| Input Mask | react-input-mask | For masked text fields |
| PDF Viewer | react-pdf | Embedded PDF viewing |
| Backend Framework | FastAPI | Backend REST APIs |
| ORM / Data Access | SQLAlchemy (async) | Database access for backend services |
| Database | SQLite | One DB per service (order_service.db, etc.) |
| Templating | Jinja2 | Notification service email/SMS templates |
| Communication | REST over HTTP | Synchronous, no message broker/event bus |
| Dev Server Ports | 5173 (Frontend), 8000 (Order), 8001 (Payment), 8002 (Notification) | Default ports for local development |
**References:**
- [KB-8fc041c6-840f-4a60-87f0-f6b2769c7f7f]
- [KB-441b0dbc-517a-4b47-8da4-2ee14b968fb5]
- [KB-9d4c9057-b9e4-4f17-9a6f-79c07e7ce038]
- [KB-77e849ec-9a76-4edd-acd5-9be1528f3106]
- [KB-680eca26-f8b5-4a18-b9c2-79fa0d573688]
- [KB-6a11385f-7e78-417d-8314-cd07604322c9]
- [KB-7cc906c2-4702-4daf-acb7-078da2cdf0c7]
- [KB-7252f2ab-eca0-4504-907e-c5bc30a543d4]
- [KB-edad7ae5-0683-489e-b45e-055b9c60f1b4]
- [KB-cfb4507a-7d25-498f-9895-656d45dd7ce5]
- [KB-b0d9ca8e-f7fc-474b-96a1-853181c1801d]
## 8. Deployment and Runtime
# 8. Deployment and Runtime
## 8.1 Deployment Architecture
### 8.1.1 AWS Cloud Infrastructure
The system is deployed on AWS using a multi-account structure for production, staging, development, and disaster recovery environments. Key components include:
- **ECS Fargate**: Hosts all application containers in the application tier. Blue/green deployments and canary analysis are supported for production workloads. [KB-500d2d8b-b1a5-4adb-8b7f-c93d1ed24846], [KB-764a83b1-2d56-47d3-a045-67435e645329]
- **RDS PostgreSQL**: Primary database for operational data, configured for high availability (Multi-AZ), encryption, and automated backups. [KB-f560bb36-3c48-4680-b1dc-4d9c17173590], [KB-5b1a27e1-9cff-42ea-a7bf-11d95c28fe80]
- **ElastiCache Redis**: Used for session storage, API response caching, and rate limiting. Cluster mode enabled, encryption in transit and at rest. [KB-4318342d-bb24-493a-4b9-30b3c6c52df4]
- **AWS S3**: Provides storage for data lifecycle management, backups, and audit logs, with automated tiering and lifecycle policies. [KB-a4e4998a-6e56-4d27-abd3-6b2a5f61576e], [KB-d3b1eb4f-a63c-4c13-a2bb-4edeebf5d635], [KB-f447ff57-3f98-4617-8e4a-3f52efa835a9]
- **ALB (Application Load Balancer)**: Handles HTTPS traffic, SSL termination, and routes requests to ECS Fargate services. Integrated with AWS WAF for security. [KB-371a2a34-c7fc-4b6d-a06c-3f4cb574f667], [KB-7b9570e3-cf8e-4150-854d-bbb720e6a740]
- **VPC Endpoints**: Private connectivity to AWS services (S3, ECR, CloudWatch, KMS, SQS, SNS, STS). [KB-b742e77d-0d02-4327-9440-d2646622ad0c]
- **Security Groups**: Strictly control inbound and outbound traffic between ALB, ECS, RDS, Redis, and other components. [KB-5755248b-41ad-4acf-8dd0-d7a280ce6111]
### 8.1.2 Network Architecture
- **VPC Design**: Segregated into public, private application, and private data subnets across multiple availability zones. [KB-6a813ea7-ce62-4533-8c67-6225ee0cb7da], [KB-2fd51f2f-8bea-4db6-b71a-2dd993905d5d], [KB-63703199-62ac-4e6e-a04e-f83f49451750]
- **Site-to-Site VPN**: Used for secure connectivity between clinic locations and the cloud. [KB-1d938fa4-bd35-4169-99fa-1a9def5866e5], [KB-437d6eab-fcee-4c7b-9a1f-0ae537e1fab4]
### 8.1.3 Disaster Recovery
- **DR Region**: Standby resources in us-west-2 with cross-region replication for RDS, S3, and pre-built ECS images. [KB-cf88dc85-f65d-4237-bb77-514ccc693a73]
- **Failover**: Route 53 health checks enable rapid failover. RPO and RTO targets are defined for each component.
| Component | DR Strategy | RPO | RTO |
|-----------------|----------------------------------|----------|--------|
| RDS PostgreSQL | Cross-region read replica | < 1 min | 30 min |
| S3 data | Cross-region replication (CRR) | < 15 min | 15 min |
| ECS Fargate | Pre-built images in DR ECR | N/A | 15 min |
| Route 53 | Health-check failover routing | N/A | 5 min |
| ElastiCache | Cold start in DR (cache warming) | N/A | 30 min |
| Secrets Manager | Multi-region secrets | < 1 min | 5 min |
[KB-cf88dc85-f65d-4237-bb77-514ccc693a73]
## 8.2 Deployment Procedures
### 8.2.1 CI/CD Pipeline
- **GitHub Actions**: Automated build, test, and deployment pipeline. Includes unit, integration, SAST, dependency, container, and DAST scans. [KB-8cd4788c-4e85-4d54-a987-2987ef1f6dee]
- **Staging Environment**: Smoke tests and performance tests executed prior to production deployment.
- **Production Deployment**: Blue/green deployment with canary analysis (10% → 50% → 100%), manual approval required. Rollback triggered if error rate > 1%. [KB-500d2d8b-b1a5-4adb-8b7f-c93d1ed24846], [KB-c255b72d-301a-4f4b-b61b-49b9d81e3150]
### 8.2.2 Emergency Hotfix and Rollback
| Step | Action | Responsibility |
|------|---------------------------------------------------|--------------------|
| 1 | Create hotfix branch from main | Developer |
| 2 | Implement fix with tests | Developer |
| 3 | Expedited code review (1 reviewer minimum) | Senior Developer |
| 4 | Deploy to staging, verify fix | DevOps |
| 5 | Manual approval for production deployment | Incident Commander |
| 6 | Deploy with monitoring for 30 minutes post-deploy | DevOps |
| 7 | Merge hotfix branch back to main and develop | Developer |
Rollback is performed by switching the ALB target group back to the previous version using Terraform. [KB-c7514001-7836-4542-a406-e60d3d718d40], [KB-c255b72d-301a-4f4b-b61b-49b9d81e3150]
## 8.3 Runtime Architecture
### 8.3.1 Service Composition
- **Frontend**: React SPA communicates directly with Order, Payment, and Notification services via REST API. No API Gateway or Backend-for-Frontend layer. [KB-26aafd9d-c11e-450c-a1d3-470dc7a6a516]
- **Order Service**: Orchestrates order creation, payment, and notification flows. [KB-ff81ae68-7ad1-4faf-ae34-5b10224da10c], [KB-9d4054d2-4b43-440e-b02a-9201d701697d]
- **Payment Service**: Handles payment processing and refunds. [KB-60767bfc-9ce5-4341-b8f8-bf7fd8a59748], [KB-b24643bb-4c88-4c7f-82fb-aa363244fac8]
- **Notification Service**: Sends confirmation, shipping, and cancellation emails. [KB-79349dcb-8798-40ed-b5d7-4be4dd855565], [KB-fa4dd00c-51bf-47fb-a6ca-6d1cdbed7d96]
### 8.3.2 Communication Patterns
| Pattern | Use Case | Timeout |
|----------------------------|---------------------------|--------------------------------|
| Sync REST | All service calls | 30s (payment), 10s (notification/webhook) |
| Webhook (REST callback) | Payment → Order status | 10s |
No message broker, event bus, or asynchronous communication channel exists. [KB-0d7daadd-e958-4592-900a-55db91f8aa55], [KB-b8d63553-10df-4d66-abf5-a55b53f12e7b]
### 8.3.3 Service Dependencies
| Source Service | Target Service | Endpoint | Method | Pattern | Purpose |
|------------------|------------------|----------------------------------|--------------|-----------|-------------------------------|
| Order Service | Payment Service | /api/v1/payments | POST | Sync REST | Payment processing |
| Order Service | Payment Service | /api/v1/payments/refund | POST | Sync REST | Refund on cancellation |
| Order Service | Payment Service | /api/v1/payments/order/{order_id}| GET | Sync REST | Retrieve payment info |
| Order Service | Notification Svc | /api/v1/notifications/email | POST | Sync REST | Confirmation/cancellation mail|
| Payment Service | Order Service | /api/v1/orders/{order_id}/webhook| POST | Webhook | Payment status notification |
| Frontend | Order Service | /api/v1/orders | GET/POST/DEL | Sync REST | Order management UI |
| Frontend | Payment Service | /api/v1/payments/order/{order_id}| GET | Sync REST | Payment details display |
| Frontend | Notification Svc | /api/v1/notifications/order/{id} | GET | Sync REST | Notification log display |
[KB-6277ef6e-12da-47d4-a04d-66f27260b610], [KB-6fa3fbfa-477c-4724-b31a-742db2bf1db3], [KB-8ee21731-99a4-4594-8bed-325aedd9b4fb], [KB-c3b67efb-e8bf-455b-a8c3-858db3d5374b], [KB-ed4704d4-9fcc-4c60-b878-959417dbaa70]
### 8.3.4 Data Architecture
- **Database-per-Service**: Each service owns its database (SQLite or PostgreSQL). No cross-service foreign keys; logical references only. [KB-95b83826-82e1-44c0-b244-29599b7d9a45], [KB-fa4dd00c-51bf-47fb-a6ca-6d1cdbed7d96]
- **Data Lifecycle**: Active data is retained for 10 years, transitioned to S3 Standard-IA, then Glacier, and deleted via crypto-shredding after retention expires. [KB-463d7785-30cd-4736-8b69-643a99f749b0], [KB-ecd52426-ac8e-4361-a367-f9e3f335ae52], [KB-f447ff57-3f98-4617-8e4a-3f52efa835a9]
### 8.3.5 Runtime Constraints
- **Strictly Sequential Processing**: Order creation, payment, and notification flows are executed one at a time. No parallel or batch processing is supported. [KB-2c4be7d4-c6b4-4ef4-82e5-67e293132719], [KB-729336f2-e899-4b92-9472-8a92a127506c], [KB-fe50bb36-3c48-4680-b1dc-4d9c17173590]
- **Rate Limiting**: Notification Service enforces a global rate limit of 10 notifications per second. No queuing is implemented. Bulk operations are bottlenecked by this limit. [KB-9de11552-e4f6-4e7c-99bd-16e90f5c9b11]
- **Capability Matrix**: Only single create operations are supported for orders, payments, and notifications. Bulk create, CSV import, and batch processing are not supported.
| Feature | Order | Payment | Notification |
|------------------|-------------------|-------------------|-------------------|
| Single Create | Supported | Supported | Supported |
| Bulk Create | **Not Supported** | **Not Supported** | **Not Supported** |
| CSV Import | **Not Supported** | N/A | N/A |
| Batch Processing | **Not Supported** | **Not Supported** | **Not Supported** |
[KB-7d2665dd-7a87-4cd4-81b2-66cdd4e6085f], [KB-90e1ca95-a701-40c9-b586-f5b2cc0b4f94]
## 8.4 Scheduled Maintenance
| Task | Schedule | Duration | Impact |
|---------------------------|----------------------|------------|------------------|
| RDS minor version update | Monthly (1st Sunday) | 30 min | Brief DB restart |
| ECS platform update | Monthly (1st Sunday) | 0 | Rolling update |
| SSL certificate rotation | Automatic (ACM) | 0 | None |
| Redis cluster maintenance | Monthly (1st Sunday) | 15 min | Brief cache miss |
| OS patching (Fargate) | Automatic | 0 | Rolling update |
| Log rotation / archival | Daily (4:00 AM) | 0 | None |
[KB-31c99645-e4e5-4d8e-a98e-1d2b49255e84]
## 8.5 Runtime Security
- **Authentication**: Azure AD OIDC Authorization Code Flow with PKCE. JWT validated in Spring Boot resource server. [KB-f176d18a-16e9-45c9-b567-474e68c33293], [KB-289d5109-9b10-49e8-98cc-a0307cda8b10]
- **WAF**: AWS WAF on ALB with managed and custom rule groups for OWASP Top 10, SQL injection, rate limiting, geo restriction, and IP reputation. [KB-7bc2b3ea-676c-4b6c-b282-3c7682ccb8ec]
- **Container Image Management**: ECR with enhanced scanning, semantic versioning, and retention policies. [KB-b0103606-7304-4cae-a1f4-8cdcbd835453]
## 8.6 Cost Estimation
| Service | Configuration | Monthly Cost (est.) |
|----------------------------|--------------------------------------|-----------------------|
| ECS Fargate (all services) | ~24 vCPU, ~48 GB avg utilization | $2,400 |
| RDS PostgreSQL | db.r6g.2xlarge, Multi-AZ, 500 GB | $2,800 |
| RDS Read Replica | db.r6g.xlarge, 500 GB | $1,200 |
| ElastiCache Redis | cache.r6g.large, 3 shards + replicas | $1,800 |
| S3 (all buckets) | ~2 TB storage + requests | $350 |
| ALB | 2 ALBs + data processing | $200 |
| WAF | Rules + requests | $150 |
| CloudWatch | Logs, metrics, alarms | $400 |
| NAT Gateway | 3 AZs + data processing | $450 |
| KMS | CMK keys + requests | $50 |
| Route 53 | Hosted zones + health checks | $30 |
| ECR | Image storage + scanning | $50 |
| Secrets Manager | Secret storage + API calls | $30 |
| AWS X-Ray | Trace sampling | $100 |
| Data Transfer | Inter-AZ + internet | $300 |
| **Total (Production)** | | **~$10,310/month** |
[KB-d4bb1606-734b-460c-a50d-42d544e618f3], [KB-cf80d8a3-b711-4f38-96b3-364c86ffea41], [KB-d33b0fde-148f-464c-acee-151105732562]
---
**References:**
[KB-500d2d8b-b1a5-4adb-8b7f-c93d1ed24846], [KB-c7514001-7836-4542-a406-e60d3d718d40], [KB-c255b72d-301a-4f4b-b61b-49b9d81e3150], [KB-764a83b1-2d56-47d3-a045-67435e645329], [KB-8cd4788c-4e85-4d54-a987-2987ef1f6dee], [KB-371a2a34-c7fc-4b6d-a06c-3f4cb574f667], [KB-5755248b-41ad-4acf-8dd0-d7a280ce6111], [KB-4318342d-bb24-493a-4b9-30b3c6c52df4], [KB-6a813ea7-ce62-4533-8c67-6225ee0cb7da], [KB-2fd51f2f-8bea-4db6-b71a-2dd993905d5d], [KB-63703199-62ac-4e6e-a04e-f83f49451750], [KB-b742
## 9. Constraints
# 9. Constraints
This section documents all system, technical, regulatory, and operational constraints that define the boundaries and limitations of the current solution. These constraints must be considered in all design, implementation, and operational activities.
---
## 9.1 Order Processing Constraints
| ID | Constraint | Impact Area | Severity |
|---------|--------------------------------------------------------------------------------------------------------------------|------------------|----------|
| LIM-001 | **Order creation is single-entry only.** No bulk or batch order creation capability exists. Orders can only be created one at a time via the REST API. | Order Service | High |
| LIM-002 | **No CSV/file-based order import functionality.** There is no endpoint or mechanism to upload and process order data from files (CSV, Excel, etc.). | Order Service | High |
| LIM-003 | **Payment processing handles one transaction at a time.** No batch payment API exists. Each order requires an individual payment API call. | Payment Service | High |
| LIM-004 | **Notifications are sent individually per order.** No bulk notification capability exists. Each notification requires a separate API call. | Notification | Medium |
| LIM-005 | **Cross-service calls are sequential.** Order creation flow (Order → Payment → Notification) executes sequentially. No parallel processing of payment and notification. | All Services | Medium |
| LIM-006 | **No progress tracking for batch operations.** The system has no mechanism to track progress of multi-item operations because no batch operations exist. | All Services | Medium |
[KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-4b179d3b-979b-4576-b74f-2dfcbcfd1443], [KB-57bd4cf3-92c5-427a-a300-357f67b20333], [KB-7d2665dd-7a87-4cd4-81b2-66cdd4e6085f], [KB-6f0beda3-71c6-49d1-afe6-4f9a90c6574d], [KB-88f5d60d-eca2-4760-bdbe-838519a0b963]
---
## 9.2 Payment Constraints
- **Maximum amount per transaction:** 1,000,000 JPY is enforced per single payment. Orders exceeding this amount are rejected. There is no aggregated or batch payment endpoint; each order must be paid individually. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-9bbed7ab-b122-4996-8526-88b63bb5aed3], [KB-6c4af247-4d7b-458c-8ea3-77545cb88bf6]
- **1:1 payment-to-order relationship:** The payments table enforces a UNIQUE constraint on order_id. Batch payments covering multiple orders are not possible. No batch_id, bulk_payment_group, or aggregated_amount columns exist. [KB-92fe4b57-1970-4ef5-a240-867f363cff01], [KB-6714d019-5f7b-40d8-8076-f17a39d4c75b], [KB-447f3c51-a447-416e-a1ea-a5ed5855eb8d]
- **No batch payment API:** Processing 10,000 orders requires 10,000 individual payment API calls. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-9bbed7ab-b122-4996-8526-88b63bb5aed3], [KB-447f3c51-a447-416e-a1ea-a5ed5855eb8d]
---
## 9.3 Notification Constraints
- **No bulk notification:** The Notification Service processes one notification per API call. There is no batch notification endpoint. [KB-6beb41f9-8557-4eb3-930c-aff78354467a], [KB-2d9eeb1a-4e0b-4480-a030-a8c7199ebd32], [KB-51d28c72-f536-45dc-b33a-791b463888e9], [KB-6dd65a6a-aa9a-48ad-92b8-e06bd7ac610e]
- **Notification rate limiting:** Maximum 10 notifications per second (global, all channels combined). No queuing mechanism exists. Sending notifications for 10,000 orders would require at least 1,000 seconds (~17 minutes). [KB-26b502e3-480e-4dfb-acfa-b73ff1febca9], [KB-218cb3a7-84eb-4095-a465-10017f99b7a2], [KB-9de11552-e4f6-4e7c-99bd-16e90f5c9b11]
- **No batch notification tracking:** There is no batch_id column in the notifications table; notifications cannot be grouped or correlated by batch. [KB-65241a62-b269-4bc8-b9ed-b2f85e1cefce], [KB-49d60049-0541-4147-bd0c-cc092d6dbbf5], [KB-1cbe1975-7dfa-4b50-a440-cfcc5b38abc9]
---
## 9.4 API and Data Model Constraints
| Area | Constraint | Reference |
|---------------------|--------------------------------------------------------------------------------------------|-----------|
| Order Service | No batch_id, csv_source, or bulk_import_group columns. Only single order payload accepted. | [KB-6f0beda3-71c6-49d1-afe6-4f9a90c6574d], [KB-88f5d60d-eca2-4760-bdbe-838519a0b963] |
| Payment Service | order_id is UNIQUE, enforcing 1:1 payment-to-order. No batch payment fields. | [KB-92fe4b57-1970-4ef5-a240-867f363cff01], [KB-6714d019-5f7b-40d8-8076-f17a39d4c75b] |
| Notification Service| No batch_id or group tracking for notifications. | [KB-65241a62-b269-4bc8-b9ed-b2f85e1cefce], [KB-49d60049-0541-4147-bd0c-cc092d6dbbf5] |
---
## 9.5 Processing Model Constraints
- **Sequential processing:** All cross-service calls (Order → Payment → Notification) are executed sequentially, not in parallel. This increases latency for large-volume operations. [KB-9c55faa0-6c1a-428c-9586-c53f57a5f386], [KB-33c639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-729336f2-e899-4b92-9472-8a92a127506c]
- **No retry or circuit breaker:** If Payment Service is unavailable, order creation fails immediately. There is no retry or partial failure handling for batch operations. [KB-9c55faa0-6c1a-428c-9586-c53f57a5f386], [KB-91e5e2a0-82c2-476e-b32a-d637932e94cf]
- **No batch error handling:** If one order in a hypothetical batch fails, there is no mechanism to continue processing the remaining orders. [KB-91e5e2a0-82c2-476e-b32a-d637932e94cf]
---
## 9.6 Interface and Integration Constraints
- **Synchronous REST only:** All inter-service communication uses synchronous REST over HTTP. No message broker, event bus, or asynchronous channel exists. [KB-7a51aee8-14e6-495b-9d15-8a2591bb1b3f], [KB-39a54ee8-9fa2-4ced-86e4-9a73b008291c]
- **Webhook mechanisms:** Payment status updates to Order Service are single-order only. No batch webhook or batch status update exists. [KB-7730c367-49aa-434a-8b01-36a9e58e272e], [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-6c4af247-4d7b-458c-8ea3-77545cb88bf6]
---
## 9.7 Dashboard and Reporting Constraints
- **Client-side aggregation only:** All dashboard statistics are calculated in the browser. There are no server-side analytics or list-all endpoints. [KB-68f95639-6433-47c5-930c-aff78354467a], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- **N+1 query pattern:** Payment and notification logs are fetched per order due to lack of list-all endpoints. [KB-6ddaf02f-6c2b-4873-b4ca-55bf45feb86f], [KB-6dd65a6a-aa9a-48ad-92b8-e06bd7ac610e]
---
## 9.8 Data Retention and Legal Hold Constraints
- **Retention and disposal:** Data retention periods and disposal methods must comply with NIST SP 800-88. Legal holds supersede retention schedules; data under legal hold must not be disposed of until the hold is released. [KB-295d4584-2321-49c1-bd60-da7b28e7c7dc], [KB-8b66cc71-872a-4371-8aff-fd5d8d8f14dc], [KB-4b326c78-84c3-45fe-9091-dfb2f79c2920], [KB-7047525b-4db7-4214-ae8c-7ab8ce995d55]
---
## 9.9 Security and Compliance Constraints
- **Access control:** Role-based access with minimum necessary standard. Clearance levels and background checks are enforced per role. [KB-a0dcc09b-a277-4c68-bcd6-52bdd64bd527], [KB-a5833d1f-8698-43bb-b85e-e93f36a45471]
- **PHI and error handling:** Error responses must never contain PHI, stack traces, SQL queries, internal file paths, or server names. [KB-10300d8a-a98a-4726-9be3-3957c2fe7bf4], [KB-221e6244-fcbf-434c-8aa7-a850d7be2f8d], [KB-39cb0a23-daec-4c73-8b62-7bc2b4110a12]
- **Encryption:** TLS 1.3 is required for all in-transit data. [KB-3a9b6fa5-5440-4a4a-a8a3-5940b728e89f], [KB-6f168210-157d-42fe-83a1-af92325979ba]
- **Service control policies:** AWS SCPs enforce HIPAA region restriction, encryption, and MFA for IAM actions. [KB-9d14ce68-7c47-4446-b5d4-ff19138cddfd]
- **Workstation and facility security:** Physical access controls, auto-lock, privacy screens, and clean desk policy are enforced. [KB-87c89f7c-2b3c-4e3e-8f87-599d1dd5ebc9], [KB-5d2860d9-c03c-4ff5-900f-d9f3511bdb14]
---
## 9.10 Infrastructure Constraints
- **Legacy systems:** Windows Server 2012 R2 and SQL Server 2012 SP4 are end-of-life and require migration to supported platforms (AWS Linux, PostgreSQL). [KB-2b142c3b-1188-4d02-9e7f-6bdeba51e6da], [KB-8efc44a5-7143-4df1-a66b-2d2b90d1b58c], [KB-b102a172-833d-4e64-9f6e-a5a40ea73bb6]
---
## 9.11 Summary Table: Feature Support Matrix
| Feature | Order Service | Payment Service | Notification Service |
|------------------|--------------|-----------------|---------------------|
| Single Create | Supported | Supported | Supported |
| Bulk Create | Not Supported| Not Supported | Not Supported |
| CSV Import | Not Supported| N/A | N/A |
| Batch Processing | Not Supported| Not Supported | Not Supported |
[KB-7d2665dd-7a87-4cd4-81b2-66cdd4e6085f], [KB-90e1ca95-a701-40c9-b586-f5b2cc0b4f94], [KB-a04b0952-845b-4d10-8dc8-49a9b0e03776]
---
**Note:** Any feature or requirement that exceeds these constraints will require significant architectural changes across multiple services and database schemas.
## 10. Testing
# 10. Testing
This section describes the testing strategy, coverage, schedules, environments, and acceptance criteria for the DentalCare Pro migration and modernization project. All information is sourced directly from the provided context and aligns with ISO-29148 requirements.
---
## 10.1 Testing Objectives
| Objective |
|---------------------------------------------------------------------------------------------|
| 1. Verify functional parity between legacy VB6 and new Spring Boot system |
| 2. Validate data migration accuracy and completeness |
| 3. Ensure HIPAA compliance of the new system (audit, encryption, access control) |
| 4. Validate performance meets or exceeds legacy system benchmarks |
| 5. Confirm security controls are effective against OWASP Top 10 |
| 6. Verify backward compatibility during parallel-run period |
Source: [KB-8663dc13-166e-4d6e-b343-de0243f7e21e]
---
## 10.2 Testing Pyramid
| Layer | Tool/Method | Target % of Tests |
|----------------------|--------------------|-------------------|
| Unit | JUnit 5 | 60% |
| Integration | Testcontainers | 25% |
| End-to-End (E2E) | Cypress | 10% |
| Manual/Exploratory | Manual | 5% |
Source: [KB-35354629-a315-4f6d-962b-84b391e02bad]
---
## 10.3 Test Coverage Requirements
| Package / Module | Minimum Line Coverage | Minimum Branch Coverage |
|-----------------------------|-------------------------|---------------------------|
| Service layer | 85% | 80% |
| Controller layer | 80% | 75% |
| Repository (custom queries) | 90% | 85% |
| Domain model / entities | 70% | 65% |
| Security configuration | 90% | 85% |
| Utility classes | 95% | 90% |
| DTO / Mapper | 70% | 65% |
| **Overall** | **≥80%** | **≥75%** |
Source: [KB-45179f5c-c9c5-45f1-855f-abdcdb9cf406]
---
## 10.4 Test Environment Management
| Environment | Purpose | Data Source | Refresh Cycle | Access |
|----------------|---------------------------|----------------------------|-----------------|------------------|
| Local (Docker) | Developer testing | Seed data (synthetic) | On demand | Developers |
| CI (GitHub) | Automated test execution | Testcontainers (ephemeral) | Per pipeline | CI system |
| Dev | Integration development | Masked production subset | Weekly | Dev team |
| Staging | Pre-production validation | Masked production (full) | Bi-weekly | Dev + QA + UAT |
| Performance | Load/stress testing | Masked production (full) | Monthly | Perf team |
| Production | Live system | Real data | N/A | Authorized users |
Source: [KB-bdbd7378-00c0-4f79-98c2-6010b23e7e6b]
---
## 10.5 Data Migration and Reliability Testing
### 10.5.1 Legacy Data Migration Verification
- All patient records successfully migrated (100% record count match)
- Data integrity verified (checksums match for every patient record)
- Clinical notes content verified (random sampling: 5% of records)
- Dental images migrated with full quality (DICOM header validation)
- Financial records reconciled (total balances match within $0.01)
- Audit trail history migrated to new format
- Historical appointments and scheduling data migrated
- Archived/inactive patient records included in migration
- Signed verification by Clinical Director, Billing Supervisor, and IT Director
- Independent verification by external auditor
Source: [KB-7adacaa6-df86-49fa-b3ca-ad9df0fc2f4e]
### 10.5.2 Post-Migration Verification
- Data migration executed and verified (record count + checksum)
- Parallel run completed (minimum 2 weeks, comparison reports clean)
- User acceptance testing completed and signed off
- Staff training completed for affected user groups
- Monitoring and alerting configured
- Rollback plan tested
- Legacy module disabled (read-only mode)
- Post-migration support plan (2 weeks hypercare)
Source: [KB-afc1ea9f-1e80-473d-a6bf-b43e2ae5f0bd], [KB-05e90e5d-09da-4f67-85af-8f2be11cd2ce]
---
## 10.6 User Acceptance Testing (UAT)
| Phase | Module | UAT Participants | Duration | Status |
|-------|----------------------|--------------------------------------|------------|-----------|
| 1 | Patient Registration | Front desk staff (3), Office mgr (1) | 1 week | Complete |
| 1 | Scheduling | Front desk (3), Dentists (2) | 1 week | Complete |
| 2 | Insurance / Billing | Billing staff (4), Office mgr (1) | 2 weeks | Planned |
| 3 | Clinical Notes | Dentists (4), Hygienists (3) | 2 weeks | Planned |
| 4 | Imaging / Labs / Rx | Dentists (4), Hygienists (3) | 1 week | Planned |
| 5 | Reports / Admin | Office mgr (2), IT admin (2) | 1 week | Planned |
Source: [KB-169a3eb6-41b7-4fce-a195-bdee1db5c1dd], [KB-4ab3bc27-00f6-4912-a639-b17a3c1dc270]
### 10.6.1 UAT Exit Criteria
- All critical test cases passed (100%)
- All high-priority test cases passed (≥95%)
- No critical or high-severity defects open
- Medium-severity defects: documented with workarounds and remediation plan
- Performance acceptable to end users (subjective validation)
- UAT sign-off from each department representative
Source: [KB-a410215e-8c80-439c-bad3-a0a149bd04d7]
---
## 10.7 Security Testing
### 10.7.1 Static Application Security Testing (SAST)
| Tool | Integration Point | Rule Sets | Block on |
|-----------------|---------------------|---------------------------------|---------------|
| SonarQube | Every commit | OWASP Top 10, CWE Top 25 | Critical/High |
| SpotBugs | Every commit | Security, performance bugs | High |
| PMD | Every commit | Code quality, security patterns | Critical |
| OWASP Dep-Check | Every build | Known CVE in dependencies | Critical/High |
| Trivy | Image build | Container vulnerabilities | Critical/High |
Source: [KB-4b1e1077-5d75-41a3-9305-c8c42a105e0a]
### 10.7.2 Dynamic Application Security Testing (DAST) and Dependency Scanning
| Test Type | Frequency | Last Test | Next Test | Responsible |
|-------------------|------------|-------------|-------------|------------------|
| DAST | Weekly | 2025-08-10 | 2025-08-17 | CI/CD Pipeline |
| Dependency Scan | Daily | 2025-08-14 | 2025-08-15 | CI/CD Pipeline |
Source: [KB-b375c242-582e-4892-8768-3f758f02d940]
### 10.7.3 Penetration Testing and Social Engineering
| Test Type | Frequency | Last Test | Next Test | Responsible |
|--------------------------|--------------|-------------|-------------|---------------------|
| Penetration Test | Annual | 2025-05-15 | 2026-01-15 | Vendor (CrowdStrike)|
| Social Engineering Test | Semi-annual | 2025-07-20 | 2026-01-20 | Vendor |
Penetration test scope includes: external/internal network, web application (OWASP Top 10), API, authentication/authorization bypass, PHI exfiltration, social engineering, physical security, wireless, and cloud configuration.
Source: [KB-b6b02b5b-2556-4a05-b583-4d56df4488c2], [KB-837f22a9-21cb-4f12-b96f-98d39ab8c061]
### 10.7.4 OWASP Top 10 and PHI-Specific Security Tests
| Test Category | OWASP Reference | Automated |
|----------------------------|-------------------|----------------------|
| SQL Injection | A03:2021 | Yes |
| Cross-Site Scripting (XSS) | A03:2021 | Yes |
| Broken Authentication | A07:2021 | Yes |
| Broken Access Control | A01:2021 | Yes (custom scripts) |
| Security Misconfiguration | A05:2021 | Yes |
| Sensitive Data Exposure | A02:2021 | Yes (PHI detection) |
| CSRF | A01:2021 | Yes |
| SSRF | A10:2021 | Yes |
| Test | Method | Frequency |
|-------------------------------------------|-----------------------------------|-------------|
| PHI appears in error responses | Automated regex scan of responses | Every build |
| PHI appears in application logs | Log scanning for PII patterns | Daily |
| PHI appears in URLs/query strings | Request log analysis | Daily |
| Unauthorized role accessing PHI endpoints | Authorization matrix test | Every PR |
| PHI accessible after session timeout | Session timeout verification | Weekly |
| PHI cached in browser | Cache-Control header verification | Every PR |
| Encryption at rest verification | Database field inspection | Weekly |
| Audit trail for every PHI access | Audit log completeness check | Daily |
Source: [KB-2e8d1f88-e9ae-4efc-9d8c-5fd7e1e682bc], [KB-4c75377b-a037-47f6-ad8b-1434b40ebc75]
---
## 10.8 Performance Testing
| Scenario | Virtual Users | Duration | Target Response (p95) | Legacy Baseline |
|-------------------------------|-----------------|------------|-------------------------|-------------------|
| Patient search | 100 | 10 min | < 500ms | 2,300ms |
| Appointment booking | 50 | 10 min | < 300ms | 1,800ms |
| Daily schedule view | 200 | 10 min | < 1,000ms | 3,500ms |
| Clinical note save | 30 | 10 min | < 500ms | 3,100ms |
| Insurance eligibility check | 20 | 10 min | < 2,000ms | 5,000ms |
| Payment processing | 25 | 10 min | < 1,000ms | 2,200ms |
| Report generation (day sheet) | 10 | 10 min | < 10,000ms | 45,000ms |
| Mixed workload (realistic) | 500 | 30 min | < 1,000ms (avg) | N/A (max 25) |
| Spike test (300% normal load) | 1,500 | 5 min | < 3,000ms | System crash |
| Soak test (sustained load) | 200 | 4 hours | Stable, no degradation | Memory leak >2h |
Performance acceptance criteria:
| Metric | Threshold | Action if Failed |
|--------------------------|--------------------------|----------------------|
| p95 response time | ≤ target per scenario | Block release |
| p99 response time | ≤ 2x target | Block release |
| Error rate | < 0.1% | Block release |
| CPU utilization (avg) | < 70% | Scale up or optimize |
| Memory utilization (avg) | < 80% | Investigate leak |
| Database connection pool | < 80% utilization | Tune pool settings |
| Throughput | ≥ target requests/second | Block release |
Source: [KB-aa0ffcf5-fe50-400f-82d4-22c4d2d13867], [KB-67fb9c85-638b-438b-871b-3917711691a4], [KB-67fca100-30cc-4b59-8f2e-cb63c33177e8]
---
## 10.9 Disaster Recovery (DR), Rollback, and Failover Testing
| Test Type | Frequency | Last Test | Next Test | Duration | Result |
|------------------------------|--------------|-------------|-------------|------------|----------|
| Backup restoration | Monthly | 2025-07-15 | 2025-08-15 | 2 hours | Pass |
| Read replica promotion | Quarterly | 2025-06-01 | 2025-09-01 | 4 hours | Pass |
| Full DR failover | Semi-annual | 2025-03-15 | 2025-09-15 | 8 hours | Pass |
| DR runbook review | Quarterly | 2025-07-01 | 2025-10-01 | 1 hour | Pass |
| Blue/green deployment rollback | Monthly | 2025-07-15 | 2025-08-15 | N/A | Pass |
| Database backup restoration | Monthly | 2025-07-15 | 2025-08-15 | N/A | Pass |
| Full migration rollback (staging) | Quarterly| 2025-06-01 | 2025-09-01 | N/A | Pass |
| Service-level rollback | Monthly | 2025-07-15 | 2025-08-15 | N/A | Pass |
| Communication plan test | Quarterly | 2025-04-01 | 2025-07-01 | N/A | Pass |
Source: [KB-0ad2d5a6-1c32-426e-b9db-8c8bd6d32e36], [KB-0e7db777-ce75-42c0-aac9-256614f5e8a4], [KB-b40a8978-9ef3-44aa-a3cd-c56a30b5dcfa]
---
## 10.10 Defect Management
| Severity | Definition | SLA (Fix) | SLA (Verify) |
|------------|--------------------------------------------------------|-------------|----------------|
| Critical | System crash, data loss, PHI exposure, security breach | 4 hours | 8 hours |
| High | Major feature broken, no workaround | 1 day | 2 days |
| Medium | Feature impaired, workaround available | 1 sprint | Same sprint |
| Low | Minor issue, cosmetic, edge case | Backlog | Next sprint |
Source: [KB-5a290b8b-e1e3-41ca-bbdf-a7972ec2c2f0]
---
## 10.11 CI/CD Pipeline Testing Flow
```
Developer Workstation
│
│ git push
│
▼
GitHub Actions CI Pipeline
│
├── Build (Maven)
├── Unit Tests
├── Integration Tests (Testcontainers)
├── SAST (SonarQube)
├── Dependency Scan (OWASP Dependency-Check)
├── Docker Image Build
├── Container Scan (Trivy)
│
▼
Staging Environment (ECS Fargate)
│
├── Smoke Tests
├── DAST (OWASP ZAP)
├── Performance Tests (Gatling)
│
▼ (Manual approval gate)
│
Production Environment (ECS Fargate)
│
├── Blue/Green Deployment
├── Health Check Verification
├── Canary Analysis (10% → 50% → 100%)
└── Rollback trigger if error rate > 1%
```
Source: [KB-8cd4788c-4e85-4d54-a987-2987ef1f6dee]
---
If any required information is missing for a specific testing area, it is indicated as follows:
[GAP: Missing data for 10. Testing]
## 11. References
## 11. References
This section lists all referenced documents, standards, and supporting materials cited in this specification. All sources are internal or directly relevant to DentalCare Pro system documentation.
### 11.1 Regulatory and Compliance References
| Regulation | Citation | Topic |
|---------------------|----------------------|------------------------------------------|
| HIPAA Privacy Rule | 45 CFR Part 160, 164 | Use and disclosure of PHI |
| HIPAA Security Rule | 45 CFR §164.302-318 | ePHI safeguards |
| HITECH Act | 42 USC §17931-17940 | Breach notification, enforcement |
| Omnibus Rule (2013) | 78 FR 5566 | BAA requirements, breach definition |
| NIST SP 800-66 | Rev. 2 | HIPAA Security Rule implementation guide |
| NIST SP 800-88 | Rev. 1 | Media sanitization guidelines |
| State Laws | Varies | State-specific breach notification |
_Source: [KB-9a27e347-4e71-4db0-bb22-72254b755315], [KB-b7fc6007-eb00-4eaa-a18a-3954b408a733]_
### 11.2 HIPAA and Security Documentation
- HIPAA Compliance Checklist — Overall compliance status
- Access Control Policy — Detailed access control procedures
- PHI Data Handling Policy — PHI handling requirements
- Audit Trail Requirements — Audit logging specifications
- Security Architecture Review — Technical security architecture
- Cloud Deployment Architecture — AWS deployment security
_Source: [KB-2c4a511f-2ac4-4f71-bd99-515d4b8ee5a0], [KB-401fb277-3246-4168-ae38-d9d02b37654d]_
### 11.3 System and Database Documentation
| Document | Description |
|---------------------------------------------|------------------------------------------------------------------|
| Database Schema Documentation — DentalCare Pro | Describes schemas for legacy SQL Server and target PostgreSQL |
| Database Migration Strategy | Mapping between legacy and target schemas |
| Entity Relationship Summary | Entity relationships across patient, clinical, billing modules |
| Legacy Known Issues and Tech Debt | Inventory of legacy system issues |
_Source: [KB-9015c9bb-88b3-45ee-b20e-b11d73864de8], [KB-bca95227-9970-4317-a9fd-3ae80fa75a9e], [KB-ce6894cd-423d-4213-ab50-bd358f0e88bb], [KB-6395bc66-d8d9-4ad7-a0fa-4dea39549cc8]_
### 11.4 Clinical Coding and Reference Guides
- ADA Treatment Codes Reference — DentalCare Pro
- ADA CDT code reference
- ICD-10 Diagnosis Codes — Common Dental
- Dentist Clinical Guide
_Source: [KB-87e769dc-56f0-41e9-a43e-a57995466a25], [KB-907056f5-69f1-46e2-99f5-e6458a7f1888], [KB-efab16ae-2534-406c-b89b-4f10bde1da28], [KB-5e6ba2df-b2a8-485b-a615-f85574c029a9]_
### 11.5 Drug Interaction and Medication Management
- Drug Interaction Guidelines — DentalCare Pro
- E-prescribing module integration
- Medications Causing Dry Mouth (Xerostomia)
- Immunosuppressant Medications
_Source: [KB-ab500c81-fb0d-468d-ac71-ced650494500], [KB-aa9c4bd8-2051-4a94-9f3a-fa3487a191ee], [KB-654057a0-9e6b-4e8c-8458-d5c20feb64dc], [KB-9f4d7546-b728-4562-a55a-8d17ee5c3116]_
### 11.6 Technical Standards and API Documentation
| Standard/Document | Description |
|--------------------------------------------|--------------------------------------------|
| OpenAPI Specification (OpenAPI 3.1) | API documentation standard |
| Error Handling Standards (RFC 7807) | Standard for error response format |
| API Design Standards (RESTful) | Internal API design and security standards |
| VB6 to Java Mapping Patterns | Migration reference for legacy to Java |
_Source: [KB-24ec7e64-e20f-4a95-b3cf-9948d8ba4afb], [KB-5f9395a7-3eb2-40ef-949b-28422a21e4a9], [KB-b05fa671-858f-4433-a417-ba5cdd56b840], [KB-70990e23-4f9b-41da-af0b-7c2eb8e035be], [KB-4235ffa2-de34-43f8-a48d-ebc32d0a7503], [KB-9767cb6a-06bf-49b5-a4ca-b7ec2cabb858]_
### 11.7 Approval and Review Records
| Role | Name | Date | Document/Area |
|--------------------|---------------|------------|-------------------------------|
| Practice Director | Dr. Alan Brooks| 2025-09-01 | Clinical, billing, admin docs |
| Office Manager | Karen Mitchell | 2025-09-01 | Billing, scheduling, admin docs|
| Billing Supervisor | Maria Santos | 2025-09-01 | Billing operations guide |
| Clinical Director | Dr. Lisa Wong | 2025-05-01 | Clinical reference |
_Source: [KB-ac35c5fb-5563-4393-a68c-de6257d92250], [KB-cf7eab4e-3a49-416b-99c3-ebc1ccdba124], [KB-c53919f6-477c-46fe-855f-ef5bd11f5955], [KB-9c4aed0b-7ce3-49f6-b0e1-d606b37f6d3b]_
### 11.8 Additional References
- Rollback and Contingency Plan
- Billing and Insurance Procedures
- Error Handling Standards
_Source: [KB-3f61786e-e89d-4015-8718-417b49b16d70], [KB-f50b6b0e-f771-453b-b8a2-76cf73c7de19], [KB-b05fa671-858f-4433-a417-ba5cdd56b840], [KB-9767cb6a-06bf-49b5-a4ca-b7ec2cabb858]_
If further reference details are required, see the cited block IDs for full document access.