# ADR-015: Independent Delivery & Fleet Platform Service

| Field | Value |
| --- | --- |
| Status | Accepted |
| Date | 2026-07-25 |
| Deciders | Platform Architecture |
| Supersedes | — |
| Superseded by | — |

## Context

Restaurant, Cafe, Marketplace, Store, Pharmacy, Clinic, Sports Center, and future verticals all need last-mile logistics: drivers, fleets, dispatch, routing, tracking, proof of delivery, and settlement. Embedding this inside any single vertical would duplicate business logic and couple unrelated domains.

TorbatYar already isolates shared platforms as independent services (Loyalty [ADR-011](ADR-011.md), Communication [ADR-012](ADR-012.md), Sports Center [ADR-014](ADR-014.md)). Physical goods / courier logistics need the same independence. This must not be confused with Communication **message** delivery tracking.

Commercial product name: **Torbat Driver**.

## Decision

1. Introduce `delivery` as an **independent Delivery & Fleet Platform service** with sole ownership of `delivery_db` ([ADR-001](ADR-001.md)).
2. Permission prefix: `delivery.*`. Publish-only domain events: `delivery.*`.
3. Row-level multi-tenancy via `tenant_id` ([ADR-003](ADR-003.md)).
4. Consume Accounting, CRM, Loyalty, Communication, and vertical services (Restaurant, Marketplace, Sports Center, Clinic, etc.) **only** via REST API and Events — never shared tables or foreign model imports.
5. Financial journals only through Accounting Posting Engine ([ADR-010](ADR-010.md)). Settlement posts via Accounting APIs/events — Delivery never creates journal entries locally.
6. Driver/customer notifications only through Communication ([ADR-012](ADR-012.md)).
7. Loyalty points/rewards only through Loyalty ([ADR-011](ADR-011.md)).
8. Routing engines and external fleet providers sit behind protocols/adapters owned by Delivery; future engines plug in without changing verticals.
9. Implementation phases are registered as **Phase 10.0–10.10** in [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml); roadmap in [delivery-roadmap.md](../../delivery-roadmap.md).
10. Product AI remains optional and external ([ai-architecture.md](../ai-architecture.md)). Core dispatch/tracking works when AI is off.
11. UI for Driver App / Dispatcher Panel lives in `frontend/` only ([ADR-002](ADR-002.md)); this service exposes APIs and events.

## Consequences

### Positive

- One reusable logistics platform for all verticals
- No duplicated driver/dispatch logic across Restaurant/Marketplace/etc.
- Enforceable tenancy, audit, and boundary tests
- External routing engines and fleet providers can be swapped behind adapters

### Negative

- Additional deployable service and database
- Eventual consistency for cross-service order/delivery views

### Neutral

- Registration (this ADR + manifests) precedes business code; Phase 10.0 implements the scaffold
- Message delivery status remains owned by Communication — glossary disambiguates terms

## Alternatives Considered

1. Delivery subsystem inside Restaurant — rejected (blocks Marketplace/Pharmacy/Clinic reuse).
2. Delivery tables inside Core — rejected (violates business-module boundaries and ADR-001).
3. Per-vertical bespoke courier stacks — rejected (duplicates logic; contradicts SuperApp platform goals).

## Related Documents

- [Delivery Roadmap](../../delivery-roadmap.md)
- [Phase Area](../../phases/Delivery/README.md)
- [Module Boundaries](../module-boundaries.md)
- [Module Registry — delivery](../../module-registry.md#delivery)
- [Phase Manifest](../../ai-framework/phase-manifest.yaml)
- [Service Manifest](../../ai-framework/service-manifest.yaml)
- [ADR-001](ADR-001.md) · [ADR-002](ADR-002.md) · [ADR-003](ADR-003.md) · [ADR-010](ADR-010.md) · [ADR-011](ADR-011.md) · [ADR-012](ADR-012.md) · [ADR-014](ADR-014.md)