🌍 MtaaLink (East Africa Hyperlocal & Transit Platform)

Kuunganisha Mtaa — Connecting East African neighborhoods, biasharas, matatu stages, boda sheds, and 24/7 lifesaving public services.

---

🚀 Overview

MtaaLink is a full-stack monolithic Laravel web application designed specifically to solve geographic, logistical, transit, and civic emergency challenges in Kenya and East Africa.

Unlike traditional mapping platforms that rely heavily on formal street numbers, MtaaLink is built around informal landmark micro-addressing, crowdsourced neighborhood intelligence, public transit navigation, and lifesaving 24/7 service discovery.

---

🌟 The Three Core Pillars

1. 🛒 MtaaPin (Biashara & Landmark Micro-Addressing)

• Landmark-Based Directions: Find places through contextual local cues ("Opposite Quickmart, behind Total petrol station, 2nd floor above Kinyozi").
• M-Pesa Commerce Hub: Instant one-tap copy for M-Pesa Buy Goods Till and Paybill numbers.
• Direct WhatsApp Chat: 1-click WhatsApp messaging prefilled with local place inquiries.
• Shareable Mtaa Code: Generates short digital codes (e.g. ML-7K8219) for easy sharing with delivery riders and friends.

2. 🚌 Matatu & Boda Stage Navigator

• Stage Directory: Mapped Matatu termini, pick-up stages, and Boda Boda sheds.
• Route & SACCO Intelligence: Search stages by destination ("Find stages going to Thika, Roysambu, Upper Hill"), with operating SACCOs (Super Metro, 2NK, Forward, Citi Hoppa, KBS, etc.).
• Crowd-Sourced Fares: Community-updated normal vs. rush hour fare ranges.

3. 🏥 Huduma & Emergency Explorer (Kenya Feature-Flagged)

• 24/7 Lifesaving Hotspots: 24-hour open pharmacies & chemists, SHA/NHIF accredited hospitals, clean reverse osmosis water ATMs, and police stations.
• Speed Dial Hotlines: One-tap emergency calling (999, 112, 1199).
• Feature Flag Control: Enabled via config('features.huduma_kenya').

---

🤝 Community Crowdsourcing Engine

Almost all data on MtaaLink is community-driven:

• "Ongeza Mahali" Wizard: Mobile-friendly 2-step submission with an interactive Leaflet map pin-picker and GPS "Here I Am" locator.
• "Thibitisha" Trust Scoring: 1-tap community validations (👍 Confirm Active & Accurate, 💵 Update Today's Fare, ⚠️ Report Closed) that increment the place's trust score and unlock the "Mtaa Verified ⭐" badge.

---

🎨 Design System: Theme 1 — Safari Green 🌿

The UI uses a civic-focused color system tailored for East African landscapes, transit energy, and emergency readiness:

Category / Feature	Color Code	Accent Meaning
Primary (Safari Green)	#2E7D32	Trust, neighborhood growth, sustainability
Secondary / Matatu	#F9A825	Matatu stages, routes, transit energy
Boda Boda Sheds	#F97316	Motorcycle bases & parcel stages
Hospitals & Afya	#1976D2	Civic healthcare & SHA/NHIF clinics
24/7 Chemists	#10B981	Night pharmacies & prescription health
Clean Water ATMs	#06B6D4	Water points & borehole dispensers
Police & Emergency	#D32F2F	Emergency hotlines, security posts
M-Pesa Actions	#00A651	Direct Till & Paybill copy actions
WhatsApp Chat	#25D366	Direct merchant communication

---

🛠️ Tech Stack & Infrastructure

• Framework: Laravel 11 (Monolith Architecture with Blade Views)
• PHP: ^8.2
• Database: MySQL (Spatial Coordinate Indexing & Relational Metadata)
• Cache Store: Redis (PlaceCacheService for geospatial radius query caching & instant eviction)
• Map & Geospatial: Leaflet.js + OpenStreetMap (CartoDB Positron tiles)
• Testing: Pest PHP & PHPUnit with Isolated SQLite In-Memory Database (:memory:)

---

📦 Installation & Setup

1. Clone & Install Dependencies

git clone <repository-url>
cd location_api
composer install

2. Environment Configuration

Copy .env.example to create .env:

cp .env.example .env
php artisan key:generate

Configure your MySQL and Redis credentials in .env:

APP_NAME=MtaaLink
APP_ENV=local
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mtaalink
DB_USERNAME=root
DB_PASSWORD=

CACHE_STORE=redis
CACHE_DRIVER=redis
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Regional Feature Flags
FEATURE_HUDUMA_KENYA=true
FEATURE_CROWDSOURCE_AUTO_PUBLISH=true
VERIFICATION_THRESHOLD=3

3. Run Migrations & Seed Sample Data

php artisan migrate --seed

Seeds rich realistic data across Nairobi (CBD, Westlands, Roysambu, Kibera), Mombasa, Kisumu, and Nakuru.

4. Start Development Server

php artisan serve

Open your browser at http://127.0.0.1:8000.

---

🧪 Running Automated Tests

Tests are configured in phpunit.xml to run against in-memory SQLite (DB_DATABASE=:memory:, CACHE_STORE=array). Tests never touch or modify your MySQL database:

php artisan test

Or run via Pest:

./vendor/bin/pest

---

🛣️ Web & API Routes Summary

Web Routes

Method	URI	Description
GET	/	Home landing page with hero search, stats & featured places
GET	/explore	Split-screen interactive Leaflet map & filterable directory
GET	/places/{slug}	Detailed place view with landmark card, M-Pesa till copy & WhatsApp chat
GET	/ongeza	"Ongeza Mahali" 2-step map pin-drop & community submission wizard (supports custom "Other" categories)
POST	/ongeza	Stores new place, creates custom categories if specified & purges Redis cache
POST	/places/{id}/thibitisha	1-tap community trust verification vote, author confirmation & live fare update
GET	/transit	Matatu & Boda stage navigator by destination and SACCO
GET	/huduma	24/7 Emergency & essential services (Kenya feature-flagged)
GET	/login / /register	Session web authentication for contributors and merchants

API Routes (30-Day Tokens with Refreshing)

Method	URI	Description
POST	/api/register	Register new user and receive 30-day API token
POST	/api/login	Authenticate with email/password and receive 30-day API token
POST	/api/refresh-token	Refresh active or expired token for an additional 30 days (Authorization: Bearer <token> or body token)
GET	/api/profile	Protected user profile endpoint (auth.token middleware)

---

📄 License

This project is open-source software licensed under the MIT license.