st-integration — Documentation

Complete technical documentation for the JB360 ServiceTitan integration — the system connecting HVAC dealers’ Field Service Management Systems (FSMs) — ServiceTitan, Workiz — to the JB Warranties platform.

Sources: static analysis of jbandassociates/st-integration main @ 1ce5b3e (“Terms of use, Renewal fixes and July stability release changes”), a live read-only verification of AWS account 660537473428, and a read-only inspection of the production database — July 2026, refreshed 2026-07-17. See analysis-process.md for method, trust boundaries, and the corrections log.

How to Read These Docs

Three styles of box appear throughout, in increasing order of weight:

Info panel

Neutral orientation — “At a glance” summaries, code maps, and reference pointers. Read these first on any page.

Caution — architecture & reliability

Caveats you must know before changing things: behavior that lives outside the repo, out-of-band wiring, drift, code defects, silent failure modes.

Danger — security & operational risk

Genuine risk: hardcoded credentials, SQL injection surface, data-loss paths (e.g. queues without DLQs). Every one of these is a real finding, not boilerplate.

Table of Contents

Start here

Doc	What it gives you
01-overview.md	The mental model: what the system does, architecture diagram, the five end-to-end flows (onboarding, matching, agreement creation, per-tenant sync, claims), environments, cross-cutting concerns

The four codebases (repo: st-integration/)

Doc	Module	Stack
02-extraction.md	extraction/ — per-tenant ServiceTitan sync worker (invoice/equipment pull, agreement/claim push), SQS-triggered	Java 17 / Spring Boot 3 Lambda
03-jbw-sam.md	jbw-sam/ — backend: 63 templated Lambdas (+44 untemplated), API Gateway, SPA hosting, sync orchestration	AWS SAM / Node.js 20
04-jbwui.md	jbwui/ — JB360 portal (admin + dealer roles): onboarding wizard, match/approve grids, claims	React 18 / MUI / Cognito
05-jbw-api.md	jbw-api/ — vendor-facing integration API over jbwst, deployed as the jb360dealer Lambdas. No IaC	Java 17 / Spring Boot 3.5 Lambda

Code references (find the exact file)

Doc	Granularity
code-reference/extraction-code.md	Class-by-class: services, repositories, entities, DTOs, config
code-reference/jbw-sam-code.md	Per-Lambda: full method+path→function route table, sync engine, non-templated functions
code-reference/jbwui-code.md	Per-page/component group, every service module’s endpoints

External integrations (integrations/)

Doc	What it covers
integrations/servicetitan.md	The ServiceTitan contract: app registration (“JB-360” v5) + scopes, per-tenant OAuth model, full endpoint inventory, what gets written into ST, onboarding requirements, sync cadence, pitfalls
integrations/workiz.md	The Workiz contract: shared static API token, the endpoints in repo code, job→invoice pull and write-back push, onboarding via Account ID, the untemplated prod pull/push Lambdas, known gaps and bugs

The live AWS environment (aws/)

Doc	What it covers
aws/README.md	Headline findings (template drift, dev environment, missing IaC, the scaffolded prod vendor API) + follow-up list
aws/lambda-inventory.md	All 206 deployed functions, extraction’s real config, template-vs-deployed diff, CloudFormation stack staleness
aws/schedules-and-queues.md	All 20 EventBridge schedules (the sync heartbeat) and SQS queues/DLQ wiring
aws/apis-auth-hosting.md	API Gateways + verified authorizer state, Cognito pools, CloudFront/S3, RDS instances & proxies, VPC/subnet/NAT layout
aws/s3-buckets.md	The 13 JB360 S3 buckets (hosting, deploy jars, sync CSVs, vendor-API store) detailed, with out-of-scope buckets listed by name
aws/database.md	The jbwst schema: 44 tables with row counts, 12 views, all 10 stored procedures explained (matching engine, agreement factory, claims detection, archival)
aws/deployment-history.md	Jan-2024 origin (Maktix handover), manual deploy procedure per module, release cadence

Meta

Doc
analysis-process.md	How these docs were produced: method, model, what was and wasn’t verified

Known Issues Index

Security/maintenance items discovered during documentation (details in the linked docs):

• Hardcoded secrets — ST app key + JBW API token in jbw-sam/template.yaml & samconfig.toml; Workiz token in handler source; AES key in jbwui/src/utils/encryption.js; plaintext dev DB creds in extraction/src/main/resources/application.yml (03, 04, 02)
• Template drift — CloudFormation untouched since May 2024; 40 prod Lambdas outside the template, ~12 with no source in the repo; a plain sam deploy would revert live changes (aws/lambda-inventory.md)
• Auth attached out-of-band — the template deploys API Gateway open; jbwapiauthorizerupdate must run post-deploy (currently attached, verified) (03, aws/apis-auth-hosting.md)
• String-interpolated SQL in jbw-sam handlers and extraction outbound updates (03, 02)
• Tokens printed to logs in extraction (02)
• No DLQ on dev/Workiz queues; duplicate daily schedules on two prod functions (aws/schedules-and-queues.md)
• Template bugs — indentation break (~lines 1511–1654), misnamed !Refs, route collision (03)
• jbw_agreementSyncList stored proc looks defective as written — verify it’s not the live path (aws/database.md)