Vertical products and automation specification

Status — Proposed product contracts and pilot acceptance criteria. Paths beginning with /addons/v1 describe future services. Use the repository's current API guide to integrate with the local telemetry release.

Shared product model

The deployment unit is a tenant with independently enabled modules. A tenant administrator registers an application, grants scopes, defines retention and enables modules in a sandbox first. Every business record carries a tenant ID derived from the authenticated principal, an opaque resource ID, version, creation time and audit actor. Human membership, hardware identity, asset ownership and trip assignment each have their own validity intervals. A private vehicle can be shared across shifts without exposing a previous driver's trip.

Command and data integrity. Writes accept an idempotency key scoped to tenant, principal and operation. Reuse with different content returns 409. If-Match protects state transitions from stale screens. A database transaction persists the business revision and outbound event together. Connectors retry until acknowledgement with bounded backoff and a dead-letter workflow. Consumer deduplication uses the stable event ID. Event time controls business windows. Ingestion sequence drives cursors. Backfills can revise an aggregate and preserve the prior revision for audit.

Developer contract. Resource collection reads expose opaque cursor pagination and bounded time ranges. Publish OpenAPI for request/response types and AsyncAPI for event types. Each event includes id, type, schemaVersion, subject, occurredAt, recordedAt, resourceVersion and a correlation ID. Sign outbound callbacks over the timestamp and raw request body using a per-subscription secret. Support overlapping signing keys on rotation, replay by time/cursor and an observable poison-event queue. Mobile clients consume projections narrowed to their grant. API clients receive 401 for invalid authentication, 403 for a missing scope, 404 for invisible resource IDs, 409 for conflicting assignments, 412 for a stale version, 422 for an invalid transition and 429 with a retry interval for quotas.

Map and time quality. Mappls map, routing, distance-matrix and geocoding connectors accept tenant credentials from a server-side secret store. Persist the normalized location and the provider observation independently. Set accuracy, heading validity, freshness and route source on every projected position. Treat stale data as unknown for assignment, zone entry and SLA escalation. Enter and exit fences with distinct thresholds and dwell intervals. Preserve the map revision used for a route or geofence. Show age and a gap when a phone stops reporting.

Family and friend locator

A member creates a private circle, invites another member with a single-use expiring invitation, then chooses a sharing duration and precision for that circle. A member can check in once, share while a timer runs, pause or revoke. Receiving an invitation cannot start tracking. Each phone lists active audiences and permits local stop even when disconnected. The mobile view puts last-fix time, accuracy and sharing controls beside the member's own position. The web view gives each recipient their permitted map and place subscriptions.

• POST /addons/v1/circles, POST /circles/{id}/invitations, POST /invitations/{id}/accept, PUT /circles/{id}/my-grant, DELETE /circles/{id}/my-grant and GET /circles/{id}/positions are the proposed operations. Unqualified paths here and below are relative to /addons/v1.
• The owner manages membership and named places. Only the sharing subject can grant their personal location. Place events include subject, place, direction, observed time, accuracy and the effective grant. Default to current position, coarse precision, no camera access and explicitly selected history.
• Pilot gate. With one phone in two circles, revoke one grant mid-session. Within five seconds of the server observing revocation, its live subscribers lose access and fresh reads omit the position. Reconnect a previously offline phone. Its buffered data cannot backfill a revoked interval. Previously received screenshots and exports are outside server revocation. Disclose this in sharing controls.

Caravan and group driving

A leader creates a time-bounded drive with waypoints, meeting points and a planned end. Members opt into that drive and can leave independently. A participant sees the last good fix for peers, distance to the next rendezvous, and whether their own network has stalled. A leader can issue a rendezvous update. Changing the route increments a revision and delivers it when the device reconnects. The client coalesces nonurgent notifications while moving.

• POST /convoys, POST /convoys/{id}/memberships, PATCH /convoys/{id}/route, POST /convoys/{id}/check-ins, GET /convoys/{id}/progress. Events include convoy.route.changed, convoy.member.separated and convoy.closed.
• For the pilot, signal separation after two minutes of fresh observations more than a configured along-route threshold apart. Track route branches, accuracy and event-time order. Silence is an offline state. Close the session at the leader's end or scheduled expiry and invalidate active subscriptions.
• Pilot gate. Drive three synthetic vehicles through a junction, tunnel and rendezvous. A parked phone offline in the tunnel produces a stale marker. A participant who leaves can neither retrieve later fixes nor receive route changes. Debounce a five-second detour.

Rider fleet, transport and video telematics

A dispatcher onboards bikes, vans, drivers, sensors and gateways, imports a roster and assigns shifts. Drivers accept shifts on their phones. Supervisors see an age-coded fleet board, route replay, open exceptions and device/battery health. A reviewer has an independent permission to inspect incident evidence. Record the mount/orientation calibration and rule version. A high-motion trigger requests a bounded trace with pre/post context and a clip only where a participant has already enabled capture. Keep a correction path for false positives.

• POST /shifts, POST /shifts/{id}/assignments, POST /tasks, POST /tasks/{id}/outcomes, GET /fleets/{id}/board, POST /incidents/{id}/reviews, GET /incidents/{id}/evidence. Task states progress from planned through assigned, accepted, in progress and succeeded/failed. Cancellation carries a reason.
• Resolve driver attribution at observation time using assignment intervals. Give dispatchers operational status and delay alerts. Give authorized safety reviewers a time-limited URL and audit each view. Aggregate reviewed incidents per driving hour and display the sample size. A missed or unavailable measurement stays unknown.
• Pilot gate. Reassign a vehicle after a shift. Deliver delayed data from both shifts and show the correct driver on each trip. Two dispatchers assigning one rider concurrently get one accepted assignment. A dispatcher without evidence scope can see an event count and cannot retrieve video. After shift closure, end the work location grant.

Logistics, cold chain and proof of delivery

A planner imports a shipment and its legs from the TMS, associates a carrier and equipment per leg, orders stops and attaches task windows and proof requirements. The operator sees exception age, responsible party and next action. Recipients get one delivery projection. A photo, barcode or signature belongs to a specific task. Permit a failed stop, retry and return leg. Record proof hash, author, capture time and retention policy. Keep a recipient's address out of fleet-wide exports by default.

• POST /shipments, PUT /shipments/{id}/legs/{leg}, POST /shipments/{id}/milestones, POST /tasks/{id}/proofs, GET /shipments/{id}/exceptions, POST /exceptions/{id}/resolutions. Join a sensor to a shipment only inside the active binding interval. Compute dwell from attested arrival and departure or qualified fence transitions. Store the ETA provider, generation time and plan revision.
• In the refrigerated shipment fixture, a temperature above 8 °C for five observed minutes opens one excursion. Close after ten continuous minutes below 7 °C. Mark gaps longer than the configured reporting tolerance as insufficient coverage. Alert the assigned carrier, open a TMS exception and escalate after 15 unacknowledged minutes. Thresholds are sample cargo policy values for this test.
• Pilot gate. Transfer one shipment between carriers, deliver duplicated and late temperature samples, miss one stop window and reject a mismatched barcode. The shipper sees one excursion, an explicit coverage gap and one missed-window task. The recipient sees only their delivery. Replay of a successful proof cannot duplicate the delivery completion.

On-demand taxi and mobility

A passenger requests pickup and drop-off. Dispatch narrows candidates to available vehicles with a current shift, capacity and fresh fixes. Rank a shortlist using route duration with a declared provider freshness limit. Send a time-limited offer. Atomically award a single winner and withdraw competing offers. Share driver approach with the passenger once assigned. Close the passenger grant at trip end. Show dispatch the reason for no eligible vehicles and offer a manual reassignment workflow.

• POST /ride-requests, POST /ride-requests/{id}/offers, POST /offers/{id}/accept, POST /trips/{id}/transitions, GET /trips/{id}/share. Trip states progress through requested, offered, assigned, approaching, arrived, in service and completed. Permit a recorded cancellation or no-show from the applicable states. Store wait time and route deviations as auditable facts. Tariff calculation belongs to the operator's billing integration.
• Rider and driver views expose the active trip, assigned peer and pickup state. Operator views include assignment lineage and opt-in incident evidence. Pooled trips require a separate per-passenger projection so co-passenger addresses stay private.
• Pilot gate. Two drivers accept one offer concurrently and one wins. A stale location is excluded from ranking. A disconnected driver's late acceptance fails after expiry. Simulate routing failure and show a time-stamped fallback or dispatch review. A passenger who completed a trip cannot use their token to locate the vehicle on its next trip.

Industrial assets and plant operations

A site engineer commissions a gateway into a site/area/line/machine/channel hierarchy. Bind OPC UA node IDs or Modbus register definitions to versioned signals with type, engineering unit, scaling, endianness, calibration and quality. Select polling or subscription, deadband and max silence for each tag. Expose gateway disk, poll latency, clock offset and invalid-quality counts to maintenance. Provide a historian view with raw observations, rollups, gaps and alarm annotations. Capture bounded vibration waveforms locally around threshold events.

• POST /sites/{id}/bindings, POST /tag-mappings/validate, GET /assets/{id}/history, POST /alarms/{id}/acknowledgements, POST /work-orders, POST /assets/{id}/command-requests. Model alarm active/clear separately from acknowledged/unacknowledged. Acknowledge identifies a person and time. Shelving requires an expiry and reason. Reconcile work orders with the CMMS by stable external ID.
• A supervisor can propose a bounded setpoint for an explicitly writable tag. A separately authorized approver, site-local permissive check, engineering-unit/range validation, expiry, read-back and audit are required for the planned write pilot. A gateway rejects stale revisions. Emergency stops and interlocks stay on certified local circuits. Local mode always wins. Operations requiring a hardware safety case stay unavailable until site acceptance.
• A plant leader sees scheduled production, running time, ideal cycle, total count, good count and data coverage per shift. Compute availability as run time / planned production time, performance as ideal cycle time × total count / run time, quality as good / total count, and OEE as their product. Represent zero denominators as unavailable. Persist the shift calendar and formula revision.
• Pilot gate. Disconnect WAN for 30 minutes with enough local disk, reboot the gateway and reconcile recorded observations and quality after recovery. Inject one bad-quality temperature and an out-of-range proposed write. The measurement remains flagged and the write never reaches the adapter. On a fixture with 480 scheduled minutes, 420 running minutes, 400 units, 380 good and a one-minute ideal cycle, report OEE of 79.17%.

Automation, integrations and commercial operations

Release sequence and field acceptance

1. Local foundation. Verify the device SDK, store-and-send, viewer, configuration and media flows documented for this repo. Capture a repeatable test fixture with observed and ingest times.
2. Identity and platform pilot. Add tenant-scoped people, grants, device/asset bindings, audit, quotas and replayable business events. Exercise mixed-tenant, expired grant, stale/replayed command and out-of-order event cases before allowing customer data.
3. People and mobility pilots. Start with circle and convoy duration controls, then rider shifts and exclusive taxi assignment. Evaluate on physical phones during a full shift with consent changes, network loss and realistic load. Measure time-to-assignment, stale-position minutes, device energy and delivery of opted-in notifications.
4. Transport and logistics pilot. Add shipment legs, proof and temperature cases. Review a carrier transfer, partial delivery, delayed clip and ERP replay with dispatcher and carrier operators. Measure exception acknowledgement time, proof completion and ETA absolute error by route and data age.
5. Industrial pilot. Start with read-only tags and historian trends on a test rig. Obtain plant sign-off on units, quality, uptime, clock drift and offline recovery. Enable limited write operations only after the site-specific control review and acceptance test.
6. Wider rollout. Publish each module through a tenant feature flag. Compare source/target counts through a shadow-read window, run a restore drill, reconcile the usage ledger and measure support burden. Roll back a module independently of device capture.

Pilot owners should set SLOs with the operating team using observed workload and the cost/energy experiment in the benchmark. A rule trigger is an observation requiring domain review, especially for driving incidents and industrial maintenance.