Complete technical documentation for the JB360 ServiceTitan integration — the system connecting HVAC dealers’ field-service CRMs (ServiceTitan, Workiz) to the JB Warranties platform. Prepared for handover to a new engineering team.
Sources: static analysis of jbandassociates/st-integration main @ f16313c (“Renewal Functionality changes”), a live read-only verification of AWS account 660537473428, and a read-only inspection of the production database — all July 2026. See analysis-process.md for method and trust boundaries.
| 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 |
| 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: ~65 templated Lambdas, 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 |
| 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 |
| Doc | What it covers |
|---|
| aws/README.md | Headline findings (template drift, dev environment, repo-less functions) + 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/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 |
| Doc | |
|---|
| analysis-process.md | How these docs were produced: method, model, what was and wasn’t verified |
- 01-overview.md — the mental model (10 min)
- aws/README.md — how reality differs from the repo (5 min)
- aws/database.md §Stored Procedures — where the business logic actually lives
- The module doc + code reference for whatever you’re changing
- aws/deployment-history.md — before your first deploy (drift warning + authorizer step)
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)