System requirements

Functional:

User Registration: Register customers, stores/farmers, and delivery personnel with role-based access.

Product Catalog: Stores can manage product details, pricing, and availability.

Search & Discovery: Customers can search for products, filter by price, and check store ratings.

Order Management: Customers place orders, schedule deliveries, and track status.

Payment Integration: Support for multiple payment methods and secure transactions.

Delivery Management: Match orders to delivery personnel and provide real-time tracking.

Notifications: Real-time notifications for order status and delivery updates.

Ratings & Reviews: Customers review stores and delivery experience.

Admin Dashboard: Admins can manage users, orders, and system performance.

Non-Functional:

Scalability: Support growth in users and order volumes.

Availability: 99.9% uptime for uninterrupted service.

Performance: API response time < 300 ms.

Capacity estimation

Assumptions:

Users: 100,000 active users.
Stores/Farmers: 500 stores and farmers.
Daily Orders: 20,000 orders/day.
Peak Traffic: 5x traffic during peak hours (around 100 orders/min).
Delivery Personnel: 500 delivery personnel.
Notifications: Real-time notifications for 90% of orders.

API design

There will be following API's required for this:

Notification APIs
Order Management APIs
User Management APIs
Product Management APIs

Product Management APIs (For Stores)

Add Product

POST /api/products
Request:
{
  "storeId": "54321",
  "productName": "Fresh Apples",
  "category": "Fruits",
  "price": 2.5,
  "quantity": 100,
  "description": "Fresh red apples from local farms",
  "imageUrl": "https://example.com/images/apples.jpg"
}

Response:
{
  "productId": "67890",
  "storeId": "54321",
  "productName": "Fresh Apples",
  "created_at": "2024-09-29T14:05:00Z"
}

Get Products by Store

GET /api/stores/{storeId}/products
Response:
[
  {
    "productId": "67890",
    "productName": "Fresh Apples",
    "price": 2.5,
    "quantity": 100,
    "description": "Fresh red apples from local farms",
    "imageUrl": "https://example.com/images/apples.jpg"
  }
]

Database design

Entities and Relationships:

Users Table: Stores information about all users (customers, stores, delivery personnel, and admins).
Stores Table: Contains store details for stores and farmers.
Products Table: Stores details of products listed by stores and farmers.
Orders Table: Captures order details and maps to customer and product entities.
OrderItems Table: Contains line items for each order, mapping products to orders.
Delivery Table: Manages delivery details for each order, including status and delivery personnel information.
Notifications Table: Stores real-time notifications related to order updates or promotions.

graph LR
    A[Order Management Service] -->|Validate Inventory| B(Product Catalog Service)
    A -->|Process Payment| C[Payment Gateway]
    A -->|Send Order Status| D[Notification Service]
    A -->|New Order| E[Delivery Service]
    E -->|Assign Delivery| F[Delivery Personnel]
    D -->|Send Notification| G[Customer]

High-level design

Key Components:

API Gateway: Handles incoming HTTP requests and routes them to the appropriate services.
User Service: Manages user-related operations, such as registration, authentication, and profile management.
Product Catalog Service: Handles all operations related to the management of products by stores/farmers.
Order Management Service: Manages order creation, status tracking, and payment processing.
Delivery Service: Coordinates delivery operations, including order assignment to delivery personnel and tracking.
Notification Service: Handles real-time notifications for order updates and promotions.
Admin Dashboard Service: Provides a UI for platform administrators to manage users, orders, and monitor platform health.
Database Layer: A separate database for each service to ensure service independence and easier scaling.
Cache Layer: Caching frequently accessed data such as product catalogs and user profiles to reduce database load.
External Integrations: Handles integrations with external services such as payment gateways and third-party delivery providers.

graph TD
    A[API Gateway] --> B[User Service]
    A --> C[Product Catalog Service]
    A --> D[Order Management Service]
    A --> E[Delivery Service]
    A --> F[Notification Service]
    A --> G[Admin Dashboard Service]
    
    B --> DB1[(User Database)]
    C --> DB2[(Product Database)]
    D --> DB3[(Order Database)]
    E --> DB4[(Delivery Database)]
    F --> DB5[(Notification Database)]

    D --> P[Payment Gateway]
    E --> L[Third-Party Logistics]

    subgraph Cache Layer
        C1[User Cache]
        C2[Product Cache]
        C3[Order Cache]
    end

    B --> C1
    C --> C2
    D --> C3

flowchart TD
    B[client] --> C{server}
    C --> D[Database]

Request flows

Order Placement Flow

Customer places an order via the API Gateway.
The request is routed to the Order Management Service.
Order Management Service verifies products, updates inventory in the Product Catalog Service, and creates the order.
Sends a message to the Notification Service and confirms payment through Payment Gateway.
The response is sent back to the customer.

sequenceDiagram
    participant Customer
    participant APIGateway
    participant OrderService
    participant ProductService
    participant PaymentGateway
    participant NotificationService

    Customer->>APIGateway: POST /api/orders
    APIGateway->>OrderService: Forward order request
    OrderService->>ProductService: Validate and reserve products
    ProductService-->>OrderService: Products validated
    OrderService->>PaymentGateway: Process payment
    PaymentGateway-->>OrderService: Payment successful
    OrderService->>NotificationService: Send order confirmation
    NotificationService-->>OrderService: Notification sent
    OrderService-->>APIGateway: Order created response
    APIGateway-->>Customer: Response (Order ID, Status)

Order Delivery Flow

Order status changes to Out for Delivery in the Order Service.
Delivery Service assigns a delivery person to the order.
Delivery person updates the order status as Delivered.
Notification Service informs the customer about the delivery status.

sequenceDiagram
    participant OrderService
    participant DeliveryService
    participant DeliveryPerson
    participant NotificationService
    participant Customer

    OrderService->>DeliveryService: New Order, status "Out for Delivery"
    DeliveryService->>DeliveryPerson: Assign delivery task
    DeliveryPerson-->>DeliveryService: Update order status "Delivered"
    DeliveryService-->>OrderService: Delivery status updated
    OrderService->>NotificationService: Send delivery notification
    NotificationService-->>Customer: Your order has been delivered

Detailed component design

Order Management Service

Responsibilities:

Handle order creation, validation, and updates.
Interface with Product Catalog Service for inventory checks.
Manage payment processing and order status changes.

Scalability Considerations:

Use message queues (e.g., RabbitMQ or Kafka) for handling order lifecycle events (e.g., "Order Created", "Order Payment Confirmed").
Implement a sharded database structure to distribute read and write loads across multiple nodes.

Delivery Service

Responsibilities:

Assign delivery personnel based on location and order priority.
Track delivery status and update Order Management Service.

Scalability Considerations:

Use geospatial indexing (e.g., MongoDB geospatial queries) to match delivery personnel with orders efficiently.
Implement a worker-based system for handling delivery assignments during high-volume periods.

Notification Service

Responsibilities:

Send real-time notifications to users for order updates, promotions, and alerts.
Interface with external notification services like SMS and email providers.

Scalability Considerations:

Implement a message queue for high-throughput processing of notifications.
Use a publish-subscribe pattern for different notification types (e.g., order updates vs. promotions).

graph LR
    A[Order Management Service] -->|Validate Inventory| B(Product Catalog Service)
    A -->|Process Payment| C[Payment Gateway]
    A -->|Send Order Status| D[Notification Service]
    A -->|New Order| E[Delivery Service]
    E -->|Assign Delivery| F[Delivery Personnel]
    D -->|Send Notification| G[Customer]

Trade offs/Tech choices

Geospatial Indexing is crucial for optimizing location-based queries in the Delivery Service. In the Fresh Grocery Delivery System, the Delivery Service uses geospatial indexing to efficiently assign delivery personnel to orders based on their proximity to the store and the customer. This ensures that deliveries are completed in the shortest possible time, minimizing delivery costs and improving user experience.

How Geospatial Indexing is Used:

Delivery Personnel Location Storage:
- Each delivery personnel's current location is stored with geospatial coordinates (latitude and longitude) in the database.
- A location field with a geospatial index is used to quickly find delivery personnel within a given radius from a store or customer.
Efficient Querying:
- When a new order is placed, the system queries the database to find the nearest delivery personnel using a geoNear or $nearSphere query.
- The query checks for delivery personnel within a defined radius (e.g., 10 km) and sorts by proximity to determine the best match.
Handling Dynamic Location Updates:
- Delivery personnel update their location in real-time (e.g., every few seconds) via a mobile app.
- The database efficiently updates the geospatial index to reflect new positions without locking the entire table, ensuring real-time data accuracy.
Delivery Assignment Workflow:
- When an order is ready for delivery, the Delivery Service executes a geospatial query to find the nearest available delivery person.
- After finding potential candidates, the system applies further filtering based on availability and load (e.g., no. of active deliveries).

Trade-off: Slightly higher read/write latency due to complex spatial queries.

Failure scenarios/bottlenecks

High Latency in Delivery Assignments:

Scenario: Delivery personnel location updates are delayed, leading to suboptimal assignments.
Mitigation: Use WebSocket-based communication for real-time location updates and implement exponential backoff for retries.

Network Failures:

Scenario: Temporary network outages cause failed API calls between services.
Mitigation: Implement circuit breakers and retry mechanisms with fallback strategies.

Cache Inconsistency:

Scenario: Stale data in cache due to delayed invalidation, leading to incorrect product availability or pricing.
Mitigation: Implement cache expiration policies and event-based cache invalidation.

Future improvements

Introduce Machine Learning for Delivery Optimization:

Use machine learning to predict delivery times, optimize routes, and dynamically allocate delivery personnel based on historical data and traffic patterns.

Implement a Recommendation System:

Build a recommendation engine to suggest products to users based on their past orders and preferences, enhancing user engagement and boosting sales.

Dynamic Pricing for High Demand Periods:

Implement dynamic pricing strategies for delivery fees or product prices during high-demand periods to manage load and maximize revenue.

Enhanced Real-time Tracking and Notifications:

Provide real-time map-based tracking for customers to see exact delivery personnel movement.
Implement in-app and voice notifications for a richer user experience.

Solutions

nectar4678 - 09/29/2024

0

nina_v - 07/03/2026

0