Analysis Process

How this documentation set was produced, for reproducibility and for judging how much to trust it.

Summary

Date	2026-07-07
Source analyzed	jbandassociates/st-integration, branch main, commit f16313c (“Renewal Functionality changes”)
Tooling	Claude Code (CLI) with multi-agent orchestration
Model	Claude Fable 5 (claude-fable-5, Anthropic Claude 5 family) — same model for the orchestrator and all subagents
Method	Phase 1: static source analysis. Phase 2: read-only verification of the live AWS environment and production database schema. No code was executed and nothing was modified.

Method

The analysis ran as one orchestrating session plus three read-only explorer subagents in parallel, one per subproject:

Subagent scope	What it read	Effort
extraction/	pom.xml, all Java source (src/main/java/...), application.yml, HELP.md	~71k tokens, 25 tool calls, ~2.5 min
jbw-sam/	template.yaml (all ~1,750 lines), samconfig.toml, events/, Lambda handler sources under src/	~100k tokens, 33 tool calls, ~6.5 min
jbwui/	package.json, env files, router, AuthContext, all src/services/*, pages/components/layouts	~106k tokens, 68 tool calls, ~4 min

Each subagent was prompted to return structured factual notes with file paths for every claim (not prose), covering: purpose, tech stack, entry points, external systems, configuration, data flow, build/run/deploy, and error handling. The orchestrator then cross-referenced the three reports (e.g. matching the getTenantInfo SQS hand-off in jbw-sam to the extraction Lambda’s SQS trigger, and jbwui service endpoints to jbw-sam API routes) and wrote the docs.

Supplementary inputs gathered by the orchestrator directly: repo git log (release cadence), top-level directory structure.

Conventions Applied

• Secrets masked: hardcoded credentials found in source (ServiceTitan app key, JBW API token, Workiz token, Cognito pool IDs, AES key, dev DB password) are referenced by location in these docs but their values are not reproduced.
• Every architectural claim traces to a file path in the repo; the code-reference docs are the path index.
• Discovered defects (template indentation bug, name-mismatch !Refs, route collision, injection-prone SQL, logged tokens) are reported as-found under “Caveats / Known Issues” in each module doc — none were fixed as part of this analysis.

Phase 2 — Live AWS & Database Verification (added 2026-07-07)

After the source-only pass, the deployed environment was verified with read-only AWS CLI calls (list/get/describe only; no drift-detection run, nothing modified) against account 660537473428: Lambda inventory + event source mappings, EventBridge schedules, SQS queue attributes, API Gateway authorizers and sampled method auth, Cognito pools, CloudFormation stacks, S3/CloudFront, EC2 network resources (VPCs/subnets/SGs/NAT), RDS instances/proxies/proxy targets. The production database was inspected read-only (information_schema tables/views/routine definitions only — no data rows queried beyond counts). Historical context from the January 2024 deployment notes went into aws/deployment-history.md. Results: the aws/ section.

Known Limitations

• The source docs (01–04) are static analysis. Runtime facts live in aws/; the account has drifted far from the repo (CloudFormation last ran May 2024), so docs 01–04 describe the code and aws/ describes reality.
• Where the notes/code and the live account conflicted, the live account won (e.g. prod runs in the “JBW Network” VPC, not the default VPC; the prod DB instance is jbw-st-integration; there is no jbw_workiz_dataSync procedure).
• CloudWatch metrics/error rates and SES sending state were not reviewed.
• In docs 01–04, database details are inferred from entity classes and SQL in handlers; the verified schema lives in aws/database.md.
• Coverage of the ~72 jbwui components and ~30 non-templated jbw-sam source dirs is at the responsibility level, not line-by-line.
• The docs describe commit f16313c; the repo evolves by quarterly release commits, so re-run the analysis after each release.

Reproducing / Refreshing

1. Pull latest main in st-integration.
2. Launch three parallel read-only explorer subagents with the same per-module scope and reporting prompts as above.
3. Cross-reference the reports, update the module docs and code references, and refresh the commit hash and date in this file and README.md.