💧 Borehole Water Management
and Billing System

1. Introduction

This Software Requirements Specification (SRS) document provides a comprehensive description of the Borehole Water Management and Billing System, a purpose-built solution intended for deployment in Moyale. The system is designed to automate and streamline the critical operational workflows associated with borehole water sales, including billing, payment processing, financial reconciliation, expense management, and comprehensive reporting. The primary objective of this engagement is to replace manual or fragmented processes with a unified, transparent, and accountable digital platform that enhances operational efficiency and ensures rigorous financial oversight.

↑ Back to top

2. System Overview

The Borehole Water Management and Billing System is architected as a capacity-based billing platform. In this model, customer invoices are generated based on the registered capacity of the water truck utilized for each transaction. Meter readings captured at the borehole source serve a dual purpose: they function as a primary consumption record for operational verification and provide a critical mechanism for identifying and resolving load discrepancies between the invoiced capacity and the actual volume of water dispensed. This architecture ensures financial accuracy, deters revenue leakage, and provides a robust framework for managing the unique operational dynamics of water distribution in the Moyale region.

↑ Back to top

3. User Roles & Permissions

The system implements a role-based access control (RBAC) model to ensure that users are granted only the permissions necessary to perform their designated functions. The defined roles are as follows:

• Administrator (Admin): This role holds the highest level of system privilege. Responsibilities encompass full configuration control, user account management and role assignment, approval authority for high-impact adjustments, validation of inter-account fund transfers, and final authorization for the remittance of collected revenue.
• Manager: This role is responsible for day-to-day operational execution. Permissions include recording and managing water sales transactions, processing customer payments, registering and categorizing operational expenses, and initiating cash remittance workflows between the operational site and the central administration.
• Operator: This role is designated for frontline personnel responsible for capturing operational data. Permissions are limited to recording meter readings associated with water dispensing events. The Administrator possesses the capability to temporarily elevate an Operator's permissions, enabling them to perform Manager-level functions in exceptional circumstances, with such elevations being meticulously tracked in the audit log.

↑ Back to top

4. Functional Requirements

The system shall deliver the following functional capabilities to support the complete operational lifecycle:

• Meter Tracking: The system shall enable the recording of meter readings at the point of water dispensing. Consumption shall be automatically calculated based on the differential between consecutive meter readings.
• Billing Logic: The system shall generate invoices based on a dual-unit model, calculating charges according to the registered truck capacity and supporting billing for individual jerrican sales where applicable.
• Payment Processing: The system shall support the recording of payments via two primary methods: cash and M-Pesa mobile money. All payments shall be reconciled against outstanding invoices.
• Vehicle & Capacity Tracking: The system shall maintain a master register of vehicles, including their registered water capacity, and shall log all trips to facilitate capacity-based billing and utilization analysis.
• Discounts & Incentives: The system shall provide a configurable mechanism to apply discounts or promotional incentives based on predefined criteria, such as customer payment history or purchase volume.
• Deviation Handling: The system shall incorporate a formal workflow for managing operational deviations, requiring managerial or administrative approval for any adjustments outside standard operating parameters.
• Load Discrepancy Management: In instances where the actual water dispensed (based on meter readings) deviates from the invoiced truck capacity, the system shall enforce the following rules:
  • Over-delivery (Actual > Capacity): A discount or adjustment shall be automatically calculated and applied to the transaction.
  • Under-delivery (Actual < Capacity): The system shall charge the customer for the full registered capacity of the truck, with the discrepancy flagged for managerial review to identify potential operational issues.
• Expense Tracking: The system shall allow Managers to record and categorize all operational expenses, including fuel, maintenance, and labor, providing a complete picture of site-level costs.
• Revenue Monitoring: The system shall provide real-time visibility into total revenue collected, outstanding accounts receivable, and reconciliation status.
• Customer Statements: The system shall generate detailed statements of account for individual customers, displaying all transactions, payments, and current outstanding balance.
• Cash Remittance Tracking: The system shall provide a dedicated module to track the flow of cash remittances from the Manager at the operational site to the central Administration, including initiation, confirmation, and reconciliation of transferred funds.

↑ Back to top

5. Dashboard

Upon authentication, users shall be presented with a role-specific dashboard that consolidates key performance indicators and operational metrics into a single, at-a-glance interface. The dashboard shall display, at a minimum:

• Total volume of water sold (in liters or cubic meters) over a selected period.
• A comparison of expected revenue (based on capacity-billed) versus actual revenue collected.
• Total operational expenses incurred.
• Current cash and M-Pesa balances held at the site level.
• A summary of outstanding customer balances.
• A visual or text-based alert feed highlighting critical issues requiring immediate attention.

↑ Back to top

6. Audit Log

The system shall maintain an immutable and time-stamped audit log of all user activities. This log is a foundational element for accountability and forensic analysis. For every significant action, the audit log shall record:

• The user who performed the action.
• The timestamp of the action.
• The nature of the action (e.g., create, update, delete, approve).
• The specific data record affected (e.g., transaction ID, customer ID).
• The previous and new values of any modified fields.
• Any instance of user role elevation, including the authorizing administrator and the duration of the elevation.

↑ Back to top

7. Alerts & Notifications

The system shall incorporate a proactive alerting mechanism to notify designated users of predefined events that require attention. These alerts shall be surfaced on the dashboard and may be configured for delivery via SMS in low-connectivity scenarios. Alert triggers shall include:

• A customer account exceeding a defined credit limit or with invoices overdue beyond a specified grace period.
• Detection of a load discrepancy during transaction processing.
• Unpaid invoices exceeding a configurable aging threshold.
• A delay in the scheduled remittance of funds from the Manager to the Admin.

↑ Back to top

8. Reporting

The system shall feature a robust reporting engine that enables users to generate, export, and print structured reports for operational and financial analysis. Required report types include:

• Transaction Report: A detailed, filterable list of all water sales transactions within a specified date range, including customer, vehicle, capacity, amount, payment method, and status.
• Expense Report: A categorized summary of all operational expenses, allowing for analysis of cost drivers over time.
• Financial Summary: A comprehensive report detailing total revenue, total expenses, net income, and reconciliation status for a selected period.
• Vehicle Report: An analysis of vehicle activity, including total trips, total water delivered, and average load per vehicle.
• Audit Log Report: A filterable export of the audit trail for security and compliance reviews.

↑ Back to top

9. Non-Functional Requirements

The system's operational effectiveness is governed by the following non-functional requirements:

• Usability: The user interface shall be intuitive and require minimal training for personnel with varying levels of technical proficiency. Workflows shall be streamlined to minimize data entry time.
• Reliability: The system shall be designed for high availability, with robust error handling and data integrity safeguards to prevent transaction loss or corruption.
• Security: All sensitive data shall be encrypted at rest and in transit. Authentication shall be secure, and the role-based access control model shall be strictly enforced.
• Offline Capability: Recognizing the potential for unreliable network connectivity in Moyale, the system shall be architected to function in a low-connectivity or offline-first mode. Core operational functions, such as recording meter readings and transactions, must remain available without an active internet connection, synchronizing data with the central server once connectivity is restored.

↑ Back to top

10. System Flow

The operational logic of the system follows the defined sequence below, ensuring a consistent and auditable process from water dispensing to financial reporting:

1. Meter Reading: Operator records the starting and ending meter readings for a water dispensing event.
2. Transaction Calculation: System calculates the actual volume dispensed and applies billing logic based on registered truck capacity.
3. Transaction Recording: System creates the transaction record, including any applied discounts or discrepancy flags.
4. Payment Recording: Manager records the customer's payment (cash or M-Pesa) and reconciles it against the open transaction.
5. Expense Recording: Manager records any associated operational expenses incurred.
6. Remittance: Manager initiates a cash remittance transfer to Admin, which is tracked and confirmed within the system.
7. Reporting: Data from all preceding steps is aggregated to populate dashboards and generate analytical reports.

↑ Back to top

11. Constraints

The development and operation of the system are subject to the following constraints:

• Manual M-Pesa Integration: Due to external system limitations, M-Pesa transactions must be manually entered into the system. No direct API integration for payment processing is within the scope of this initial release.
• Cash Reconciliation: The system will facilitate but not automate the physical reconciliation of cash on hand. Processes for verifying cash balances against system records must be defined and enforced operationally.
• Low-Connectivity Environment: The system architecture must account for limited and intermittent internet connectivity at the deployment site. Critical functionalities must be accessible offline.

↑ Back to top

12. Sample Data Fields

The following table provides illustrative examples of key data fields that will be captured within the system's primary entities. This list is not exhaustive but serves to clarify the required data model.

Entity	Field Examples
Transaction	Transaction ID, Date/Time, Customer Name, Truck Registration, Registered Capacity (m³), Units (Jerricans), Start Meter Reading, End Meter Reading, Actual Volume Dispensed, Invoice Amount, Discount Applied, Net Amount, Payment Status, Payment Method, Operator Name, Remarks
Payment	Payment ID, Transaction ID, Date, Amount Paid, Payment Method (Cash/M-Pesa), M-Pesa Confirmation Code (if applicable), Received By
Expense	Expense ID, Date, Category (e.g., Fuel, Maintenance), Amount, Description, Recorded By
Customer	Customer ID, Name, Contact Information, Account Balance, Credit Limit, Default Status
Vehicle	Vehicle ID, Registration Number, Registered Capacity (m³), Type
Remittance	Remittance ID, Initiation Date, Amount, Manager Initiator, Admin Confirmation Status, Confirmation Date

↑ Back to top

13. Pricing Structure

The following pricing structure outlines the total investment required for the development and deployment of the Borehole Water Management and Billing System. Two delivery options are available to accommodate varying operational urgency and budget considerations.

Delivery Option	Duration	Total Price (KES)	Description
Option A: Tight Delivery	1 Month	39,000 KES	An accelerated development schedule suitable for scenarios requiring rapid deployment. This option prioritizes core feature delivery with compressed testing cycles. Recommended for immediate operational needs where time-to-value is the primary driver.
Option B: Eased Delivery	2 Months	33,000 KES	A standard development schedule incorporating comprehensive testing, iterative feedback cycles, thorough documentation, and dedicated buffer periods for quality assurance. Recommended for production-ready deployments where reliability and long-term maintainability are prioritized.

Payment Terms (60% Deposit)

Milestone	Percentage	Amount (KES)	Trigger
Deposit / Project Initiation	60%	19,800 - 23,400*	Upon signing of the agreement and project kickoff
Milestone 1: Core Development Completion	20%	6,600 - 7,800*	Upon completion of Phase 2 (Backend Development) and successful demonstration
Final Payment / Deployment	20%	6,600 - 7,800*	Upon successful User Acceptance Testing (UAT) and production deployment

↑ Back to top

14. Conclusion

This Software Requirements Specification outlines a comprehensive solution for the Borehole Water Management and Billing System. By automating key operational and financial workflows, implementing rigorous accountability through audit logging, and providing real-time visibility into performance metrics, the proposed system directly addresses the need for improved transparency, operational efficiency, and financial control in borehole water management. This document serves as the definitive agreement on the system's requirements and provides the foundation for the subsequent design, development, and implementation phases.

Upon your selection of the preferred delivery timeline and approval of this specification, development will commence in accordance with the agreed schedule.

↑ Back to top

📊 Project Timeline A: Tight Duration (1 Month) – 39,000 KES

The following Gantt chart outlines an aggressive four-week delivery schedule. This timeline requires focused daily execution, parallelized work streams, and minimal revision cycles.

Task ID	Task Name	Week 1	Week 2	Week 3	Week 4
Phase 1: Planning & Setup
1.1	Requirements Finalization	█
1.2	Database Schema Design	██
1.3	Environment & Repo Setup	█
Phase 2: Backend Development
2.1	Authentication & RBAC	██
2.2	Meter & Transaction Engine		███
2.3	Billing & Discrepancy Logic		██
2.4	Payment & Expense Modules			██
2.5	Remittance Tracking			█
Phase 3: Frontend Development
3.1	Dashboard UI		██
3.2	Transaction & Payment Interfaces			███
3.3	Reporting Module			██
3.4	Audit Log & Alerts UI				█
Phase 4: Integration & QA
4.1	Offline-Capability Implementation				██
4.2	System Integration Testing				██
4.3	Bug Fixing & Stabilization				██
Phase 5: Deployment
5.1	User Acceptance Testing (UAT)				█
5.2	Production Deployment				█
5.3	Knowledge Transfer & Handover				█

Total Duration: 23 Days (Approximately 1 Month)
Total Price: 39,000 KES (Deposit 60%: 23,400 KES)

↑ Back to top

📅 Project Timeline B: Eased Duration (2 Months) – 33,000 KES

The following Gantt chart outlines a standard eight-week delivery schedule. This timeline incorporates dedicated buffer periods for each phase, allowing for thorough testing, iterative feedback cycles, and comprehensive documentation.

Task ID	Task Name	Week 1-2	Week 3-4	Week 5-6	Week 7-8
Phase 1: Planning & Setup
1.1-1.4	Requirements, Architecture, Database, Environment	████
Phase 2: Backend Development
2.1-2.5	Auth, Transaction Engine, Billing, Payments, Remittance		████	████
Phase 3: Frontend Development
3.1-3.4	Dashboard, Interfaces, Reports, Audit UI		██	████
Phase 4: Offline & Integration
4.1-4.3	Offline Capability, Integration Testing, Optimization			██	██
Phase 5: Quality Assurance
5.1-5.3	Functional Testing, Bug Fixing, UAT				████
Phase 6: Deployment
6.1-6.3	Production Deployment, Documentation, Handover				██

Total Duration: 56 Days (Approximately 2 Months)
Total Price: 33,000 KES (Deposit 60%: 19,800 KES)

↑ Back to top