System operating model · §2 / §14 / §23–24
One canonical live company state. Role views, not competing realities.
A completed field event can update technician availability, route position, inventory, booking capacity, forecasts, warranty context, and dispatch recommendations without each department keeping its own version of the day.
Canonical state inputs
Customer, equipment, membership, service history, booking state, technician/Van state, location, inventory, active call state, media evidence, quote state, warranty state, route state, manager queue, pricebook state, and integration health.
Company heartbeat — role interfaces
| Role | Primary view / actions |
|---|---|
| Client Booking | Identity, membership, equipment/history, windows, urgency, appointment precedence. |
| Office | Booking state, issues, warranty/membership, schedule changes, contact actions. |
| Dispatch | Live Van state, route, Call-Fit, runtime, inventory fit, alternatives, override controls. |
| Field Tech | Call context, Field Advisor, history, warranty, inventory, quote/parts, media capture. |
| Manager | Escalation queue, override/recalibration, technician trends, quality, revenue, risk. |
| IT / System Admin | Integration health, MCP/API status, permissions, event integrity, model health, audit logs. |
Heartbeat updates are event-driven where possible, with periodic health checks so a stale integration is visible instead of silently corrupting the picture.
Communications layer
An internal Teams-style layer on the same canonical event stream. Managers can create and moderate company, branch, department, trade, dispatch, sales, field, warehouse, project, and incident channels by permission. Recognition is context-aware and must not reward raw revenue alone. Daily mission boards show target, actual, pace, gap, and projected finish.
Pricebook, stock, weather
ServiceTitan pricebook is the initial shadow baseline. Managers can ACCEPT, OVERRIDE, or LOCK recommendations; a lock cannot be superseded. Van stock, warehouse fulfillment (REQUESTED → RECONCILED), and branch weather windows (past 7 / current / forward 7) feed the same state. Lunar/Earth-tide plumbing features are experimental and must earn weight or go to zero.