Code Reference — extraction

High-level, class-by-class guide. All paths relative to st-integration/extraction/src/main/java/com/maktix/jb/extraction/.

Application & Entry Points

Class	Responsibility
ExtractionApplication	@SpringBootApplication and the production entry point. Defines the Lambda bean Function<SQSEvent,String> loadInvoices(): parses each SQS record body into a Tenant (Gson) and delegates to JbDataLoadService.loadInvoices.
controller/InvoiceController	@RestController, POST /api/invoices/load. HTTP mirror of the Lambda bean for local/dev invocation — accepts an SQSEvent-shaped JSON body.

Services

Class	Responsibility
service/JbDataLoadService	Thin orchestrator. Calls InvoiceService.loadInvoices(tenant), then persists the audit: updates tblTransmissionDetails for the tenant and inserts a tblTransmissionDetailsHistory row including the captured run log.
service/InvoiceService	The core (~1,300 lines). Everything ServiceTitan: paged invoice extraction and mapping to entities, contact enrichment (batched, 250 location ids per call), installed-equipment pulls, and the outbound callServiceTitan(...) push (agreements → location tags/custom fields/notes + equipment warranty dates; claims → job PATCHes). Also applies the inbound transforms (name splitting, truncation, price summation, missingEquipment / isSeaCoast flags).
service/TokenService	ServiceTitan OAuth2 client-credentials flow. Builds the token request against ST_AUTH_URL, adds the ST-App-key header from ST_APP_KEY, and produces authenticated headers for all subsequent calls.

Configuration

Class	Responsibility
config/JpaConfiguration	Builds the real (Lambda) datasource in code: MySQL URL from DATABASE_ENDPOINT/DATABASE_PORT, username from the Secrets Manager secret (SECRET_NAME), password from a generated RDS IAM auth token. Also configures the JPA entity manager (Hibernate, MySQL dialect, entity scan of this package).
config/PersistenceConfig	JPA/transaction wiring companion to JpaConfiguration.
config/RestConfig	RestTemplate bean using the Apache HttpClient 5 request factory.

Repositories

Class	Responsibility
repository/InvoiceRepository, InvoiceItemRepository	Spring Data JPA repos for tblInvoice / tblInvoiceItem (upsert flow diffs existing vs new by id).
repository/AgreementRepository, AgreementEquipmentsRepository	JPA repos for tblAgreement / tblAgreementEquipments.
repository/TransmissionDetailsRepository, TransmissionDetailsHistoryRepository	Audit tables.
repository/JbRepository	Raw JdbcTemplate queries that don’t fit JPA: batch phone/email UPDATEs, location/agreement id lookups for equipment pulls, and the outbound read queries (getAgreementDetails — join of tblAgreement+tblAgreementEquipments+tblProducts filtered to agreementStatus='PAID' AND isSentToST=0; getClaimsDetails — isReadyForST=1 AND isSentToST=0; custom tag/field lookups from tblTenantCustomTags/tblTenantCustomFields).

Model

JPA entities (map 1:1 to jbwst tables — standard physical naming)

Entity	Table	Notes
Invoice / InvoiceItem	tblInvoice / tblInvoiceItem	Inbound invoice landing zone
Agreement / AgreementEquipments	tblAgreement / tblAgreementEquipments	Warranty agreements + equipment rows (dataReceivedFromST flag gates ST pulls)
Claims	tblClaims	isReadyForST / isSentToST flags gate the outbound push
TransmissionDetails / TransmissionDetailsHistory	audit tables	Counts, sync status, start/end, stored run log

DTOs

DTO	Purpose
Tenant	SQS message body: tenantId, dealerId, ST OAuth clientId/clientSecret, batchId, syncStartDate, invoiceStatus
AccessToken, AwsSecret	OAuth token response; Secrets Manager secret shape
AgreementDetails, AgreementUpdate, AgreementEquipmentUpdate, AgreementLocationNotesUpdate	Outbound agreement push payloads
ClaimsUpdate, ServiceTitanUpdateInfo	Outbound claim push payloads
CustomField, CustomFieldDetails, CustomTagDetails	ServiceTitan tag/custom-field merge structures
InvoiceResponse	Paged ST invoice response wrapper

Utilities

Class	Responsibility
util/JbConstants	Status constants: BATCH_PROCESS, SUCCESS, FAILED, SERVICE_TITAN.
util/JsonUtils	Null-safe Gson helpers (getStringValue, getIntegerValue, getDateTimeValue, getAsBigDecimal).
util/LogContext	In-memory per-run log buffer (“INFO:”/“ERROR:” lines) that ends up stored in tblTransmissionDetails.logDetails.