System Requirements Document for dawn-attached

1. Introduction

1.1 Source overview

"product_positioning": {

  "description": "A digital fuel-credit and mobility-support ecosystem connecting verified public transport drivers with fuel supply, payment facilitation, rewards, vehicle intelligence, mechanics, repair shops and spare-parts providers.",

  "core_promise": "Keep public transport vehicles fueled, moving and economically productive.",

  "design_philosophy": [

    "Simple",

    "Fast",

    "Trustworthy",

    "Offline-first",

    "Low-data",

    "Secure",

    "Transparent",

    "African-market optimized"

  ]

}

},

"brand": {

"name": "NeNo-Lubs",

"parent_company": "Veltrava Energy",

"brand_personality": [

  "Professional",

  "Modern",

  "Reliable",

  "Energetic",

  "African",

  "Technology-driven",

  "Trustworthy"

],

"recommended_slogan": "Fuel. Fix. Move Forward.",

"alternative_positioning_line": "Smart Fuel. Smarter Mobility.",

2. System Overview

2.1 Source overview

  "05_operational_modules.json",

  "06_ai_security_offline.json",

  "07_animations_legal_deployment.json"

]

},

"master_instruction": {

"role": "You are the principal software architect, senior mobile engineer, product designer, security engineer, fintech systems engineer, QA engineer and DevOps engineer responsible for building NeNo-Lubs.",

"objective": "Design and implement NeNo-Lubs as a production-grade, scalable, secure, offline-first native mobile platform for Botswana public transport fuel-credit operations and vehicle-support services.",

    "Payment orchestration",

    "Notification service",

    "AI orchestration",

    "Marketplace service",

    "Reporting service",

    "Audit service"

  ]

},

  "Presentation",

  "Application",

  "Domain",

  "Data",

  "Infrastructure",

  "Integration",

],

"core_services": [

  "IdentityService",

  "UserService",

  "DriverService",

  "VehicleService",

  "UnionValidationService",

  "MerchantService",

  "StationService",

  "AttendantService",

  "FuelInventoryService",

  "FuelTransactionService",

  "CreditEngine",

    "review_users",

    "review_merchants",

    "review_stations",

    "review_content",

    "review_disputes"

  ]

}

},

"navigation": {

"navigation_principle": "Role-driven navigation",

  "RoleDashboard"

3. Functional Requirements

3.1 Source overview

    "Offline-first state handling",

    "Skeleton loading",

    "Error recovery",

    "Empty states",

    "Network state indicators"

  "Role-based access control",

  "Audit logging",

  "Automated backups",

  "Monitoring",

  "Error tracking",

  "Rate limiting",

  "API authentication",

  "Database migration control"

    "manage_drivers",

    "manage_vehicles",

    "manage_unions",

    "manage_merchants",

    "manage_stations",

    "manage_attendants",

    "manage_fuel_inventory",

    "manage_fuel_purchases",

    "manage_pricing",

    "manage_credit_rules",

    "manage_rewards_rules",

    "suspend_accounts",

    "blacklist_accounts",

    "view_audit_logs"

  ]

},

    "view_profile",

    "manage_assigned_vehicle",

    "view_credit_status",

    "fuel_vehicle",

    "make_repayments",

    "view_points",

    "redeem_rewards",

    "view_fuel_stations",

    "view_fuel_prices",

    "use_vehicle_calculator",

    "use_speedometer",

    "use_ai_diagnostics",

    "use_ai_repair_guidance",

    "request_mechanic_quotes",

    "view_vehicle_service_history",

    "receive_reminders"

    "select_vehicle",

    "declare_fuel_amount",

    "select_payment_methods",

    "generate_qr",

    "confirm_transaction",

    "view_transaction_history",

    "view_wet_stock",

    "submit_stock_alert"

  "permissions": [

    "manage_station_profile",

    "manage_station_services",

    "publish_fuel_prices",

    "manage_station_staff",

    "view_transactions",

    "view_station_reports",

    "manage_subscription"

  "permissions": [

    "manage_business_profile",

  "Register",

  "ForgotPassword",

  "OTPVerification",

  "PINSetup",

  "BiometricSetup",

  "SecurityConfirmation"

],

"driver_navigation": {

  "type": "BottomTabNavigation",

  "tabs": [

    {

      "id": "HOME",

      "label": "Home",

      "icon": "home"

    },

    {

      "id": "FUEL",

      "label": "Fuel",

      "icon": "fuel"

    },

    {

      "id": "SERVICES",

      "label": "Services",

      "icon": "tools"

    },

    {

      "id": "REWARDS",

      "label": "Rewards",

      "icon": "gift"

    },

    {

      "id": "PROFILE",

      "label": "Profile",

      "icon": "person"

    }

  ],

  "home_sections": [

    "CurrentVehicle",

    "FuelCreditStatus",

    "AmountDue",

    "RepaymentCountdown",

    "NearestFuelStation",

    "PointsBalance",

    "CreditScore",

    "QuickActions",

    "Alerts"

  ],

  "quick_actions": [

    "FuelNow",

    "PayDebt",

    "FindStation",

    "VehicleDiagnosis",

    "FuelCalculator",

    "Speedometer"

  ]

},

"merchant_navigation": {

  "type": "BottomTabNavigation",

  "tabs": [

    "Sell",

    "Transactions",

    "Stock",

    "Alerts",

    "Profile"

  ]

},

"station_navigation": {

  "type": "BottomTabNavigation",

  "tabs": [

    "Dashboard",

    "Prices",

    "Services",

    "Transactions",

    "Profile"

  ]

},

"mechanic_navigation": {

  "type": "BottomTabNavigation",

  "tabs": [

    "Dashboard",

    "RFQs",

    "Services",

    "Products",

    "Profile"

  ]

},

"admin_navigation": {

  "type": "SidebarNavigation",

  "sections": [

    "Dashboard",

    "Drivers",

    "Vehicles",

    "Unions",

    "Merchants",

    "Fuel Stations",

    "Attendants",

    "Fuel Inventory",

    "Credit",

    "Repayments",

    "Rewards",

    "Payments",

    "Mechanics",

    "RFQs",

    "Subscriptions",

    "Notifications",

    "Reports",

    "Audit Logs",

    "System Settings"

  ]

}

},

"authentication": {

"authentication_model": "Multi-factor authentication",

"required_factors": [

  "PASSWORD",

  "PIN",

  "OTP",

  "BIOMETRICS"

],

"four_factor_mode": {

  "name": "4FA",

  "enabled": true,

  "description": "The platform supports password, application PIN, one-time password and biometric authentication. The security engine may require all four according to risk policy and transaction sensitivity.",

  "factor_order": [

    "PASSWORD",

    "PIN",

    "OTP",

    "BIOMETRICS"

  ]

},

"registration": {

  "required": [

    "full_name",

    "mobile_number",

    "email",

    "national_identifier_or_supported_identity_reference",

    "role",

    "password",

    "PIN",

    "OTP_verification"

  ],

  "driver_specific": [

    "union",

    "vehicle_registration",

    "vehicle_information",

    "driver_validation"

  ]

},

"password": {

  "minimum_length": 12,

  "require_uppercase": true,

  "require_lowercase": true,

  "require_number": true,

  "require_special_character": true,

  "fallback": "PIN or password according to security policy"

},

"device_binding": {

  "enabled": true,

  "maximum_primary_devices": 2,

  "new_device_requires_verification": true,

  "device_change_requires_otp": true

},

"session": {

  "access_token": "Short-lived",

  "refresh_token": "Rotating",

  "idle_timeout_minutes": 15,

  "sensitive_operation_reauthentication": true

},

"risk_based_authentication": {

  "enabled": true,

  "high_risk_triggers": [

    "New device",

    "Unusual location",

    "Multiple failed PIN attempts",

    "Large transaction",

    "Rapid transaction frequency",

    "Suspicious QR activity",

    "Account recovery",

    "Payment method change"

  ]

}

},

"authorization": {

"model": "RBAC + resource-level authorization",

"principle": "Least privilege",

"server_side_enforcement": true,

"client_side_enforcement": false,

"requirements": [

  "Every protected API endpoint must validate role and permissions.",

  "Every transaction must validate ownership or authorized operational relationship.",

  "Driver A must never access Driver B's private transaction data.",

  "Merchant A must never modify Merchant B's inventory.",

  "Station users must only access their assigned station.",

  "Administrators must have auditable privileged actions."

},

"fueling_vehicle_selection": {

  "required": true,

  "actor": "MERCHANT",

  "validation": [

    "Vehicle belongs to driver",

    "Vehicle is active",

    "Vehicle is eligible",

    "Vehicle is not blacklisted",

    "Vehicle registration is valid"

  ]

}

},

],

"financial_transaction_rules": [

  "Never trust client-calculated payment totals.",

  "Server calculates authoritative transaction values.",

  "Every transaction receives an immutable transaction identifier.",

  "Idempotency keys are required for payment-changing requests.",

  "Duplicate payment events must not create duplicate credits.",

  "Payment status must be verified from the authoritative payment provider."

  "Previously synchronized repayment information",

  "Previously synchronized station information",

  "Fuel consumption calculator",

  "Cached user profile",

  "Cached rewards balance",

  "Cached reminders",

  "Draft RFQs",

  "Draft service requests"

"sync": {

  "strategy": "Queue-and-sync",

  "conflict_resolution": "Server-authoritative",

  "retry": "Exponential backoff",

  "idempotency": true,

  "network_detection": true

"features": [

  "Compressed API responses",

  "Lazy image loading",

  "Low-resolution thumbnails",

  "Reduced map detail",

  "Text-first notifications",

],

"user_control": true,

"automatic_adaptation": true

},

"notifications": {

"channels": [

  "Push",

  "SMS",

  "Email",

  "In-App"

],

"critical_events": [

  "Fuel transaction created",

  "Payment received",

  "Repayment approaching deadline",

  "Repayment overdue",

  "Account suspension",

  "Credit limit change",

  "Reward qualification",

  "Full tank reward available",

  "Station stock alert",

  "Security alert"

],

"notification_principle": "Financially significant events must have a durable in-app record even if push delivery fails."

},

"auditability": {

"enabled": true,

"immutable_events": [

  "Login",

  "Logout",

  "Password change",

  "PIN change",

  "Device registration",

  "Driver verification",

  "Vehicle registration",

  "Fuel transaction",

  "Payment",

"primary": [

],

  "Authentication",

  "Password",

  "PIN",

  "OTP if required",

  "Biometric confirmation if enabled",

  "Dashboard"

],

"fuel_transaction": [

  "Payment provider confirmation",

  "Server records payment",

  "Debt recalculated",

  "Reward points calculated",

  "Credit score updated",

  "Receipt generated"

],

"reward_qualification": [

  "Vehicle completes qualifying cycle",

  "System verifies six consecutive successful cycles",

  "System creates seventh-cycle reward eligibility",

  "Driver chooses full-tank reward or points alternative",

  "System records immutable reward decision",

  "Vehicle-specific reward ledger updated"

]

},

  "Loading state implemented",

  "Empty state implemented",

  "Error state implemented",

  "Offline state considered",

  "Authorization verified",

  "Audit requirements implemented",

  "Analytics event defined where appropriate",

"gemini_execution_protocol": {

"phase_1": "Read all supplied specification files.",

"phase_2": "Create architecture plan and dependency map.",

"phase_3": "Create project structure.",

"phase_4": "Implement design system and navigation shell.",

"phase_5": "Implement authentication and authorization.",

"phase_14": "Update CHANGELOG.md.",

4. User Personas

4.1 Source overview

"primary_users": [

  "Public transport taxi drivers",

  "Fuel station attendants",

  "Fuel station/depot operators",

  "Mechanics",

  "Repair shops",

  "Spare-parts shops",

  "Veltrava Energy administrators"

],

"DRIVER": {

  "description": "Verified public transport driver",

  "permissions": [

"MERCHANT": {

  "description": "Fuel transaction operator/merchant working under the NeNo-Lubs supply structure",

5. Core User Flows

5.1 Source overview

"startup_sequence": [

  "AppLaunch",

  "SplashScreen",

  "OnboardingCheck",

  "AuthenticationStateCheck",

  "RoleResolution",

],

"unauthenticated": [

  "Welcome",

  "Onboarding01",

  "Onboarding02",

  "Onboarding03",

  "Onboarding04",

  "Onboarding05",

  "Login",

"driver_registration": [

  "Launch",

  "Onboarding",

  "Register",

  "Verify mobile/email",

  "Create password",

  "Create PIN",

  "Enable biometrics",

  "Submit driver information",

  "Select union",

  "Submit vehicle",

  "Await validation",

  "Account activation"

],

"driver_login": [

  "Launch",

  "Driver arrives at registered fueling location",

  "Merchant authenticates",

  "Merchant searches/selects driver",

  "Merchant selects vehicle",

  "Merchant enters requested fuel amount",

  "System validates eligibility",

  "System calculates authoritative transaction",

  "Driver reviews transaction",

  "Payment method selected",

  "QR/payment workflow initiated where applicable",

  "Payment confirmed",

  "Fuel transaction recorded",

  "Vehicle-specific reward engine updated",

  "Driver and merchant receive confirmation"

],

"repayment": [

  "Driver views outstanding balance",

  "Driver selects Pay Debt",

  "System displays authoritative amount",

  "Driver selects payment method",

  "Payment authentication",

6. Visuals Colors and Theme

[Design proposal; unspecified choices are defaults.]

NeNo (dawn-attached) is a premium mobility-fintech product for Botswana public-transport fuel credit and vehicle support, carrying the brand personality Professional, Modern, Reliable, Energetic and African, and the slogan Fuel. Fix. Move Forward. The visual direction is a fuel instrument panel, not a fintech template: honest, mechanical, calm under financial pressure, legible one-handed beside a pump in bright sunlight on low-end Android.

Palette (light mode). Ground #F7F9FC; surfaces #FFFFFF panels with #D0D5DD hairlines; text #14213D primary and #667085 secondary. NeNo Deep Blue #0B1F3A carries primary navigation, header bands, brand backgrounds and primary buttons. Energy Gold #F4B400 is the single signal accent — fuel highlights, rewards, progress indicators and one primary action per screen — never body text, never paired with white text (use Deep Blue on gold). Fuel Green #19A974 marks successful payments, healthy stock and completed repayments; Amber #F59E0B upcoming repayment, low stock and warnings; Safety Red #D92D20 overdue payments, suspension and critical alerts. One accent competes per screen.

Typography. Archivo throughout: headings 600–800 with -0.02em tracking, sentence case for headlines, uppercase small-caps labels at 11–12px with +0.08em tracking for data fields (BWP amounts, plate numbers, station codes). Numerals are the ornament — tabular, large, always paired with a label. Modular scale 1.25 mobile / 1.333 desktop: 12/14/16/20/25/31/39/49/61/76; dashboard amount display clamp(30px, 4.6vw, 44px); section headline clamp(22px, 3.2vw, 31px). Readable on low-end Android and outdoor sunlight.

Shape and elevation. 4px radius inputs and chips, 8px panels, 12px only for the top-level Fuel Now action. No pills, blobs or blur shadows; elevation is a second hairline plus a 4% tint. Circular gauges only where a real instrument exists (fuel level, credit utilisation).

Layout. Visible 12-column grid, 16px mobile / 24px desktop gutter, 8-pt baseline. Role navigation is a fixed left rail at ≥1280px and a bottom tab bar at 375–768px, each tab icon + text label. Minimum touch target 48dp, WCAG-oriented high contrast, screen-reader and dynamic-text support; critical financial information is never hidden behind decorative UI.

Iconography and imagery. Simple outlined and filled mobility pictograms at a single 1.75px stroke on a 24px grid, consistent stroke weight, never mixed families, always labelled, never the only signal for a critical action. No photography in operational surfaces; imagery is diagrammatic — fuel-gauge arc, ruled station map tile, vehicle silhouette. Any station or vehicle photo is cropped square, desaturated 20%, hairline-framed, never full-bleed behind text. Avoid excessive gradients, cluttered dashboards, childish illustrations, bright-colour overuse, generic template appearance, unnecessary animation and low-contrast text.

6.1 Source overview

],

"visual_direction": {

  "style": "Premium mobility-fintech",

  "avoid": [

    "Excessive gradients",

    "Cluttered dashboards",

    "Childish illustrations",

    "Overuse of bright colors",

    "Generic template appearance",

    "Unnecessary animations",

    "Low-contrast text"

  ],

  "principles": [

    "Strong visual hierarchy",

    "Large touch targets",

    "Readable typography",

    "High contrast",

    "Minimal cognitive load",

    "Professional transportation aesthetic"

  ]

},

"color_system": {

  "primary": {

    "name": "NeNo Deep Blue",

    "hex": "#0B1F3A",

    "usage": [

      "Primary navigation",

      "Headers",

      "Brand backgrounds",

      "Primary buttons"

    ]

  },

  "secondary": {

    "name": "Energy Gold",

    "hex": "#F4B400",

    "usage": [

      "Fuel highlights",

      "Rewards",

      "Important actions",

      "Progress indicators"

    ]

  },

  "accent": {

    "name": "Fuel Green",

    "hex": "#19A974",

    "usage": [

      "Successful payments",

      "Healthy stock",

      "Completed repayments"

    ]

  },

  "warning": {

    "name": "Amber",

    "hex": "#F59E0B",

    "usage": [

      "Upcoming repayment",

      "Low stock",

      "Warnings"

    ]

  },

  "danger": {

    "name": "Safety Red",

    "hex": "#D92D20",

    "usage": [

      "Overdue payments",

      "Suspension",

      "Critical alerts"

    ]

  },

  "background": "#F7F9FC",

  "surface": "#FFFFFF",

  "text_primary": "#14213D",

  "text_secondary": "#667085",

  "border": "#D0D5DD"

},

"typography": {

  "primary_font": "Inter",

  "fallback_fonts": [

    "Roboto",

    "sans-serif"

  ],

  "weights": [

    400,

    500,

    600,

    700,

    800

  ],

  "principle": "Readable on low-end Android devices and outdoor sunlight."

},

"iconography": {

  "style": "Simple outlined and filled mobility icons",

  "rules": [

    "Use consistent stroke weight",

    "Do not mix unrelated icon families",

    "Icons must have accessible labels",

    "Never use icons as the only communication method for critical actions"

  ]

}

},

7. Signature Design Concept

[Design proposal; unspecified choices are defaults.]

Less, but better — a fuel instrument panel. The muse is Dieter Rams: functional clarity for users who must read debt, stock and eligibility at a glance in daylight. The strict grid, honest controls and single signal accent translate the mandated token system without decoration competing with money — no editorial swagger, no glass, no gradient.

The instrument header. The first screen is a panel, not a marketing hero. A full-bleed NeNo Deep Blue #0B1F3A band occupies the top 38% of the viewport: a 12px uppercase gold label BWP CREDIT LINE, the vehicle plate in Archivo 700 uppercase at clamp(28px, 5vw, 44px) flush left, and the outstanding amount in tabular numerals at clamp(30px, 4.6vw, 44px) to its right, split by a 1px rgba(255,255,255,0.18) rule. The number is the largest element on screen. No centred headline, no subtext stack, no gradient.

Signature moves. A 6px Energy Gold progress rule spans full width beneath the band, filling to the vehicle's cycle utilisation with the percentage as a small-caps label at its right end. Below, a white surface holds three aligned label/value rows — Outstanding, Next repayment, Available credit — as two-column pairs with dotted leader hairlines, reading like a printed meter rather than cards. A 2×3 quick-action grid of bordered static tiles follows: 24px single-weight line icon, all-caps 11px label, no shadow, active tile marked by a 2px Deep Blue inset border. A single solid gold Fuel Now button pins full-width at the card's bottom. The circular fuel gauge — 270° arc, 8px stroke, needle tick — is the only curved element, used for stock and fuel level.

Driver dashboard composition. A ruled stack: Deep Blue header band with plate and credit status, the gold progress rule, the hairline-separated value rows, then the quick-action grid. Every headline, wordmark, label, number and control stays whole inside the viewport and its container at 375px, 768px and 1280px, wrapping or scaling via clamp(); imagery and decoration may crop or bleed, readable text and controls never do.

8. Interaction Model & Motion Direction

[Design proposal; unspecified choices are defaults.]

Interaction Model: Static (direction) Motion Tempo: restrained Hero Dimensionality: flat

Motion vocabulary. Instant, mechanical feedback: 120ms linear state changes, no bounce, no parallax, no decorative animation, marquees or autoplay video in financial surfaces. Numerals count up once on data arrival (200ms) and stop. Progress rules fill from left with a single linear sweep. Hover and focus are a 1px border colour change, not a lift; tiles are bordered and static.

Landing Hero Motion Brief. Focal subject: the Deep Blue instrument band with the plate and the tabular outstanding-credit readout. Thesis: on load, the accepted dashboard data arrives → the outstanding numeral counts up once over 200ms while the gold progress rule sweeps linearly to cycle utilisation → the settled state, a readable meter with the single gold Fuel Now action. Composed first frame: the band, plate, gold label and amount already in place at final size, progress rule at zero, value rows and quick-action grid visible below. Reduced-motion state: identical layout with numerals and progress rule rendered at final values immediately, no count-up or sweep.

Supporting states. Skeleton loading and network-state indicators communicate offline-first behaviour; text-first notifications carry status. Animation complexity reduces on low-performance devices, and user control plus automatic adaptation govern all transitions. No 3D scene is required: the direction's hero dimensionality is flat.

9. Non-Functional Requirements

9.1 Source overview

  "Security",

  "Observability"

"release_strategy": {

  "method": "Controlled staged releases",

  "rollback_required": true,

  "database_migrations_backward_compatible": true

  "password_storage": "Argon2id or equivalent modern password hashing",

  "never_store_plaintext": true

"requirements": [

  "Every protected API endpoint must validate role and permissions.",

  "Every transaction must validate ownership or authorized operational relationship.",

  "Driver A must never access Driver B's private transaction data.",

  "Merchant A must never modify Merchant B's inventory.",

  "Station users must only access their assigned station.",

  "Administrators must have auditable privileged actions."

"security_baseline": {

"principles": [

  "Zero trust",

  "Least privilege",

  "Defense in depth",

  "Secure by default",

  "Privacy by design",

  "Auditability"

],

"mandatory": [

  "TLS",

  "Encrypted sensitive local storage",

  "Server-side authorization",

  "Input validation",

  "Output encoding",

  "Rate limiting",

  "Audit logs",

  "Fraud detection",

  "Secure secrets management",

  "Dependency vulnerability monitoring"

]

},

"offline_first": {

"enabled": true,

"principle": "The application must remain useful when network connectivity is unavailable.",

"offline_features": [

  "Speedometer",

  "Vehicle information",

  "Previously synchronized transaction history",

],

"offline_restrictions": [

  "Do not finalize financial transactions offline.",

  "Do not mark a debt as paid solely from local state.",

  "Do not create authoritative fuel-credit transactions offline.",

  "Do not modify credit limits offline.",

  "Minimal background synchronization",

  "No autoplay video",

  "Reduced animation complexity on low-performance devices"

"timestamp_standard": "UTC",

"display_timezone": "Africa/Gaborone"

},

"observability": {

"logging": {

  "enabled": true,

  "never_log": [

    "Passwords",

    "PINs",

    "OTP values",

    "Biometric data",

    "Full card numbers",

    "Payment secrets"

  ]

},

"monitoring": [

  "API latency",

  "API error rate",

  "Authentication failures",

  "Payment failures",

  "Transaction failures",

  "Synchronization failures",

  "Crash rate",

  "Database health",

  "Notification delivery"

],

  "A driver should reach Fuel Now within two interactions from Home.",

  "A merchant should complete a normal fueling transaction quickly.",

  "Critical financial information must never be hidden behind decorative UI.",

  "Every irreversible financial action requires explicit confirmation.",

  "Errors must explain what happened and what the user should do next."

"accessibility": {

  "minimum_touch_target_dp": 48,

  "contrast": "WCAG-oriented high contrast",

  "screen_reader_support": true,

  "dynamic_text_support": true

}

},

"core_user_journeys": {

"design_quality_gates": {

"before_feature_completion": [

  "UI implemented",

  "Accessibility reviewed",

  "Payment sandbox tests passed",

  "Database migrations tested",

  "Offline synchronization tested",

  "Authentication recovery tested",

  "Fraud controls tested",

  "Crash-free baseline established",

  "CHANGELOG.md updated"

"phase_15": "Perform final completeness audit."

},

"completeness_audit": {

"gemini_must_verify": [

  "Every requirement in every JSON specification has an implementation or documented integration point.",

  "Every user role has a working navigation path.",

  "Every financial operation is server-authoritative.",

  "Every vehicle maintains independent reward accounting.",

  "Every authentication factor has a recovery strategy.",

  "Offline functionality does not compromise financial integrity.",

  "Payment failures do not create false successful transactions.",

  "Duplicate payment callbacks are idempotent.",

  "Administrative actions are auditable.",

  "AI advice is clearly distinguished from professional services.",

  "The application remains usable on low-end Android devices.",

  "No placeholder screen remains in production build.",

  "No fake API or simulated payment flow remains in production configuration.",

  "All unresolved assumptions are documented."

],

"final_output_required": [

  "Source code",

  "Database migrations",

  "API documentation",

  "Environment configuration template",

  "Test suite",

  "Security documentation",

  "Deployment documentation",

  "CHANGELOG.md",

  "README.md"

]

}

10. Tech Stack

10.1 Source overview

"target_platform": "Google AI Studio / Gemini",

"implementation_target": "Production-ready native mobile application",

"technical_architecture": {

"architecture_pattern": "Modular Clean Architecture",

"application_pattern": "Offline-first, API-driven, event-aware",

"mobile_strategy": {

  "priority": "Native mobile experience",

  "primary_platform": "Android",

  "secondary_platform": "iOS",

  "reason": "Botswana public transport users are expected to have substantial Android adoption while preserving future iOS support."

"frontend": {

  "preferred": "Native-quality mobile implementation",

  "ui_requirements": [

    "Responsive layouts",

    "Accessibility",

    "Dark-mode readiness",

    "Low-memory optimization",

  ]

},

"backend": {

  "style": "Modular service-oriented backend",

  "requirements": [

    "REST API",

    "Authentication service",

    "Authorization service",

    "Transaction service",

    "Credit engine",

    "Rewards engine",

"data": {

  "primary_database": "PostgreSQL-compatible relational database",

  "local_mobile_database": "SQLite-compatible encrypted local database",

  "cache": "Secure local cache",

  "object_storage": "Encrypted cloud object storage",

  "analytics": "Privacy-conscious event analytics"

},

"architecture_layers": [

  "RepaymentService",

  "RewardsEngine",

  "PaymentOrchestrator",

  "QRTransactionService",

  "NotificationService",

  "AIService",

  "MarketplaceService",

  "RFQService",

  "MapsService",

  "VehicleUtilityService",

  "ComplianceService",

  "AuditService",

  "ReportingService",

  "AdminService"

]

},

"deployment_architecture": {

"environments": [

  "development",

  "staging",

  "production"

],

"environment_isolation": true,

"production_requirements": [

  "HTTPS only",

  "Encrypted database connections",

  "Secret management",

],

"mobile_distribution": {

  "android": [

    "Internal testing",

    "Closed testing",

    "Production release"

  ],

  "ios": [

    "TestFlight",

    "App Store"

  ]

},

11. Assumptions and Constraints

The user instructed to read from the attached document (Paste_August_07__2026_-_9_03AM.txt) and build. The user chose the project name "dawn-attached".

11.1 Source overview

{

"$schema": "https://json-schema.org/draft/2020-12/schema",

"specification": {

"name": "NeNo-Lubs Gemini Development Constitution",

"file": "01_core_project.json",

"version": "1.0.0",

"status": "FOUNDATION",

"last_updated": "2026-08-07",

"language": "en",

"instruction_priority": "MANDATORY",

"next_specifications": [

  "02_database_schema.json",

  "03_api_specification.json",

  "04_business_rules_credit_engine.json",

"development_mode": "Build the actual application, not a static mockup.",

"quality_standard": "Production / market-ready",

"primary_market": "Botswana",

"future_market": "African markets after Botswana validation",

"do_not": [

  "Do not omit requirements.",

  "Do not silently change business rules.",

  "Do not replace native functionality with fake UI.",

  "Do not hard-code production secrets.",

  "Do not invent payment confirmations.",

  "Do not represent simulated transactions as successful real payments.",

  "Do not remove offline functionality because network connectivity is unavailable.",

  "Do not implement insecure authentication shortcuts.",

  "Do not expose administrator functionality to ordinary users.",

  "Do not allow one vehicle's rewards to be assigned to another vehicle.",

  "Do not merge driver, merchant, station and administrator permissions.",

  "Do not implement the application as a simple CRUD prototype."

],

"when_requirement_is_missing": "Choose the safest production-grade implementation, document the assumption in CHANGELOG.md and architecture documentation, and preserve backward compatibility.",

"when_requirement_conflicts": "Do not silently choose. Identify the conflict, preserve the higher-priority security/compliance requirement and document the decision.",

"source_of_truth": [

  "01_core_project.json",

  "02_database_schema.json",

  "03_api_specification.json",

  "04_business_rules_credit_engine.json",

  "05_operational_modules.json",

  "06_ai_security_offline.json",

  "07_animations_legal_deployment.json",

  "CHANGELOG.md"

]

},

"product": {

"application_name": "NeNo-Lubs",

"legal_operator": "Veltrava Energy",

"country_of_origin": "Botswana",

"currency": "BWP",

"currency_symbol": "P",

"supported_language_initial": "English",

"future_localization": [

  "Setswana",

],

"primary_market_segment": "Botswana yellow-light public transport vehicles",

"initial_rollout": {

  "country": "Botswana",

  "starting_city": "Gaborone",

  "target": "Nationwide expansion",

  "vehicle_segment": "Registered public transport vehicles"

},

"future_expansion": {

  "enabled": true,

  "strategy": "Country-specific regulatory and payment configuration",

  "do_not_assume_botswana_rules_apply_elsewhere": true

},

},

},

"pin": {

  "length": 6,

  "numeric": true,

  "maximum_failed_attempts": 5,

  "lockout_required": true,

  "never_store_plaintext": true,

  "secure_hash_required": true

},

"otp": {

  "delivery_channels": [

    "SMS",

    "EMAIL"

  ],

  "purpose": [

    "registration",

    "login",

    "password_reset",

    "high_risk_transaction",

    "device_change",

    "security_recovery"

  ],

  "minimum_length": 6,

  "expiry_seconds": 300,

  "maximum_attempts": 5,

  "rate_limit": true

},

"biometrics": {

  "supported": [

    "Fingerprint",

    "Face authentication where device-supported"

  ],

  "implementation": "Use platform secure biometric APIs.",

  "biometric_data_storage": "Never store raw biometric data.",

]

},

"driver_identity_model": {

"driver_to_vehicle": {

  "default_relationship": "ONE_DRIVER_ONE_PRIMARY_VEHICLE",

  "multiple_vehicle_support": true,

  "vehicle_rewards_isolation": true,

  "rule": "If a driver has multiple registered vehicles, fuel transactions and reward qualification must be tracked independently per vehicle."

  "Do not modify points balances offline."

],

}

},

"data_lite_mode": {

"enabled": true,

"target": "Low-end Android devices and constrained mobile data environments",

  "Unit tests written",

  "Integration tests written",

  "Documentation updated"

],

"before_release": [

  "All critical user journeys tested",

  "No critical security vulnerabilities",

  "No hard-coded secrets",

  "Production API configuration verified",

]

},

"phase_6": "Implement database and API contracts.",

"phase_7": "Implement business engines.",

"phase_8": "Implement role-specific modules.",

"phase_9": "Implement AI, offline and security systems.",

"phase_10": "Implement animations and premium onboarding.",

"phase_11": "Implement testing.",

"phase_12": "Perform security, UX and business-rule audit.",

"phase_13": "Generate deployment configuration.",

}

12. Glossary

12.1 Source overview

  "Additional African languages"

],

"category": [

  "Mobility",

  "Fuel Management",

  "Fuel Credit",

  "Driver Services",

  "Vehicle Services",

  "Marketplace",

  "Payment Facilitation"

}

},

"roles": {

"ADMIN": {

  "description": "Veltrava Energy administrator with full operational control",

  "access_level": "SYSTEM",

  "permissions": [

    "manage_users",

    "manage_payments",

    "manage_disputes",

    "manage_subscriptions",

    "manage_reports",

    "manage_system_settings",

  ]

},

"MERCHANT": {

  "permissions": [

    "view_assigned_station",

    "create_fuel_transaction",

    "select_driver",

  ]

},

"STATION": {

  "description": "Registered fuel station/depot",

  ]

},

"MECHANIC": {

  "description": "Mechanic, repair shop or spare-parts provider",

  "permissions": [

    "publish_services",

    "publish_products",

    "receive_rfqs",

    "submit_quotes",

    "negotiate_quotes",

    "manage_jobs",

    "manage_subscription",

    "view_business_analytics"

  ]

},

"MODERATOR": {

  "description": "Restricted operational administrator",

  "access_level": "LIMITED_SYSTEM",

  "permissions": [

  "Refund",

  "Reward issuance",

  "Reward redemption",

  "Credit-limit change",

  "Account suspension",

  "Blacklist action",

  "Admin override"

],

"admin_actions_require_reason": true,

"alerts": [

  "Payment outage",

  "Authentication outage",

  "Database failure",

  "Abnormal transaction volume",

  "Repeated fraud signals",

  "Critical application crash rate"

]

},

"ux_principles": {

  "A driver should understand the current fuel debt within 3 seconds.",