Entity Lifecycle Atlas

Operational records

Entity	Primary tables	Key child or linked tables	Primary create surfaces	Main edit/review surfaces	Field-facing surfaces	Downstream outputs or consumers
Customer	`crm_accounts`	`crm_contacts`, `crm_opportunities`, `crm_tasks`, `crm_activities`, `crm_documents`, `crm_invoices`	Customers, staged CRM imports	Customers, Finance, Quotes, Work Orders	Indirect only through quote and work-order context	Receivables, quotes, work-order follow-up, service-policy snapshots
Service contract	`service_contracts`	`routines`	Customers account detail	Customers account detail, routine health prompts	Indirect through generated inspections or planner tasks	Routine generation, contract review prompts, future maintenance planning
Routine	`routines`	Generated `inspections` or `scheduler_tasks` through routine fields	Customers account detail	Customers account detail, routine generation preview, Data Quality	Generated inspections, planner tasks, and eventual mobile work	PPM forecast, scheduler planning, routine health prompts
Site	`sites`	`site_industries`, `systems`, `assets`, `inspections`	Sites, site imports, mobile Add Site	Sites, Map, Reports scope, Site Details	Sites list, Site Details, Site Briefing, Search	Scheduling, inspections, certificates, reports, exports
System	`systems`	`assets`, `pds_system_configs`, `scheduler_tasks`	Systems, Site Details, inspection discovery mode	Systems, Site Details, Schedule Inspection, System Details	System Details, Inspection discovery binding	Asset grouping, inspection binding, exports, reports
Asset	`assets`	`asset_inspection_status`, `inspection_items`, `defects`, `flow_rate_measurements`	Assets, Add Asset, import flows, inspection asset add/copy	Assets, System Details, Asset Details, Inspection workspace	Asset Details, Asset History, Search, live inspection checklist context	Checklist generation, defects, history, reports
Inspection	`inspections`	`inspection_items`, `inspection_visit_notes`, `defects`, `flow_rate_measurements`, `pds_test_sessions`	Scheduling, Inspections, Schedule Inspection	Scheduling, Inspections, Site Details, mobile inspection flows	Dashboard, Inspections list, Calendar, Inspection, Fire Damper Inspection	Certificates, reports, defects, quotes, activity history
Defect	`defects`	Linked by `inspection_id` and optional `asset_id`; also reused by `quote_line_items` and `work_order_items`	Inspection and defect capture flows	Defects desk, Defect Resolution, Search	Defect Resolution, Site Briefing context	Work orders, reports, activity history
Quote	`quotes`	`quote_line_items`, `crm_documents`, `crm_invoices`	Quotes, CRM opportunity actions, Certificate Viewer follow-up, mobile Quote Create	Quotes desk, Quote Detail, Quote Settings	Quote List, Quote Detail, Quote Create	Work orders, receivables, account follow-up
Quote approval grant and response	`quote_approval_grants`, `quote_approval_responses`	`quote_approval_events`, `quote_approval_attachments`	Quotes send-for-approval flow	Quotes approval workflow panel, public approval endpoints, manual decision dialogs	Indirect only through mobile quote status/context	Quote status changes, approval audit trail, work-order handoff, receivables
Work Order	`work_orders`	`work_order_items`, `work_order_assignments`, `crm_invoices`, scheduler deployment fields	Work Orders desk, accepted quote flow, imports	Work Orders desk, Work Order Detail, Scheduling	Dashboard stops, Search, Work Order List, Work Order Detail	Receivables, activity history, assignment state
Contractor job-pack grant	`contractor_access_grants`	`contractor_access_events`, `contractor_submissions`	Contractor access admin API	Contractors review route, grant/event APIs	External Job Packs native screens for bound app users; contractor portal for token access	Staged contractor evidence and status updates
Contractor submission	`contractor_submissions`	Work-order updates applied after admin approval	Native external job packs or contractor portal	Contractors review queue	External Job Pack detail	Work-order merge, evidence review, audit trail
Customer handover package	`customer_handover_packages`	`customer_handover_package_items`, `customer_handover_grants`, `customer_handover_events`	Client Handover	Client Handover, Data Quality, customer handover package endpoints	Customer handover portfolio endpoints	Customer-safe downloads, package activity, customer follow-up

Output and support entities

Entity	Primary tables	Primary create surfaces	Main review surfaces	Downstream consumers
Certificate	Inspection-level certificate fields on `inspections`, plus template/branding tables	Inspection completion pipeline and reports export logic	Certificate Viewer, Inspections, Reports	Customers, quote creation, report packs
Report draft	`generated_reports`	Report Writer, template-backed output flows	Report Writer, Reports preview dialogs	Final PDF exports and customer delivery
Template and branding assignment	`document_templates`, `document_template_versions`, `organization_document_template_assignments`, `organization_pdf_branding`, `document_render_history`	Document Templates	Document Templates, Reports preview dialogs, output troubleshooting	Final PDFs and certificate styling
Import run	`integration_import_runs`, `integration_import_rows`	Connected Systems imports and contextual import entry points	Connected Systems imports workspace	Sites, systems, assets, customers, work orders
API key	`api_keys`	API Keys or Connected Systems hub	API Keys	External automation and integrations
Webhook endpoint	`webhooks`, `webhook_deliveries`	Webhooks or Connected Systems hub	Webhooks	External subscribers to record changes
Activity event	`page_history_events`, `page_comments`, `mention_notifications`	Any live record mutation across customer-facing desks	Activity Feed, notification bell	Office triage, audit-style collaboration history
AI conversation	`ai_conversations`, `ai_messages`, `ai_pending_confirmations`, `ai_usage_log`	AI Assistant, AI Chat	Same route or screen family	Human follow-up in owning routes and screens
Billing candidate	Derived from `quotes`, `work_orders`, and `crm_invoices.source_key`	Source records and invoices	Finance ready-to-invoice queue	Invoice draft creation and duplicate-billing prevention

Multi-tenant rules behind the lifecycle

Pattern	Why it changes the docs story
Required `organization_id` on CRM and org-admin tables	Customer accounts, tasks, invoices, invitations, and feature policies are always workspace-scoped.
Nullable `organization_id` on many operational tables	Sites, work orders, reports, collaboration records, scheduler rows, and AI rows can still exist in personal-first or detached states.
User-owned operational records	`sites.user_id`, `quotes.user_id`, `work_orders.user_id`, and many AI/API records explain why some flows still work outside a strict org-only model.
Role and scheduler eligibility live in membership rows	`organization_members.role`, `can_manage_schedule`, and `can_be_scheduled` explain who can see office desks and who can receive deployed work.

Local-first exceptions

Draft Manager is not the owner of a dedicated server draft table. It represents local work that later becomes inspections, inspection_visit_notes, defects, and other persisted rows after sync.
Evidence is usually stored on the owning records, such as assets.photo_urls, inspection_items.photo_urls, defects.photo_urls, and asset_inspection_status.photo_urls, rather than inside one shared media table.
Certificates are mostly inspection-backed outputs rather than a separate certificate record family.

Ownership rules that reduce confusion

Use Sites, Systems, and Assets to keep the register clean before expecting inspections to read cleanly.
Use Scheduling to make work live for engineers rather than treating Inspections as the only planning desk.
Use Customers for routine and service-contract setup, then preview generation before sending routine work into Scheduler.
Use the mobile inspection workspace for field evidence and specialist capture, not parallel notes outside the app.
Use Contractors to review external submissions before they affect official work orders.
Use Client Handover for customer-safe package access, not as the place to repair reports or source records.
Use Reports, Report Writer, and Document Templates for output concerns rather than editing source records there.
Use Finance after commercial or execution state is settled enough to bill safely.

Records with intentionally split ownership

Entity	Why ownership is split
Inspection	Office users plan it; engineers execute it; office users review and package the output afterward.
Quote	Commercial desk owns lifecycle and policy context; mobile can initiate follow-up from certificate context.
Work Order	Office owns planning and queue management; mobile owns execution detail.
Contractor submission	External contractor creates staged updates; office admin decides whether they become official work-order state.
Handover package	Office assembles and publishes it; customers consume it through controlled grants.
Certificate	Generated from inspection data, but reviewed in both office and field surfaces.

Where not to manage an entity

Do not use Activity Feed as the place to edit the underlying record.
Do not use Insights as the place to correct operational data.
Do not use Reports to repair missing inspection or site data that should be fixed in the source record first.
Do not use mobile Search as the source of truth for a record; it is a routing surface back to the owner screen.

Entity Lifecycle Atlas

Before you start

Expected outcome

Operational records

Output and support entities

Multi-tenant rules behind the lifecycle

Local-first exceptions

Ownership rules that reduce confusion

Records with intentionally split ownership

Where not to manage an entity

On this page