Waze (subsidiary of Google) pioneered community-driven GPS navigation. Its core competitive moat is crowdsourced, low-latency road intelligence combined with volunteer decentralized governance. Recent updates have focused on proactive driver safety, AI-driven crash history, and infrastructure warnings.

Introducing a live feature allowing users to report bad or reckless drivers in South Africa invokes three critical statutes and common-law principles. RoadGuard SA was architected from the ground up to guarantee strict statutory compliance.

The working prototype in /uploads/roadwatch/ is fully functional and built strictly to the stack rules (PHP 8 + MySQL PDO + Bootstrap 5 + Leaflet.js).

To transition from the current web demonstration to a production-grade native Android application, adhere to the following architectural stack and system design:

Below are the canonical Kotlin architectural components for the native Android application:

A. Android Background Location Service (FusedLocationProviderClient)

Ensures proximity detection runs continuously with persistent notification:

// LocationService.kt
package com.roadguard.sa.service

import android.app.*
import android.content.Intent
import android.os.IBinder
import androidx.core.app.NotificationCompat
import com.google.android.gms.location.*

class RoadGuardLocationService : Service() {
    private lateinit var fusedLocationClient: FusedLocationProviderClient
    private lateinit var locationCallback: LocationCallback

    override fun onCreate() {
        super.onCreate()
        fusedLocationClient = LocationServices.getFusedLocationProviderClient(this)

        val locationRequest = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 3000)
            .setMinUpdateIntervalMillis(1500)
            .build()

        locationCallback = object : LocationCallback() {
            override fun onLocationResult(result: LocationResult) {
                result.lastLocation?.let { location ->
                    // Broadcast location to Hazard Proximity Radar
                    HazardRadarManager.evaluateProximity(location.latitude, location.longitude)
                }
            }
        }

        startForeground(1001, buildNotification())
        fusedLocationClient.requestLocationUpdates(locationRequest, locationCallback, mainLooper)
    }

    private fun buildNotification(): Notification {
        val channelId = "roadguard_radar"
        val channel = NotificationChannel(channelId, "RoadGuard Radar", NotificationManager.IMPORTANCE_LOW)
        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)

        return NotificationCompat.Builder(this, channelId)
            .setContentTitle("RoadGuard Active")
            .setContentText("Monitoring hazards & reckless driver danger zones (POPIA Guard Engaged)")
            .setSmallIcon(android.R.drawable.ic_menu_compass)
            .build()
    }

    override fun onBind(intent: Intent?): IBinder? = null
}

B. Hands-Free Voice Command Recognition (Regulation 308A Compliance)

Speech recognition handler for hands-free driver hazard submission:

// VoiceCommandManager.kt
package com.roadguard.sa.voice

import android.content.Context
import android.content.Intent
import android.os.Bundle
import android.speech.RecognitionListener
import android.speech.RecognizerIntent
import android.speech.SpeechRecognizer
import android.speech.tts.TextToSpeech
import java.util.Locale

class VoiceCommandManager(private val context: Context) : RecognitionListener {
    private val speechRecognizer: SpeechRecognizer = SpeechRecognizer.createSpeechRecognizer(context)
    private var tts: TextToSpeech? = null

    init {
        speechRecognizer.setRecognitionListener(this)
        tts = TextToSpeech(context) { status ->
            if (status == TextToSpeech.SUCCESS) {
                tts?.language = Locale("en", "ZA")
            }
        }
    }

    fun startListening() {
        val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
            putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
            putExtra(RecognizerIntent.EXTRA_LANGUAGE, "en-ZA")
        }
        speechRecognizer.startListening(intent)
    }

    override fun onResults(results: Bundle?) {
        val matches = results?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
        val text = matches?.firstOrNull()?.lowercase() ?: return

        when {
            text.contains("reckless") || text.contains("bad driver") -> {
                speak("Reckless driver reported. Broadcasting anonymized hazard zone.")
                HazardRepository.submitVoiceReport("reckless", "Erratic / Aggressive Driving")
            }
            text.contains("police") || text.contains("trap") -> {
                speak("Speed trap reported.")
                HazardRepository.submitVoiceReport("police", "Speed Radar Enforcement")
            }
            text.contains("still there") -> {
                speak("Hazard confirmed. Thank you.")
                HazardRepository.verifyActiveHazard(isStillThere = true)
            }
        }
    }

    private fun speak(message: String) {
        tts?.speak(message, TextToSpeech.QUEUE_FLUSH, null, "roadguard_voice")
    }

    // Unused RecognitionListener overrides omitted for brevity
    override fun onReadyForSpeech(params: Bundle?) {}
    override fun onBeginningOfSpeech() {}
    override fun onRmsChanged(rmsdB: Float) {}
    override fun onBufferReceived(buffer: ByteArray?) {}
    override fun onEndOfSpeech() {}
    override fun onError(error: Int) {}
    override fun onPartialResults(partialResults: Bundle?) {}
    override fun onEvent(eventType: Int, params: Bundle?) {}
}

C. POPIA Client-Side Plate Masking & Cryptographic Hasher

Ensures raw registration plates never leave the Android device in plaintext:

// PopiaSecurityHelper.kt
package com.roadguard.sa.security

import java.security.MessageDigest

object PopiaSecurityHelper {
    private const val APP_SALT = "roadguard_sa_secure_salt_2026"

    /**
     * Masks registration plate for public display (e.g. "CA 123-456" -> "CA 123***")
     */
    fun maskPlate(rawPlate: String): String {
        val clean = rawPlate.replace("[^A-Za-z0-9]".toRegex(), "").uppercase()
        if (clean.length <= 3) return clean + "***"
        val visibleCount = minOf(4, clean.length / 2 + 1)
        return clean.substring(0, visibleCount) + "***"
    }

    /**
     * Generates irreversible SHA-256 hash for internal duplicate detection
     */
    fun hashPlate(rawPlate: String): String {
        val clean = rawPlate.replace("[^A-Za-z0-9]".toRegex(), "").uppercase()
        val saltedInput = "${clean}_$APP_SALT"
        val bytes = MessageDigest.getInstance("SHA-256").digest(saltedInput.toByteArray())
        return bytes.joinToString("") { "%02x".format(it) }
    }
}