Architecture
& Design

Tech profile (canonical) First pass

Job record (canonical) First pass

08Recommendation engine (Sales) First pass

Runs entirely on the device — no internet call — so the recommendation works with no signal. Lives inside the Sales app.

Sizing (heuristic, not a Manual J)

Good / Better / Best tiers (fixed reference table)

Flags

Per-system: equipment age 15+ (end-of-life) or 12–14 (aging); condition Failed; gas furnace → heat-pump conversion candidate. Whole-home: heat-pump rec + small panel (100A or 125A, or no open breaker spaces) → panel-upgrade flag; Poor/Fair ductwork and line-set marked Replace → scope items; humidity/dust → indoor-air-quality opportunity; hot-cold/uneven → zoning opportunity; maintenance-agreement prompt always appears.

Sizing is a check, not an authority. The heuristic estimate is used to cross-check the installed equipment: when the estimate and the existing tonnage disagree (by ~1+ ton), or confidence is low (square footage missing/suspect, conflicting inputs), the survey raises an "office to verify sizing" flag rather than presenting a confident number. It confirms a sane match or routes the questionable ones to the office — it never stands in for a proper load calculation.

Electrical panel field. Captured in Site Conditions as one of 100A · 125A · 150A · 200A · 200A+, plus an open-breaker-spaces check. The panel-upgrade flag fires for an electrification (heat-pump) recommendation when the panel is 100A or 125A, or when there are no open breaker spaces; 150A and up generally clear unless spaces are full.

Savings Profile (estimate) Planned

A directional estimate of annual energy cost, current setup vs. each proposed tier — the value story for the close. Computed on-device (offline) from the energy profile (§07), the sizing estimate above, and the confirmed utility rate. It is an estimate, never a guarantee.

Comparison baseline (selectable)

The salesperson picks what the proposed system is measured against from a dropdown, so the screen always reads "estimated savings vs. [baseline]." Options appear only when they apply:

One engine, two tools. This is the same calculation the Repair-vs-Replace Advisor (Stage 2 §B8) uses — its "replace" column is simply this panel with the Repairing your current system baseline selected. The proposed tier is switchable too; changing either side recomputes the range at its confidence tier. Honest framing (Safety): the baseline is always stated in words, every option uses real figures, and no baseline is hidden to inflate the number.

Estimate, not a guarantee (Safety condition). Every figure is shown as a range with its assumptions visible (fuel rate, usage, efficiency, solar offset), labeled an estimate, and never called "guaranteed" — the same discipline as the sizing heuristic. Even the top tier projects future savings, so it stays an estimate; more data only narrows the band. The salesperson can adjust any assumption, and figures are tech-verifiable before the customer sees them.

Rate vintage & escalation (the asterisk)

Because the rates data lags (§06), the Basis tier must be honest about when the rate is from. On the recommendation/presentation screen, every Basis-tier dollar figure carries an asterisk tied to a footnote stating the source and the as-of date — and the gap to today:

So a 2024 rate viewed in 2026 reads, e.g., "* Based on 2024 EIA rates; prices are up ~10% since, so real savings are likely higher." Two deliberate choices: the headline number is computed on the as-of rate (the conservative figure — we don't silently inflate the rate to bump savings), and the escalation appears as a stated, EIA-trend-derived note so the salesperson can speak to it honestly. Framed this way the vintage is a strength — the estimate is conservative, and rising prices make the case better, not worse. When the customer supplies bills, the figure switches to actuals and the asterisk goes away.

Headline cases the MVP targets first: propane → heat pump (large, defensible delta) and solar-offset electrification (PV covers much of a new heat pump's load). Battery presence informs the resilience/outage talking point and may affect incentive eligibility, but is not part of the cost math in the MVP.

Confidence tiers

The number the customer sees comes in three levels — the more real billing data they share, the tighter the band. The level is set by how many months of bills parsebill (§06) returns, and the label on screen states it plainly.

Always available, never required. Basis needs nothing from the homeowner and works offline, so a number is always there. Better and Best are opt-in upgrades via parsebill — bills can be added on-site or emailed after the visit, and the survey never blocks waiting for them. Privacy stays bounded per the parsebill rules (usage/cost only, image never persisted).

Customer goals → recommendation framing Planned

Captured on the Comfort & Needs step as a multi-select with one marked primary. Goals don't change the engineering (sizing, tiers, flags are unchanged) — they decide which tier the screen leads with and which story gets top billing, so the same survey lands differently for a price-driven buyer than a comfort-driven one.

Honest framing, not steering. Goals reorder emphasis, never hide options — all tiers and the real numbers stay visible. A price-driven customer still sees the value case; a value-driven one still sees the cheap option. This keeps the "Quality Without an Upsell" brand intact while meeting the customer where they are.

Pricing the job Planned (prototype: AI estimate)

The quote auto-builds from the chosen tier — each tier is assembled from components at quote time (slower than fixed packages, but more accurate). It estimates the parts the job actually needs, not a generic list:

• Line set — reuse the existing one if it's compatible and sound, or price a new run.
• Tear-out & disposal of the old equipment, plus hazardous handling where flagged (old-refrigerant recovery; possible asbestos in pre-1980 homes).
• Equipment, labor, materials, consumables, and permit.

It asks about access & special conditions that move the price — a new line set fished through a finished basement, work in a crawlspace or attic, etc. — pre-filling what Site Conditions already captured (access easy/moderate/tight) and asking only for what's missing.

For the prototype, the estimate action (§06) returns this as a single all-in package price (with a range), web-researched and labeled rough — e.g. a complete furnace + AC for a ~2,000 sq ft Front Range home estimates around $11,000–$15,000 all-in. When pricing import is built, the same call is served from the Pricing tool: price-book cost + company-entered labor + company-entered markup → sell price, with cost/margin hidden from the salesperson per §11.

Adjustments & scope add-ons

Flagged scope items are preset, priced add-ons the rep can toggle on — panel upgrade, ductwork replacement, new line set, IAQ, zoning. Beyond the presets, an "Other" entry lets the rep describe a need in their own words; the tool prices it from company labor rate + company markup + AI-estimated materials (all AI-estimated in the prototype; labor and markup come from config once entered).

Proposal & close Planned

The survey now ends in a customer-facing proposal that closes the deal, not a text summary. It does four things: present the proposal, show financing, capture acceptance, and hand off the scheduled job.

• Customer-facing proposal — a clean, shareable document (PDF) with the recommended tier(s), the savings profile, and the full price breakdown.
• Price breakdown — what the customer pays, the deposit due at acceptance (default 60%, office-configurable), the balance due at completion (default 40%), the estimated rebates, and the net out-of-pocket total. That net number is the headline.
• Financing (third-party, entered) — credit applications are not submitted by this tool; that happens in the lender's own application. The rep enters up to two financing options back onto the proposal, each with an estimated monthly payment, term (years), and APR, shown side by side. Office can maintain the list of available lenders to pick from. Every financing figure carries a conditional disclaimer — "estimated, subject to credit approval."
• E-signature & acceptance — captured in the tool.
• Schedule / handoff — on acceptance the job is marked "ready to install" and the complete package (survey, proposal, photos, signature, deposit, financing selection, scope) is pushed to the office. The office confirms equipment and availability and sets the date — the rep doesn't book a firm slot. The office backend (a later build — §14) syncs the job to a Google job calendar and to QuickBooks for the deposit invoice.

Pricing visibility & commission (roles). The customer and salesperson see the sell price and the out-of-pocket total. The salesperson may discount only down to an enforced minimum (a floor that protects margin) and never sees the cost or the margin. Commission scales with the sell price — closing higher earns more; discounting toward the floor (never below it) earns less. Only the sales manager and office see the exact system cost and margin. This requires the roles/accounts model (deferred — §14); until logins exist the app can enforce the floor and hide cost, but true protection arrives with accounts. Live prices come from the Pricing tool once wired (Stage 3).

Office handoff & integrations Planned. The accepted job pushes to the office backend, which integrates with a Google job calendar (the install slot once the office confirms) and QuickBooks (the 60% deposit invoice, 40% on completion). Actual payment is handled in QuickBooks/office, not the field app. The Google and QuickBooks OAuth credentials live server-side in the office backend, never in the field app — same principle as the API keys (§11). Deposit split and the lender list are office-configurable.

Proposal document layout Planned

The customer-facing PDF, in order — Empower-branded (charcoal header, cobalt accent, orange action), single page:

1. Header — Empower wordmark + "Quality without an upsell," proposal #, date, valid-through date.
2. Customer & property, prepared-by rep.
3. Recommended system — the goal-driven primary tier, highlighted, with key specs and a one-line why.
4. Good / Better / Best — three columns side by side, recommended one outlined, each with spec + price (lets the customer trade up/down).
5. What's included — equipment, install, removal & disposal, line set, permit, startup/testing, warranty, rebate paperwork.
6. Your investment — system price, estimated rebates (−), net out-of-pocket (headline), deposit (60%) at acceptance, balance (40%) at completion.
7. Estimated savings — annual figure vs. the selected baseline, carrying the dated-rate asterisk.
8. Financing — the two entered options (monthly / term / APR), "subject to credit approval."
9. Rebates & incentives — programs with level + estimated amount, "amounts subject to verification."
10. Acceptance — signature + date; signing accepts and authorizes scheduling.
11. Fine print — estimates not guarantees; savings on dated rates; financing subject to approval; rebates to verify; sizing preliminary/confirmed before install; proposal valid 30 days (configurable).
12. Footer — contact, license #.

Never on the customer document: cost, margin, or commission. The proposal shows sell price, rebates, net out-of-pocket, deposit/balance, savings, and financing only — the internal figures stay in the rep's private screen and the manager/office views (§11). Optional second page: site photos + detailed scope/terms.

09Credential model & gate evaluation (Repair) First pass

Two layers plus an override flag, all admin-set. Gates govern what work is permitted; level governs how much guidance and override eligibility; the override flag clears specific conditional stops. Evaluated authoritatively in the Repair app.

Gate principle. Measurement & diagnosis are never gated (3-phase included) — only hands-on modification carries a gate. Combustion-dependent work on any fuel-burning unit also requires G2. Gates stack (a 3-phase HP contactor swap needs E2; a boiler combustion tune needs B1+G2). Gates are admin-set; a tech cannot self-grant.

10Safety enforcement in app logic First pass

Three mechanisms, all enforced in the Repair app — never left to the model.

• Inline caution — advisory text within a step; never blocks.
• Credential gate — when a repair step needs a gate the tech lacks: block the hands-on action, preserve the diagnosis, escalate. Measurement is never gated.
• Hard stop — halts the flow for danger / out-of-scope and routes to a defined action (shut down, red-tag, advise, escalate).

Universal stops apply to everyone regardless of credential. Conditional stops halt baseline/mid techs, but a tech with the matching gate and the conditionalOverride flag may proceed after an on-screen acknowledgment that is stamped to the job with the Tech ID.

The Repair-vs-Replace Advisor is subordinate to safety. The advisor (Stage 2 §B8) runs only after any hard stop has been actioned and never overrides one. A cracked heat exchanger is red-tagged and the unit shut down whether or not a replacement is sold; the replace conversation happens after the safety action, never instead of it.

11Security & privacy

• Keys server-side only. RentCast & Anthropic keys live as Vercel environment variables — never in any app or repo.
• Optional access gate. An APP_TOKEN env var requires every request to send a matching token, blocking casual use of the endpoint.
• CORS. Currently open so the apps can reach the function; tighten to your app domains once stable. With the split, each tool app has its own origin — CORS can be scoped per app.
• Spend limits set in both the RentCast and Anthropic dashboards as a hard backstop.
• Third-party data handling. During a lookup, the address goes to RentCast and Anthropic, and nameplate/step photos go to Anthropic, processed under their own terms. The tool deliberately does not look up occupant personal information.
• Customer-app boundary. The separate customer build never loads cost, margin, inventory, or credential logic; it reaches the system only through the backend.

Roles & accounts Planned

Three roles, office-assigned. Sensitive values are filtered at the source for the role — in production the backend never sends cost/margin to a salesperson's session, so hiding isn't just a UI toggle. (In the on-device prototype, roles are set locally for testing and the app gates the view; true enforcement arrives with the central store + login.)

• Auth. Prototype: email + PIN (email identifies the user/org; a short PIN unlocks on a shared truck tablet). Production: a hosted auth provider with email/password or org SSO (Google/Microsoft) as the real identity, plus the per-user PIN for fast field switching — not a hand-rolled auth system.
• Role assignment. Office/admin only — a salesperson can't promote themselves (same principle as the Repair credential model). Prototype keeps roles device-local for testing.
• Salesperson's private screen. A rep-only view the customer never sees, showing this deal's incentive and the rep's own payout — never other reps' or org-wide numbers. A quick toggle returns to the customer-facing view so it's never shown by accident.

12Storage & persistence

The core storage abstraction uses the platform store when present (Claude preview) and falls back to the browser's localStorage on the hosted site, so surveys and trouble calls persist on the device across sessions. Data is per-device and per-browser — not synced to a central server. Photo thumbnails (~200px) are persisted within each record; full-resolution images are held in memory only for the session and sent once for the AI read, never saved.

Data sharing (central store) Planned

For a manager to see a rep's deals, records must live beyond the device — designed to share without heavy transfer:

• Records are light. A survey is compact JSON (text + thumbnail/photo references), cheap to sync. The weight is photos, handled separately.
• Photos to object storage, once. Full-res images upload to object storage and are referenced by URL; only the ~200px thumbnails travel with the record, and full images load on demand.
• Incremental, scoped sync. Devices stay offline-first and sync only new/changed records (deltas) when connected — scoped by role, so a rep pulls only their own deals, a manager the team, office everything. No bulk transfer.

13Cross-tool integration (planned) Planned

With apps split, the planned Stage 3 links become explicit contracts rather than in-process calls. Each is a read across a boundary, mediated so isolation holds.

• Pricing → Sales. In the prototype, Sales prices the job with the estimate action (AI/web, all-in). In production, the same call is served by the Pricing tool — price-book cost + company labor + markup → sell price — with cost/margin hidden from the salesperson (§11). The contract stays the same, so wiring Pricing is a drop-in; Sales degrades gracefully (shows the rec without prices) if pricing is unavailable.
• Inventory → Tech & Customer. Repair reads part availability when a part is needed; the customer app may read availability for scheduling. Read-only, by SKU.
• Pricing ↔ Inventory. Linked by SKU as one source of truth.
• Repair → Sales (Repair-vs-Replace Advisor). At a diagnosis with a repair estimate, the Repair app evaluates repair cost vs. equipment age / remaining useful life (Stage 2 spec §B8); on a crossover it offers a one-tap handoff that opens the Sales app pre-filled with the captured equipment and diagnosis as context. Repair computes the recommendation and passes context; it does not embed Sales logic. Runs after and never overrides a safety hard stop.

Design rule for links. A cross-tool read must never be a hard dependency that breaks the consumer — if Pricing is down, Sales still runs. This preserves the fault isolation the split exists to provide.

14Migration path & open decisions

From single file to split

• Step 1 — Extract core. Pull the design system, storage abstraction, backend client, and nameplate read out of the current single file into the versioned core library.
• Step 2 — Carve the Repair app first. It carries the safety-critical logic and benefits most from isolation; splitting it first protects hard stops from regression soonest.
• Step 3 — Carve Sales, Pricing, Inventory as separate deployables on core.
• Step 4 — Thin shell/launcher routes to each, keeping one front door for the field.
• Step 5 — Customer app stays a separate build throughout (already mandated).

Open decisions

• Central database + accounts. Per-device storage caps cross-device history and true cost-hiding (which needs roles). When do the internal tools justify a central DB? Planned
• Offline diagnosis. Diagnosis needs the model; define a degraded capture-and-reconcile mode for no-signal. Planned
• Curated diagnostic trees. Curate the high-frequency calls (no-heat, no-cool, no-hot-water); model handles the long tail under the same guardrails. Planned
• Backend domain-split. Only if the single function becomes a contention point (§05).

15June 2026 additions — electrification & identification

These extend the existing module boundaries; none break the device-local, stateless-relay model. Reasons are recorded so future maintainers understand intent.

New backend action contracts (stateless relay)

Both follow the existing relay contract: no state stored server-side, images passed through to the model and discarded. nameplate (single unit) is retained for per-system reads.

Data-model deltas

• utility.gasService ∈ {confirmed, none, unknown} — field-confirmed; never inferred from the map. Gates dual-fuel and the gas-service rebate.
• energy.cooling ∈ {central, window, swamp, none} — drives the added-AC value flag.
• energy.bills.months[] entries gain fuelType, provider, unit, pricePerUnit, peakKw, avgTempF (fuel-tagged, multi-utility).
• System object gains sys.ac = {brand, model, serial} for the AC condenser of a two-unit furnace_ac, plus sys.acPhotos, sys.typeAuto, and (ductless) sys.zones.
• Equipment type ductless added across TYPE_NAMES/TYPE_OPTIONS/TIER_SPECS/TIER_COST_BASE/EQUIP_DEFAULTS; existing-equipment type evap added.
• Sidekick (Repair) components carry a typed type (13-item taxonomy) with per-type spec fields (COMPONENT_TYPES / COMP_SPEC); job-type templates pre-load typed components; a batch identify auto-types components via mapIdentifyToCompType().

Engine routing & gating (shared core)

• recommendedType() → ductless for electric baseboard, and for electric/propane/oil when ductwork = "none".
• Ductless pricing is head-based: ductlessTierCost(idx, zones); zones default ~1/500 sq ft, editable via App.setZones.
• rebatesFromTons(tonsByType, gasService) — no-gas swaps the cold-climate $/heating-ton line for a conservative electric-utility line; ductless tons count as cold-climate.
• computeGasCheck() infers gas presence from fuel-tagged bills + fuel (flag, not authority).
• effectiveFuelPrices() prefers the customer's parsed bill rates over office regional rates.
• assembleSystems(units) pairs furnace+AC into one system, appends rather than overwrites, and reuses applyUnitFields() (the shared field-mapping core split out of applyNameplate).

Boundary note: all of the above lives in the Sales module and shared core; the customer-app security boundary and the Repair safety-enforcement rules are unchanged. The richer per-home dataset (bills, specs, multi-unit identities) is the same data Sidekick (Repair) will consume.

Field Engineer — Architecture & Design (software definition). Canonical reference for the modular-split build; supersedes the architecture fragments in the Technical Reference and Stage 2 spec. Update alongside future changes.