Skip to content

LogistiX System Design and Architecture

This document outlines the proposed system design and architecture for the LogistiX platform, based on the requirements gathered during the feasibility study.

1. High-Level Architecture

LogistiX will be designed as a cloud-native application leveraging a modular architecture. While initially potentially developed as a well-structured monolith for faster MVP development with a small team, the design will facilitate future evolution towards microservices if scaling demands necessitate it.

The core components will include:

  1. Merchant API: A RESTful API serving as the primary interface for e-commerce merchants (SMEs) to integrate their systems (e.g., websites, order management systems) with LogistiX. This API will handle tasks like creating delivery orders, fetching quotes, tracking shipments, and managing merchant accounts.
  2. Courier Mobile Application: A cross-platform mobile application (built with Flutter) for delivery couriers. This app will allow couriers to view assigned deliveries, update delivery statuses (picked up, delivered, failed), navigate routes, and manage their earnings/profile.
  3. Merchant Dashboard: A web-based application (built with React) for merchants who prefer not to integrate via API or need a visual interface. It will provide functionality similar to the Merchant API, allowing manual order creation, shipment tracking, account management, reporting, and potentially courier management tools.
  4. Admin Dashboard: A separate web-based application (likely also React) for the LogistiX operations team. This will be used for managing merchants, couriers, system settings, monitoring platform health, handling disputes, and generating operational reports.
  5. Backend Services / Core Logic: The central engine built with Node.js. This component will house the business logic for:
    • Order Management (creation, assignment, tracking)
    • Courier Matching & Dispatching (algorithms for assigning orders to suitable couriers)
    • Route Optimization (integrating with mapping services)
    • Pricing Calculation
    • User Management (Merchants, Couriers, Admins)
    • Notifications (SMS/Push via Firebase/Twilio)
    • Database Interaction (PostgreSQL)
    • Integration with third-party services (Mapping, Payments like M-Pesa).
  6. Database: A PostgreSQL database to store all persistent data, including user information, orders, delivery statuses, pricing rules, etc.
  7. Caching Layer: Redis will be used for caching frequently accessed data (e.g., session information, configuration, potentially pre-calculated routes or quotes) to improve performance and reduce database load.

Interaction Flow (Simplified Example - Order Creation): * Merchant creates an order via API or Dashboard. * Backend Service validates the order, calculates pricing, stores it in the PostgreSQL DB. * Backend Service uses the matching algorithm to find suitable couriers. * Notifications are sent to potential couriers via the Courier Mobile App (Push Notification via FCM). * A courier accepts the order via the mobile app. * Backend Service updates the order status in the DB and notifies the merchant (API webhook or Dashboard update).

2. Technology Stack

Based on project requirements and feasibility findings:

  • Backend: Node.js (with Express.js or similar framework)
  • Database: PostgreSQL
  • Caching: Redis
  • Merchant Dashboard / Admin Dashboard: React (using create_react_app template with Tailwind, shadcn/ui)
  • Courier Mobile App: Flutter
  • Cloud Platform: AWS or GCP (leveraging free tiers initially)
  • Mapping Service: OpenStreetMap (initially, potentially Google Maps API later)
  • Notifications: Firebase Cloud Messaging (FCM) for push notifications, Twilio for SMS
  • API Specification: OpenAPI 3.0 (Swagger)
  • Containerization: Docker (for development consistency and deployment)
  • Version Control: Git

This stack balances performance, developer productivity (JavaScript ecosystem for backend/frontend), cross-platform mobile development, cost-effectiveness (open-source DB, mapping, free cloud tiers), and scalability.

3. Database Design (Conceptual)

Database: PostgreSQL

Key Entities (Tables):

  • Users: Stores information about all user types (Merchants, Couriers, Admins). Includes common fields like user_id, email, password_hash, first_name, last_name, phone_number, role (Merchant, Courier, Admin), status (Active, Inactive, Pending), created_at, updated_at.
  • Merchants: Extends Users. Stores merchant-specific information like merchant_id (FK to Users), business_name, business_address, billing_details, api_key, webhook_url.
  • Couriers: Extends Users. Stores courier-specific information like courier_id (FK to Users), vehicle_type, vehicle_registration, license_number, current_location (lat/long, updated periodically), availability_status (Available, Busy, Offline), rating.
  • Orders: Core entity storing delivery order details. Includes order_id, merchant_id (FK to Merchants), pickup_address, delivery_address, recipient_name, recipient_phone, package_description, package_dimensions, package_weight, delivery_instructions, status (Pending, Assigned, PickedUp, InTransit, Delivered, Failed, Cancelled), estimated_delivery_time, actual_delivery_time, pickup_time, delivery_fee, payment_status, created_at, updated_at.
  • OrderAssignments: Links Orders to Couriers. Includes assignment_id, order_id (FK to Orders), courier_id (FK to Couriers), assigned_at, accepted_at, status (Offered, Accepted, Rejected, Completed).
  • OrderTracking: Stores historical location/status updates for an order. Includes tracking_id, order_id (FK to Orders), courier_id (FK to Couriers), location (lat/long), status_update, timestamp.
  • Ratings: Stores ratings given by merchants/customers to couriers (and potentially vice-versa). Includes rating_id, order_id (FK to Orders), rated_by_user_id (FK to Users), rated_user_id (FK to Users), score (1-5), comment, timestamp.
  • Payments: Tracks payments related to deliveries. Includes payment_id, order_id (FK to Orders), amount, payment_method (M-Pesa, Card), transaction_id, status (Pending, Completed, Failed), timestamp.

(Note: This is a conceptual schema. A detailed ERD and SQL schema will be created later. Relationships (one-to-many, many-to-many) need to be defined, and appropriate indexing strategies applied for performance.)*

4. Security Design

Security is paramount, especially handling user data, location information, and payment details.

  • Authentication:
    • Use JSON Web Tokens (JWT) for API authentication (Merchant API, Courier App API).
    • Implement secure password hashing (e.g., bcrypt) for user passwords.
    • Consider multi-factor authentication (MFA) for sensitive operations or admin access.
  • Authorization:
    • Implement Role-Based Access Control (RBAC) to ensure users can only access resources and perform actions appropriate for their role (Merchant, Courier, Admin).
    • Validate permissions at the API endpoint level.
  • Data Encryption:
    • Encrypt sensitive data at rest (e.g., API keys, potentially PII) in the database.
    • Use HTTPS (TLS/SSL) for all communication channels (API, Dashboards, Mobile App) to encrypt data in transit.
  • API Security:
    • Implement rate limiting to prevent abuse.
    • Validate all input data to prevent injection attacks (SQL injection, XSS).
    • Use API keys for merchant API access, ensuring secure generation and storage.
  • Infrastructure Security:
    • Configure firewalls and security groups in the cloud environment to restrict access.
    • Regularly update dependencies and system software to patch vulnerabilities.
  • Compliance: Adhere strictly to the Kenya Data Protection Act (DPA) 2019 regarding data handling, consent, and user rights.

5. Scalability and Caching

  • Scalability:
    • Horizontal Scaling: Design the backend services to be stateless where possible, allowing multiple instances to run behind a load balancer (AWS ELB / GCP Load Balancer).
    • Database Scaling: Start with a single PostgreSQL instance. Plan for read replicas to handle increased read load. Consider sharding later if write volume becomes a bottleneck.
    • Asynchronous Processing: Use message queues (e.g., RabbitMQ, AWS SQS) for non-critical tasks like sending notifications, generating reports, or complex calculations to decouple services and improve responsiveness.
  • Caching:
    • Use Redis for caching frequently accessed, relatively static data (e.g., user session data, configuration settings, potentially results of complex queries).
    • Implement appropriate cache invalidation strategies.

6. Third-Party Integrations

  • Mapping Service:
    • Initial: OpenStreetMap (via libraries like Leaflet for frontend, and routing engines like OSRM/Valhalla potentially self-hosted or via free APIs for backend route optimization).
    • Future: Google Maps Platform (Directions API, Geocoding API, Maps SDK) - Requires API keys and budget management.
  • Notifications:
    • Push Notifications: Firebase Cloud Messaging (FCM) for sending notifications to the Courier Mobile App.
    • SMS Notifications: Twilio API for sending SMS alerts (e.g., delivery status updates to customers/merchants).
  • Payment Gateway:
    • Integration with M-Pesa (via Safaricom Daraja API) is crucial for the Kenyan market.
    • Potentially integrate with other providers like Stripe or local card processors for broader payment options.
  • E-commerce Platforms (Optional/Future):
    • Develop plugins or use existing APIs to integrate directly with platforms like Shopify, WooCommerce to automate order fetching for merchants.