Twende — Product & Design Workboard

UI/UX Interactive Mockups

Click any card to open the interactive screen-by-screen mockup for that app.

Passenger App Flow

29 interactive screens: full sign-up & log-in, home map, saved places, multi-stop builder, schedule-for-later, fare quote + Fare Explainer, matching, in-app chat, pickup + helmet verification, cancel, in-trip safety, share trip, MoMo payment + tipping, wallet, history, profile, referrals, lost & found, help center, and offline / USSD fallback.

29 screens Flutter Helmet · Multi-stop · Schedule

Driver App Flow

25 interactive screens: full sign-up flow, pre-shift plate verification, availability + demand heatmap + Head-Home mode, offer countdown, active trip + PIN, earnings + 4-hour Forecast + Quests & Bonuses + Tier (Bronze/Silver/Gold) loyalty, history, withdrawal, performance, vehicle & docs, change-vehicle, and safety center.

25 screens Flutter Quests · Tiers · Head-Home

17 interactive screens: full admin sign-in (password, 2FA, Google SSO, forgot password), live ops map, fraud console, Pricing Engine (live signals + autonomous decisions), Fuel & FX Feeds, pricing controls, disputes, KYC review, vehicle compliance (plate-mismatch handling), user management, MoMo reconciliation, analytics + demand forecast, audit log, and platform settings.

17 screens React Web Pricing Engine

→

PRIMARY SECONDARY

Foundations

Design System & Foundations

Color tokens, typography, spacing scale, core components, target viewports (360×640+), accessibility rules, microcopy reference, connectivity-state matrix, Pricing Intelligence (formula + signals), Vehicle Identity Trust (5-layer defence), and Google Maps integration architecture.

Tokens Pricing Vehicle Trust Maps

→

UX Principles

⚡

Fast-first

Primary action reachable in 1 tap from home screen

📶

Low-bandwidth

Minimal payload UI, skeletons, graceful retry, offline-lite queue

🔒

Trust-first

Transparent fare breakdown, verified badges, safety always visible

♿

Accessible

Large tap targets, high contrast, readable on low-end Android

📍

Uganda-first

Map + landmark hybrid, +256 default, UGX currency, MoMo-first

🛡️

Safety-first

SOS button always visible in-trip, share trip, safety AI prompts

System Architecture

Microservices + event-driven platform optimized for low connectivity and MoMo-first payments in Uganda.

┌─────────────────────────────────────────────────────────────────────────────────┐
│  CLIENT LAYER                                                                   │
│  Passenger App (Flutter)  ·  Driver App (Flutter)  ·  Admin Web (React)        │
└──────────────────────────────────┬──────────────────────────────────────────────┘
                                   │  HTTPS / WebSocket (TLS 1.3)
┌──────────────────────────────────▼──────────────────────────────────────────────┐
│  API GATEWAY  (Kong / AWS API Gateway)                                          │
│  WAF · Rate Limiter · JWT Validation · RBAC scope check · Request routing       │
└──────────┬──────────┬──────────┬───────────┬────────────┬────────────┬──────────┘
           │          │          │           │            │            │
      ┌────▼───┐ ┌────▼────┐ ┌──▼──────┐ ┌─▼────────┐ ┌▼──────────┐ ┌▼──────────┐
      │  Auth  │ │  Trip   │ │Dispatch │ │ Pricing  │ │ Payment   │ │  Safety   │
      │  KYC   │ │ Service │ │Service  │ │ Service  │ │ Service   │ │  Fraud    │
      │Service │ │  FSM    │ │Matching │ │ AI Fare  │ │ MoMo/Cash │ │ Service   │
      └────────┘ └────────┘ └─────────┘ └──────────┘ └───────────┘ └───────────┘
           │          │          │           │            │            │
           └──────────┴──────────┴───────────┴────────────┴────────────┘
                                             │
                            ┌────────────────▼───────────────────┐
                            │   Apache Kafka (Event Bus)          │
                            │   Topics: trip.* · payment.* ·     │
                            │   driver.* · fraud.* · safety.*    │
                            └────────────────┬───────────────────┘
                                             │
         ┌───────────────┬──────────────────┼──────────────────┬───────────────┐
   ┌─────▼──────┐ ┌──────▼─────┐ ┌─────────▼──────┐ ┌────────▼──────┐ ┌──────▼────┐
   │ PostgreSQL │ │   Redis    │ │  ClickHouse    │ │ Object Store  │ │  Elastic  │
   │ Primary DB │ │Cache+Queue │ │ OLAP Analytics │ │ Receipts/KYC  │ │  Search   │
   └────────────┘ └────────────┘ └────────────────┘ └───────────────┘ └───────────┘

Microservices

🔑

Auth / KYC Service

Identity · Access · Verification

Handles OTP-based login (+256), JWT issuance, refresh token rotation, and driver KYC document review workflow. RBAC scopes: passenger, driver, ops, fraud_analyst, finance, superadmin.

JWT RS256 OTP via Africa's Talking Redis OTP TTL KYC docs → S3

🗺️

Trip Service

Lifecycle FSM · Audit · GPS Polyline

Owns the trip lifecycle finite state machine: REQUESTED → SEARCHING → MATCHED → ARRIVING → IN_PROGRESS → COMPLETED / CANCELLED. Records full GPS polyline in PostGIS for dispute resolution and safety audit.

PostgreSQL + PostGIS FSM validation Kafka trip.* events Driver PIN

📡

Dispatch Service

Matching · Fairness · WebSocket Offers

Smart driver matching using Haversine nearest-driver + fairness rotation (equal trip distribution per zone). Delivers offers via WebSocket with 12–15 s countdown. Auto-retries with expanded radius if no accept.

Haversine geospatial Fairness rotation Redis offer locks WebSocket push

💰

Pricing Service

Explainable AI Fare · Surge · Fuel

Computes transparent upfront fares: Fare = (base + dist×k_d + time×k_t) × surge + fuel_adj − promo. Surge capped at 1.8× (Uganda policy). Fuel index from NITA-U API weekly. All components returned to client for display.

Explainable formula Demand from ClickHouse NITA-U fuel API Quote token (Redis)

💳

Payment Service

MoMo · Airtel · Wallet Ledger · Disbursement

Unified payment layer wrapping MTN MoMo Collection API, Airtel Money API, and internal wallet (append-only ledger). Idempotency keys prevent double-charge. Daily bulk driver disbursement via MoMo Bulk API at 23:00.

MTN MoMo API Airtel Money API Idempotency keys Append-only ledger

🛡️

Safety & Fraud Services

SOS · Anomaly Detection · Rules + ML

Safety: monitors trip via Kafka position events, detects detours/stops, triggers SOS pipeline (FCM + SMS + Police). Fraud: hybrid rules engine (instant) + XGBoost ML model (async) for GPS spoof, cancel abuse, promo abuse, device reuse.

Dedicated SLA queue XGBoost model Device fingerprint Kafka stream analytics

Core Database Schema (PostgreSQL)

users Auth Service

iduuidPK

msisdn_hashvarchar(64)hashed

roleenumpassenger/driver/admin

kyc_statusenumpending/approved/rejected

created_attimestamptz

trips Trip Service

iduuidPK

passenger_iduuidFK→users

driver_iduuidFK→users

statusenumFSM state

pickup_geomgeometry(Point)

dropoff_geomgeometry(Point)

route_polylinegeometry(LineString)

fare_ugxinteger

service_typeenumboda/car/delivery

payment_transactions Payment Service

iduuidPK

trip_iduuidFK→trips

amount_ugxinteger

methodenummtn_momo/airtel/wallet/cash

statusenumpending/completed/failed

idempotency_keyvarchar(64)unique

momo_refvarchar(64)operator ref

fraud_alerts Fraud Service

iduuidPK

trip_iduuidFK→trips

subject_iduuidFK→users

fraud_typeenumgps_spoof/cancel_abuse/…

ml_scorefloat40.0–1.0

severityenumlow/medium/high/critical

statusenumopen/actioned/dismissed

AI / ML Modules

📊

Dynamic Pricing Engine

Explainable · Capped · Transparent

Demand score: ClickHouse aggregation of trip density per H3 hex zone every 5 min
Traffic score: Google Maps Distance Matrix API (travel time vs free-flow)
Surge = clamp(1 + α×demand + β×traffic, 1.0, 1.8) — hard cap for Uganda fairness
Fuel adjustment: weekly NITA-U fuel index diff, bounded ±15%
All components returned to client — passengers see exactly why fare is X

🎯

Smart Matching Algorithm

Proximity · Fairness · Preference

Phase 1: Haversine nearest available driver within 5 km radius
Phase 2: Fairness rotation weight — drivers with fewer trips in zone get priority
Phase 3: Driver preference model — learns accepted/declined route patterns per driver
Anti-bias: no demographic signals used in matching — only geo + performance data
Offer timeout retry: expand radius by 1 km, retry up to 3 times

🚨

Fraud Detection System

Rules Engine + XGBoost ML

Rules (instant): GPS speed > 100 km/h jump, payment before trip start, cancel-after-accept pattern
ML model (async ~500ms): XGBoost trained on labeled fraud events, F1 score > 0.91
Features: speed variance, route deviation, device fingerprint, payment timing, cancellation history
Weekly retraining on newly labeled cases via MLflow-tracked pipeline
False positive SLA: < 5% — protected by human review before account freeze

🔮

Demand Prediction & Safety AI

Hotspot Forecasting · Anomaly Detection

Demand: time-series model (Prophet + zone features) predicts hotspots 30 min ahead
Driver positioning hints: top 3 demand zones shown on driver home screen
Safety AI: monitors trip via Kafka stream, flags stalls > 5 min off-route
Night-hour escalation: anomaly sensitivity increased 21:00–05:00
Zone risk scoring: trip anomaly density + incident reports → hourly ClickHouse update

Tech Stack Rationale

📱 Flutter (Mobile Apps)

Single codebase for Android + iOS. Compiles to native ARM — fast on low-end devices. Riverpod for reactive state. Flutter Background Service for trip tracking when app is backgrounded. Works well on Android 8+ (dominant in Uganda).

⚙️ Java Spring Boot (Backend)

Production-proven for high-throughput APIs. Spring WebFlux for reactive WebSocket streams (driver positions). Spring Security for JWT + RBAC. Large talent pool in East Africa. Docker + Kubernetes for horizontal scaling.

📊 PostgreSQL + PostGIS + ClickHouse

PostgreSQL: ACID-safe ledger for payments and trips. PostGIS: native geospatial queries for driver matching and route storage. ClickHouse: columnar OLAP for analytics KPIs and ML features — avoids PostgreSQL OLTP pressure.

🔥 Kafka + Redis

Kafka: event bus decouples microservices — trip events fan-out to Safety, Fraud, Analytics without tight coupling. Redis: low-latency driver presence, OTP storage, offer locks, session cache. Both managed (Confluent Cloud + Redis Cloud) to reduce ops overhead.

MVP Roadmap — 6 Sprints

Sprint 1

Platform foundation, OTP auth (+256), app shells, observability

P0 · Foundation

Sprint 2

Ride request, nearest-driver dispatch, real-time WebSocket tracking

P0 · Core Flow

Sprint 3

MTN MoMo + Airtel Money, wallet/ledger, SOS + share trip, KYC review

P0 · Payments & Safety

Sprint 4

Dynamic pricing engine, fare transparency breakdown, fairness-aware matching, earnings dashboard

P1 · Intelligence

Sprint 5

Fraud rules engine, dispute management workflow, masked calling, reliability hardening

P1 · Trust

Sprint 6

Offline-lite queue, USSD/SMS fallback, multi-city config framework, go-live runbook

P0 · Scale

Sprint Issue Backlog

ID	Sprint	Epic	Title	Type	Priority
S1-01	S1	EPIC-07	Bootstrap backend microservices monorepo	backend	P0
S1-02	S1	EPIC-01	OTP authentication + JWT sessions	security	P0
S1-04	S1	EPIC-01	Client app shell (Flutter) with OTP login	mobile	P0
S2-01	S2	EPIC-02	Ride quote + request endpoint	backend	P0
S2-02	S2	EPIC-02	Nearest-driver dispatch engine	AI	P0
S2-04	S2	EPIC-02	Client booking + trip tracking screens	mobile	P0
S3-01	S3	EPIC-04	MTN MoMo integration	backend	P0
S3-05	S3	EPIC-05	SOS + share trip feature	security	P0
S4-01	S4	EPIC-03	Dynamic pricing engine v1	AI	P0
S5-01	S5	EPIC-05	Fraud rules engine (real-time)	security	P0
S5-03	S5	EPIC-05	Dispute management workflow	admin	P0
S6-03	S6	EPIC-08	Offline-lite queue + USSD/SMS fallback	mobile	P0