System Requirements

Functional Requirements:

• Track order states strictly (Placed -> Processing -> Shipped -> Delivered).
• Enable admins to manage orders and update statuses.
• Customers can only view and receive notifications for their own orders.
• Support multi-channel asynchronous notifications (Email, SMS, Push) upon status changes.

Non-Functional Requirements:

• Strong Consistency (Write Path): The database must be the absolute source of truth for the order state.
• Guaranteed Delivery (Eventual Consistency): If an order state changes, the notification must eventually be sent, even if the email provider goes down.
• Idempotency: A customer must never receive duplicate notifications for the same state change.

API Design

We keep the APIs RESTful, utilizing JWT tokens to enforce the authorization boundaries between Admins and Customers.

1. Update Order Status (Admin Only) PATCH /v1/orders/{order_id}/status

JSON

2. Get Order Status (Customer) GET /v1/orders/{order_id} The API Gateway checks the JWT. If the userId in the token does not match the userId attached to the order in the database, it returns a 403 Forbidden.

High-Level Design

• API Gateway: Routes traffic and strictly enforces Role-Based Access Control (RBAC).
• Order Service: Handles the incoming REST requests, enforces the state machine (e.g., you cannot go from PLACED to DELIVERED), and commits the write to the database.
• Primary Database (PostgreSQL): The absolute source of truth.
• CDC Pipeline (Debezium): Tails the database's write-ahead log (WAL). When it detects a row change in the Orders table, it instantly publishes a structured event to Kafka.
• Message Broker (Kafka): Acts as the reliable buffer and distributor for the state change events.
• Notification Service: Consumes the Kafka events, determines the user's notification preferences, and dispatches the payload to the respective third-party providers (APNs, FCM, SendGrid, Twilio).

Detailed Component Design

Here is where we solve the "Dual Write" redundancy and make the system robust.

1. The "Listen to Yourself" Pattern (Pure CDC) Instead of your application API writing to Kafka and the database, the API only does one thing: it updates the PostgreSQL database. Because Debezium is directly monitoring the database transaction log, the very act of updating the database automatically generates the event for the Notification Service. This guarantees that an event is only ever published if the database transaction was successful. You never have a scenario where an event hits Kafka, but the database write fails.

2. Notification Idempotency Kafka guarantees "at-least-once" delivery. This means during a network blip, your Notification Service might read the same "Order Shipped" event twice. To prevent sending two identical text messages to a customer, the Notification Service must implement an Idempotency Key. It can generate a unique hash (e.g., orderId_status_SHIPPED) and store it in Redis with a 24-hour TTL. Before making the API call to Twilio or APNs, it checks Redis. If the key exists, it drops the duplicate event.

3. State Machine Guardrails The Order Service must enforce a strict state machine before committing to the database. If an Admin tries to update an order from PROCESSING back to PLACED, the application layer should reject it with a 400 Bad Request. This ensures the CDC pipeline only ever broadcasts valid, forward-moving business events.