TorbatYar/docs/delivery-roadmap.md

# Delivery & Fleet Platform — Roadmap

> Platform roadmap. Implementation proceeds phase-by-phase under the AI Framework.  
> Framework: [ai-framework/](ai-framework/README.md) · ADR: [ADR-015](architecture/adr/ADR-015.md) · Manifests: [phase-manifest.yaml](ai-framework/phase-manifest.yaml), [service-manifest.yaml](ai-framework/service-manifest.yaml)

| Field | Value |
| --- | --- |
| Service | `delivery` |
| Commercial Product | Torbat Driver |
| Database | `delivery_db` |
| Permission Prefix | `delivery.*` |
| API Port (planned) | 8007 |
| Phases | 10.0 – 10.10 |
| Status | Phase 10.1 Driver Management complete; next 10.2 Fleet & Vehicle Types |

## Vision

Deliver an independent, multi-tenant **Delivery & Fleet Platform** inside TorbatYar so Restaurant, Cafe, Marketplace, Store, Pharmacy, Clinic, Sports Center, and future services can request logistics without owning drivers, fleets, dispatch, or routing — and without duplicating business logic or sharing databases.

## Business Scope

In scope (over Phases 10.0–10.10):

- Driver management and operational readiness
- Fleet management and vehicle types
- Dispatch engine and assignment
- Routing, multi pickup / multi drop, optimization
- Live tracking and proof of delivery
- Availability, shift management, working zones
- Pricing and capability bundles
- Settlement (via Accounting APIs/events only)
- Merchant connector contracts for vertical services
- Customer tracking APIs
- Notifications via Communication only
- Fleet analytics shells; AI-ready hooks (optional)
- External providers and future routing engines behind adapters
- Driver App / Dispatcher Panel **API contracts** (UI in frontend)

## Architecture Scope

| Rule | Reference |
| --- | --- |
| Independent service + `delivery_db` | [ADR-015](architecture/adr/ADR-015.md), [ADR-001](architecture/adr/ADR-001.md) |
| Layering API → Service → Repository → Model | [service-architecture.md](architecture/service-architecture.md) |
| Tenant-aware business tables | [ADR-003](architecture/adr/ADR-003.md) |
| Outbox-ready events `delivery.*` | [ADR-006](architecture/adr/ADR-006.md) |
| No journal ownership | [ADR-010](architecture/adr/ADR-010.md) |
| Messaging via Communication only | [ADR-012](architecture/adr/ADR-012.md) |
| Loyalty via Loyalty service only | [ADR-011](architecture/adr/ADR-011.md) |
| AI optional / independent | [ai-architecture.md](architecture/ai-architecture.md) |
| FE/BE separation for Driver App / Dispatcher Panel | [ADR-002](architecture/adr/ADR-002.md) |
| Implementation via AI Framework | [ai-framework/](ai-framework/README.md) |

## Module Map

| Module | Responsibility | Introduced |
| --- | --- | --- |
| Drivers | Driver profiles, credentials refs, status | 10.1 |
| Fleet | Fleet units and ownership shells | 10.2 |
| Vehicle Types | Catalog of vehicle classes/capabilities | 10.2 |
| Vehicles | Concrete vehicles assigned to fleets/drivers | 10.2 |
| Availability | Online/offline and capacity readiness | 10.3 |
| Shifts | Shift definitions and assignments | 10.3 |
| Working Zones | Geo / operational zones | 10.3 |
| Pricing | Delivery pricing rules shells | 10.4 |
| Capabilities | Capability flags for jobs/vehicles/drivers | 10.4 |
| Bundles | Packaged capability/pricing offerings | 10.4 |
| Dispatch | Dispatch engine and assignment | 10.5 |
| Routing | Route plans; multi pickup / multi drop | 10.6 |
| Optimization | Route/job optimization strategies | 10.6 |
| Tracking | Live location and journey timeline | 10.7 |
| Proof of Delivery | POD capture (signature/photo/code refs) | 10.7 |
| Settlement | Settlement intents; Accounting posts externally | 10.8 |
| Merchant Connector | Vertical order/job intake contracts | 10.9 |
| Notifications | Outbound notify via Communication client | 10.9 |
| Driver App APIs | Mobile driver contract surfaces | 10.9 |
| Dispatcher Panel APIs | Ops panel contract surfaces | 10.9 |
| Customer Tracking | Public/customer tracking token APIs | 10.7 / 10.9 |
| Fleet Analytics | Metrics/export shells | 10.10 |
| AI Hooks | Optional AI contracts (dispatch assist, ETA) | 10.10 |
| External Providers | Fleet/routing provider adapters | 10.0+ |
| Audit / Config / Health | Foundation shells | 10.0 |

Canonical inventory: [module-registry.md](module-registry.md#delivery).

## Integration Map

```
Verticals (Restaurant / Marketplace / Store / Pharmacy / Clinic / Sports Center / …)
        │
        │ API / Events (job refs only — no shared DB)
        ▼
   Delivery Platform ──API/Events──▶ Accounting   (settlement → Posting Engine)
   Delivery Platform ──API/Events──▶ Communication (SMS/push/OTP notifications)
   Delivery Platform ──API/Events──▶ Loyalty      (optional earn refs)
   Delivery Platform ──API/Events──▶ CRM          (contact refs only)
   Delivery Platform ──API─────────▶ Core         (entitlement, tenant)
   Delivery Platform ──Adapters───▶ External routing / fleet providers
```

Forbidden: cross-DB queries, embedding SMS providers inside Delivery, creating JournalEntry locally, owning Restaurant/Marketplace order aggregates.

## Disambiguation

| Term | Owner |
| --- | --- |
| Message delivery (queued/sent/delivered) | Communication |
| Physical / courier delivery jobs | Delivery Platform (`delivery`) |

## Phase Map

| Phase | ID | Name | Status |
| --- | --- | --- | --- |
| Reg | `delivery-reg` | Platform Registration | Complete |
| 10.0 | `delivery-10.0` | Foundation | Complete |
| 10.1 | `delivery-10.1` | Driver Management | Complete |
| 10.2 | `delivery-10.2` | Fleet & Vehicle Types | Planned |
| 10.3 | `delivery-10.3` | Availability, Shifts & Working Zones | Planned |
| 10.4 | `delivery-10.4` | Pricing, Capabilities & Bundles | Planned |
| 10.5 | `delivery-10.5` | Dispatch Engine | Planned |
| 10.6 | `delivery-10.6` | Routing & Optimization | Planned |
| 10.7 | `delivery-10.7` | Tracking & Proof of Delivery | Planned |
| 10.8 | `delivery-10.8` | Settlement | Planned |
| 10.9 | `delivery-10.9` | Merchant Connector & App Surfaces | Planned |
| 10.10 | `delivery-10.10` | Analytics, AI Ready & Enterprise Validation | Planned |

Details (dependencies, required docs/services, completion criteria): [phase-manifest.yaml](ai-framework/phase-manifest.yaml).

## Platform Expose (every implementation phase)

Health API · Capability API · Metrics · Events · REST APIs · Permission APIs

## Future Expansion

- Additional routing engine adapters without vertical changes
- Third-party fleet marketplaces behind provider protocols
- Deeper ETA / surge pricing engines when scoped
- Cross-tenant platform-admin fleet analytics (explicit + audited)

## Out of Scope

- Owning Accounting ledgers or Posting Engine
- Owning Sales CRM aggregates
- Owning Loyalty ledger / campaigns
- Owning SMS/email/push providers (Communication owns them)
- Owning Restaurant/Marketplace/Clinic/Sports Center order domains
- Implementing Phase 10.x business code in the registration phase
- Driver App / Dispatcher Panel UI (frontend phases)

## Related Documents

- [Phase Area README](phases/Delivery/README.md)
- [ADR-015](architecture/adr/ADR-015.md)
- [Module Registry](module-registry.md#delivery)
- [Glossary — Delivery](glossary.md#delivery--fleet-platform)
- [Service Manifest](ai-framework/service-manifest.yaml)
- [Progress](progress.md)
- [Roadmap](roadmap.md)
- [Next Steps](next-steps.md)
- [Phase Handover DP-Reg](phase-handover/phase-dp-reg.md)