TrafficGrid
System Design Document · v0.1 Draft¶
1. Project Overview¶
Road users in Harare currently face a fragmented, paper-heavy process when dealing with traffic offences, vehicle registration, parking fines, and renewals. After receiving an offence, a driver must physically visit multiple offices — ZRP, City Parking, VTS, and the local council — often at different sites, just to resolve a single matter. This results in delays, lost time, and an opaque system with no centralised record.
This platform consolidates all of these touchpoints into a single, unified digital system. Officers can log offences on mobile devices in the field. Citizens can view their vehicle records, outstanding fines, and renewal deadlines from a mobile app. Payments can be made electronically, clearing records across all relevant authorities automatically. Administrators and supervisors have a transparent, audited view of every action taken within the system.
2. Problem Statement¶
2.1 Current Pain Points¶
- Citizens must visit multiple physical locations after a single offence (ZRP, VTS/Southerton for rekuchura mota, City Parking, Council)
- No centralised record of a vehicle's offence history — officers and clerks rely on physical books and paper tickets
- ZRP and City Council have no digital fines system — all processes are manual
- Renewing a vehicle licence, insurance, and ZBC licence requires tracking expiry dates manually with no reminders
- Payments are cash-only with no digital receipts, creating opportunities for record loss and corruption
- Spot fines issued on the road have no automatic link to a vehicle's central record
2.2 Proposed Solution¶
Build a unified platform that acts as the single source of truth for vehicle records, traffic offences, parking tickets, and fine payments across all relevant Harare authorities. The system will:
- Consolidate records from ZRP, ZINARA, VTS, City Parking, and City Council into one searchable database
- Allow officers to log and search offences from a secure mobile interface in the field
- Allow citizens to view their vehicle dashboard, outstanding fines, and renewal reminders from a mobile app
- Process digital payments (EcoCash, bank transfer, cash-recorded) and automatically mark fines as cleared across all parties
- Provide full audit trails for every action performed in the system
3. Stakeholders & Integrations¶
3.1 Organisations in Scope¶
The following organisations are part of the initial scope for Harare:
| Organisation | Role in System | Integration Type |
|---|---|---|
| ZRP | Issues traffic offences and spot fines. Officers log fines via mobile. | Manual entry via officer mobile app (no existing digital fines system) |
| VTS (Vehicle Theft Squad) | Verifies vehicle ownership, VIN numbers, and registration details. Falls under ZRP. | API integration — VTS has an existing vehicle registration system |
| ZINARA | Source of vehicle licence and registration data. Triggers renewal reminders. | API integration — ZINARA has existing digital records |
| City Parking | Issues parking tickets and manages parking sessions. | API integration — City Parking has an existing ticketing system |
| City Council (Harare) | Issues council-related fines and violations. | Manual entry via council officer interface (no existing digital system) |
| System Provider (Us) | Builds, owns, and administers the platform. Holds super-admin access. | Full system access and administration |
3.2 Organisations Out of Scope (Future)¶
- ZIMRA — vehicle import duties and tax clearance. Planned for a future phase.
- Foreign vehicle authorities — vehicles registered outside Zimbabwe will be categorised separately and handled in a future phase.
- Insurance providers — insurance expiry data will initially be self-declared by the vehicle owner.
4. User Roles & Access¶
| Role | Description & Access |
|---|---|
| General Public | Vehicle owners. Can view their own vehicle dashboard, outstanding fines, renewal reminders, and payment history. Mobile-first interface. |
| ZRP Officer | Field officers. Can log new offences and spot fines against a vehicle registration number. Can search a vehicle's offence history. Mobile interface. Cannot see unrelated records. |
| City Council Officer | Can log council-related fines. Can query outstanding fines on a vehicle. Cannot see ZRP-specific records beyond what is relevant. |
| City Parking Officer | Can view and manage parking tickets. Scoped to parking data only. |
| Authority Admin | Supervisors within each organisation. Can view records and reports scoped to their organisation. Cannot edit records from other authorities. |
| Super Admin | System provider (us). Full system access, user management, cross-authority reporting, and audit log access. |
5. Functional Requirements¶
5.1 Vehicle Management¶
- Citizens can register their vehicles in the system using a number plate and link them to their account
- Each registered vehicle has its own dashboard showing registration details, active fines, payment history, and upcoming renewal dates
- Vehicle information (VIN, ownership, registration) is sourced from VTS and ZINARA via API, with dummy data used during development
- Ownership verification will require at least a partial check against VTS/ZINARA records at registration time
5.2 Offences & Fines¶
- ZRP officers can log a new traffic offence against a vehicle registration number from their mobile device
- City Council officers can log council-related fines similarly
- Spot fines issued on the road are recorded immediately to the vehicle's central record
- Each fine has a status: Pending, Paid, Cleared, or Disputed
- A default payment window of 30 days applies from the date of issue, subject to change by the relevant authority
- Officers can optionally record a cash payment on the spot; the system logs who recorded it, when, and against which fine — creating an audit trail to deter corrupt recording
5.3 Parking¶
- City Parking tickets are synced from City Parking's existing system or entered manually
- Parking tickets appear on the relevant vehicle's record and can be paid through the platform
5.4 Payments¶
- Supported payment methods: EcoCash, bank transfer, and cash (recorded by an officer)
- Payment must be idempotent — duplicate payment attempts for the same fine must be detected and rejected
- A successful payment automatically marks the fine as cleared across all relevant authorities
- Manual clearance is available for cases that must be resolved at a physical office — an authorised officer records the manual resolution with a reason and timestamp
- Full payment receipts are generated and accessible to the vehicle owner
- Partial payments are out of scope for the initial phase
5.5 Notifications & Alerts¶
- Citizens receive reminders for upcoming expiry of vehicle licence, insurance, and ZBC licence
- Insurance and ZBC expiry dates can be entered manually by the vehicle owner, or defaulted to the same date as the vehicle licence
- Citizens receive notifications when a new fine is added to their vehicle record
- Citizens choose their preferred notification channel: SMS, email, or push notification (not all at once)
- Notification preferences are configurable per user
5.6 Audit & Transparency¶
- Every action in the system is logged with: who performed it, what was changed, when, and from which interface
- Audit logs are immutable and accessible only to super admins and authority admins within their scope
- This includes fine creation, payment recording, manual clearances, and user account changes
5.7 Documentation¶
- All backend API endpoints will be documented (Swagger / OpenAPI)
- Documentation will be versioned alongside the codebase
6. Non-Functional Requirements¶
| Concern | Requirement |
|---|---|
| Security | Secure login for all roles. Role-based access control (RBAC). Officer mobile sessions must be protected against device sharing. |
| Rate Limiting | API gateway enforces rate limits per user/role to prevent abuse and protect downstream services. |
| Idempotency | Payment endpoints must be idempotent. Duplicate requests for the same fine must not result in double charges. |
| Race Conditions | Concurrent payment attempts on the same fine must be handled safely using distributed locking or optimistic concurrency. |
| Scalability | Architecture must support horizontal scaling. Initial scope is Harare only but design must not preclude national expansion. |
| Auditability | Every write action is logged with actor, timestamp, and changed data. Logs are immutable. |
| Availability | Core services (fine lookup, payment) should target high availability. Degraded mode acceptable for non-critical services. |
| Offline Support | Officer mobile app should support offline fine logging with sync when connectivity is restored (critical for field use on poor networks). |
7. Proposed System Architecture¶
7.1 Architecture Style¶
The system will be built using a microservices architecture deployed on Kubernetes, with each service owning its own domain and data store. Services communicate synchronously via REST for queries and asynchronously via a message broker (Apache Kafka) for events such as payment completion and fine status changes.
An API Gateway sits in front of all services, handling authentication validation, rate limiting, and routing. All client applications (mobile, web, officer app) communicate exclusively through the gateway.
7.2 Services¶
| Service | Responsibility | Key Dependencies |
|---|---|---|
| Identity & Auth | User registration, login, JWT issuance, RBAC, role management | All services |
| Vehicle Service | Vehicle records, ownership, VIN, registration data, ZINARA/VTS sync | ZINARA API, VTS API |
| Fines & Offences | Logging, tracking, and status management of traffic and council fines | Vehicle Service, Payments Service |
| Parking Service | Parking ticket management, City Parking sync | City Parking API, Payments Service |
| Payments Service | EcoCash, bank transfer, cash recording, idempotency, receipts | Fines Service, Parking Service, EcoCash API |
| Notifications Service | SMS, email, push notifications, user channel preferences | All event-producing services |
| Audit Service | Immutable action logging across all services | All services (via Kafka events) |
| Admin Service | Super admin dashboard, cross-authority reporting, user management | All services |
| API Gateway | Auth validation, rate limiting, routing, SSL termination | All services |
7.3 Infrastructure¶
- Containerisation: Docker — each service packaged as an image
- Orchestration: Kubernetes (K8s) — manages deployment, scaling, and self-healing
- CI/CD: GitHub Actions — automated testing, Docker image build, and K8s deployment on push
- Message Broker: Apache Kafka — async event streaming between services (payment cleared, fine issued, etc.)
- Caching: Redis — session storage, caching of frequently queried vehicle records, distributed locks for payment idempotency
- Database: PostgreSQL per service (each service owns its own schema)
- API Documentation: Swagger / OpenAPI auto-generated from Spring Boot annotations
8. Client Interfaces¶
| Interface | Target Users & Notes |
|---|---|
| Citizen Mobile App | General public. Android and iOS. Primary interface for vehicle dashboard, fines, payments, and renewal reminders. Mobile-first. |
| Officer Mobile App | ZRP and Council officers. Android (field use). Offline-capable for logging fines. Syncs when connectivity is restored. Secure login required. |
| Authority Web Portal | Authority admins and supervisors. Query vehicle records, view reports, manage manual clearances within their scope. |
| Super Admin Dashboard | System provider. Full system oversight, user management, audit log access, cross-authority reporting. |
USSD and WhatsApp interfaces are planned for a future phase to increase accessibility.
9. Future Development Backlog¶
The following features and integrations are deliberately out of scope for the initial phase and are logged here for future planning:
- ZIMRA integration — vehicle import duties and tax clearance
- Foreign vehicle handling — separate category and workflow for non-Zimbabwe-registered vehicles
- Partial and installment payments — for larger fines that require payment plans
- USSD interface — for users without smartphones or data access
- WhatsApp notifications — as an additional notification channel
- National expansion — extending the platform beyond Harare to other cities and councils
- Full regulatory compliance framework — data residency, formal data ownership agreements with authorities, government approval
- Insurance provider API integration — automated insurance expiry data instead of self-declaration
10. Open Questions & Risks¶
| Item | Notes |
|---|---|
| Data Ownership | Legally, personal vehicle and offence data should belong to the relevant authority (ZRP, ZINARA). Since most authorities lack their own digital systems, this platform will act as the operational source of truth in trust, pending formal data governance agreements when the system is officially adopted. |
| ZINARA/VTS API Access | Integration feasibility and data access agreements with ZINARA and VTS are not yet confirmed. Dummy data will be used during development. |
| City Parking Sync | The City Parking system exists but the integration capability and API availability are not yet confirmed. |
| Officer Adoption | If field officers find the mobile app cumbersome, they will not use it. UX and offline capability are critical for adoption. |
| Cash Payment Integrity | Cash payments recorded by officers in the system carry corruption risk. The audit trail mitigates this but a supervisory approval step for cash recordings may be needed. |
| Regulatory Approval | A government or regulatory body will need to formally oversee this system before it can be officially deployed. Security and data requirements may change significantly at that stage. |
| Concurrent Users | Expected concurrent users are not yet estimated. Architecture is designed to scale but load testing benchmarks are to be defined. |
End of Document — v0.1 Draft