Skip to content

LogistiX UML Diagrams (Draft)

This document contains textual descriptions and potentially PlantUML/Mermaid code for the UML diagrams related to the LogistiX system design.

1. Use Case Diagram

Actors:

  • Merchant (SME): Represents the e-commerce business using LogistiX for deliveries.
  • Courier: Represents the individual performing the deliveries.
  • Admin: Represents the LogistiX operations/support staff.
  • System: Represents the LogistiX platform itself (handling automated processes).
  • External Systems: Represents third-party services like Payment Gateway (M-Pesa), Mapping Service, Notification Service.

Use Cases:

Merchant Use Cases: * Manage Account (Register, Login, Update Profile, Manage API Keys, Manage Billing) * Create Delivery Order (Input details, Get Quote) * Track Order Status * View Order History * Manage Webhooks * Rate Courier * View Reports/Analytics * Contact Support

Courier Use Cases: * Manage Account (Register, Login, Update Profile, Vehicle Details) * Set Availability Status (Available, Busy, Offline) * View Available Orders * Accept/Reject Order * View Assigned Order Details * Navigate Route (via integrated Mapping Service) * Update Order Status (Picked Up, Delivered, Failed Attempt) * Upload Proof of Delivery (e.g., signature, photo) * View Earnings * Contact Support

Admin Use Cases: * Manage Merchant Accounts (Approve, Suspend, View Details) * Manage Courier Accounts (Approve, Suspend, Verify Documents, View Details) * Manage Orders (View All, Monitor Status, Intervene/Reassign) * Manage System Settings (Pricing Rules, Service Areas) * View Platform Analytics/Reports * Handle Disputes/Support Tickets * Manage Notifications

System Use Cases (Automated Processes): * Authenticate User * Authorize Action * Calculate Delivery Quote * Match Order to Courier (Dispatch Algorithm) * Optimize Route (via Mapping Service) * Send Notifications (to Merchant, Courier, Customer via Notification Service) * Process Payment (via Payment Gateway) * Update Order Status Automatically (based on Courier actions/time) * Generate Reports

(Note: This provides a high-level overview. Relationships like <> and <> can be added for more detail. A visual diagram would typically show actors linked to their respective use cases.)*

2. Class Diagram (Conceptual)

This describes the main classes and their relationships.

Classes:

  • User:
    • Attributes: userId, email, passwordHash, firstName, lastName, phoneNumber, role, status, createdAt, updatedAt
    • Methods: register(), login(), updateProfile(), verifyPassword()
  • Merchant (inherits from User):
    • Attributes: businessName, businessAddress, billingDetails, apiKey, webhookUrl
    • Methods: createOrder(), getQuote(), trackOrder(), viewHistory(), manageApiKey(), rateCourier()
  • Courier (inherits from User):
    • Attributes: vehicleType, vehicleRegistration, licenseNumber, currentLocation, availabilityStatus, rating
    • Methods: setAvailability(), acceptOrder(), rejectOrder(), updateOrderStatus(), updateLocation(), viewEarnings()
  • Admin (inherits from User):
    • Attributes: adminLevel
    • Methods: manageMerchant(), manageCourier(), manageOrder(), viewAnalytics(), manageSettings()
  • Order:
    • Attributes: orderId, pickupAddress, deliveryAddress, recipientName, recipientPhone, packageDetails, status, deliveryFee, estimatedDeliveryTime, actualDeliveryTime, createdAt, updatedAt
    • Methods: calculateFee(), assignCourier(), updateStatus(), getTrackingInfo()
  • Address:
    • Attributes: street, city, postalCode, country, latitude, longitude
  • Package:
    • Attributes: description, weight, dimensions
  • OrderAssignment:
    • Attributes: assignmentId, assignedAt, acceptedAt, status
  • TrackingUpdate:
    • Attributes: updateId, location, status, timestamp
  • Rating:
    • Attributes: ratingId, score, comment, timestamp
  • Payment:
    • Attributes: paymentId, amount, method, transactionId, status, timestamp
  • Notification:
    • Attributes: notificationId, type (SMS, Push), recipient, message, status, timestamp

Relationships:

  • Merchant 1 -- * creates Order
  • Courier 1 -- * accepts OrderAssignment
  • Order 1 -- 1 has PickupAddress (Address)
  • Order 1 -- 1 has DeliveryAddress (Address)
  • Order 1 -- 1 contains Package
  • Order 1 -- * has OrderAssignment
  • Order 1 -- * has TrackingUpdate
  • Order 1 -- * has Rating
  • Order 1 -- * has Payment
  • OrderAssignment 1 -- 1 relates Order
  • OrderAssignment 1 -- 1 relates Courier
  • User 1 -- * can be ratedBy Rating
  • User 1 -- * can be ratedUser Rating
  • User 1 -- * receives Notification

(Note: This is conceptual. Attributes like packageDetails might be broken down further. Methods represent key responsibilities.)*

3. Sequence Diagram (Example: Merchant Creates Order via API)

Participants: Merchant System, LogistiX API Gateway, Authentication Service, Order Service, Pricing Service, Database, Notification Service, Dispatch Service

  1. Merchant System -> API Gateway: POST /orders (Request with order details, API Key)
  2. API Gateway -> Authentication Service: validateApiKey(apiKey)
  3. Authentication Service -> API Gateway: apiKeyValid(merchantId)
  4. API Gateway -> Order Service: createOrder(orderDetails, merchantId)
  5. Order Service -> Pricing Service: calculateQuote(pickup, delivery, package)
  6. Pricing Service -> Order Service: quote(deliveryFee)
  7. Order Service -> Database: saveOrder(orderDetails, merchantId, deliveryFee, status='Pending')
  8. Database -> Order Service: orderRecord(orderId)
  9. Order Service -> Dispatch Service: newOrderAvailable(orderId, pickupLocation) (Async via Message Queue)
  10. Order Service -> API Gateway: orderCreatedResponse(orderId, deliveryFee, status='Pending')
  11. API Gateway -> Merchant System: 201 Created (Response with orderId, fee)
  12. Order Service -> Notification Service: sendOrderConfirmation(merchantId, orderId) (Async via Message Queue)

(Note: This shows a simplified happy path. Error handling, detailed validation, and courier assignment sequences would be separate diagrams.)*

4. Activity Diagram (Example: Courier Delivery Process)

  1. Start: Courier logs into Mobile App.
  2. Set Status: Courier sets availability to 'Available'.
  3. Receive Notification: System notifies Courier of a new order offer.
  4. View Offer: Courier views order details (pickup, dropoff, fee).
  5. Decision: Accept Order?
    • [Yes] -> Accept Order: Courier accepts the order via the app.
    • [No] -> Reject Order: Courier rejects the order. -> End
  6. Update Status: System updates order status to 'Assigned', notifies Merchant.
  7. Navigate to Pickup: Courier uses map integration to navigate to the pickup location.
  8. Confirm Pickup: Courier confirms package pickup via the app (scan QR, photo, etc.).
  9. Update Status: System updates order status to 'PickedUp'.
  10. Navigate to Delivery: Courier uses map integration to navigate to the delivery location.
  11. Attempt Delivery: Courier arrives at the delivery location.
  12. Decision: Delivery Successful?
    • [Yes] -> Confirm Delivery: Courier confirms delivery (recipient signature, photo, code).
      • Update Status: System updates order status to 'Delivered', notifies Merchant.
      • Process Payment (if COD): Courier collects payment if applicable.
      • -> End
    • [No] -> Record Failed Attempt: Courier records reason for failure (recipient unavailable, address issue).
      • Update Status: System updates order status to 'FailedAttempt', notifies Merchant.
      • (Optional): Follow re-delivery/return procedures. -> End

5. Component Diagram

Components:

  • Merchant Web App (React): Frontend for merchant dashboard.
  • Courier Mobile App (Flutter): Frontend for couriers.
  • Admin Web App (React): Frontend for admin dashboard.
  • API Gateway: Entry point for all external requests (Merchant API, Mobile App API).
  • Auth Service: Handles user authentication and token generation/validation.
  • Order Service: Core logic for order creation, tracking, status updates.
  • Courier Service: Manages courier profiles, availability, matching.
  • Pricing Service: Calculates delivery fees.
  • Notification Service: Sends SMS and Push notifications.
  • Mapping Service Interface: Adapter for interacting with OpenStreetMap/Google Maps.
  • Payment Service Interface: Adapter for interacting with M-Pesa/Stripe.
  • Database (PostgreSQL): Data persistence.
  • Cache (Redis): Caching layer.
  • Message Queue (RabbitMQ/SQS): For asynchronous tasks.

Relationships (Simplified):

  • Web/Mobile Apps communicate with API Gateway.
  • API Gateway routes requests to relevant backend services (Auth, Order, Courier, Pricing).
  • Backend services interact with Database, Cache, Message Queue.
  • Backend services use interfaces to communicate with external Mapping and Payment services.
  • Notification Service consumes messages from the queue and interacts with FCM/Twilio.

6. Deployment Diagram (Initial AWS/GCP Free Tier Focus)

Nodes:

  • Cloud Region (e.g., AWS eu-west-1 or GCP equivalent):
    • VPC (Virtual Private Cloud): Network isolation.
      • Public Subnet:
        • Load Balancer (ELB/Cloud Load Balancer): Distributes traffic (Free tier might offer limited version or require careful config).
        • NAT Gateway (Optional/Cost): Allows private instances internet access (May not be needed if all services are public initially or use free tier endpoints).
      • Private Subnet(s):
        • Compute Instances (EC2/Compute Engine - Free Tier): Running Docker containers for:
          • API Gateway
          • Auth Service
          • Order Service
          • Courier Service
          • Pricing Service
          • Notification Service
        • Database Service (RDS/Cloud SQL - Free Tier PostgreSQL): Managed database instance.
        • Caching Service (ElastiCache/Memorystore - Free Tier Redis): Managed cache instance.
        • (Optional) Message Queue Service (SQS/Pub/Sub - Free Tier): Managed queue.
    • Static Asset Hosting (S3/Cloud Storage - Free Tier): Hosting React build files for Merchant/Admin dashboards.
    • CDN (CloudFront/Cloud CDN - Free Tier): Serving static assets and potentially caching API responses.
  • External Services:
    • Firebase Cloud Messaging (FCM): Google infrastructure.
    • Twilio API: Twilio infrastructure.
    • OpenStreetMap Servers: OSM infrastructure.
    • M-Pesa API (Daraja): Safaricom infrastructure.
  • User Devices:
    • Merchant Browser (accessing Dashboards via CDN/S3).
    • Courier Mobile Device (accessing API via Load Balancer).
    • Merchant System (accessing API via Load Balancer).

(Note: This is a simplified view focusing on free/low-cost tiers. Production deployment would involve auto-scaling groups, more robust networking, monitoring, logging, and potentially container orchestration like ECS/EKS/GKE.)*