Skip to content

LogistiX - Software Requirements Specification (SRS) - Draft

Version: 0.1 Date: April 30, 2025

Table of Contents

  1. Introduction 1.1 Purpose 1.2 Document Conventions 1.3 Intended Audience and Reading Suggestions 1.4 Project Scope 1.5 References
  2. Overall Description 2.1 Product Perspective 2.2 Product Features 2.3 User Classes and Characteristics 2.4 Operating Environment 2.5 Design and Implementation Constraints 2.6 User Documentation 2.7 Assumptions and Dependencies
  3. System Features (Functional Requirements) 3.1 Merchant Management 3.2 Courier Management 3.3 Order Management 3.4 Pricing and Quoting 3.5 Dispatching and Routing 3.6 Tracking and Notifications 3.7 Rating and Feedback 3.8 Payment Processing 3.9 Reporting and Analytics 3.10 Administration
  4. External Interface Requirements 4.1 User Interfaces (Merchant Dashboard, Courier App, Admin Dashboard) 4.2 Hardware Interfaces 4.3 Software Interfaces (Merchant API, Mapping API, Notification API, Payment API) 4.4 Communications Interfaces
  5. Non-Functional Requirements 5.1 Performance Requirements 5.2 Safety Requirements 5.3 Security Requirements 5.4 Software Quality Attributes (Reliability, Availability, Maintainability, Usability) 5.5 Business Rules
  6. Other Requirements

1. Introduction

1.1 Purpose

This Software Requirements Specification (SRS) document defines the functional and non-functional requirements for the LogistiX platform. LogistiX aims to provide an affordable, reliable, and efficient last-mile delivery aggregation service primarily targeting Small and Medium Enterprises (SMEs) involved in e-commerce within Kenya, with potential future expansion. This document serves as the primary reference for design, development, and testing activities.

1.2 Document Conventions

  • Requirements are identified using a hierarchical numbering scheme (e.g., 3.1.1).
  • The terms "shall" and "must" indicate mandatory requirements.
  • The terms "should" indicate desirable requirements.
  • The terms "may" indicate optional requirements.

1.3 Intended Audience and Reading Suggestions

This document is intended for: * Project Managers: For project planning and tracking. * Developers: To understand the features and constraints for implementation. * Testers: To create test cases and verify functionality. * Designers: To guide UI/UX design. * Stakeholders: To understand the scope and capabilities of the system.

It is recommended to read Section 1 and 2 for an overview, then focus on Sections 3, 4, and 5 for detailed requirements relevant to specific roles.

1.4 Project Scope

The LogistiX platform will provide: * An API for merchants (SMEs) to integrate their e-commerce systems for creating and managing delivery orders. * A web-based dashboard for merchants to manage orders and accounts visually. * A mobile application for couriers to accept jobs, manage deliveries, and track earnings. * An administrative dashboard for LogistiX staff to manage users, orders, and system settings. * Core backend services for order processing, courier matching, route optimization (basic), pricing, notifications, and tracking. * Integration with third-party services for mapping (OpenStreetMap initially), SMS/Push notifications (Twilio/FCM), and payments (M-Pesa).

The initial focus market is Nairobi, Kenya.

Out of Scope (Initial MVP): * Advanced route optimization considering real-time traffic (beyond basic distance/time). * Warehousing or fulfillment services. * International shipping. * Direct customer-facing ordering interface (focus is B2B - Merchant to Customer). * Complex multi-parcel consolidation logic. * Self-hosted mapping/routing engines (will rely on external APIs).

1.5 References

  • LogistiX Project Requirements (pasted_content.txt)
  • LogistiX Market Research and Feasibility Study (/home/ubuntu/logistix_project/docs/market_research_draft.md)
  • LogistiX System Design and Architecture (/home/ubuntu/logistix_project/docs/system_architecture_draft.md)
  • LogistiX UML Diagrams (/home/ubuntu/logistix_project/docs/uml_diagrams_draft.md)
  • LogistiX API Specification (/home/ubuntu/logistix_project/docs/api_spec_draft.yaml)
  • LogistiX Database Schema (/home/ubuntu/logistix_project/docs/database_schema.sql)
  • Kenya Data Protection Act, 2019

2. Overall Description

2.1 Product Perspective

LogistiX is a new, independent platform designed to aggregate last-mile delivery services for e-commerce SMEs. It connects merchants needing deliveries with independent couriers via a technology platform that includes APIs, dashboards, and mobile applications. It aims to differentiate itself through affordability, reliability, and ease of integration, specifically addressing the pain points identified for Kenyan SMEs.

2.2 Product Features

  • Merchant Order Creation (API & Dashboard)
  • Delivery Quoting
  • Automated Courier Dispatching
  • Real-time Order Tracking
  • Courier Mobile App for Job Management & Navigation
  • Status Updates & Notifications (SMS/Push)
  • Proof of Delivery (Signature/Photo)
  • Merchant & Admin Dashboards
  • User Management (Merchant, Courier, Admin)
  • Rating & Feedback System
  • Basic Reporting
  • Payment Integration (M-Pesa)

2.3 User Classes and Characteristics

  • Merchants (SMEs): E-commerce businesses, often small, operating via websites or social media. Need affordable, reliable delivery. May have varying technical expertise (some prefer API, others dashboard). Primarily based in Kenya.
  • Couriers: Independent individuals (or small companies) with vehicles (motorbikes, potentially small vans). Need a consistent source of delivery jobs, clear instructions, easy navigation, and timely payments. Must have smartphones (iOS/Android) and meet basic vetting requirements (license, insurance).
  • End Customers (Recipients): Individuals receiving packages ordered from merchants. Expect timely delivery, status updates, and professional courier interaction. (Indirect users of the system via notifications and interaction with couriers).
  • Administrators: LogistiX internal staff responsible for platform operation, user support, monitoring, and management.

2.4 Operating Environment

  • The system shall operate on a cloud platform (AWS or GCP).
  • Backend services shall run in Docker containers.
  • Merchant Dashboard and Admin Dashboard shall be web-based, accessible via modern browsers (Chrome, Firefox, Safari, Edge).
  • Courier Mobile App shall run on iOS and Android devices with internet connectivity and GPS capabilities.
  • The system depends on reliable internet connectivity for all users and integrations.

2.5 Design and Implementation Constraints

  • Technology Stack: Must adhere to the defined stack (Node.js, PostgreSQL, Redis, React, Flutter, etc.) as specified in the System Architecture document.
  • API First: The Merchant API is a primary interface and must be well-documented (OpenAPI) and stable.
  • Cost Optimization: Leverage cloud free tiers and open-source technologies where feasible for the initial MVP.
  • Mapping: Use OpenStreetMap for initial mapping and basic routing to minimize costs.
  • Data Privacy: Must comply with the Kenya Data Protection Act, 2019.
  • Scalability: Architecture should allow for future horizontal scaling.
  • MVP Focus: Initial development must focus on core features required for market entry.

2.6 User Documentation

  • API Documentation (Generated from OpenAPI spec, with guides/examples).
  • Merchant Dashboard User Guide.
  • Courier Mobile App User Guide.
  • Admin Dashboard User Guide.

2.7 Assumptions and Dependencies

  • Courier Availability: Assumes a sufficient pool of independent couriers can be recruited and retained in target operating areas (Nairobi initially).
  • Merchant Adoption: Assumes SMEs will find the platform valuable and integrate/use it.
  • Third-Party Services: Depends on the availability and reliability of external services (Cloud provider, Mapping APIs, Notification APIs, Payment Gateway APIs).
  • Regulatory Compliance: Assumes LogistiX and its users can meet all relevant Kenyan regulations for logistics and data handling.
  • Internet & GPS: Assumes reliable internet connectivity and GPS signal for couriers and users.

(Sections 3-6 will be populated with detailed requirements based on previous documents)

3. System Features (Functional Requirements)

This section details the functional requirements, describing what the system shall do.

3.1 Merchant Management

  • 3.1.1 Merchant Registration:
    • 3.1.1.1 The system shall allow potential merchants to register for an account via the Merchant Dashboard.
    • 3.1.1.2 Registration shall require business name, contact person name, email, phone number, and password creation.
    • 3.1.1.3 The system shall verify the uniqueness of the email address and phone number upon registration.
    • 3.1.1.4 The system should send a verification email or SMS to confirm the merchant's contact information.
    • 3.1.1.5 Merchant accounts shall initially be in a 'PendingVerification' or 'PendingApproval' status.
  • 3.1.2 Merchant Login:
    • 3.1.2.1 The system shall allow registered merchants to log in using their email and password via the Merchant Dashboard and API (using API Key).
    • 3.1.2.2 The system shall implement measures against brute-force login attempts.
    • 3.1.2.3 The system should provide a password reset mechanism.
  • 3.1.3 Merchant Profile Management:
    • 3.1.3.1 Merchants shall be able to view and update their profile information (contact details, business address) via the Merchant Dashboard.
    • 3.1.3.2 Merchants shall be able to manage billing details (if applicable) via the Merchant Dashboard.
  • 3.1.4 API Key Management:
    • 3.1.4.1 Merchants shall be able to generate and revoke API keys via the Merchant Dashboard.
    • 3.1.4.2 The system shall ensure API keys are securely stored and only displayed once upon generation.
  • 3.1.5 Webhook Management:
    • 3.1.5.1 Merchants should be able to configure webhook URLs via the Merchant Dashboard to receive real-time updates (e.g., order status changes).

3.2 Courier Management

  • 3.2.1 Courier Registration:
    • 3.2.1.1 The system shall allow potential couriers to register via the Courier Mobile App.
    • 3.2.1.2 Registration shall require name, email, phone number, password, vehicle type, vehicle registration, and license number.
    • 3.2.1.3 The system should allow couriers to upload necessary documents (e.g., driver's license, vehicle insurance) during or after registration.
    • 3.2.1.4 Courier accounts shall initially be in a 'PendingVerification' status until approved by an Admin.
  • 3.2.2 Courier Login:
    • 3.2.2.1 The system shall allow registered and approved couriers to log in via the Courier Mobile App using their phone number/email and password.
  • 3.2.3 Courier Profile Management:
    • 3.2.3.1 Couriers shall be able to view and update their profile information (contact details, vehicle details) via the Mobile App.
  • 3.2.4 Availability Status:
    • 3.2.4.1 Couriers shall be able to set their availability status (Available, Busy, Offline) via the Mobile App.
    • 3.2.4.2 The system shall only assign new orders to couriers with 'Available' status.
  • 3.2.5 Earnings Tracking:
    • 3.2.5.1 Couriers shall be able to view their completed deliveries and estimated earnings via the Mobile App.

3.3 Order Management

  • 3.3.1 Order Creation (Merchant):
    • 3.3.1.1 Merchants shall be able to create new delivery orders via the Merchant API.
    • 3.3.1.2 Merchants shall be able to create new delivery orders via the Merchant Dashboard.
    • 3.3.1.3 Order creation shall require pickup address, delivery address, recipient details (name, phone), and package details (description, weight, dimensions).
    • 3.3.1.4 The system shall validate address information (basic format check, potentially geocoding via Mapping Service).
    • 3.3.1.5 The system shall provide a delivery quote before the merchant confirms the order.
    • 3.3.1.6 Upon confirmation, the system shall assign a unique Order ID and set the initial status to 'Pending'.
  • 3.3.2 Order Viewing (Merchant):
    • 3.3.2.1 Merchants shall be able to view a list of their past and current orders via the API and Dashboard.
    • 3.3.2.2 Merchants shall be able to filter and search their orders (e.g., by status, date, Order ID).
    • 3.3.2.3 Merchants shall be able to view the detailed status and tracking history for a specific order.
  • 3.3.3 Order Viewing (Courier):
    • 3.3.3.1 Available couriers shall be able to view details of offered orders (pickup/delivery locations, fee) via the Mobile App before accepting.
    • 3.3.3.2 Assigned couriers shall be able to view full details of their accepted orders via the Mobile App.
  • 3.3.4 Order Acceptance/Rejection (Courier):
    • 3.3.4.1 Couriers shall be able to accept or reject offered orders via the Mobile App within a defined timeframe.
    • 3.3.4.2 If an order is rejected or not accepted within the timeframe, the system shall attempt to assign it to another courier.
  • 3.3.5 Order Status Updates (Courier):
    • 3.3.5.1 Couriers shall update the order status via the Mobile App upon:
      • Confirming pickup ('PickedUp')
      • Confirming successful delivery ('Delivered')
      • Recording a failed delivery attempt ('FailedAttempt')
    • 3.3.5.2 The system may require proof for status updates (e.g., photo/signature for 'Delivered', reason for 'FailedAttempt').
  • 3.3.6 Order Cancellation:
    • 3.3.6.1 Merchants should be able to request cancellation of an order via API or Dashboard before it is picked up (subject to rules/fees).
    • 3.3.6.2 Admins shall be able to cancel orders.

(Continue with sections 3.4 to 3.10, 4, 5, 6)

3.4 Pricing and Quoting

  • 3.4.1 Quote Calculation:
    • 3.4.1.1 The system shall calculate a delivery quote based on factors including pickup location, delivery location, package weight/dimensions, and potentially service level (e.g., standard, express - if implemented).
    • 3.4.1.2 The system shall provide the calculated quote to the merchant via API or Dashboard before order confirmation.
    • 3.4.1.3 Pricing rules shall be configurable by Admins.
  • 3.4.2 Quote Request (API):
    • 3.4.2.1 The system shall provide an API endpoint for merchants to request a delivery quote without creating an order.

3.5 Dispatching and Routing

  • 3.5.1 Courier Matching:
    • 3.5.1.1 Upon order creation (status 'Pending'), the system shall identify suitable, available couriers based on proximity to the pickup location, vehicle type (if relevant), and potentially courier rating.
    • 3.5.1.2 The system shall offer the order to one or more matched couriers via the Courier Mobile App.
    • 3.5.1.3 The system shall handle scenarios where no couriers are available or accept the offer (e.g., retry, notify admin/merchant).
  • 3.5.2 Order Assignment:
    • 3.5.2.1 When a courier accepts an order, the system shall update the order status to 'Assigned' (or 'Accepted') and assign the courier to the order.
    • 3.5.2.2 The system shall prevent the order from being offered to other couriers once accepted.
  • 3.5.3 Route Guidance (Courier App):
    • 3.5.3.1 The Courier Mobile App shall integrate with a mapping service (OpenStreetMap initially) to display the pickup and delivery locations.
    • 3.5.3.2 The Courier Mobile App should provide turn-by-turn navigation guidance to the courier.
  • 3.5.4 Basic Route Optimization (Future):
    • 3.5.4.1 The system may provide optimized routing for couriers handling multiple concurrent deliveries (out of scope for initial MVP).

3.6 Tracking and Notifications

  • 3.6.1 Real-time Location Tracking (Courier):
    • 3.6.1.1 The Courier Mobile App shall periodically transmit the courier's current GPS location to the backend while they are online and/or handling an active delivery.
    • 3.6.1.2 Location data transmission frequency shall be configurable and optimized for battery life.
  • 3.6.2 Order Tracking (Merchant):
    • 3.6.2.1 Merchants shall be able to view the current status and location (if available) of their active orders via the API and Dashboard.
    • 3.6.2.2 The system shall provide a history of status updates and location points for each order.
  • 3.6.3 Notifications:
    • 3.6.3.1 The system shall send notifications (Push/SMS) to relevant parties upon key order events:
      • Courier: New order offer, order assignment confirmation, order cancellation.
      • Merchant: Order confirmation, courier assigned, pickup confirmation, delivery confirmation, failed attempt, order cancellation, webhook events.
      • End Customer (Optional/Configurable): Courier assigned (with ETA), delivery imminent, delivery confirmation/failure.
    • 3.6.3.2 Notification content and triggers shall be configurable by Admins.
    • 3.6.3.3 The system shall use FCM for push notifications to the Courier App and Twilio (or similar) for SMS.

3.7 Rating and Feedback

  • 3.7.1 Courier Rating (by Merchant):
    • 3.7.1.1 Merchants shall be able to rate a courier (e.g., 1-5 stars) and provide optional feedback after a delivery is completed via the API or Dashboard.
  • 3.7.2 Feedback Viewing (Admin):
    • 3.7.2.1 Admins shall be able to view ratings and feedback submitted for couriers.
  • 3.7.3 Courier Average Rating:
    • 3.7.3.1 The system shall calculate and display an average rating for each courier, potentially visible to Admins and used in matching algorithms.

3.8 Payment Processing

  • 3.8.1 Merchant Billing:
    • 3.8.1.1 The system shall track delivery fees incurred by merchants.
    • 3.8.1.2 The system shall support a billing mechanism for merchants (e.g., pre-paid wallet, post-paid invoicing - specific model TBD based on Revenue Model).
  • 3.8.2 Courier Payouts:
    • 3.8.2.1 The system shall track earnings for couriers based on completed deliveries.
    • 3.8.2.2 The system shall facilitate regular payouts to couriers (e.g., via M-Pesa integration).
  • 3.8.3 Payment Gateway Integration:
    • 3.8.3.1 The system shall integrate with M-Pesa (Daraja API) for processing merchant payments and courier payouts.
    • 3.8.3.2 The system may integrate with other payment gateways (e.g., card payments) in the future.
  • 3.8.4 Cash on Delivery (COD) Handling (If Supported):
    • 3.8.4.1 If COD is supported, the system must track COD amounts collected by couriers and manage reconciliation.

3.9 Reporting and Analytics

  • 3.9.1 Merchant Reports:
    • 3.9.1.1 Merchants should be able to view basic reports on their delivery volume, costs, and delivery performance (e.g., success rate, average delivery time) via the Dashboard.
  • 3.9.2 Courier Reports:
    • 3.9.2.1 Couriers should be able to view reports on their earnings, number of deliveries, and rating history via the Mobile App.
  • 3.9.3 Admin Reports:
    • 3.9.3.1 Admins shall have access to comprehensive operational reports, including platform-wide delivery volume, revenue, courier performance, merchant activity, system health, etc.

3.10 Administration

  • 3.10.1 Admin User Management:
    • 3.10.1.1 Super Admins shall be able to create and manage other Admin accounts and roles/permissions.
  • 3.10.2 Merchant Account Management (Admin):
    • 3.10.2.1 Admins shall be able to view, approve, suspend, and manage merchant accounts.
  • 3.10.3 Courier Account Management (Admin):
    • 3.10.3.1 Admins shall be able to view courier applications, verify documents, approve, suspend, and manage courier accounts.
  • 3.10.4 Order Monitoring and Intervention (Admin):
    • 3.10.4.1 Admins shall be able to monitor the status of all orders in the system.
    • 3.10.4.2 Admins shall be able to manually intervene in order issues (e.g., reassign an order if a courier becomes unavailable).
  • 3.10.5 System Configuration (Admin):
    • 3.10.5.1 Admins shall be able to configure system settings, such as pricing rules, service areas, notification templates, and dispatch parameters.
  • 3.10.6 Dispute Resolution (Admin):
    • 3.10.6.1 Admins shall have tools to investigate and resolve disputes reported by merchants or couriers.

4. External Interface Requirements

4.1 User Interfaces

  • 4.1.1 Merchant Dashboard (Web):
    • Shall provide a clean, intuitive, and responsive web interface for merchants.
    • Shall be compatible with modern web browsers (Chrome, Firefox, Safari, Edge).
    • Shall allow merchants to perform all relevant functions (Order creation/viewing, tracking, account management, etc.).
  • 4.1.2 Courier Mobile Application (iOS/Android):
    • Shall provide a native or cross-platform (Flutter) mobile application for couriers.
    • Shall have a simple, task-oriented interface optimized for use on the go.
    • Shall integrate with device features like GPS and camera.
  • 4.1.3 Admin Dashboard (Web):
    • Shall provide a comprehensive web interface for administrators.
    • Shall prioritize functionality and data visibility for operational management.

4.2 Hardware Interfaces

  • No direct hardware interfaces are specified beyond standard user devices (computers, smartphones) and cloud infrastructure.

4.3 Software Interfaces

  • 4.3.1 Merchant API:
    • Shall be a RESTful API adhering to the OpenAPI 3.0 specification (api_spec_draft.yaml).
    • Shall use JSON for data exchange.
    • Shall use API Keys for authentication.
    • Shall provide endpoints for order creation, quoting, status retrieval, etc.
  • 4.3.2 Mapping Service API:
    • Shall interface with OpenStreetMap (e.g., Nominatim for geocoding, OSRM/Valhalla or equivalent for routing/ETA) or Google Maps Platform APIs.
    • Shall handle requests for geocoding addresses, calculating route distances/times, and potentially fetching map tiles.
  • 4.3.3 Notification Service API:
    • Shall interface with Firebase Cloud Messaging (FCM) API for sending push notifications.
    • Shall interface with Twilio API (or similar) for sending SMS messages.
  • 4.3.4 Payment Gateway API:
    • Shall interface with Safaricom Daraja API for M-Pesa transactions.
    • May interface with other payment APIs (e.g., Stripe) in the future.

4.4 Communications Interfaces

  • All external communications (API calls, web traffic) shall use HTTPS for encryption.
  • The system will rely on standard internet protocols (TCP/IP, HTTP/S).

5. Non-Functional Requirements

5.1 Performance Requirements

  • 5.1.1 API Response Time: Core API endpoints (e.g., create order, get status) should respond within 1 second under average load.
  • 5.1.2 Quote Response Time: Quote requests should be processed and returned within 3 seconds.
  • 5.1.3 Dashboard Load Time: Merchant and Admin dashboards should load initial views within 3 seconds.
  • 5.1.4 Courier Location Update: Location updates from the courier app should be processed by the backend within 5 seconds.
  • 5.1.5 Scalability: The system should be designed to handle an initial load of 1,000 concurrent users (merchants, couriers) and 10,000 orders per day, with the ability to scale horizontally to handle 10x this load in the future.

5.2 Safety Requirements

  • No specific safety-critical requirements identified, beyond ensuring data integrity and preventing unauthorized actions.

5.3 Security Requirements

  • 5.3.1 Authentication: All access to non-public functions shall require authentication (as detailed in System Architecture).
  • 5.3.2 Authorization: Role-Based Access Control (RBAC) shall be strictly enforced.
  • 5.3.3 Data Encryption: Sensitive data (passwords, API keys) shall be encrypted at rest. All external communication shall use HTTPS.
  • 5.3.4 Input Validation: All inputs from users and external systems shall be validated to prevent injection attacks (SQLi, XSS) and other vulnerabilities.
  • 5.3.5 Data Privacy Compliance: The system shall comply with the Kenya Data Protection Act (DPA) 2019, including obtaining consent, protecting PII, and facilitating data subject rights.
  • 5.3.6 API Security: Merchant API shall be protected by API keys and rate limiting.

5.4 Software Quality Attributes

  • 5.4.1 Reliability: The core system (order processing, tracking) shall have an uptime of 99.5% or higher.
  • 5.4.2 Availability: The Merchant API and dashboards should be available 99.5% of the time.
  • 5.4.3 Maintainability: Code shall be well-structured, commented, and follow consistent coding standards. The architecture should support modularity.
  • 5.4.4 Usability: User interfaces (Dashboards, Mobile App) shall be intuitive and easy to use for their respective target users.
  • 5.4.5 Testability: The system shall be designed to facilitate unit, integration, and end-to-end testing.

5.5 Business Rules

  • Pricing rules are configurable by Admins.
  • Service areas (initially Nairobi) are configurable by Admins.
  • Courier acceptance time limits are configurable.
  • Specific rules around order cancellation fees/windows need to be defined.
  • Courier vetting and approval processes need to be defined.

6. Other Requirements

  • 6.1 Legal and Regulatory Compliance: Besides DPA, the system and its operation must comply with all relevant Kenyan laws regarding e-commerce, transportation, courier services, and business operations.
  • 6.2 Internationalization (Future): While initially focused on Kenya (English, KES), the design should consider future support for other languages, currencies, and regions.
  • 6.3 Logging and Monitoring: Comprehensive logging and monitoring shall be implemented across all system components to facilitate debugging, performance analysis, and security auditing.