Architecture blueprint

ServiceTitan-ready architecture blueprint.

A no-database, no-API implementation map for the private tables, code modules, route gates, rendering boundaries, and lead-flow invariants PageToJob needs before live ServiceTitan automation.

Build map
8
data models
6
modules
4
future routes
5
lead-flow steps
This page is an implementation blueprint. It does not create tables, accept secrets, receive webhooks, or call ServiceTitan.

Private data model blueprint

servicetitan_connections

Track customer connection status, tenant identifiers, granted scopes, token expiry metadata, and last connection errors.

database gated
tenant_idservice_titan_tenant_idstatusgranted_scopesencrypted_token_referencelast_connection_error

Sensitivity: secret

Offline substitute: Connection readiness matrix and API readiness pack.

Gate: Requires approved app access, secure token storage, customer authorization, and disconnect/delete runbooks.

booking_requests

Preserve structured booking intent, source context, preferred time, urgency, address, and original lead relationship.

offline modeled
lead_idtenant_idservice_typepreferred_datepreferred_windowurgencysource_page_pathutm_fields

Sensitivity: pii

Offline substitute: Structured booking envelope and handoff simulator.

Gate: Can become durable after database migration and retention policy approval.

servicetitan_taxonomy_items

Store reviewed or imported job types, business units, campaigns, zones, memberships, and pricebook services.

database gated
tenant_idsource_familyexternal_iddisplay_nameactiveraw_payloadsynced_at

Sensitivity: operational

Offline substitute: Manual taxonomy importer and demo Titan Map.

Gate: Requires customer-approved import source or read-only API scopes.

servicetitan_page_bindings

Map public pages, CTAs, forms, offers, and campaigns to ServiceTitan operating concepts.

offline modeled
tenant_idpage_pathsection_idjob_type_idbusiness_unit_idcampaign_idzone_idfallback_status

Sensitivity: operational

Offline substitute: Titan Map workbench and readiness coverage score.

Gate: Can be persisted after page-binding review workflow and tenant-level feature flags exist.

servicetitan_syncs

Track async handoffs, retries, idempotency keys, external IDs, next retry time, and operator-visible errors.

offline modeled
tenant_idsource_idsync_typestatusattemptsnext_retry_atidempotency_keylast_error

Sensitivity: operational

Offline substitute: Offline sync queue and support center.

Gate: Requires durable database queue, worker execution, API credentials, and retry policy.

servicetitan_webhook_events

Record verified webhook events with replay protection, raw payload retention controls, and processing state.

api gated
connection_idexternal_event_idevent_typereceived_atsignature_statusprocessing_statusraw_payload

Sensitivity: operational

Offline substitute: Webhook verification requirements in API readiness and marketplace packet.

Gate: Requires webhook signing details, raw body verification, idempotent event storage, and sandbox validation.

servicetitan_drift_findings

Store drift findings, affected URLs, severity, owner, recommended fix, customer review status, and resolution timestamp.

offline modeled
tenant_idfinding_typeseverityaffected_pathservice_titan_referencerecommended_fixstatusresolved_at

Sensitivity: operational

Offline substitute: Monthly drift report.

Gate: Can be persisted after owner workflow and change-approval rules are implemented.

servicetitan_outcome_events

Match local leads and bookings to ServiceTitan bookings, jobs, invoices, payments, campaign attribution, and match quality.

database gated
lead_idbooking_request_idexternal_booking_idexternal_job_idinvoice_idrevenue_centsmatch_quality

Sensitivity: operational

Offline substitute: Outcome report with demo and supplied-export labels.

Gate: Requires durable local IDs, approved outcome source, and customer-visible match-quality labels.

Code module boundaries

src/lib/servicetitan/client.ts

api gated

Token handling, base URLs, ST-App-Key headers, timeout, retry, and ServiceTitan error classification.

Current: API readiness pack and connection readiness matrix.
Do not implement live requests until app credentials, scopes, sandbox access, and secret storage are approved.

src/lib/servicetitan/repo.ts

database gated

Private persistence for connections, taxonomy, bindings, syncs, webhook events, drift findings, and outcomes.

Current: Typed static packets under src/lib/servicetitan.
Requires migrations, row-level access rules, retention policy, and tests against real persistence.

src/lib/servicetitan/map.ts

offline modeled

Map PageToJob leads, booking envelopes, source context, and Titan Map bindings to future ServiceTitan payload candidates.

Current: Booking foundation, source context, handoff simulator, and Titan Map workbench.
Payload writes remain disabled until customer mapping validation and endpoint eligibility are proven.

src/lib/servicetitan/taxonomy.ts

offline modeled

Normalize job types, business units, campaigns, zones, memberships, and pricebook items from manual exports or future APIs.

Current: Manual taxonomy importer.
Read-only API import requires approved scopes and customer module eligibility.

src/lib/servicetitan/verify.ts

api gated

Webhook signature verification, replay protection, raw body handling, and event deduplication.

Current: API readiness and marketplace webhook requirements.
Requires ServiceTitan webhook signing details and sandbox validation.

src/worker/servicetitan-jobs.ts

database gated

Process taxonomy imports, sync queue jobs, outcome matching, drift checks, retries, and disconnect cleanup outside public requests.

Current: Sync queue, drift report, importer, outcome report, and support runbooks.
Requires durable queue tables, idempotency keys, worker scheduling, and operator-visible failure states.

Future route gates

src/app/api/servicetitan/webhook/route.ts

Audience: system
api gated

Receive verified ServiceTitan or Scheduling Pro webhook events.

Current: API readiness webhook requirements.

Requires signing verification, replay protection, raw event persistence, and sandbox proof.

src/app/api/ops/servicetitan/route.ts

Audience: operator
database gated

Expose tenant connection status, sync state, mapping readiness, and last errors to operators.

Current: Connection readiness, sync queue, implementation playbook, and support center pages.

Requires authenticated ops context, tenant-level feature flags, and private persistence.

src/app/api/ops/servicetitan/sync/route.ts

Audience: operator
api gated

Trigger approved taxonomy, outcome, or retry sync for a tenant.

Current: Manual taxonomy importer and sync queue model.

Requires durable jobs, customer authorization, granted scopes, idempotency, and rate limits.

src/app/api/ops/servicetitan/bindings/route.ts

Audience: operator
database gated

Create and update reviewed page, CTA, form, campaign, zone, membership, and pricebook bindings.

Current: Titan Map workbench.

Requires binding persistence, audit log, and customer approval workflow.

SiteConfig boundaries

Public rendering hints

Allowed in SiteConfig
  • - serviceTitanReady flag
  • - booking provider
  • - safe scheduler embed config
  • - public tracking labels
Never in SiteConfig
  • - tokens
  • - app keys
  • - tenant secrets
  • - raw ServiceTitan payloads
SiteConfig can render safe public behavior, but private connection and taxonomy data must stay outside public site data.

Booking provider mode

Allowed in SiteConfig
  • - PageToJob
  • - scheduling_pro
  • - phone
  • - manual
Never in SiteConfig
  • - availability tokens
  • - private dispatch configuration
  • - unreviewed capacity data
The public site can choose a safe booking path while the private system owns sync, retries, and connection state.

Customer proof labels

Allowed in SiteConfig
  • - demo
  • - manual export
  • - matched
  • - needs review
Never in SiteConfig
  • - raw invoice payloads
  • - payment details
  • - customer PII beyond submitted form context
Outcome proof must show source and match quality without leaking operational data into public rendering.

Lead and booking flow

Step 1

Visitor submits a lead or booking request

Current: Existing lead route and structured booking envelope model capture source context.

Future: Insert lead and booking_requests row in one durable request path.

Do not call ServiceTitan synchronously from the public lead route.
Step 2

Business notification fallback fires

Current: Manual notification fallback remains the customer-safe handoff path.

Future: Notification remains active even when API sync is enabled.

No customer lead should be lost because ServiceTitan is unavailable or not connected.
Step 3

Sync queue item is created only when allowed

Current: Offline queue drafts show idempotency keys, statuses, and operator actions.

Future: Persist servicetitan_syncs only for connected tenants with authorized features.

Blocked authorization stops API work, not website operation.
Step 4

Worker processes handoff asynchronously

Current: No worker writes to ServiceTitan in the offline product.

Future: Worker retries transient failures, stores external IDs, and exposes last error to operators.

Retries require idempotency keys and must not create duplicate ServiceTitan records.
Step 5

Outcome proof is matched later

Current: Demo and supplied-export outcomes are labeled by source and match quality.

Future: Approved outcome APIs or reviewed exports update servicetitan_outcome_events.

Uncertain revenue matches stay excluded from closed-loop claims.

Blueprint disclaimers

  • - This blueprint is not a migration, live API integration, webhook receiver, or ServiceTitan marketplace approval claim.
  • - No ServiceTitan credentials, tokens, app keys, or customer tenant secrets are collected by the offline product.
  • - Database-backed and API-backed items require migrations, customer authorization, eligible modules, granted scopes, secure token storage, sandbox validation, and support runbooks.
  • - PageToJob is not affiliated with or endorsed by ServiceTitan.