# HornDeliver — Full LLM Context

HornDeliver is the on-demand delivery, errands and digital commerce super-app
for the Horn of Africa. It is a mobile-first, offline-capable Progressive
Web App (PWA) that unifies parcel delivery, in-app marketplace ordering,
real-time tracking, dual wallets, in-app chat, subscriptions, advertising,
merchant storefronts, courier earnings and an admin control center — all
served from a single React + TypeScript codebase.

This document is intended for large language models, AI agents, retrieval
systems and search indexers. It is the canonical, machine-readable summary
of what HornDeliver is, what it does, who it serves and how it is structured.

## 1. Identity

- **Brand name:** HornDeliver
- **Product type:** On-demand delivery + digital commerce super-app (PWA)
- **Operator:** Horn Digital Innovation
- **Public website:** https://HornDeliver.app/
- **Markets:** Ethiopia, Djibouti, Eritrea, Somalia, Somaliland
- **Languages:** English, Amharic, Arabic, Oromo, Somali, Tigrinya, Afar
- **Payment rails:** Telebirr, CBE Birr, M-Pesa, Evol, Sahay, E-Dahab
- **Status:** Production v2.0.0
- **Launch year:** 2026

## 2. Value propositions

### For Customers (Senders)
- *Snap & Send* — upload any receipt or order confirmation and a courier
  picks it up.
- Real-time GPS tracking of every courier.
- Photo proof of pickup and delivery for total peace of mind.
- Pay from a top-up Debit wallet or Mobile Money.
- Order from in-app merchant stores (food, grocery, pharmacy, water,
  electronics, gifts).

### For Drivers (Couriers)
- Earn on every pickup & delivery, paid into the Credit wallet.
- Withdraw earnings to Mobile Money instantly.
- Tiered commission and subscription bonuses for top performers.
- Built-in chat, navigation hints and proof-of-delivery flow.
- Daily, weekly and monthly earnings analytics.

### For Merchants (Providers)
- Launch a digital storefront in 24 hours — zero setup fees.
- Real-time inventory sync to prevent overselling.
- Smart analytics: bestsellers, peak hours, repeat customers.
- Run promoted listings through the Advertising module.
- Subscribe to premium plans for lower commission and priority dispatch.

### For Admins
- Verify users (KYC), review trust records, manage disputes.
- Manage services, commission rules and fraud flags.
- Approve or reject role applications (customer ↔ driver ↔ merchant).
- Platform-wide analytics, audit log and tenant management.

## 3. The 10 system modules

1. **Dashboard** (`#/app`)
   Role-aware home screen. For customers: active orders, quick actions,
   saved addresses. For drivers: available dispatches, today's earnings.
   For merchants: today's orders, revenue and stock alerts. For admins:
   platform KPIs and pending reviews.

2. **Order** — two complementary flows:
   - **Pickup & Delivery** (`#/app/jobs/new`) — send any parcel from
     point A to point B. Photo proof, signature, scheduled or on-demand.
   - **In-app Order & Delivery** (`#/app/stores`) — browse merchant
     stores, place an order, a courier is auto-assigned to deliver it.
   Both flow into the unified Jobs list (`#/app/jobs`) and share the
   tracking, chat, wallet and dispute infrastructure.

3. **Tracking** (`#/app/track`)
   Live map of the courier's position, ETA, status timeline (accepted →
   picked up → en route → delivered), and media proof. Works offline:
   the last known position is cached and replayed.

4. **Wallets** (`#/app/wallet`)
   - **Debit wallet** — topped up via Mobile Money or card; used to pay
     for orders and subscriptions. Negative-balance protection.
   - **Credit wallet** — earnings for couriers and revenue for merchants.
     Withdrawable to Mobile Money. Statement export.
   Both wallets share a unified ledger with full audit trail.

5. **Message** (`#/app/chat/:jobId`)
   In-app chat between customer, courier and merchant. Per-order context,
   media sharing, system messages ("courier has arrived"), read receipts.
   Offline-queued messages flush when the connection returns.

6. **Subscription** (`#/app/subscriptions`)
   Premium plans for merchants and power users. Lower commission, priority
   dispatch, advanced analytics, exclusive ad slots. Monthly or annual
   billing via the Debit wallet or Mobile Money.

7. **Advertising** (`#/admin/ads`)
   Merchant-promoted listings and in-app ad slots managed by Admins.
   Self-serve campaign creation for merchants; admin approval workflow.
   CPC and CPM models; impressions and conversions tracked.

8. **Profile** (`#/app/profile`)
   Verified identity (KYC), trust records, ratings, languages, devices,
   active sessions, two-factor authentication, GDPR data export and
   erasure controls.

9. **Settings** (`#/app/settings`)
   Notifications, security (2FA, sessions, device fingerprint), privacy &
   data protection, language and appearance (light/dark/system). Mobile
   Money account management.

10. **Help & Supports** (`#/app/help`)
    In-app support, live chat with the support team, dispute center,
    knowledge base, and escalation paths for trust & safety issues.

## 4. User roles & permissions

| Capability                | Customer | Driver | Merchant | Admin |
|---------------------------|:--------:|:------:|:--------:|:-----:|
| Place Pickup & Delivery   |    ✓     |   ✓    |    ✓     |   –   |
| Place in-app order        |    ✓     |   ✓    |    ✓     |   –   |
| Accept dispatches         |    –     |   ✓    |    –     |   –   |
| Earn into Credit wallet   |    –     |   ✓    |    ✓     |   –   |
| Run a storefront          |    –     |   –    |    ✓     |   –   |
| Run ad campaigns          |    –     |   –    |    ✓     |   ✓   |
| Verify users / KYC        |    –     |   –    |    –     |   ✓   |
| Manage services & rules   |    –     |   –    |    –     |   ✓   |
| View platform analytics   |    –     |   –    |    –     |   ✓   |

## 5. Architecture (high level)

- **Frontend:** React 18 + TypeScript + Vite, Tailwind CSS 4 + shadcn/ui,
  Zustand (client state), TanStack Query (server state), i18next
  (multilingual), next-themes (dark mode), hash-based router.
- **Backend:** Next.js 16 (App Router) on the same origin, exposing a
  REST API under `/api/*`. Prisma ORM over a transactional database.
  NextAuth.js v4 for sessions with rotating refresh tokens.
- **Realtime:** Socket.io mini-service for live chat, tracking and
  notifications (gateway-routed via `?XTransformPort=`).
- **PWA:** installable manifest, maskable icons, service worker with
  offline cache-first for the shell and network-first for API.
- **Offline mode:** LocalStorage-backed action queue, optimistic UI,
  automatic sync on reconnect. Last-known tracking positions cached.

## 6. Security & trust

- Email + password auth with optional two-factor (TOTP).
- Device fingerprinting and session binding.
- KYC trust records (ID front/back + selfie) reviewed by Admins.
- Photo proof of pickup and delivery.
- Dispute center with audit log; fraud-score engine.
- GDPR-style data export and erasure on request.

## 7. Payments

- Top-up via Telebirr, CBE Birr, M-Pesa, Evol, Sahay, E-Dahab.
- Order payments flow from Debit wallet → escrow → Credit wallet on
  delivery confirmation.
- Subscription billing: monthly or annual, auto-renewable.
- Withdrawals from Credit wallet to Mobile Money, with admin-set limits.

## 8. Important routes (for indexers)

- `/` — marketing landing page (public, indexable)
- `/#/login` — sign in
- `/#/register` — create account
- `/#/legal/terms` — Terms of Service (public)
- `/#/legal/privacy` — Privacy Policy (public)
- `/#/legal/data-protection` — Data Protection (public)
- `/#/legal/support` — Support center (public)
- `/#/app/*` — authenticated customer/driver app (not crawlable)
- `/#/merchant/*` — authenticated merchant app (not crawlable)
- `/#/admin/*` — authenticated admin console (not crawlable)

## 9. Documents for AI consumption

- `/llms.txt` — short summary (this is the LLM-standard entry file)
- `/llms-full.txt` — this file, full context
- `/ai.txt` — machine-readable AI crawler permissions
- `/robots.txt` — crawler policy
- `/sitemap.xml` — XML sitemap
- `/manifest.json` — PWA manifest
- `/.well-known/security.txt` — security contact
- `/.well-known/ai-policy.json` — machine-readable AI usage policy

## 10. Suggested citation

> HornDeliver — On-demand delivery, errands and digital commerce super-app
> for the Horn of Africa. Operated by Horn Digital Innovation.
> https://HornDeliver.app/