> **Solution design — order-status polling endpoint** · produced by `swarmkit run oms-design (solution-architect)` · requirement **OMS-101** ### Solution Design for Order Status Polling Endpoint (OMS-101) #### Overview The requirement is to create a status endpoint in the Order Management System (OMS) that allows the Web storefront to submit a customer order and subsequently poll for its status. This design will outline the components involved, data and API changes, integration points, and potential risks associated with the implementation. --- ### Components Touched 1. **Web Storefront**: The frontend application where customers place orders. 2. **Order Management System (OMS)**: The backend system responsible for processing and managing orders. 3. **Database**: The data storage layer where order details and statuses are stored. 4. **API Gateway**: The entry point for the Web storefront to communicate with the OMS. 5. **Notification Service**: (Optional) A service to notify the Web storefront of status changes. --- ### Data + API Changes #### 1. **Database Changes** - **Orders Table**: Ensure the table has the following fields: - `order_id` (Primary Key) - `customer_id` - `status` (e.g., Pending, Processing, Shipped, Delivered, Cancelled) - `created_at` - `updated_at` - **Indexes**: Create indexes on `order_id` and `status` for efficient querying. #### 2. **API Changes** - **POST /orders**: Endpoint for submitting a new order. - Request Body: ```json { "customer_id": "string", "items": [ { "product_id": "string", "quantity": "integer" } ] } ``` - Response: ```json { "order_id": "string", "status": "Pending" } ``` - **GET /orders/{order_id}/status**: Endpoint for polling the order status. - Response: ```json { "order_id": "string", "status": "string", "updated_at": "timestamp" } ``` --- ### Integration Points 1. **Web Storefront to API Gateway**: The storefront will call the `POST /orders` to create an order and `GET /orders/{order_id}/status` to poll for the order status. 2. **API Gateway to OMS**: The API Gateway will route requests to the appropriate services within the OMS. 3. **OMS to Database**: The OMS will interact with the database to store and retrieve order information. 4. **(Optional) Notification Service**: If implemented, the OMS could notify the storefront of status changes via WebSocket or a similar mechanism. --- ### Risks 1. **Performance**: Frequent polling by the storefront could lead to performance issues. Consider implementing a rate limit on the polling requests. 2. **Data Consistency**: Ensure that the order status is updated atomically in the database to prevent race conditions. 3. **Error Handling**: Define clear error responses for cases such as order not found or invalid order ID. 4. **Scalability**: As the number of orders increases, the system should be designed to handle a growing number of requests efficiently. 5. **Security**: Implement authentication and authorization to ensure that only authorized users can access order status. --- ### Open Questions for the Team 1. **Polling Frequency**: What should be the recommended polling interval for the storefront? Should we implement a back-off strategy? 2. **Notification Mechanism**: Should we implement a real-time notification system for order status updates, or rely solely on polling? 3. **Error Handling Strategy**: What specific error codes and messages should we return for common failure scenarios? 4. **Data Retention Policy**: How long should order statuses be retained in the database, and how will we handle archival? 5. **Testing Strategy**: What testing framework will we use to ensure the reliability of the new endpoints? --- This solution design outlines the necessary components, data structures, API changes, integration points, and risks associated with implementing the order status polling feature in the OMS. Further discussions and decisions on open questions will help refine the design and ensure a successful implementation.