# Delivery Frontend Architecture

**Module:** Torbat Driver (Delivery Platform)  
**Date:** 2026-07-26  
**Backend phase:** 10.1 (Driver Management)

## Overview

The Delivery frontend is the enterprise reference implementation for logistics and courier operations inside TorbatYar SuperApp. Business code lives under `frontend/modules/delivery/`; App Router routes under `app/delivery/` are thin re-exports only.

## Layer diagram

```
app/delivery/              → Routes (page, layout, loading, error, not-found)
        ↓
modules/delivery/          → Business UI, hooks, API client, constants
        ↓
components/ds/             → Shared design system primitives
        ↓
/api/delivery/* BFF        → delivery-service :8007
```

## Directory structure

```
modules/delivery/
├── components/           Portal shell, CRUD factory, phase gates, map placeholder
├── constants/            portals.ts, permissions.ts, phaseRegistry.ts
├── design-system/        tokens, status chips, table page
├── features/             One file per screen (56+ routes)
├── hooks/                capabilities, permissions, lookups
├── pages/shared.tsx      PageLoader, PageError, CSV export
├── services/delivery-api.ts
└── types/index.ts
```

## Backend integration (Phase 10.0–10.1)

| Domain | API prefix | CRUD status |
|--------|------------|-------------|
| Organizations | `/api/v1/organizations` | ✅ Full |
| Hubs (Branches) | `/api/v1/hubs` | ✅ Full |
| External providers | `/api/v1/external-providers` | ✅ Full |
| Routing engines | `/api/v1/routing-engines` | ✅ Full |
| Configurations | `/api/v1/configurations` | ✅ Full |
| Settings | `/api/v1/settings` | ✅ Upsert + list |
| Audit | `/api/v1/audit` | ✅ Query by entity |
| Drivers | `/api/v1/drivers` | ✅ Full + lifecycle |
| Permissions catalog | `/api/v1/permissions/catalog` | ✅ Read |
| Health / Capabilities / Metrics | `/health`, `/capabilities`, `/metrics` | ✅ Read |

## Future phases (capability-gated UI)

Screens for fleet, dispatch, orders, tracking, maps (live), settlement, AI, etc. render **phase gate pages** that read `/capabilities` — no mock data, no fake CRUD. When backend enables a feature flag, the UI unlocks automatically.

## Real-time

WebSocket/SSE for driver locations, dispatch queue, and tracking is planned for Phase 10.7. The map placeholder documents the integration point.

## Commands

```bash
node scripts/scaffold-delivery-module.mjs   # Regenerate routes + feature stubs
npm run validate:delivery                   # Route + architecture validation
```

## Related docs

- [delivery-component-map.md](./delivery-component-map.md)
- [delivery-routing-map.md](./delivery-routing-map.md)
- [delivery-design-system.md](./delivery-design-system.md)
- [delivery-validation-report.md](./delivery-validation-report.md)
- [delivery-ui-checklist.md](./delivery-ui-checklist.md)