Phase 10.1 — Driver Management
| Field |
Value |
| Identifier |
delivery-10.1 |
| Status |
Complete |
| Module |
delivery |
| Service |
delivery-service |
| Version |
0.10.1.0 |
| Database |
delivery_db |
| API Port |
8007 |
| Depends On |
Phase 10.0 |
| ADR(s) |
ADR-001, ADR-003, ADR-006, ADR-015 |
| Commercial Product |
Torbat Driver |
| Manifest |
phase-manifest.yaml |
Enterprise Phase Discovery Summary
| Item |
Detail |
| Capabilities required |
Driver profiles, credential/document refs, status lifecycle, list UX (filter/sort/search/page), audit, outbox events, permissions |
| Gaps closed |
Driver aggregate + lifecycle policy + credentials/documents + transactional outbox + permission leaves |
| Exclusions |
Fleet/vehicles (10.2), availability/shifts/zones (10.3), dispatch (10.5), routing execution (10.6), tracking/POD (10.7) |
| CRUD-only rejected |
Yes — lifecycle machine, credentials, documents, outbox, specs, policies required |
Goal
Deliver production-ready Driver Management for the Delivery & Fleet Platform (Torbat Driver): profiles, credential and document references, status lifecycle with append-only history, tenant-isolated APIs, audit, and outbox events — without fleet, dispatch, routing, or tracking engines.
Scope Delivered
In Scope
- Aggregates:
Driver, DriverCredential, DriverDocument, DriverLifecycleEvent, OutboxEvent
- Lifecycle: activate, suspend, resume, deactivate, block, unblock, archive
- Soft delete + optimistic locking on drivers
- List: pagination, filtering (status/org/hub), sorting, searching
- Commands / queries / policies / specifications / validators
- Permissions
delivery.drivers.* leaves + catalog discovery API
- Publish-only events
delivery.driver.* via transactional outbox
- Health / capabilities / metrics updated (
phase: 10.1, drivers: true)
- Alembic
0002_phase_101_drivers
- Tests: unit, API/integration, tenant, architecture, migration, permissions, performance indexes, docs
Out of Scope
- Fleet / vehicle types / vehicles (10.2)
- Availability / shifts / working zones (10.3)
- Pricing / capability bundles (10.4)
- Dispatch engine (10.5)
- Routing / optimization execution (10.6)
- Tracking / POD (10.7)
- Settlement (10.8)
- Merchant connector / app UI (10.9)
- Analytics / AI (10.10)
Service Boundaries
| Delivery owns |
Delivery does not own |
Driver profiles and lifecycle in delivery_db |
Identity user administration |
| Credential/document metadata + Storage file refs |
File blobs (Storage) |
| External user / CRM contact refs |
CRM contact master |
Driver permissions delivery.drivers.* |
Communication message delivery |
Outbox delivery.driver.* events |
Accounting journals |
Domain Model
Driver statuses
pending → active ↔ suspended → inactive → archived (terminal); block → blocked → unblock → inactive.
| Action |
Allowed from |
To |
Reason required |
| activate |
pending, inactive, suspended |
active |
No |
| suspend |
active |
suspended |
Yes |
| resume |
suspended |
active |
No |
| deactivate |
active, suspended |
inactive |
Yes |
| block |
pending, active, suspended, inactive |
blocked |
Yes |
| unblock |
blocked |
inactive |
No |
| archive |
inactive, blocked |
archived |
Yes |
Aggregates
| Entity |
Soft delete |
Optimistic lock |
Tenant |
| Driver |
Yes |
Yes |
Yes |
| DriverCredential |
Yes |
No |
Yes |
| DriverDocument |
Yes |
No |
Yes |
| DriverLifecycleEvent |
No (append-only) |
No |
Yes |
| OutboxEvent |
N/A |
N/A |
Yes |
APIs
| Method |
Path |
Permission |
| POST |
/api/v1/drivers |
delivery.drivers.create |
| GET |
/api/v1/drivers |
delivery.drivers.view |
| GET |
/api/v1/drivers/{id} |
delivery.drivers.view |
| PATCH |
/api/v1/drivers/{id} |
delivery.drivers.update |
| POST |
/api/v1/drivers/{id}/activate |
delivery.drivers.activate |
| POST |
/api/v1/drivers/{id}/suspend |
delivery.drivers.suspend |
| POST |
/api/v1/drivers/{id}/resume |
delivery.drivers.resume |
| POST |
/api/v1/drivers/{id}/deactivate |
delivery.drivers.deactivate |
| POST |
/api/v1/drivers/{id}/block |
delivery.drivers.block |
| POST |
/api/v1/drivers/{id}/unblock |
delivery.drivers.unblock |
| POST |
/api/v1/drivers/{id}/archive |
delivery.drivers.archive |
| GET |
/api/v1/drivers/{id}/lifecycle |
delivery.drivers.lifecycle.view |
| POST/GET |
/api/v1/drivers/{id}/credentials |
credentials.manage / view |
| POST/GET |
/api/v1/drivers/{id}/documents |
documents.manage / view |
| POST |
/api/v1/drivers/{id}/delete |
delivery.drivers.delete |
| GET |
/api/v1/permissions/catalog |
delivery.view |
| GET |
/health, /capabilities, /metrics |
Public |
List query params: page, page_size, status, organization_id, hub_id, q, sort_by, sort_dir.
Events
| Event |
Aggregate |
delivery.driver.created |
driver |
delivery.driver.updated |
driver |
delivery.driver.activated / suspended / resumed / deactivated / blocked / unblocked / archived |
driver |
delivery.driver.status_changed |
driver |
delivery.driver.deleted |
driver |
delivery.driver.credential_added |
driver_credential |
delivery.driver.document_attached |
driver_document |
Persisted via transactional outbox (outbox_events) per ADR-006; mirrored in-memory under test.
Permissions
delivery.drivers.view|create|update|delete|activate|suspend|resume|deactivate|block|unblock|archive|lifecycle.view|credentials.view|credentials.manage|documents.view|documents.manage|manage
Migration
| Item |
Detail |
| Alembic |
0002_phase_101_drivers (down_revision 0001_initial) |
| Breaking |
None — additive tables |
| Backfill |
None |
Architecture Decisions
- Driver status machine owned by Delivery validators/policies — not Identity
- Credential/document binaries remain Storage refs only
- Transactional outbox introduced for driver mutations (backward-compatible with foundation in-memory publisher)
- No fleet/vehicle/dispatch tables in this phase
- Soft delete + optimistic lock on Driver; append-only lifecycle history
Folder Additions
app/models/drivers.py
app/models/outbox.py
app/validators/drivers.py
app/policies/drivers.py
app/specifications/drivers.py
app/repositories/drivers.py
app/services/drivers.py
app/schemas/drivers.py
app/commands/drivers.py
app/queries/drivers.py
app/api/v1/drivers.py
app/api/v1/permissions.py
alembic/versions/0002_phase_101_drivers.py
Tests
- Unit: lifecycle transition matrix
- Integration: lifecycle flow, credentials/documents, filter/sort/search, optimistic lock, soft delete, tenant isolation
- Architecture / migration / permissions / performance indexes / docs / security (auth required)
Definition of Done
All Enterprise Quality Gates for Phase 10.1 satisfied. See phase-handover/phase-10-1.md.
Related Documents
5c6a2e78cf