Code Reference — extraction

High-level, class-by-class guide.

All paths relative to st-integration/extraction/src/main/java/com/maktix/jb/extraction/.

Code map

• Entry points: ExtractionApplication.loadInvoices() (Lambda/SQS) · InvoiceController (POST /api/invoices/load, local dev)
• Core orchestrator: JbDataLoadService → does the work in InvoiceService
• Biggest class: InvoiceService (~1,300 lines) — all ST pull and push logic lives here
• DB access: Spring Data JPA repos for entities + JbRepository (raw JdbcTemplate) for everything that doesn’t fit
• Logs: per-run buffer in LogContext → persisted to tblTransmissionDetails.logDetails

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

Start with InvoiceService — it is where nearly every change to this module lands.

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.

Risks / notable quirks

• InvoiceService is oversized (~1,300 lines) and mixes concerns: inbound extraction and the outbound callServiceTitan push live in one class — a change to either risks the other.
• JbRepository mixes raw SQL (JdbcTemplate, some string-built) alongside the JPA repos — check both layers when tracing a table write.
• Run logs are persisted to audit tables (LogContext → tblTransmissionDetails.logDetails) — anything logged, including tokens printed via System.out, can end up in the database (see module caveats).

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

The JPA repos are unremarkable; JbRepository is the row to read — it holds the raw SQL that drives the outbound push.

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.