jbwui — JBW360 Web Portal (React)

Module path: st-integration/jbwui/ · package jbw-client v0.1.0 · Create React App

At a glance

• App: React 18 SPA (CRA), served from S3 + CloudFront at jbw360.jbwarranties.com
• Roles: jbw-admin (JBW staff) · jbw-dealer (contractors) — via Cognito groups
• Auth: AWS Cognito (JWT in localStorage, axios interceptors, 30-min idle timeout)
• Backend: the jbw-sam API Gateway (REACT_APP_AWS_GATEWAY_BASE_URL)
• Biggest footgun: plain npm start runs against production config

Purpose

React portal for JBW staff and dealers, backed by Cognito and jbw-sam.

The web front-end for the JB Warranties ServiceTitan integration (“JB360”, hosted at jbw360.jbwarranties.com). It is an internal/partner portal — login only, no public signup. Two roles via Cognito groups:

• jbw-admin — JB Warranties staff: dashboards, dealer onboarding, user management, admin tools.
• jbw-dealer — HVAC dealers/contractors: their own dashboard, agreement sync, claims.

Core flows: Cognito auth (incl. forced new-password, forgot/reset, idle timeout), a Terms-of-Use acceptance gate between sign-in and any navigation, a 4–5 step dealer onboarding wizard (ServiceTitan or Workiz), agreement sync/matching/approval against ServiceTitan data, claims management (with embedded JB Warranties iframes), and admin/dealer KPI dashboards.

Tech Stack

Concern	Choice
Framework	React 18.3 (CRA / react-scripts 5), JavaScript (no TypeScript)
UI	MUI v5 + MUI X (DataGrid, Charts, DatePickers), Emotion, styled-components
State	React Context (src/AuthContext.jsx) + local state + localStorage; no Redux
Forms	Formik + Yup
Routing	react-router-dom v6 (createBrowserRouter in src/App.js), guard in src/RouteGuard.jsx
Auth	AWS Cognito via amazon-cognito-identity-js (src/services/jbwAuthServices.js)
HTTP	axios shared instance with interceptors (src/services/configs/axiosConfig.js)
Misc	crypto-js (AES), lodash, date-fns/dayjs/moment, export-from-json, mammoth (client-side DOCX→HTML for the Terms panel)

The Terms-of-Use Gate

Added by the July 2026 release. It is not a route — it is an in-page state swap on the sign-in page, which is why the route tables below are unaffected. It sits in front of every login.

Flow. After Cognito auth succeeds, a useEffect on src/pages/SignIn.js:277-300 runs checkTermsAndNavigate():

1. getUserDetails(user.email) → GET user?email= → the tblDealerRegistration row
2. If isTermsAccepted === 1 → handleUserNavigation() (the normal admin/dealer branch)
3. Otherwise → setShowTermsDialog(true), and the login form is replaced in place by <TermsOfUsePanel> inside the same Grid/Paper (SignIn.js:329-333)

The panel (src/components/TermsOfUsePanel.jsx) fetches the .docx named by envConfig.TermsUrl (:25), converts it with mammoth.convertToHtml (:30), and injects it via dangerouslySetInnerHTML (:105). Accept stays disabled until the user scrolls to the bottom (:41-47, gate at :130).

• Accept → updateUserTrems(loginUser.id, 1) → PUT user/updateterms → handleUserNavigation() — SignIn.js:248-266
• Decline → signOut(); the user is bounced

Consent is persisted per dealer-registration row, not per Cognito user. A second entry point — a “Download Terms of Use” Fab — is on every authenticated page via src/components/TopBar.jsx:134-143,323-334.

Backing Lambdas (both untemplated, added the same release):

Call	Lambda	SQL
GET user?email=	jbw-sam/src/jbwgetactivedealerregistrationdetails/	SELECT * FROM tblDealerRegistration WHERE registeredEmail = ? AND isactive = 1 — 404s if no row
PUT user/updateterms	jbw-sam/src/jbwsetusertermsagreed/	UPDATE tblDealerRegistration SET isTermsAccepted = ?, termsAcceptedOn = NOW() WHERE id = ?

The trailing space in user/updateterms is harmless — verified 2026-07-17

src/services/userservice.js:9 reads const url = `user/updateterms `; with a trailing space, which looks like it would request user/updateterms%20 and miss the real resource (/user/updateterms, confirmed via aws apigateway get-resources).

It doesn’t. The space lands at the end of the full URL string, and WHATWG URL parsing — which is what the browser’s XMLHttpRequest.open() applies to whatever axios hands it — strips leading and trailing spaces from the input. The browser sends /prod/user/updateterms. Verified: new URL('user/updateterms ', base).pathname → /prod/user/updateterms.

Worth tidying, but it is not a defect. It would become one if a query string were ever appended after it (the space would no longer be trailing) or if the path were used somewhere that doesn’t parse it as a URL.

Two ways this gate can lock users out

1 — Terms-acceptance failures are swallowed. handleTermsAccept (SignIn.js:249-256) wraps updateUserTrems in a try/catch that only console.errors, then navigates anyway. If the write fails for any other reason — network, 5xx, a DB error — the user gets in, the acceptance is never recorded, and the gate silently returns next login. Nothing surfaces the failure.

2 — The terms document has no source in the repo. Nothing in jbwui/public/ provides the .docx; npm run build does not produce it. If the manual S3 upload is missed, the panel shows “Failed to load terms document.”, Accept stays permanently disabled (it requires the scroll-to-bottom, which requires loaded content), and Decline signs the user out — every un-accepted user is locked out with no path forward.

3 — Admins are gated on a dealer table. getUserDetails runs at SignIn.js:281, before the group !== "jbw-dealer" branch in handleUserNavigation. This is the one worth resolving first. The Lambda 404s when no tblDealerRegistration row matches; the catch (SignIn.js:292-296) sets an error and clears the navigation flags — no navigation, no retry. Unverified: whether jbw-admin users have rows in that table. Resolve with SELECT registeredEmail FROM tblDealerRegistration WHERE isactive = 1 cross-checked against the jbw-admin Cognito group.

Trust boundary: dangerouslySetInnerHTML on an S3 object

TermsOfUsePanel.jsx:105 injects mammoth-converted DOCX HTML into the authenticated origin. Trust rests entirely on the S3 object — write access to that bucket root becomes script injection into the portal.

Routes

Public auth routes live under RootLayout; all business flows sit under /home behind Cognito (RouteGuard).

Public (under RootLayout):

Route	Page	Purpose
/, /signin, /signin/:id	pages/SignIn.js	Cognito login; :id carries encrypted email+code for invited users. Post-login: admins → /home/overview, dealers → onboarding check → dashboard or wizard
/signup	pages/Register.js	Dealer/user registration (verify-then-register)
/forgotpassword	pages/VerifyUser.js	Initiate forgot-password
/resetpassword/:id	pages/ResetPassword.js	Reset with code
/changepassword/:id	pages/ChangePassword.js	Forced new-password challenge

Authenticated (/home, HomeLayout = TopBar + Sidebar):

Route	Page	Purpose
/home, /home/overview	pages/Overview.js	Admin dashboard: KPI cards, latest onboardings, Admin Tools console
/home/dealerdetails[/:id]	pages/DealerDetails.jsx	Dealer dashboard: info, KPIs, tenants, agreements/claims/invoices tabs
/home/onboardinghome	pages/Onboarding.js	All dealers grid + “Onboard New Dealer” + per-dealer sync
/home/agreementssynchome	pages/AgreementsSyncHome.jsx	Agreement sync: Map Location / Pending Approval / Approved tabs, Sync Data button
/home/userslist	pages/UsersList.js	User management
/home/transactionlog	pages/TransactionLogs.jsx	Transmission/sync logs (from tblTransmissionDetails)
/home/jbwclaims	pages/JBWarrantiesFrame.jsx	Embedded JB Warranties claim360.aspx iframe
/home/todohome[/:id]	pages/ToDoHome.jsx	Email-notification inbox (sidebar link currently commented out)
/home/settings	—	Stub (route renders an MUI icon; pages/settings.js exists but is unused)
/home/onboarding/*	pages/onboarding/	Wizard: ClientName → ClientLocation → ClientPlatform → (ST: ClientCustom → ClientId) / (Workiz: ClientAccountId) → CLientConnect

Auth & Session Behavior

• Cognito ID token (JWT) stored in localStorage["token"]; role read from cognito:groups[0] (any group ≠ jbw-dealer is treated as admin).
• Axios request interceptor attaches Authorization: Bearer <token> and drives a global loader via api-loading events.
• Response interceptor: on 401, refreshes the Cognito session once (queueing concurrent requests) and retries; on failure fires session-expired → re-auth dialog.
• AuthContext proactively refreshes tokens when <5 min to expiry (60 s check loop) and enforces a 30-minute idle timeout (src/hooks/useIdleTimer.js).

Backend Integration

Everything business-related goes to one place — the jbw-sam gateway; the only non-gateway traffic is deep links and embedded JB Warranties iframes.

All API calls go through the shared axios instance with baseURL = REACT_APP_AWS_GATEWAY_BASE_URL (the jbw-sam API Gateway). Service modules live in src/services/ — the complete endpoint-per-module list is in the code reference.

External (non-gateway) integrations:

• ServiceTitan deep links: REACT_APP_ST_URL; Workiz job links: REACT_APP_WZ_URL.
• JB Warranties member portal iframes (hardcoded jbandassociates.biz URLs): claims console (claim360.aspx), claim dialog (jb360claim.aspx, with postMessage origin check), agreement PDF (customeragpdf.aspx), payment link.
• Release-notes PDF from REACT_APP_RELEASE_NOTE_URL.

Quirk: several callers branch on APP_ENV === "Development" to read res.data.body vs res.data (API Gateway proxy wrapping differs between stages).

Environment Configuration

CRA REACT_APP_* vars, baked into the bundle at build time. Files: .env (default = Production values), prod.env, stage.env; selected via env-cmd in npm scripts.

Variable	Purpose
REACT_APP_MYVARNAME	Env label (“Production”/“Staging”) — drives staging banner + dev response unwrapping
REACT_APP_USER_POOL_ID / REACT_APP_CLIENT_ID	Cognito user pool / app client
REACT_APP_AWS_GATEWAY_BASE_URL	Backend API Gateway base URL
REACT_APP_ST_URL / REACT_APP_WZ_URL	ServiceTitan / Workiz deep-link bases
REACT_APP_RELEASE_NOTE_URL / REACT_APP_RELEASE_NOTE_MONTH	Release-notes PDF + label
REACT_APP_ISSTAGING	Staging flag (YES/NO)
REACT_APP_TERMS_DOC_URL	Site-root path to the Terms-of-Use .docx fetched by the sign-in consent panel and the TopBar download. Identical value in all three env files (line 10 each); surfaced as envConfig.TermsUrl (src/services/configs/envConfig.js:6)

Prod points at go.servicetitan.com and the prod API Gateway stage; stage points at integration.servicetitan.com and the dev stage.

Run / Build / Deploy

Local dev — ⚠ the default .env holds production values:

npm install
npm start        # dev server :3000 — Production config!

Staging dev — the safe option for day-to-day work:

npm run start:stage    # staging config (stage.env), :3006

Production build:

npm run build          # default .env
npm run build:prod     # explicit prod.env bundle

Staging build:

npm run build:stage    # stage.env bundle

Deployment note: there is no deploy config in the repo — the CRA build/ output is synced to the S3 bucket and served via the CloudFront distribution defined in jbw-sam/template.yaml (manual upload + invalidation). npm scripts use Windows set PORT= syntax, so they assume a Windows workstation.

Second manual deploy step — easy to miss, breaks login if you do

The Terms-of-Use .docx named by REACT_APP_TERMS_DOC_URL is not in the repo and is not produced by npm run build. It must be uploaded to the bucket root separately. If it is missing, the login gate locks out every un-accepted user.

Caveats / Known Issues

Security / trust boundary

• Hardcoded AES key in src/utils/encryption.js (used for the signin/reset URL payloads) — obfuscation only, not real encryption security.
• .env, stage.env, prod.env are committed to the repo (Cognito pool/client IDs and gateway URLs; not strictly secret since CRA bakes them into the public bundle, but part of the trust boundary worth knowing).

Operational / maintainability

• Default npm start runs against production config — use start:stage for day-to-day work.
• .env and prod.env are near-duplicates that drift (release-notes URL differs).
• No tests (@testing-library/* present, no test files); README is CRA boilerplate.
• Unused deps: aws-amplify, react-google-recaptcha. Stub /home/settings route.
• Dead component: src/components/TermsOfUseDialog.jsx is never imported. It duplicates TermsOfUsePanel but hardcodes the terms path instead of reading envConfig.TermsUrl (:14), so it would silently drift from the env config if ever wired up.
• GlobalLoader’s progress bar is fake — variant="determinate" driven by Math.random() * 10 increments on a 500 ms interval that runs unconditionally for the app’s lifetime (GlobalLoader.jsx:6-21, [] deps, no loading check). It is also color="error" (:42), so every normal API call renders a red bar that reads as failure.
• A typo makes a control never fire: disabled={ctxStEquipments.lenght >= allowedUnits} (AgreementEquimentDialog.jsx:1092) — .lenght is undefined, so the comparison is always false and Add Equipment is never disabled by this path. The July 2026 release edited this line without fixing the typo.

Renewal & equipment rules are undocumented at baseline

Neither this page nor the code reference describes the renewal flow, isRenewalPlan, parent SKUs, or “Original Plan Id” — and most of that machinery predates the July 2026 release. What the code does today:

• Allowed units come from the selected product (param.maxUnits), not agreement.equipmentUnits — AgreementEquimentDialog.jsx:71,499,1074, consumed at EquipmentsTable.jsx:49,143
• Unit-limit enforcement is dealer-only — admins are explicitly exempt (AgreementEquimentDialog.jsx:104-107,719-724)
• Installed-date validity is SKU-configurable — installDateValidity (default 2 years) from the product API (:79,387-389,508-510); replaced a hardcoded 2-year minDate (:960)
• Renewal parent-SKU eligibility — if the current originalPlanId is not in the new product’s parentProducts list, the dialog blocks with “Original coverage purchased is not eligible for renewal…” (:515-522)

The intended behaviour needs a product owner to confirm; the above is only what the code does.

See Also

• Code reference — jbwui (components & services)
• System overview