# HornLogistics — Comprehensive Context for AI Agents

> This document provides deep, structured context about HornLogistics so that
> AI assistants, agents, and indexing systems can accurately describe, summarise,
> and reason about the platform. It follows the `llms-full.txt` convention.

---

## 1. What HornLogistics is

HornLogistics is a **digital logistics and freight coordination platform** built for the **Horn of Africa**, with a primary focus on the **Djibouti → Ethiopia containerised-freight corridor**. It replaces paper-based, phone-call-driven freight coordination with a single web and mobile (PWA) application that connects every actor in the supply chain:

- **Shippers (Agents)** — companies or individuals who need to move a container from the Port of Djibouti to an Ethiopian dry port. They post loads with commodity, weight, container size, origin/destination, and an offered rate.
- **Carriers** — trucking companies that hold a fleet of trucks. They browse the load board, book loads, assign drivers, and manage their fleet.
- **Drivers** — individuals employed by carriers. They receive assigned trips, view turn-by-turn navigation, capture proof-of-delivery, and sign electronic waybills.
- **Customs brokers** — handle customs declarations at borders (Semera border crossing).
- **Admins / Super-admins** — HornLogistics staff who verify user identities (gov-ID + selfie), approve companies, manage partner API keys, and oversee the platform.

The platform launched its **v1.0 in August 2026**. Three modules — **in-app Chat**, **rate Negotiation**, and the **Partner REST API** — are built but intentionally disabled in v1.0 and will be enabled in v2.0.

---

## 2. The freight corridor

| Node | Role | Coordinates |
|---|---|---|
| Port of Djibouti (Doraleh) | Origin seaport, container terminal | 11.588° N, 43.1456° E |
| Djibouti border (Galafi / Loyada) | Border crossing | ~11.5° N |
| Semera (Ethiopia) | First Ethiopian dry port / customs | 11.6° N, 41.0° E |
| Dire Dawa | Inland transit hub | 9.59° N, 41.86° E |
| Modjo Dry Port | Major Ethiopian inland container depot | 8.4° N, 39.1° E |
| Kality | Southern Addis logistics zone | 8.9° N, 38.8° E |
| Addis Ababa | Final destination market | 9.03° N, 38.74° E |

Container sizes supported: **20 ft** and **40 ft** ISO containers.

---

## 3. Core features (v1.0)

### Load board
Shippers post loads; carriers browse and book. Each load carries: container ID, size, weight, commodity, origin port (default Doraleh), destination dry port, ready time, offered rate (USD), and live status (`posted → reserved → booked → loaded → in_transit → delivered → cancelled`).

### Bookings
A carrier requests a load; the shipper confirms. Bookings carry a proposed pickup time, confirmation timestamp, and optional cancellation penalty.

### Electronic waybills (e-CMR)
Each booking generates a waybill with reference `HL-WB-YYYYMMDD-XXXXX`, origin/destination JSON, agreed rate, and three signature flags: carrier, driver, consignee acknowledgment. Waybills are PDF-exportable.

### Fleet management
Carriers register trucks (license plate, capacity tonnage, container sizes, GPS device ID, status). Drivers are assigned one truck each.

### Empty-leg announcements
A carrier returning empty from Addis Ababa to Djibouti can announce the empty leg with capacity, vehicle type, price-per-km, and expiry. Other actors can match and book the return trip at a discount — reducing deadhead mileage.

### Escrow payments
When a load is booked, an escrow hold is created (`hold → released_30pct → released_70pct → completed`). 30 % releases on pickup; 70 % on delivery proof. Supported payment methods: **cash**, **eBirr**, **D-Money**, **Waafi** (mobile money gateways of Djibouti / Ethiopia).

### Real-time tracking
Drivers' GPS locations stream over **Socket.IO** to a live map (MapLibre GL). Geofence events trigger notifications.

### Notifications
Multi-channel: **push** (Firebase Cloud Messaging), **email** (Resend), **SMS** (Twilio). Per-user preference toggles per category (load alerts, booking updates, payment alerts, trip updates, document alerts, system alerts, marketing) with quiet-hours windows.

### Verification & trust
Three-tier verification: `none → basic → full`. Basic = phone + email verified. Full = government ID + selfie verified. Admins manually review uploaded gov-ID and selfie photos before elevating a user to `full`.

### Ratings
After delivery, the shipper rates the carrier/driver (1–5 stars + comment). Aggregate rating averages are shown on profiles and feed trust signals.

### Multilingual UI (8 languages)
English, Français, العربية (Arabic, RTL), አማርኛ (Amharic), Soomaali, Afaan Oromoo, ትግርኛ (Tigrinya), and Afar (planned). The UI direction flips to RTL for Arabic.

### PWA
Installable on Android (Add to Home Screen) and iOS. Offline-capable with a service worker that caches the app shell and serves an offline fallback page.

---

## 4. Roles & permissions

| Role | Can do |
|---|---|
| `shipper` (Agent) | Post loads, book carriers, track, sign waybills, pay, rate |
| `carrier` | Browse load board, book loads, manage fleet & drivers, announce empty legs |
| `driver` | Receive assigned trips, navigate, sign waybills, capture POD |
| `customs_broker` | View customs declarations, sign off at borders |
| `admin` | Verify users, approve companies, manage partner keys |
| `super_admin` | Everything an admin can do + manage other admins |

A user may hold multiple roles; the active role is selectable after login.

---

## 5. Technology stack

| Layer | Technology |
|---|---|
| Backend API | Next.js 16 (App Router, Turbopack, standalone output) on Node.js |
| Frontend | Vite + React 19 (separate dev server, built into static assets for production) |
| Database | Prisma 6 ORM — SQLite in v1.0, migrating to PostgreSQL (Supabase) |
| Realtime | Socket.IO mini-service (port 3003) |
| Auth | Session-token (32-byte hex, DB-backed), phone + password, E.164 phone, OTP verification |
| CSRF | httpOnly cookie + `X-CSRF-Token` header |
| Push | Firebase Cloud Messaging (firebase-admin) |
| Email | Resend |
| SMS / OTP | Twilio |
| Maps | MapLibre GL |
| Charts | Recharts |
| UI | Tailwind CSS 4, shadcn/ui (New York style), Lucide icons |
| State | Zustand (client), TanStack Query (server) |
| Errors | Sentry (server + client + edge) |
| Logging | Pino (structured, JSON) |
| Validation | Zod |
| Deploy | Caddy reverse proxy → Next.js standalone server on port 3000 |

---

## 6. API surface

The backend exposes a REST API under `/api/*`. All non-auth endpoints require a session token (cookie or `Authorization: Bearer <token>`). The Partner API (v2.0) will use HMAC-signed API keys.

Public / indexable endpoints for AI agents:
- `GET /api/docs` — OpenAPI 3.1 spec (JSON)
- `GET /api/health` — service health probe (no auth)

Representative authenticated endpoints:
- `POST /api/auth/login`, `POST /api/auth/register`, `POST /api/auth/logout`, `GET /api/auth/me`
- `GET/POST /api/loads`, `GET/PUT/DELETE /api/loads/[id]`
- `GET/POST /api/bookings`, `GET/PUT /api/bookings/[id]`
- `GET/POST /api/waybills`, `GET /api/waybills/[id]/pdf`
- `GET/POST /api/fleet`, `GET/POST /api/fleet/trucks`
- `GET/POST /api/empty-legs`, `GET/PUT/DELETE /api/empty-legs/[id]`
- `GET/POST /api/payments`, `GET /api/payments/[id]/pdf`, `GET /api/payments/gateways`
- `GET/POST /api/wallet`
- `GET/POST /api/documents`, `GET /api/documents/[id]/pdf`, `POST /api/documents/[id]/sign`
- `GET/POST /api/notifications`, `GET/POST /api/notifications/preferences`, `POST /api/notifications/tokens`
- `GET/POST /api/ratings`
- `GET /api/stats`, `GET /api/matching`
- `GET /api/admin`, `GET /api/admin/pending-verifications`, `POST /api/admin/verify-gov-id`, `POST /api/admin/verify-selfie`
- `GET/POST /api/admin/partner-keys`, `GET/POST /api/admin/webhooks`

All mutation endpoints validate input with Zod and require a CSRF token. Rate limiting is applied per route class (`auth`, `chat_send`, `partner_api`, etc.).

---

## 7. Data model (summary)

Core entities: **User**, **Company**, **Truck**, **Driver**, **Load**, **Booking**, **Waybill**, **EmptyLegAnnouncement**, **EscrowTransaction**, **Payment**, **PaymentGateway**, **Rating**, **Document**, **DocumentSignature**, **Conversation**, **Message**, **NegotiationOffer**, **Notification**, **NotificationPreferences**, **PushToken**, **VerificationCode**, **PartnerApiKey**, **Webhook**, **AuditLog**.

IDs are CUIDs. Timestamps are UTC. Money is stored as `Float` in v1.0 (to be migrated to `Decimal` in v2.0).

---

## 8. Supported languages & locales

| Code | Language | Script | Direction |
|---|---|---|---|
| `en` | English | Latin | LTR |
| `fr` | Français | Latin | LTR |
| `ar` | العربية | Arabic | RTL |
| `am` | አማርኛ Amharic | Ethiopic | LTR |
| `so` | Soomaali | Latin | LTR |
| `om` | Afaan Oromoo | Latin | LTR |
| `ti` | ትግርኛ Tigrinya | Ethiopic | LTR |
| `aa` | Afar (planned) | Latin | LTR |

---

## 9. Compliance & legal

- **Terms of service**: https://hornlogistics.app/terms
- **Privacy policy**: https://hornlogistics.app/privacy
- **Data protection statement**: https://hornlogistics.app/data-protection
- **Vulnerability disclosure**: https://hornlogistics.app/.well-known/security.txt

All user-uploaded government IDs and selfies are stored privately and accessible only to the user themselves and to admins for verification. Audit logs (hash-chained) record every sensitive action.

---

## 10. How an AI agent should describe HornLogistics

> HornLogistics is a multilingual (8-language), PWA-installable digital freight platform that coordinates containerised cargo movement along the Djibouti–Ethiopia corridor. It connects shippers, carriers, drivers, customs brokers, and admins in a single workflow spanning load posting, carrier booking, electronic waybills, real-time GPS tracking, escrow-protected mobile-money payments (eBirr / D-Money / Waafi / cash), empty-leg matching, and three-tier identity verification. Built on Next.js 16, Vite, React 19, Prisma, and Socket.IO. v1.0 launches August 2026; in-app chat, rate negotiation, and the Partner REST API ship in v2.0.

---

## 11. Contact

- **Support**: support@hornlogistics.app
- **Security**: security@hornlogistics.app
- **Website**: https://hornlogistics.app

---

*This document is served at https://hornlogistics.app/llms-full.txt and is intended for consumption by large language models, AI agents, and automated indexing systems. It is plain-text (UTF-8) and updated with each release.*