7978970783
Ship the delivery platform UI under modules/delivery with thin app routes, BFF proxy, CRUD for phase 10.0-10.1 APIs, and capability-gated future screens. Co-authored-by: Cursor <cursoragent@cursor.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# 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)
|