## Introduction

# Introduction

This document provides a detailed overview of the current system architecture, business processes, and technical constraints relevant to the DentalCare Pro order management and associated services. The content herein is based solely on the documented requirements, system limitations, and business needs as captured in the provided knowledge base.

The primary focus is on the order management system, including its REST API interfaces, payment and notification integration, and operational constraints. The document also addresses the lack of bulk or batch processing capabilities, CSV import functionality, and outlines the sequential nature of cross-service interactions. These limitations have a significant impact on operational efficiency, particularly for enterprise customers seeking to process large volumes of orders.

Additionally, the document references the business rationale for migration from legacy systems, compliance requirements (including HIPAA and data retention policies), and the technical debt inherent in the current architecture. Where applicable, the document includes tables and structured data to preserve the original format and clarity of the source material.

This introduction sets the stage for a comprehensive analysis of the system’s current state, identifies gaps, and provides a foundation for future enhancements and migration planning in accordance with ISO-29148 requirements.

**References:**
- [KB-146a6a29-932f-485d-96d6-6a92ee610336]
- [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c]
- [KB-150eb89c-77b0-415b-a547-3ed0502eec24]
- [KB-16181d30-2dd3-421e-bab0-939cd85255d2]
- [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1]
- [KB-1603dccf-0e13-426d-a4c3-527af9e69c16]
- [KB-1714d093-cdf6-43c2-b866-d630dd5509e4]

## Getting Started

# 1. Getting Started

This section provides an overview of how to begin using the system, including its current capabilities, limitations, and user interface guidance. The information below is based strictly on the provided system documentation and requirements.

---

## 1.1 System Overview

The order management system provides a web-based interface for managing orders, payments, and notifications. The frontend is implemented as a React single-page application (SPA) and connects to three backend microservices via REST API. All inter-service communication is synchronous REST over HTTP, with no message brokers or asynchronous channels present. Each service is responsible for a specific domain: Order Service, Payment Service, and Notification Service. [KB-050d0be4-11bc-4945-80e4-1ed80f2de11e]

---

## 1.2 Core Functionalities

- **Order Management:** Users can create, view, and manage orders one at a time via the web interface. Each order requires customer information and order details (product name, quantity, unit price). [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]
- **Payment Processing:** Each order triggers an individual payment transaction. Payments are processed per order; batch or aggregate payments are not supported. [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c]
- **Notification Service:** Notifications (such as order confirmations) are sent individually per order. There is no bulk notification capability. [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a]
- **Order Detail View:** For each order, the system fetches data from all three services in parallel: order details, payment status, and notification history. [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

---

## 1.3 System Limitations

The current system has several important limitations:

| ID      | Limitation                                                                                                         | 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 Service | 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]

Additional technical constraints:

- **No bulk order import UI:** There is no CSV upload, drag-and-drop, or batch creation form available in the frontend. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- **N+1 API pattern:** The frontend must make individual API calls for each payment and notification due to the lack of list-all endpoints. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- **Client-side aggregation:** Dashboard statistics are computed in the browser, not on the backend. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- **No real-time updates:** The system uses polling for updates; WebSocket or push-based real-time updates are not supported. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- **Single language:** The interface is Japanese-only; there is no internationalization (i18n) framework. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]

---

## 1.4 User Interface Guidance

- **Order Management Page (/orders):**
  - Users can search orders by customer name or email (client-side filter).
  - Status filter and sortable order table are available.
  - Single order creation form is provided.
  - CSV Import button is present but disabled and labeled “CSVインポート（未実装）” (CSV Import (Not Implemented)).
  - A banner indicates that CSV import is not available. [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

- **Order Detail Page (/orders/:id):**
  - Displays order information, payment card, and notification history.
  - Data is fetched from all three backend services in parallel. [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

---

## 1.5 Getting Help

For questions or issues related to system limitations, contact the architecture team at architecture@dentalcarepro.com. [KB-02bc6ee3-521e-4ebf-b934-b7e08bd16081]

---

## 1.6 Summary Table: Key Getting Started Facts

| Feature/Area            | Supported | Notes                                                                                 |
|-------------------------|-----------|---------------------------------------------------------------------------------------|
| Single order creation   | Yes       | Via web UI or REST API                                                                |
| Bulk order creation     | No        | Not supported; CSV/file import unavailable                                            |
| Payment processing      | Yes       | One transaction per order; no batch/aggregate payments                                |
| Notification sending    | Yes       | One notification per order; no bulk notification                                      |
| Real-time updates       | No        | Polling only; no WebSocket or push                                                    |
| Internationalization    | No        | Japanese only; no i18n framework                                                      |
| Dashboard aggregation   | Yes       | Client-side only; no backend aggregation                                              |
| Progress tracking (batch)| No       | Not available due to lack of batch operations                                         |

[KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

---

**Note:** Any feature requiring bulk or batch processing (order creation, payment, notification) is not available in the current system and will require significant architectural changes to implement. [KB-146a6a29-932f-485d-96d6-6a92ee610336]

## Build and Test

# 6. Build and Test

## 6.1 Build Approach

The system build follows a modular, service-oriented architecture, with each microservice (Order Service, Payment Service, Notification Service) deployed independently. The backend is implemented using Spring Boot, with data persistence on PostgreSQL 16 (AWS RDS). Audit logging is handled via PostgreSQL tables, CloudWatch, and Elasticsearch for analysis. The frontend is a React single-page application (SPA) interfacing with backend REST APIs. No bulk or batch order creation functionality exists; all orders are created individually via API calls. [KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-0e90d327-2678-405f-b35a-294b5435dc66], [KB-17a58f06-2387-412d-bf37-2f4d751e1d7e], [KB-1a54c453-d6ee-488f-bbdc-311c467a9661]

### Key Build Constraints

| Constraint                                                                                       | Impacted Area         | Severity   |
|--------------------------------------------------------------------------------------------------|-----------------------|------------|
| Single-entry only for order creation (no batch/CSV import)                                       | Order Service         | High       |
| Payment processing is one transaction at a time (no batch payment API)                           | Payment Service       | High       |
| Notification processing is one message per API call (no bulk notification API)                   | Notification Service  | Medium     |
| Cross-service calls are sequential (Order → Payment → Notification), no parallel processing      | All Services          | Medium     |
| No progress tracking for batch operations                                                        | All Services          | Medium     |
| No CSV upload or batch creation UI in frontend                                                   | Order Management UI   | High       |
| No bulk import tracking fields in database schema (e.g., batch_id, csv_source)                   | Data Layer            | High       |

[KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-0f930ddc-1f3a-4014-a015-49fe1808f8d8], [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-06c5403a-d177-4525-b247-1d7ae37a86b8], [KB-04a84995-0820-4319-9d26-c1582821058a], [KB-11739ab0-b209-41e4-b73e-7d7e0c4338b2]

## 6.2 Test Approach

### 6.2.1 Unit Testing

- All Spring Boot services are required to have ≥80% line coverage via unit tests.
- Unit tests cover business logic, input validation, and error handling.
- Critical security features (authentication, authorization, input validation, audit logging) are tested for compliance.

[KB-0a1640fc-d3df-49c8-9862-d52514894afd]

### 6.2.2 Integration Testing

- Integration tests are executed against PostgreSQL to verify end-to-end data flow.
- API endpoints are validated for correct response formats, error handling, and security headers (e.g., Cache-Control: no-store for PHI).
- Payment and notification service integrations are tested for timeout and error scenarios (no retry/circuit breaker; failures revert order status to PENDING).

[KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-0d7daadd-e958-4592-900a-55db91f8aa55], [KB-1718c2d8-b71b-4113-9906-a6d9765958ff]

### 6.2.3 Performance Testing

| Metric                       | Target           | Measurement Method      |
|------------------------------|------------------|------------------------|
| API response time (p50)      | < 200ms          | Application metrics    |
| API response time (p95)      | < 500ms          | Application metrics    |
| API response time (p99)      | < 1,000ms        | Application metrics    |
| Page load time (initial)     | < 2 seconds      | Lighthouse measurement |
| Page load time (subsequent)  | < 1 second       | Client-side metrics    |
| System availability          | 99.9%            | Uptime monitoring      |
| Concurrent users             | 500+             | Load testing           |
| Database query time (avg)    | < 100ms          | RDS Performance Insights|
| API throughput               | > 1,000 req/min  | Load testing           |

[KB-0d9e59c7-0414-46c2-b302-2f4cbc1e9e88]

**Note:** Due to sequential processing and rate limits, bulk operations (e.g., 10,000 orders) require 10,000 API calls and can take significant time (e.g., notification rate limit is 10/sec, so 10,000 notifications require ~17 minutes minimum). [KB-04a84995-0820-4319-9d26-c1582821058a], [KB-06c5403a-d177-4525-b247-1d7ae37a86b8], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]

### 6.2.4 Security Testing

- Authentication and authorization are validated using OAuth 2.0 Resource Server + Azure AD.
- CSRF protection, CORS policy, content security policy, rate limiting, input validation, output encoding, session management, and dependency scanning are tested as per requirements.

| Feature                 | Implementation                             | Priority   |
|-------------------------|--------------------------------------------|------------|
| Authentication          | OAuth 2.0 Resource Server + Azure AD       | Critical   |
| Authorization           | Method-level @PreAuthorize with SpEL       | Critical   |
| CSRF Protection         | SameSite cookies + CSRF tokens             | High       |
| CORS Policy             | Whitelist-based origin validation          | High       |
| Content Security Policy | Strict CSP headers                         | High       |
| Rate Limiting           | Bucket4j with Redis backend                | Medium     |
| Input Validation        | Bean Validation + custom validators        | Critical   |
| Output Encoding         | OWASP Java Encoder                         | Critical   |
| Session Management      | Stateless (JWT) with Redis token blacklist | Critical   |
| Dependency Scanning     | OWASP Dependency-Check in CI/CD            | High       |

[KB-0910e88e-c115-4411-a137-d96b5c1a2082]

**CRITICAL SECURITY RULE:** Error responses in production must NEVER contain PHI, stack traces, SQL queries, internal file paths, server names, or framework version information. Violations are treated as security incidents. [KB-10300d8a-a98a-4726-9be3-3957c2fe7bf4], [KB-140ca7f3-3348-4419-b06b-89561882a35e]

### 6.2.5 Data Migration and Integrity Testing

- Data migration is verified via record count, checksum, and parallel run (minimum 2 weeks).
- Comparison tests ensure new patient registrations, appointment counts, daily financial totals, claims submitted, payments posted, and clinical note counts match legacy system within defined tolerances.

| Comparison Test                 | Tolerance   | Alert Level         |
|---------------------------------|-------------|---------------------|
| New patient registrations match | 0           | Critical            |
| Appointment count matches       | 0           | Critical            |
| Daily financial totals match    | $0.01       | Critical            |
| Claims submitted match          | 0           | High                |
| Payments posted match           | $0.01       | Critical            |
| Clinical note count matches     | 0           | High                |
| User login count comparison     | ±5%         | Low (expected diff) |

[KB-092b662f-1233-4421-8d0a-d97f8816acb2], [KB-05e90e5d-09da-4f67-85f6-8f2be11cd2ce]

### 6.2.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 (1)               | 1 week     | Planned  |

[KB-169a81d5-18f2-41a8-9629-a593b8fc96e5]

## 6.3 Rollback and Disaster Recovery Testing

| Test Type              | Frequency     | Last Test   | Next Test   | Duration   | Result   |
|------------------------|---------------|-------------|-------------|------------|----------|
| Blue/green deployment rollback    | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |
| Database backup restoration       | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |
| Full migration rollback (staging) | Quarterly     | 2025-06-01  | 2025-09-01  | Pass     |
| Service-level rollback            | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |
| Full DR failover                  | Semi-annually | 2025-03-15  | 2025-09-15  | 8 hours   | Pass     |

[KB-0e7db777-ce75-42c0-aac9-256614f5e8a4], [KB-0ad2d5a6-1c32-426e-b9db-8c8bd6d32e36], [KB-04c5b64b-0ba0-40cd-864f-395e17b12504], [KB-190fe16f-a70b-4fa5-869a-fcb047547798]

## 6.4 Compliance Testing

- HIPAA technical safeguards are verified, including audit trail continuity, access control parity, encryption at rest and in transit, and breach notification procedures.
- Migration team signs additional confidentiality agreements.
- Parallel run compliance monitoring is conducted during migration.

[KB-1554a441-9086-4371-85f6-cb4d7472ee1b], [KB-189ad159-0642-4473-93ef-0a4cb410ea52], [KB-0f3989d4-36c1-4054-923c-c250f04c3ec3], [KB-116f84fb-2eec-4493-9762-414a92624981]

## 6.5 Known Gaps

[GAP: Missing data for Build and Test]

---

**End of Section**

## Contribute

# Contribute

## System Limitations and Constraints

The current system imposes several critical limitations that directly impact the ability of users and integrators to contribute enhancements, particularly in the area of order management and bulk processing. These constraints are summarized below:

| ID      | Limitation                                                                                                                                                               | 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 Service | 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     |

**Source:** [KB-146a6a29-932f-485d-96d6-6a92ee610336]

### Implications for Contributors

- **No Bulk Import/Export:** Contributors cannot extend the system to support bulk order creation, CSV import, or batch processing without significant architectural changes. All order-related contributions must conform to the single-entry paradigm.
- **API Design Constraints:** Any new API endpoints or enhancements must not assume the existence of batch or bulk processing capabilities. All integrations must operate on a per-order, per-payment, and per-notification basis.
- **Performance and Scalability:** Due to the lack of parallel processing and batch APIs, contributors should be aware that high-volume operations (e.g., processing thousands of orders) will result in substantial latency and operational overhead.
- **UI/UX Limitations:** User interface contributions must not expose or imply bulk upload or batch processing features. For example, the order management UI displays a disabled CSV Import button with a label indicating "CSV Import (Not Implemented)" and an amber warning banner to communicate this limitation to users. ([KB-16181d30-2dd3-421e-bab0-939cd85255d2])
- **No Progress Tracking for Batches:** Since batch operations are not supported, there is no facility for tracking progress, partial failures, or resumable imports. Contributors should not attempt to implement or expose such features in the current architecture.

## Contribution Scope

- **Permitted Contributions:**
  - Enhancements to single-order workflows (creation, update, cancellation)
  - Improvements to per-order payment and notification flows
  - UI/UX refinements that do not introduce or suggest bulk capabilities
  - Documentation, error handling, and validation improvements within the single-entry model

- **Out-of-Scope Contributions:**
  - Any feature or module that requires batch or bulk processing (e.g., CSV import, batch payments, bulk notifications)
  - Architectural changes to enable parallel or asynchronous processing without prior approval and cross-service impact analysis

## Architectural Change Process

Any proposal to introduce batch or bulk processing capabilities must be submitted as a formal architecture change request. Such changes will require:

- Impact assessment across all affected services (Order, Payment, Notification)
- Redesign of API contracts and data models to support batch operations
- Implementation of progress tracking, error handling, and rollback mechanisms for batch processes
- Review and approval by the lead architect and relevant stakeholders

## Contact and Approval

For questions regarding contribution boundaries or to initiate an architecture change request, contact the lead architect or submit an inquiry to the architecture review board as specified in the system documentation.

**Reference:**  
- [KB-146a6a29-932f-485d-96d6-6a92ee610336]  
- [KB-16181d30-2dd3-421e-bab0-939cd85255d2]