SurgePV prototypes · example data · 25 Oct 2026

Six journeys that open a market or close a live deal

Hi-fi screens drawn inside the SurgePV shell with invented data for Suryatech Solar, Northwind Commercial Solar and others. 62 screens across 6 journeys; 59 are tagged Needs backend work. Click a screen to open it. Nothing here talks to the real app.

Skim all screens →Why these six, and what they costOne at a time with arrow keys or Play, or all on one page

Where these come from

1 · SF

Smart Fill: fill a roof to a target kW on the best faces

A designer types 500 kWp and gets the best-irradiated 860 positions on the roof, with the limit named and every number recomputed, instead of deleting 195 panels by hand.

Needs backend work The per-panel annual irradiation API exists (served 15 Oct 2026). A capacity-constrained fill algorithm (rank, remove, snap to strings and rows) and a face-ranking service that aggregates irradiation and loss cause per face do not; chained re-stringing and simulation after a fill also needs a job endpoint.

Studio: fill-face today (maximum fill)
SF01
Studio: fill-face today (maximum fill)
Fill face fills every usable position: 1,055 modules, 611.9 kWp, 111.9 kWp over the 500 kWp target. The only way down today is selecting and deleting panels by hand, with no data on which ones produce least.
Smart Fill panel, first run
SF02
Smart Fill panel, first run
Smart Fill opens in the right panel with a target in kWp, a preference, a scope and string snapping. The canvas switches to the heatmap so the user sees why some faces will lose panels before they press Preview.

Needs backend work Panel and heatmap overlay are front end on top of the existing heatmap API. The 'Lowest shading loss' option needs a per-panel shading-loss value, which the heatmap API does not return today.

Preview: best faces kept, weakest removed
SF03
Preview: best faces kept, weakest removed
Faces are ranked by annual irradiation. Faces A and B stay full; Face E (shaded by the neighbouring mill) and most of Face D (shaded by the lift room) are removed. The panel names the limit: string size, 498.8 kWp against a 500 kWp target.

Needs backend work A capacity-constrained fill algorithm (rank positions, remove lowest, snap to whole strings and rows) and a face-ranking service that aggregates per-panel irradiation by face. Neither exists; only the per-panel irradiation API does.

Applied: strings and energy recomputing
SF04
Applied: strings and energy recomputing
The design drops to 860 modules and 498.8 kWp at once. Strings, inverters, energy and pricing recompute in order, shown as skeletons in the top bar. The save is confirmed (version 7) so the user is not left wondering if it went through.

Needs backend work Re-running stringing, inverter sizing and simulation as a chained job after a fill. Today each is triggered by hand; a job status endpoint the panel can poll is needed.

Result: recomputed numbers and why these faces
SF05
Result: recomputed numbers and why these faces
All numbers are back: 498.8 kWp, DC:AC 1.13, 1,571 kWh/kWp, 783.6 MWh a year. The 'why these faces' list explains each face in one line with its irradiation, so a designer can defend the layout to the client.

Needs backend work Per-face reason text needs the face-ranking service to return the dominant loss cause per face (object shade, parapet, neighbour building). Today the heatmap returns irradiation only, not the cause.

Blocked: target above what the roof holds
SF06
Blocked: target above what the roof holds
A 700 kWp target is above the 611.9 kWp the roof can hold (603.2 kWp in whole strings) and above the 650 kW sanctioned load. The panel names the limit, usable area after setbacks and walkways, and gives three costed ways forward instead of a bare error.

Needs backend work Option values (gain from narrower walkways or row spacing) need the fill algorithm to run what-if fills with changed rules and return position counts. Not built.

Edge case: target below one string
SF07
Edge case: target below one string
On a single selected face, a target of 8 kWp is smaller than one 20-module string (11.6 kWp). Smart Fill stops and offers three valid outcomes with their design totals rather than rounding silently.

Needs backend work String-length rules per inverter (min and max modules at site temperatures) must be available to the fill algorithm. Today stringing applies them after the layout, not during it.

Compare before and after, with undo
SF08
Compare before and after, with undo
Before and after side by side on the heatmap. Capacity drops 18.5% while energy drops only 17.3%, which is the case for keeping the best positions. Undo restores the previous version without losing the new one.

Needs backend work Design version compare (two saved versions with their simulation results) is not built; undo today is the in-session undo stack, not a saved version.

Error: heatmap API unavailable, geometry-only fallback
SF09
Error: heatmap API unavailable, geometry-only fallback
When the irradiation call fails, Smart Fill still meets the target but says plainly that it is a geometry-only fill. Without irradiation it keeps the shaded Face E, which shows what the heatmap adds. The tag stays on the design so it can be re-run.

Needs backend work Timeout and error handling on the heatmap API call, plus a 'fill method' field on the design version so the geometry-only tag persists.

Scale: 1.2 MW warehouse with 24 faces
SF10
Scale: 1.2 MW warehouse with 24 faces
The same panel on a 24-face warehouse roof. Ranking by irradiation empties the faces shaded by the office block and HVAC units first; the table scrolls, sorts and filters so a designer can check each face before applying.

Needs backend work Same fill algorithm and face-ranking service as SF03, plus performance: ranking 2,562 positions and returning a preview in under 3 s needs a server-side job, not a browser loop.

Phone: admin reviews the Smart Fill change
SF11
Phone: admin reviews the Smart Fill change
Mehul (Admin) gets the change on his phone: old and new capacity, energy, and the three reasons in plain words. He can approve or comment; editing stays in Studio on a laptop.

Needs backend work A read-only mobile design summary with approve and comment actions. Studio has no mobile view and designs have no approval state today.

2 · TB

Tariffs for US and Canada C&I: pick the real utility rate, reproduce the bill, add demand charges and accelerated depreciation

A US or Canadian C&I designer picks the customer's real utility rate from the project location, proves it by reproducing last month's bill within a few percent, sees demand savings apart from energy savings, and gets accelerated depreciation into payback: the Energy Toolbase workflow inside SurgePV.

Needs backend work There is no utility/rate library for the US or Canada (no URDB import, no location lookup, no rate version or source fields) and no demand-charge field or demand billing anywhere in master_data or financials; bill reproduction, tariff CSV import and rate-version tracking do not exist. The tax-benefit engine (MACRS + bonus US, WDV India) and 15-min interval upload already exist in the deployed backend and mostly need UI.

Energy page today: generic rates and manual entry
TB01
Energy page today: generic rates and manual entry
Current state. The provider list is filtered by country and state only and holds a generic rate plus rates the team typed in. The manual form has periods, tiers, a 12x24 schedule, fixed charge, escalation and one export rate, and nowhere to put B-19's demand charges.
Utilities for the project location, commercial rates
TB02
Utilities for the project location, commercial rates
SurgePV finds PG&E (serves the ZIP) and SMUD (nearby) from the project address, filters to commercial rates with demand charges and suggests B-19 Secondary from the 512 kW estimated peak. Each rate shows structure badges, source and rate version.

Needs backend work a bulk import of US/Canada utilities and rates (URDB plus tariff sheets) into UtilityProvider/UtilityTariff; new UtilityTariff fields for sector (commercial/residential/agricultural), eligibility range (kW), source and rate version with effective date; a utility lookup by project lat/long against service-territory polygons (today only a country/state filter exists)

Rate detail: B-19 periods, energy, demand, fixed, export
TB03
Rate detail: B-19 periods, energy, demand, fixed, export
One page that shows the whole rate: 24-hour period strips for summer/winter weekday/weekend, $/kWh per period and season, max and peak-period demand in $/kW, $300/month fixed, NEM export rule and escalation. All values are labelled as example values.

Needs backend work a demand-charge structure on UtilityTariff (max demand and period demand in $/kW, by season and period); export credit per tariff and period (today export_rate is one flat number on ProjectConsumptionDetail); season labels for the existing 12x24 weekday/weekend schedules

Reproduce last bill: within 2.1%
TB04
Reproduce last bill: within 2.1%
The designer types last September's bill total and kWh. SurgePV bills the month from B-19 and the scaled load shape and lands 2.1% above the real bill, with every line item shown. This is the check United Sun Energy will run line by line.

Needs backend work a bill-reproduction endpoint that bills one date range from the project tariff and load shape and returns line items; demand-charge billing in financials/services/billing.py; a stored bill-check result on the project that the proposal can cite

Bill check mismatch: 14% off, likely causes
TB05
Bill check mismatch: 14% off, likely causes
Error state. Against the July bill, a URDB version of B-19 without peak-period demand comes out 14.0% low. Causes are ranked with dollar impact (missing peak demand closes the gap), the estimated profile is flagged, and the season check is shown as ruled out.

Needs backend work the same bill-reproduction endpoint plus a cause ranker (missing demand component, bill dates crossing a season, estimated vs metered load); more than one rate version per UtilityTariff so the user can switch versions

Demand charges before and after solar
TB06
Demand charges before and after solar
Monthly highest kW before and after solar, demand charges per month and a separate demand-savings figure ($11,430 a year beside $311,240 energy savings). The amber note says the numbers come from an estimated profile and links to 15-min upload. Solar barely moves the 16:00-21:00 peak.

Needs backend work a demand-charge field on UtilityTariff and a change to the monthly billing calculation to bill each month's peak kW pre- and post-solar from the net load; demand savings as its own field in pricing results and on the proposal; keep the ISS-125 behaviour where TOU bills refuse rather than spread generation evenly (hourly_billing_gate.py)

Interval data uploaded vs estimated profile
TB07
Interval data uploaded vs estimated profile
A year of 15-min PG&E data (35,040 readings) replaces the warehouse estimate. The hottest-day chart shows a 538 kW spike the estimate missed. Demand charges go up 3.2% and the September bill check tightens from 2.1% to 0.6%.

Needs backend work 15/30/60-min CSV upload already exists (master_data/services/interval_upload_save.py) but billing reads the hourly year; demand billing needs the 15-min series for monthly peak kW, plus a project switch between uploaded and estimated profile that recomputes bills

Org-level TOU CSV upload: validation errors
TB08
Org-level TOU CSV upload: validation errors
An org admin uploads a rate the library lacks. The check step catches two periods overlapping 17:00-18:00 on summer weekdays (drawn as a hatched hour on the period chart) and a decimal comma, offers one-click fixes and keeps Save disabled until they are resolved.

Needs backend work an org-level tariff CSV/Excel import endpoint that turns rows into electricity_rates plus 12x24 weekday/weekend schedules, with overlap, gap and number validation; the $/kW column needs the new demand-charge field

Accelerated depreciation on Pricing > Incentives
TB09
Accelerated depreciation on Pricing > Incentives
MACRS 5-year plus 40% bonus on a $1,887,000 basis (cost less half the 30% ITC) at a 28% tax rate gives $528,360 of tax savings over 6 years and pulls payback from 4.8 to 3.4 years. India's WDV 40% is offered only on Indian projects.

Needs backend work BE engine already exists on the deployed backend (financials/services/tax_benefits: MACRS_BONUS_US and WDV_INDIA, org-level profile, design snapshot, feeds tax_savings into pricing_calculation); needs the FE Incentives panel, a with/without payback readout, the proposal page and disclaimer; confirm ISS-59 is closed

No rate found for a small co-op
TB10
No rate found for a small co-op
Empty state on a second Rivergate site in Portola, served by Plumas-Sierra REC, which has no rates in the library. The user can enter the rate (with a demand field) or send the rate sheet PDF and ask SurgePV to add the utility.

Needs backend work a service-territory lookup that returns a utility even when it has zero rates; a utility-request queue (model, admin view, email to the requester when the rates go live)

Rate version changed since the proposal was sent
TB11
Rate version changed since the proposal was sent
Blocked state. PG&E's Oct 2026 B-19 version arrived after proposal v3 went out on the Mar 2026 version. The diff shows which charges moved and the effect on savings and payback; Send and Share are paused until the user keeps the old version or recomputes as v4.

Needs backend work rate versioning on UtilityTariff (version, effective_from, superseded_by); a snapshot of the tariff version on each sent proposal; a job that flags sent proposals when a newer version is imported

Calgary: ENMAX Rate D200 with per-day demand and ratchet
TB12
Calgary: ENMAX Rate D200 with per-day demand and ratchet
Foothills Cold Storage (Maple Ridge Solar, CA$). Alberta splits the wire owner (ENMAX D200) from the energy retailer, charges demand per kW per day and applies a 90% 12-month ratchet. The September bill reproduces within 1.5%, and the ratchet note explains why solar won't cut billing demand right away.

Needs backend work per-day $/kW and per-day fixed charges; a 12-month demand ratchet (billing demand = max of metered peak and 90% of the trailing 12-month peak); separate wire-owner and retailer components on one project tariff; ENMAX D200 import

Phone: bill check computing
TB13
Phone: bill check computing
Loading state on a phone. A Northwind rep at the customer's site types the bill numbers; SurgePV shows the steps it has finished and promises to save the result to the project if the phone locks.

Needs backend work the TB04 bill-reproduction endpoint run as an async job with a saved result, so a dropped mobile connection can resume

3 · LB

Arka Lifeboat: switch from Arka 360 without redrawing your projects

An Arka 360 customer can switch in two weeks without redrawing old work: they list their projects, Heaven Green Energy's designers redraw the first 10 against the source files, the customer approves each one, and unused Arka months become free SurgePV months.

Needs backend work None of the switch flow exists in code: no public eligibility form or credit calculator, no redraw-request model or queue, no source-vs-redraw check, no HGE design-services role, no Arka-look proposal template and no WhatsApp status messages. There is no Arka import; the redraw is manual. Editable structure types (TSL, 6 Oct) exist; Arka-style fixed-tilt structures are in Release 5 planning per the requirements register.

Public offer page: surgepv.com/switch-from-arka
LB01
Public offer page: surgepv.com/switch-from-arka
One page states what the switch includes (10 redraws, Arka-look template, fixed-tilt structures, credit), who redraws, the 7-day and 14-day timeline, list prices and the credit rule. It says plainly that there is no Arka import. The short form is filled in as Shivalik Energy would fill it.

Needs backend work A public lead form with a PDF upload endpoint and storage, a SwitchLead record (company, email, Arka renewal date, project count, seats, optional current cost), and a CRM handoff. Today the website has no form that accepts files.

Eligibility result: Shivalik Energy (India)
LB02
Eligibility result: Shivalik Energy (India)
The credit is worked out in the open: Arka ends 11 Nov, 0 full months left + 2 settle-in = 2 free months from 11 Nov, first invoice 11 Jan 2027. 10 of 14 projects are covered; the 4 left over get three priced options. The sample PDF is read and matched against the template.

Needs backend work A credit-rule engine (full months left + 2, max 6, starts at the Arka end date) and a deferred first-invoice date in billing; an automatic readability check of the uploaded PDF (layout page, module count, section list). Both are new.

Eligibility result: Stage Zero Solar (rest of world, large account)
LB03
Eligibility result: Stage Zero Solar (rest of world, large account)
61 projects is over the 25-project limit, so the page shows rest-of-world pricing (5 seats at $1,299 = $6,495 a year), confirms only what is fixed (2 free months from 3 Nov, 10 redraws) and books a 30-minute scoping call instead of quoting all 51 extra redraws.

Needs backend work Region-based price lookup (India INR vs rest-of-world USD tiers), a large-account rule (over 25 projects routes to sales) and a meeting-booking integration. None exist in the product or site today.

Signed in: Projects to move (with an upload in progress)
LB04
Signed in: Projects to move (with an upload in progress)
The customer pastes Arka links or uploads PDFs/CSVs, drags to set the order, and sees each project's status: done, ready for review, drawing (with the designer's name), queued, can't read file. Projects 11 to 14 sit below a 'not covered' line. One PDF is still uploading at 62% (loading state).

Needs backend work A RedrawRequest model per project (source files, source link, priority, status enum queued/drawing/review/done/needs-file/routed, due date, credit used), an org-level redraw-credit balance, and chunked file upload with progress. Link pasting stores the URL only; Arka links cannot be fetched without the customer's Arka login.

Internal: Heaven Green Energy redraw queue
LB05
Internal: Heaven Green Energy redraw queue
HGE designers work one queue across switch customers, with assignee (Jignesh Rathod, Abhishek Patel), SLA clock that pauses while waiting for a file, and a flag when the redraw doesn't match the source: Aarogya Clinic is 140 modules against 147 (-4.8%), so the reviewer asks the customer before it ships.

Needs backend work A cross-org design-services role (HGE staff can open customer projects they are assigned to, nothing else), ticket assignment, SLA timers with pause states, and an auto-check that compares saved design totals (modules, kWp, tilt, azimuth, inverter) with values captured from the source file. Today SurgePV has Super Admin, Admin and Designer roles inside one org only.

Customer review: Arka PDF beside the SurgePV redraw
LB06
Customer review: Arka PDF beside the SurgePV redraw
Pinecrest hostel: the source PDF page sits next to the 3D design, with a side-by-side table (83 modules, 48.14 kWp, 10°/180° all match; yield differs by 1.9% and the reason is given). It shows how Arka items mapped to SurgePV items, the Arka-look template is preselected, and the customer approves or requests a change.

Needs backend work A review screen that embeds the source PDF next to the design viewer, a mapping record (Arka structure/module/obstruction to SurgePV equipment and structure IDs), an approve/request-change action that moves the project into the customer's project list, and the Arka-look proposal template itself (customizable proposal V3 is still in Release 5 planning).

Phone: redraw status on WhatsApp
LB07
Phone: redraw status on WhatsApp
The customer gets done/review/needs-a-file messages on WhatsApp, replies with the missing PDF from site, asks if it went through, and gets an explicit receipt with the ticket ID, new due date and email copy (the 'not sure it went through' state).

Needs backend work WhatsApp Business API sending with templates per status, inbound media handling that attaches a replied file to the right RedrawRequest, and email fallback. The WhatsApp number is the HGE pilot number; no SurgePV WhatsApp integration exists.

First run after the switch: dashboard on day 7
LB08
First run after the switch: dashboard on day 7
On 1 Nov the dashboard shows the 5 moved projects, the Arka-look template installed as default, the structure library with Arka-style fixed-tilt types, and a 6-step 'what's different from Arka' guide. 0 new projects yet is the empty state.

Needs backend work A first-run dashboard keyed to a switched org (moved projects, credit dates), template install as org default, seeding Arka-style fixed-tilt structure presets into the org structure library, and a checklist with completion tracking. The structure presets depend on Arka fixed-tilt types shipping.

Can't redraw: unreadable file and project over 5 MW
LB09
Can't redraw: unreadable file and project over 5 MW
Two blocked cases, each with a reason and a next step. Kandari's CSV has no geometry, so the customer is told which Arka export works and that the credit is held until 5 Nov. SIDCUL Haridwar is 5.8 MWp, over the 5 MW cap, so it goes to HGE design services for a written quote within 2 working days. No credit is used for either.

Needs backend work File-parse validation that detects missing geometry, a credit-hold with expiry, a size cap rule (over 5 MW) that routes a RedrawRequest to a Solar Desk quote, and a quote request/response record. Solar Desk quoting exists only as a pricing page today.

4 · DQ

Demo qualifier and paid pilot: route every demo request to the right next step

Three questions and an address on the demo form send each request to one of five next steps, so only commercial leads in countries that convert get a live demo. Outside India, a $99 pilot replaces the free demo.

Needs backend work None of this exists today. It needs a DemoRequest lead record with an ordered routing rule table and an audited manual override, website-side geocoding and building lookup, a payment link that creates a 14-day pilot entitlement with a licence credit, and project pre-creation from the form address.

surgepv.com booking form: three questions and the project address
DQ01
surgepv.com booking form: three questions and the project address
Three questions (country, mostly commercial or residential or above 5 MW, current tool) plus the address that becomes the live-demo project. The address is checked on the page, so the prospect sees their roof before booking. The right column lists all five next steps, so no answer is a dead end.

Needs backend work a public qualifier endpoint that stores a DemoRequest lead (name, email, company, country, segment, current tool, address) and runs the routing rule table; a geocode plus building-footprint lookup (roof area) callable from the website before any account exists

Outcome (a): commercial in a supported country, live demo booked
DQ02
Outcome (a): commercial in a supported country, live demo booked
Maple Ridge Solar (Calgary, 480 kW cold store) picks a slot shown in Mountain Time, with slots that fall in India working hours. The page asks for a bill or roof photo before the call and shows what the designer prepares from the address. A $99 pilot is offered as an alternative.

Needs backend work a slot calendar with named hosts (Vikram, Santhosh) that converts IST working hours into the prospect's time zone; pre-call file upload attached to the DemoRequest; a draft project pre-created from the address in a sales sandbox org

Outcome (b): residential outside India, pitched-roof waitlist with a date
DQ03
Outcome (b): residential outside India, pitched-roof waitlist with a date
A UK residential installer gets a launch window (target January 2027), a one-click "Tell me when it ships" and an honest list of what works today. A commercial escape hatch links back to a live demo.

Needs backend work a waitlist table tied to the smart-roof feature flag with one-click notify and a launch-day email trigger; the address saved as a pending first project created when the flag ships

Outcome (c): US residential or Australia, self-serve trial plus recorded demo
DQ04
Outcome (c): US residential or Australia, self-serve trial plus recorded demo
No live slot is offered. The prospect gets an 18-minute recorded demo with chapters and a trial with the address pre-created. A warning says pitched-roof design is not ready yet.

Needs backend work trial signup that creates an org with a trial expiry (7 days, placeholder) and pre-creates the first project from the address; a hosted recorded demo with chapter markers; the routing outcome stored on the lead so sales does not call

Outcome (d): above 5 MW, design-services conversation
DQ05
Outcome (d): above 5 MW, design-services conversation
A 40 MW plant in Oman is not sent to a demo that will stall at the 5 MW limit. It goes to a services intake (size, mounting, deliverables, KMZ boundary) that leads to a scoping call and a fixed quote.

Needs backend work a services-lead type (plant MW, mounting, deliverables, KMZ upload) routed to a Solar Desk design-services queue instead of the sales calendar; no services intake exists in the product or website today

Outcome (e): current Arka user, switch offer and handoff to Santhosh
DQ06
Outcome (e): current Arka user, switch offer and handoff to Santhosh
Shivalik Energy's Arka subscription ends 11 Nov 2026 (17 days). The offer is a redraw of all 14 projects by people, an Arka-style template, editable TSL structures and 3 months free, labelled as draft terms. Santhosh takes the call.

Needs backend work an Arka-switch lead type with subscription end date; bulk PDF upload into a redraw queue for designers (there is no Arka project import); an offer record (3 months free) applied to the first licence invoice; WhatsApp confirmation message

Paid pilot checkout: $99 or ₹5,000, credited to the licence
DQ07
Paid pilot checkout: $99 or ₹5,000, credited to the licence
US commercial (rule R7) starts with a paid pilot instead of a free demo. The page lists what $99 buys, including one design review. It shows the INR price for India and says the credit applies within 30 days. No auto-renewal. A line covers the "not sure it went through" case.

Needs backend work a payment link (Stripe for USD, Razorpay for INR) that on success creates the pilot org, a 14-day pilot entitlement and a $99 / ₹5,000 credit against the first licence invoice; receipt email

Pilot workspace in the app: countdown, pre-created project, review, checklist
DQ08
Pilot workspace in the app: countdown, pre-created project, review, checklist
First run inside the app. Rivergate Logistics is already created from the form address with roof outline and PG&E B-19, while weather data is still loading (loading state). The countdown shows 14 days and the credit. The design review is booked here, and three things to try are 0 of 3.

Needs backend work a pilot entitlement on the org (start, end, read-only from day 15); project pre-creation from the form address with roof outline, utility tariff (PG&E B-19) and weather fetch; an onboarding checklist fed by layout, simulation and proposal-export events; design-review booking against designer slots

Internal: sales view of the week's demo requests with manual override
DQ09
Internal: sales view of the week's demo requests with manual override
28 requests, but only 10 human calls (8 demos, 2 pilot reviews). Each row shows country, segment, source, outcome and the rule that fired. Harbor Point Homes was moved from Self-serve to Live demo by Vikram, with a required reason and an audit log. Only Vikram and Santhosh can override (permission state). The rule table sits under the list.

Needs backend work an internal Demo requests view over DemoRequest with routing outcome, rule id, source (UTM or event tag such as REI expo), next-step status, a manual override limited to two named users with a required reason and audit log, and an editable ordered routing rule table

Phone: booking form, address not found (error state)
DQ10
Phone: booking form, address not found (error state)
On a phone, the three answers are collapsed and step 4 fails to geocode an industrial-park address in the Philippines. The prospect can drop a pin, paste coordinates or a Maps link, or skip and share it on the call. A failed lookup never blocks the booking.

Needs backend work geocoder fallback when an address returns no building: draggable pin, coordinate and Google Maps link parsing, saved as lat/lng on the DemoRequest with an address_unverified flag for sales

5 · WA

Bill to proposal on WhatsApp, internal pilot first

An agent can turn a WhatsApp bill photo into a Customer Inquiry project and a draft proposal (everything except the 3D model), and HGE designers can grade it field by field per bill family, so a family reaches customers only after it proves 95% field accuracy over 50 bills and the financial-maths bugs are closed.

Needs backend work None of this exists in code: the HGE Quote pilot deliberately excludes bill OCR, the WhatsApp provider and agent tools. Needs a WhatsApp Business API provider and webhook, per-family bill OCR (Torrent, UGVCL, MSEDCL, Adani), an agent run log with field-level provenance, a grading model and pass-rate rollup with a per-family release flag, financial sanity checks that stop a run, and fixes for ISS-125, ISS-72 A/B/C, ISS-122 and ISS-123.

Phone: bill photo read, one question
WA01
Phone: bill photo read, one question
The customer sends a Torrent bill photo to the HGE number. The agent lists what it read (consumer no., 5 kW, 612 kWh, ₹7,840, Torrent LT-RES) and asks only about the one field it is unsure of, the billing period, in English and Hindi.

Needs backend work WhatsApp Business API provider and inbound media webhook; per-family bill OCR (Torrent LT-RES template) returning a confidence per field; interactive-button message templates in English and Hindi

Phone: confirm roof and goal
WA02
Phone: confirm roof and goal
The agent geocodes the bill address, shows a satellite thumbnail with a pin and asks 'is this your roof?', then asks bill saving vs backup. Both answers are stored as customer-confirmed, not guessed.

Needs backend work Address geocoding from the OCR'd bill address and a static satellite tile for the pin; a conversation state store that records each answer with 'customer-confirmed' provenance

Phone: proposal delivered
WA03
Phone: proposal delivered
Target state after the family goes live: 6.1 kWp, ₹3.9 lakh after the ₹78,000 PM Surya Ghar subsidy, ₹6,900 a month saving, 4.7-year payback, the PDF, and a 'talk to a designer' button. It says plainly that the 3D layout and final price come after a site visit.

Needs backend work An input-dict entry point to recommender/services/recommendation_engine.py so the agent can size, price (HGE signed price table) and apply incentives without a 3D design; headless proposal PDF render; WhatsApp document send

Phone: bill could not be read
WA04
Phone: bill could not be read
Honest failure: the photo is folded, so the agent cannot read the units. It asks for the back page and offers two fallbacks: type the units, or a designer calls. It never makes a proposal from a guessed number.

Needs backend work Per-field OCR confidence threshold that blocks the run when a required field (units) is missing; a 30-minute timeout that routes the thread to the HGE designer queue

Phone: proposal delivered, Hindi first
WA05
Phone: proposal delivered, Hindi first
Same proposal as WA03 for a customer who wrote in Hindi: Hindi first, a one-line English summary, a Hindi PDF, and an option to get it in Gujarati.

Needs backend work Language detection on the customer's messages; Hindi and Gujarati strings for WhatsApp templates and a Hindi proposal PDF template (idea #19, D6 fix)

Grading inbox: every agent run, by bill family
WA06
Grading inbox: every agent run, by bill family
Every run lands here before anyone outside HGE sees it: running, awaiting grade, stopped, or graded, with nine field squares per run. The open run shows UGVCL's two-month bill read as one month, which led to a 3.9 kWp system sized for 486 kWh instead of 243.

Needs backend work Agent run model (run id, bill family, steps, status) and a per-field grade table (agent value, designer value, pass/fail, grader, time spent); bill-family classifier; org-scoped grading inbox API

Grade one run: bill, fields, proposal, verdict
WA07
Grade one run: bill, fields, proposal, verdict
Jignesh Rathod grades the Desai run: bill photo with a box per field on the left, nine fields with pass/fix in the middle (only the fixed charge is wrong), the agent's proposal inputs, and 'would send to customer: yes/no' with the reason list. Saving the grade records 16 minutes saved.

Needs backend work OCR bounding boxes stored per field for the bill overlay; grading write API that saves corrections back into the project inputs; fixed reason taxonomy (tariff, load profile, pricing table, subsidy, size, financial result, other); manual-setup time baseline per org

Pass rates by bill family and the release rule
WA08
Pass rates by bill family and the release rule
The release rule in one place: a bill family goes live to customers at 95% field accuracy over 50 bills, and ISS-125, ISS-72, ISS-122 and ISS-123 must be closed. Torrent is at 91% (410 of 450 fields), UGVCL 78%, MSEDCL 62%, and Adani has 9 bills. Every 'Go live' button is disabled.

Needs backend work Rolling last-50 field-accuracy rollup per bill family and per field; a per-family 'live to customers' flag that the WhatsApp sender checks before any outbound agent message; issue-status link to the BE issue register

Customer Inquiry project created with provenance
WA09
Customer Inquiry project created with provenance
Saving the grade creates the Desai Customer Inquiry project. Every input carries a label: from bill, customer-confirmed, estimated, or designer-corrected. The next step is 'Open in Studio for 3D', and the open checks flag that 6.1 kWp exceeds the 5 kW sanctioned load.

Needs backend work Project fields for created_via='bill_agent' and a run link (extends the HGE pilot's created_via/lead_source); a provenance attribute per energy, tariff and pricing input that Studio reads and flips to 'from design' when the 3D design is saved

Agent stopped: financial result failed a sanity check
WA10
Agent stopped: financial result failed a sanity check
Error state shown to the grader, not the customer. A TOD bill hit ISS-125: the agent's hourly profile puts 46% of generation at night, so the saving (₹5,480) came out higher than the bill (₹5,120). The run stopped before the PDF. Recent stops for ISS-122, ISS-123 and ISS-72 are listed below.

Needs backend work A sanity-check step in the agent run (night generation, saving vs bill, payback range, yield range, subsidy vs size) that halts before PDF render and logs which check failed; depends on ISS-125/72/122/123 fixes before any family can go live

6 · API

Integrations: a channel partner's lead becomes a SurgePV project automatically

With one org-scoped API key, one create-project endpoint, one webhook, a log and a mapping screen, a Luminous M-Partner lead lands as a Customer Inquiry project assigned to a designer, bad leads are held instead of created, and M-Partner is told when the proposal is ready.

Needs backend work SurgePV has no public API, API keys, webhooks or integration settings today: design-studio-BE has no ApiKey, WebhookEndpoint, WebhookDelivery or LeadReview model, no external_id on Project, and only per-user and per-IP throttles. All of it is new, built on the existing Project model and its first status CUSTOMER_INQUIRY.

Settings > Integrations, first run
API01
Settings > Integrations, first run
Empty, first-run state on 22 Oct: nothing connected. Only API keys, Webhooks and M-Partner are marked Available; Zoho, HubSpot and Salesforce are Planned so sales cannot promise them. The four-step strip is the whole journey.

Needs backend work An Integrations settings page and Admin-only permission for it; no integrations module exists in design-studio-BE or FE today.

Create an org-scoped API key, shown once
API02
Create an org-scoped API key, shown once
The key is locked to Luminous Solar Partners and to two scopes (create projects, read proposals). It is shown once with a copy button and a warning; the right side lists what is stored: prefix, last 4, SHA-256 hash, never the key.

Needs backend work An ApiKey model (organisation FK, name, prefix, last4, sha256 hash, scopes, expires_at, revoked_at, created_by) and a key authentication class used only on /v1/ routes, never added to the default DRF authentication classes.

M-Partner field mapping with defaults
API03
M-Partner field mapping with defaults
Each M-Partner lead field (from MP-48213) maps to a real Project field: customer_name, customer_mobile_number, address_line_1/city/state/pincode, sanction_load_kw, average_monthly_cost. Defaults set status Customer Inquiry, round-robin owner in this org, profile Residential IN. Three rules hold a lead instead of creating it.

Needs backend work An IntegrationMapping record per organisation (field map, default status, round-robin designer pool with a cursor, default DesignDefault), a geocoding step to fill the non-null Project latitude/longitude, and new Project fields external_id and source_partner.

Project created from lead MP-48213
API04
Project created from lead MP-48213
Kavya Rao's view of the new project: provenance banner "Created by M-Partner on 24 Oct 14:02, lead MP-48213", lead fields tagged read-only, location marked as geocoded, and a next-step card. She never retyped anything and does not need to message the partner.

Needs backend work Project.source / external_id / source_partner / created_by_api_key fields, a per-field lock for API-sourced values with an Admin unlock, and activity entries for API creation and round-robin assignment.

Webhook settings with test event
API05
Webhook settings with test event
One endpoint, two events (proposal.ready, project.status_changed), HMAC signing secret, and a test call that returned 200 in 236 ms with the sample payload shown. Webhooks only fire for projects created by the M-Partner key, so walk-in projects never leak to Luminous.

Needs backend work A WebhookEndpoint model (organisation, url, events, hashed signing secret, source-key filter), event emission on proposal generation and Project status change, and a Celery delivery task with HMAC-SHA256 signing and a 7-attempt retry schedule.

Delivery log: in and out, a 401 and a retry
API06
Delivery log: in and out, a 401 and a retry
Requests in and events out on one timeline. After Ankit rotated the signing secret at 09:30, proposal.ready for MP-48213 got 401 three times; Luminous fixed their side at 11:12 and a manual retry delivered (200, 241 ms) with the same event id. A second retry is still sending (loading state).

Needs backend work A WebhookDelivery table (event id, attempt number, request headers and body, response code and body, latency, next_retry_at) and an ApiRequestLog for inbound calls, both org-scoped with 30-day retention, plus a manual retry endpoint.

Public developer docs: the contract
API07
Public developer docs: the contract
Public page with auth, rate limits (60/min, 5,000/day per key), POST /v1/projects with 201 and 202-held examples, GET /v1/projects/{id}, the webhook payload and signature check, and the error table. It states "This is the contract we sign against" and the v1 additive-only rule.

Needs backend work An OpenAPI 3 file for /v1 kept in the repo and tested against the serializers, per-key rate throttles (core/throttles.py has only per-user and per-IP throttles), and Idempotency-Key handling on POST /v1/projects.

Error: lead held in Needs review
API08
Error: lead held in Needs review
Error and blocked state. MP-48301 has the same mobile as an open project but comes from a different partner; MP-48297 has an address that does not geocode. Neither became a project. An Admin attaches, creates anyway or rejects; designers see it read-only. M-Partner got a 202 with a reason code and no other partner's data.

Needs backend work A LeadReview model (raw payload, reasons, status, 14-day expiry), a duplicate check on normalised customer_mobile_number across open projects in the organisation, and attach / create / reject actions that write the outcome back to the lead.

Phone: what the partner sees in M-Partner
API09
Phone: what the partner sees in M-Partner
Phone variant, illustration only: Luminous's own M-Partner app showing lead MP-48213 move to Design started and Proposal ready (4.64 kWp) because of SurgePV's two webhooks. SurgePV does not build this screen; it shows Luminous what the contract gives them.