# CarPass Production Pilot Entity Map

This map captures the closed-pilot domain model as implemented in the codebase.

## Owner Domain

- `User` owns `Car` records and authenticates through Telegram.
- `Car` is the vehicle/passport entity. It owns `FuelEntry`, `ServiceEntry`, `ExpenseEntry`, `OdometerHistory`, `CarServiceLink`, `ServiceAppointment`, `ServiceVisit`, and `MaintenanceRecommendation`.
- `FuelEntry`, `ServiceEntry`, and `ExpenseEntry` update ownership analytics and can update the vehicle odometer through `OdometerHistory`.
- `OwnershipAnalytics` is computed on demand from entries, expenses, depreciation settings, and loan settings.
- `VehicleAccess` grants non-owner user access to a vehicle for selected backend flows.

## STO Domain

- `ServiceCenter` is the STO profile and tenant boundary.
- `ServiceCenterVerification` stores moderation applications and review decisions.
- `ServiceEmployee` links users to a service center with one of `owner`, `manager`, `receptionist`, or `mechanic`.
- `CarServiceLink` is the owner-approved connection between a vehicle and an STO.
- `ServiceCenterBookingSettings` and `ServiceCenterHoliday` define the appointment calendar.
- `ServiceAppointment` is the customer booking request and can become one `ServiceVisit`.
- `ServiceCenterReview` and `ServiceCenterReviewComment` store public feedback.

## Work Order Domain

- `ServiceVisit` is the work order. It links `ServiceCenter`, `Car`, owner user, employee, appointment, labor items, product items, status history, and corrections.
- `ServiceWorkItem` stores labor/repair work and next-service intervals.
- `ServiceProductItem` stores parts, fluids, materials, SKU and quantity.
- `WorkOrderCatalogItem` is the STO price/catalog item source.
- `InventoryTransaction` records consumed products on work-order completion.
- `WorkOrderStatusHistory` audits status transitions.
- `WorkOrderCorrection` records post-completion correction requests and owner decisions.
- Completion creates immutable owner records: `ServiceEntry`, `ExpenseEntry`, `OdometerHistory`, `MaintenanceRecommendation` when applicable, `ServiceNotification`, and `AuditLog`.

## Trust, Notifications, And Exchange

- `MaintenanceRecommendation` is connected to a vehicle and optionally a service center/appointment.
- `ServiceNotification` is the internal notification queue with best-effort Telegram delivery and idempotency keys.
- `AuditLog` records sensitive and operational actions.
- `Achievement`, `UserAchievement`, `VehicleScore`, `ServiceCenterScore`, and `EngagementEvent` power passport quality, trust, and timeline features.
- Import/export is synchronous API work, not a persisted `ImportExportJob`; schema is `carpass.exchange.v1`.
- OCR returns preview candidates through API responses; no persisted `OCRResult` table exists and OCR never writes vehicle data directly.

## Pilot Gaps To Keep Explicit

- Browser Web Push stores subscriptions and has a service worker listener, but server-side Web Push delivery is beta and not part of the pilot-critical notification path.
- Inventory exists as consumption transactions and catalog products, not as full stock-level management.
- Correction requests record decisions; they do not mutate completed work-order snapshots automatically.