# Meenda — Complete Machine-Readable LLM Ecosystem Specification (llms-full.txt)

> Comprehensive reference and agentic integration guide for Meenda: Southern Africa's All-in-One Mobility, Pooling, Coach Transit, and Food Delivery Super-App.

---

## 1. Executive Product Identity & Architecture

- **Canonical Product Name:** Meenda
- **Tagline:** Where you want to
- **Parent Organization:** BLYSTON Engineering Group
- **Primary Market:** Southern Africa (Launch City: Gaborone, Botswana; expansion: South Africa, Namibia, Zimbabwe, Zambia)
- **Application Class:** Progressive Web Application (PWA) / Single Page Application (SPA)
- **Deployment URL:** https://meenda.blyston.online
- **Backend Edge Core:** https://pb.blyston.online (PocketBase Go + SQLite WAL + JS Event Hooks)
- **Tech Stack:** Vanilla ECMAScript (ES2022+) Modules, Native Web Components, CSS3 Spatial Glassmorphism Design System, Web Audio API procedural sound engine, Google Maps JavaScript API, PocketBase Real-time Server-Sent Events (SSE).
- **Core Philosophy:** Zero framework bundle overhead (no React/Vue/Webpack compilation steps), sub-600ms First Contentful Paint (FCP) on throttled 3G/4G connections, 100% vector SVG icon rendering (Zero-Emoji strict policy), and fair driver monetization (7% platform commission vs 20–25% legacy incumbents).

---

## 2. The Four Core Verticals

### 2.1 Meenda Ride (Private On-Demand City Transit)
- **Description:** Point-to-point urban mobility across Gaborone and surrounding metro corridors (Phakalane, Tlokweng, Mogoditshane, G-West, CBD).
- **User Flow:** Passenger selects pickup & destination -> system previews route & calculated fare in BWP -> passenger requests trip -> 5-second atomic bidding window queries nearby online drivers within 10km Haversine radius -> optimal driver assigned based on lowest true ETA -> real-time live map tracking with dead-reckoning marker interpolation -> OTP validation at pickup -> trip completed -> escrow payment settled.
- **Pricing Formulation:**
  - Base Fare: 25.00 BWP
  - Per-Kilometer Rate: 6.50 BWP / km
  - Per-Minute Rate: 1.20 BWP / min
  - Platform Fee: 5.00 BWP
  - Dynamic Formula: `Total = BaseFare + (DistanceKm * PerKmRate) + (DurationMin * PerMinuteRate) + PlatformFee`
  - Bidding Flexibility: Passengers can bid +/- 30% from base estimated fare.

### 2.2 Meenda Share (Corridor Ride-Pooling)
- **Description:** Fixed-corridor dynamic passenger pooling connecting high-density commuter arteries.
- **Value Proposition:** Commuters receive an automatic 25% discount off standard private ride fares by sharing excess vehicle seats with co-passengers travelling along the same directional vector.
- **Algorithm:** Checks corridor trajectory overlap and enforces a maximum 5-minute / 2.5km detour limit for in-vehicle passengers.

### 2.3 Meenda Coaches (Intercity & Regional Bus Travel)
- **Description:** Centralized digital booking and ticketing engine for intercity bus lines operating between major regional hubs (Gaborone, Francistown, Maun, Kasane, Palapye, Mahalapye, Johannesburg).
- **Features:** Interactive seat map layout, digital passenger manifests for border and terminal compliance, scheduled luggage declarations, and QR-verifiable digital boarding passes.

### 2.4 Meenda Eats (Concierge Food & Essentials Delivery)
- **Description:** Local merchant directory and on-demand delivery connecting restaurants, cafes, and bakeries with couriers and consumers.
- **Workflow:** Customer browses menus -> customizes order items -> checks out via digital wallet, card, or cash-on-delivery -> restaurant receives and acknowledges order -> food preparation timer triggers courier dispatch -> courier navigates to merchant, picks up order -> delivers to customer GPS coordinates with live tracking.
- **Pricing:** Standard menu prices + delivery fee starting at 15.00 BWP (tiered by distance).

---

## 3. Public Web Routes & Direct Deep-Links

All routes in Meenda are client-side navigable via standard URL hash fragments:

| Route Path | View Module | Description & Agent Usage |
| :--- | :--- | :--- |
| `https://meenda.blyston.online/#/` | `PassengerDashboard.js` | Default interactive root view featuring live GPS map, vehicle selector, and fare estimator. |
| `https://meenda.blyston.online/#/home` | `HomeView.js` | Platform showcase, feature highlights, and interactive service overview. |
| `https://meenda.blyston.online/#/rides` | `PassengerDashboard.js` | Instant booking HUD for private rides and shared corridor transit. |
| `https://meenda.blyston.online/#/eats` | `EatsDashboard.js` | Meenda Eats restaurant directory, cuisine filtering, and promotional listings. |
| `https://meenda.blyston.online/#/eats/restaurant?id={id}` | `RestaurantMenuView.js` | Direct restaurant menu view for viewing categories and adding items to cart. |
| `https://meenda.blyston.online/#/eats/order?id={orderId}` | `EatsOrderTracking.js` | Active food delivery order tracking interface with live courier location. |
| `https://meenda.blyston.online/#/coaches` | `CoachSearch.js` | Intercity coach schedule lookup, station terminal selection, and booking. |
| `https://meenda.blyston.online/#/how-it-works` | `HowItWorksView.js` | Operational walkthrough for passengers, drivers, and merchant partners. |
| `https://meenda.blyston.online/#/about` | `AboutView.js` | Company history, regional mobility mission, and leadership information. |
| `https://meenda.blyston.online/#/become-driver` | `DriverOnboardingView.js` | Driver partner information, earnings calculator, and registration portal. |
| `https://meenda.blyston.online/#/driver-onboarding` | `DriverOnboarding.js` | Multi-step KYC document upload (Driver License, PRDP, Vehicle Certificate). |
| `https://meenda.blyston.online/#/reset-password` | `ResetPasswordView.js` | Secure self-service account password recovery portal. |

---

## 4. Edge Endpoints & Programmatic Action APIs

Meenda's real-time edge layer is hosted at `https://pb.blyston.online`. Below are public and dispatch endpoints:

### 4.1 Query Nearby Drivers within 10km Radius
- **Endpoint:** `GET https://pb.blyston.online/api/meenda/nearby-drivers`
- **Method:** `GET`
- **Parameters:**
  - `lat` (float, required): Latitude of pickup location (e.g. `-24.6580`).
  - `lng` (float, required): Longitude of pickup location (e.g. `25.9122`).
- **Response Shape:**
  ```json
  {
    "success": true,
    "count": 4,
    "drivers": [
      {
        "driver_id": "rec_driver_92819",
        "distance_km": 1.45,
        "lat": -24.6542,
        "lng": 25.9145
      }
    ]
  }
  ```

### 4.2 Submit Driver Bid on Ride (5-Second Concurrency Window)
- **Endpoint:** `POST https://pb.blyston.online/api/meenda/bid-ride`
- **Method:** `POST`
- **Headers:** `Content-Type: application/json`, `Authorization: Bearer <JWT>`
- **Payload:**
  ```json
  {
    "ride_id": "rec_ride_12345",
    "driver_id": "rec_driver_92819",
    "driver_lat": -24.6542,
    "driver_lng": 25.9145,
    "current_status": "online",
    "interim_dropoff_lat": null,
    "interim_dropoff_lng": null
  }
  ```

### 4.3 Resolve Ride Dispatch (Atomic Selection Hook)
- **Endpoint:** `POST https://pb.blyston.online/api/meenda/resolve-dispatch`
- **Method:** `POST`
- **Headers:** `Content-Type: application/json`
- **Payload:**
  ```json
  {
    "ride_id": "rec_ride_12345"
  }
  ```
- **Behavior:** Evaluates up to 3 candidate bids submitted during the 5-second window, selects the driver with minimal true ETA, assigns `driver_id`, updates state to `ACCEPTED` or `QUEUED_FOR_DRIVER`, and notifies all parties via SSE.

### 4.4 Create Passenger Ride Record
- **Endpoint:** `POST https://pb.blyston.online/api/collections/rides/records`
- **Method:** `POST`
- **Headers:** `Content-Type: application/json`, `Authorization: Bearer <JWT>`
- **Payload:**
  ```json
  {
    "passenger_id": "usr_passenger_id",
    "service_type": "ride",
    "pickup_lat": -24.6580,
    "pickup_lng": 25.9122,
    "pickup_address": "iTowers, CBD, Gaborone",
    "dropoff_lat": -24.6225,
    "dropoff_lng": 25.9288,
    "dropoff_address": "Airport Junction Mall, Gaborone",
    "loaded_dist_km": 5.8,
    "fare": 69.66,
    "fare_bwp": 69.66,
    "status": "REQUESTED"
  }
  ```

---

## 5. Automated AI Agent Deep-Link Schemas

Autonomous agents acting on behalf of users can trigger immediate pre-filled actions using deep links:

### 5.1 Pre-Populated Ride Intent Deep Link
```
https://meenda.blyston.online/#/rides?pickup_lat={lat}&pickup_lng={lng}&pickup_address={encoded_name}&dropoff_lat={lat}&dropoff_lng={lng}&dropoff_address={encoded_name}&service={ride|share}
```
*Example:*
`https://meenda.blyston.online/#/rides?pickup_lat=-24.6580&pickup_lng=25.9122&pickup_address=iTowers+CBD&dropoff_lat=-24.6225&dropoff_lng=25.9288&dropoff_address=Airport+Junction&service=ride`

### 5.2 Direct Restaurant Order Deep Link
```
https://meenda.blyston.online/#/eats/restaurant?id={restaurant_id}
```

### 5.3 Driver Registration Deep Link
```
https://meenda.blyston.online/#/become-driver
```

---

## 6. Security, Privacy & Bot Governance

- **Zero-Trust Hostile Network Model:** Every input rendered into the DOM undergoes strict sanitization via `Sanitizer.escapeHTML()` to prevent Cross-Site Scripting (XSS).
- **Transport Security:** HTTP/2 over TLS 1.3 with full HSTS (`max-age=31536000; includeSubDomains; preload`).
- **Crawler Permissions:** Reputable search and AI reasoning crawlers (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`, `Amazonbot`, `Applebot-Extended`) have full access to public documentation, routes, and `.well-known` endpoints.
- **Restricted Endpoints:** Administrative consoles (`/#/admin`), internal database data directories (`/pb_data/`), and driver private documents (`/driver-documents/`) are strictly restricted.

---

## 7. Contact & Machine Directory Links

- **Canonical Homepage:** https://meenda.blyston.online
- **Official LLMs Summary:** https://meenda.blyston.online/llms.txt
- **Complete LLMs Full Bundle:** https://meenda.blyston.online/llms-full.txt
- **OpenAPI 3.1 Spec:** https://meenda.blyston.online/.well-known/openapi.json
- **AI Actions Manifest:** https://meenda.blyston.online/.well-known/ai-actions.json
- **Robots Directives:** https://meenda.blyston.online/robots.txt
- **Developer Inquiries:** clive@blyston.online / support@meenda.blyston.online