# Phase 10.0 — Delivery Platform Foundation

| Field | Value |
| --- | --- |
| Status | Complete |
| Module | delivery |
| Version | 0.10.0.0 |
| Database | `delivery_db` |
| API Port | 8007 |
| ADR | ADR-001, ADR-003, ADR-006, ADR-015 |
| Commercial Product | Torbat Driver |

## Goal

Establish the **Delivery & Fleet Platform** as a completely independent enterprise microservice foundation (commercial product: **Torbat Driver**).

Reusable by Hospitality, Marketplace, Store, Pharmacy, Clinic, Sports Center, and future services via **API + Events only** — no shared databases, no business logic duplication.

This phase implements foundation shells and discovery surfaces only. It does **not** implement driver workflows, dispatch, routing engines, tracking, or settlement engines.

## Scope Delivered

### In Scope

- Service scaffold under `backend/services/delivery` (API → Service → Repository → Model)
- Foundation aggregates: DeliveryOrganization, DeliveryHub, DeliveryRole, DeliveryPermission, ExternalProviderConfig, RoutingEngineRegistration, DeliveryConfiguration, DeliverySetting, DeliveryAuditLog
- Health `/health`, Capability `/capabilities`, Metrics `/metrics`
- Permissions `delivery.*` trees (foundation + planned leaves)
- Publish-only events `delivery.*` (organization/hub/provider/routing/config/setting)
- Platform provider contracts (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, RoutingEngine, Fleet)
- Tenant isolation via `X-Tenant-ID`
- Alembic `0001_initial` + compose wiring (port 8007)
- Tests: architecture, API/tenant, permissions, migration, dependency, security, docs

### Out of Scope

- Driver management (10.1)
- Fleet / vehicle types (10.2)
- Availability / shifts / zones (10.3)
- Pricing / capability bundles (10.4)
- Dispatch engine (10.5)
- Routing / optimization execution (10.6)
- Tracking / POD (10.7)
- Settlement posting (10.8)
- Merchant connector / app UI (10.9)
- Analytics / AI (10.10)

## Service Boundaries

| Delivery owns | Delivery does not own |
| --- | --- |
| Aggregates above | Accounting / Posting Engine |
| Delivery HTTP APIs under `/api/v1/*` | CRM sales entities |
| `delivery.*` permissions | Loyalty ledger / points |
| Publish-only delivery events | Communication / SMS providers / message delivery timeline |
| External provider & routing-engine **registrations** | Vertical order aggregates |
| Tenant delivery configuration | Identity / Storage blobs / AI inference |

## Published Events (Phase 10.0)

| Event | Aggregate |
| --- | --- |
| `delivery.organization.created` / `updated` | organization |
| `delivery.hub.created` / `updated` | hub |
| `delivery.external_provider.registered` / `updated` | external_provider_config |
| `delivery.routing_engine.registered` / `updated` | routing_engine_registration |
| `delivery.configuration.created` / `updated` | configuration |
| `delivery.setting.upserted` | setting |

## API Contracts

| Resource | Prefix |
| --- | --- |
| Organizations | `/api/v1/organizations` |
| Hubs | `/api/v1/hubs` |
| External providers | `/api/v1/external-providers` |
| Routing engines | `/api/v1/routing-engines` |
| Configurations | `/api/v1/configurations` |
| Settings | `/api/v1/settings` |
| Audit | `/api/v1/audit` |
| Health / Capabilities / Metrics | `/health`, `/capabilities`, `/metrics` |

## Permissions

`delivery.*` trees covering organizations, hubs, external providers, routing engines, configurations, settings, audit, plus planned leaves for drivers/fleet/dispatch/routing/tracking/settlement.

## Architecture Decisions

1. Database-per-service (`delivery_db`) — ADR-001 / ADR-015
2. Row-level `tenant_id` — ADR-003
3. Event publish contracts via `EventEnvelope` — ADR-006
4. Vertical-agnostic logistics platform — no hardcoded Hospitality/Marketplace rules
5. External routing/fleet providers behind Protocols — vendor logic outside business services
6. Soft delete + actor audit + delivery audit log
7. Optimistic locking on organizations, providers, routing engines, configurations

## Folder Structure

```
backend/services/delivery/
  app/
    api/v1/
    core/
    middlewares/
    models/
    repositories/
    services/
    validators/
    schemas/
    events/
    permissions/
    providers/
    policies/
    specifications/
    commands/
    queries/
    tests/
  alembic/versions/0001_initial.py
  scripts/ensure_db.py
  README.md
```

## Tests Executed

Architecture · API foundation flow · tenant isolation · permissions · migration · dependency · security · docs

## Related Documents

- [Phase Handover 10.0](phase-handover/phase-10-0.md)
- [Delivery Roadmap](delivery-roadmap.md)
- [ADR-015](architecture/adr/ADR-015.md)
- [Module Registry](module-registry.md#delivery)
- [Progress](progress.md)