How SubsGPT injects the active proposal into AI answers

A free-form plain-text field (≤ 4000 chars) that SubsGPT ships on every Design Chat turn. The backend's answer writer sanitises it (control chars stripped, length-bounded) and appends it to the prompt under a "Current Layout:" header so answers can reference the active proposal alongside the chosen standards corpus. Built by lib/proposalSummary.js → summarizeProposal() / summarizeLayout(); capped at 3800 chars to leave headroom under the 4000-char Pydantic limit.

A named multi-agent pipeline stored in MongoDB

A JSON document that defines a list of agents, each with its own system prompt, tools, and dependencies. The backend executor runs the DAG via /agentic/generate. Two configs SubsGPT depends on by name: rural-substation-advisor (Design Chat) and verify-layout (Verify Standards). Each of the 19 document/drawing widgets also maps to a config — see DEFAULT_WIDGET_CONFIG_MAP in lib/proposalConfig.js, overridable in Settings → Doc Mappings. If a config is missing the backend falls back to substation-document-generator.

NFPA 70E hazard band for an electrical system

Categories 0 through 4 indicating the incident-energy level workers may be exposed to. calcArcFlash() in lib/engineeringHelpers.js bands the fault level against simplified NFPA 70E thresholds and StepSpec shows the result read-only; the arcFlashOverride checkbox swaps in an editable select. Caveat worth knowing: the helper also takes a protectionScheme and applies a 0.6× multiplier for fast-clearing schemes, but no UI writes that field any more (StepSpec now sets layoutType instead), so it sits at its default and the multiplier never fires — every in-range fault level lands on Category 4 unless overridden. Treat the calculated value as an early-estimating placeholder, not an incident-energy study.

Structured properties of the substation being designed

A typed object — voltage_class, technology (AIS / GIS), environment, jurisdiction, utility — derived from the active proposal and forwarded to the AI surfaces (Design Chat, Verify Standards). Lets the backend filter retrieval to relevant standards and lets the answer writer phrase responses appropriately.

The 2-second debounced write to MongoDB

Every change writes to localStorage immediately (subsGPT-proposal), then fires a 2-second debounced PUT /subsgpt/proposals/{id}. The header chip shows "Saving…" and "Save error — click to retry"; note "Saved" only flashes after a manual Save, so a quiet chip during auto-save is normal. The PUT carries a version integer for optimistic concurrency, but a 409 is not surfaced to you — the client immediately retries with version null, so the last writer wins and a concurrent edit in another tab can be overwritten. Caveat: the debounced save no-ops while proposalId is null, so a brand-new proposal isn't persisted server-side until an explicit Save.

The lightning-impulse withstand voltage rating

Measured in kV. SubsGPT auto-suggests BIL from HV voltage: 345 kV → 1300, 230 kV → 900, 138 kV → 650, 115 kV → 550, 69 kV → 350, 34.5 kV → 200, < 34.5 kV → 110. You can override the suggestion on Step 1 (Spec).

Where Design Chat persistence lives on the proposal

Two fields written to the proposal blob by DesignChat. chatMessages is the conversation log: [{ role, content, isError, timestamp }]. chatContextGroupId is the picked standards corpus. Persisted via the onTouch callback so the auto-save sees them; survives page reload and the drawer close/open cycle.

A traceable pointer to a source chunk

Every Design Chat or Verify Standards answer carries citations back to the source documents (doc_id, version, page, section, chunk_id). For Design Chat they're inline in the prose ("[RUS Bulletin 1724E-300, §4.9, p. 154]"); for Verify Standards they appear as structured rows in the report table.

Per-proposal sharing by email, view or edit

The /shared-proposals page. Share a proposal you own with a teammate by email at one of two permission levels — view or edit — via shareProposalAPI; remove access with unshareProposalAPI. Collaborators show as chips with a permission badge. Only proposals you own can be shared. The page also offers a copy-link action and a stats row (owned / collaborators / shared).

A backend corpus boundary

An isolation unit on the SBS_AI backend. Each group has its own SQLite scope, ChromaDB collection, and knowledge graph. The pickers in Design Chat and Verify Standards forward the chosen context_group_id to /ask and /agentic/generate so retrieval scopes consistently across both surfaces.

RAG-grounded engineering Q&A drawer

A drawer reachable from the proposal-builder toolbar. Backed by the rural-substation-advisor agentic pipeline (3 agents: searcher → analyst → engineer-formatter). Multi-angle retrieval over the chosen standards corpus, with the active proposal+sites injected as additional_context. ~30–60 s per turn on Ollama; structured markdown output with inline citations. Each turn is independent — prior turns aren't resent.

The default shape of a new proposal

The constant in lib/proposalConfig.js that defines all wizard fields and their defaults — name, location, station type, voltages, frequency, fault level, etc. Anything in EMPTY_PROPOSAL is part of the proposal blob; chat/verify fields (chatMessages, verifyResult) are added by the drawers as needed.

Which of the 10 drawings can actually be generated

lib/proposalConfig.js exports 9 DOC_WIDGETS and 10 DWG_WIDGETS (19 total), but only ENABLED_DRAWINGS = [dwg_sld, dwg_siteLayout] are live. The other 8 drawings render on the Generate step greyed out with a "Not in demo mode" footer and are never generated. All 9 documents are enabled. Both live drawings are derived from the site's generated layout (sldUrl and planObjects) rather than from an agentic document pipeline.

The 3D model format for substation layouts

A self-contained 3D scene file — what the Map Designer actually renders for a generated layout. Site-Fit assembles one per candidate via /xinfra/sitefit-export-glb, keyed by a geometry hash so an unchanged layout reuses the cached file and an edited one busts it. Source equipment models live in baseModels/ on the backend.

A generated substation layout for one site

The chosen Site-Fit candidate, stored on each site in mapState as site.result. Contains the components[] array (equipment items with x/y/z coordinates, type, rated_voltage), the assembled GLB path, an sldUrl, planObjects for the Site Layout Plan, and the station/site dimensions. A point-site has no footprint until this exists — which is why site dimensions, the Site report, and site analysis are only meaningful after a layout is generated. The Verify Standards drawer reasons over site.result.

The thumbs-up/down loop that improves Site-Fit

Rating a Site-Fit candidate (thumbs up/down + optional note, across bus scheme / transmission lines / spacing / chat edit) writes feedback the model later trains on. Settings → Neural Net embeds LayoutModelPanel.js with two tabs: feedback (GET /xinfra/layout/feedback) to review what was captured, and train (POST /api/neuralnet-services/substation/retrain) to run the pipeline — harvest feedback, assemble corpus, build vocab, train generator, train the hand-crafted and spatial re-rankers, reload — with progress polled and shown per step.

The strength of a requirement: SHALL / SHOULD / MAY

Borrowed from RFC 2119. Tagged on every extracted requirement during ingestion so the conflict checker can reason about strength. SHALL / MUST are mandatory; SHOULD is strong recommendation; MAY is permissive. The Verify Standards report uses modality to decide PASS / REVIEW / FAIL severity.

The .pt layout model file, resolved per browser

A trained layout-generation model under neuralNet_Models/ on the backend. Held browser-local by lib/userPreferences.js at subsgpt_user_prefs_v1.neuralnetCheckpoint; getNeuralnetCheckpointPath() builds the relative path the backend expects, and the default is Windfarm_from_new_interface.pt. It is seeded from the account's neuralnet_checkpoint on login and cleared on logout. Note there is no longer a checkpoint picker in Settings → Neural Net — that tab is now the Layout Model feedback/retraining workspace, and the live consumer of the preference is the Layout creation (Revit) page. Layout generation from the Map step goes through Site-Fit instead.

The full state of one proposal

The JSON document persisted in MongoDB at /subsgpt/proposals/{id}. Carries the wizard fields (EMPTY_PROPOSAL + edits), chat persistence (chatMessages, chatContextGroupId), verify persistence (verifyResult, verifyContextGroupId), generated documents, and a version integer for optimistic concurrency.

How SubsGPT talks to a running Revit session

The sidebar's CAD Tools section has two pages: Revit Analysis (/cad-panel) snapshots and summarises the open Revit document; Layout creation (/cad-layout) adds a proposal picker, generates a layout from the proposal's equipment counts, then places it into the live model as native families, reporting families placed and skipped. Both reach Revit through the SBS AI add-in's WebView2 host object (lib/revitHost.js, lib/revitBridge.js) — detected via window.__REVIT_HOST__, a ?revit=1 query, the UA, or the host object. Opened in an ordinary browser tab they load but report the bridge as unavailable.

The agentic config behind Design Chat

A 3-agent linear pipeline: searcher (multi-angle RAG retrieval) → analyst (synthesises) → engineer-formatter (writes structured markdown with inline citations). Materially better answers than single-shot /ask in side-by-side comparisons; trade-off is latency. Seeded from data/rural-substation-advisor.agentic-config.json into MongoDB.

JSON-LD schema for substation layouts

The interchange format the neural-net layout pipeline emits: POST /api/neuralnet-services/layout/generate returns SBIF JSON-LD, and /layout/assemble turns SBIF into a GLB. It carries equipment positions, rated voltages, and station/site dimensions. This is the path the Layout creation (Revit) page still uses; the Map step's layout generation now goes through Site-Fit instead.

The candidate-based substation layout generator

The layout workflow on the Map step, reached per-site via Generate Layout / Edit Layout (components/sitefit/SiteFitDrawer.js). It POSTs to /xinfra/layout/site-fit to generate N candidate layouts at the site's centre point — built from the proposal's HV kV, transformer and line counts, LV system, and the templateId taken from layoutType — then re-ranks them via /xinfra/sitefit-rerank and sorts by preferenceScore. Re-ranking is best-effort: if it fails, the candidates still show, unranked. Defaults for candidate counts and spacing come from Settings → Gen AI Layouts. The drawer has three tabs: candidates, chat, sld.

Conversational layout editing — distinct from Design Chat

The chat tab in the Site-Fit drawer (components/sitefit/SiteFitChat.js), talking to /xinfra/sitefit-chat. Two things make it the opposite of Design Chat: it sends the whole conversation (so follow-ups work), and it can mutate the layout — spacing, orientation, nudges — returning updatedObjects that re-render live, plus overlap and clearance warnings. It has its own corpus picker for scoping knowledge-graph tools, and reports stopReason "no_tool_support" when the configured model can't call tools. ToolTrace.js renders which tools it invoked per message.

The 2D top-down plan drawing, rendered client-side

One of the two live drawings. Built entirely in the browser by lib/planSvg.js → buildPlanSvg() from the layout's planObjects — no backend call. Draws each equipment item at its true metre footprint (x_m/y_m centre, width_m/depth_m, orientation_deg), y-up with a north arrow, a colour-coded legend by family (XFMR, CB, DS, CT, VT, SA, STR, BUS), an auto-computed fence line at the equipment bbox plus setback, and a rounded scale bar. PlanViewer.js wraps it with an SVG download. Surfaced as a per-site modal on the Generate step.

The 6-step proposal flow

The proposal-builder UI: Step 0 Setup (project + location), Step 1 Spec (electrical standards + layout type), Step 2 Design (voltages + switchgear), Step 3 Map (3D site designer), Step 4 Generate (AI documents + drawings), Step 5 Summary (reports + export). Any step can be clicked directly in the stepper. Visited steps are tracked in proposal._visitedSteps; each step component lives under components/proposal/.

The in-app guided walkthroughs

SubsGPT ships five react-joyride tours: dashboard, wizard (the 6 builder steps), map (the Sites panel and per-site controls), generate (the Generate step options), and collaborate (sharing). Each auto-starts once for a user who hasn't seen it — the dashboard, wizard, and collaborate tours by route; the map and generate tours on a DOM event, since their anchors only exist when that step is live. Each tour's "seen" flag is a separate localStorage key (e.g. subsGPT-wizard-tour-done), cleared on replay. The sidebar's "Take the tour" dispatches subsgpt:start-tour, which restarts the tour for the current route. Steps whose anchor isn't in the DOM are dropped so a tour never stalls.

The agentic config behind Verify Standards

A 3-agent linear pipeline: clearance-extractor (pulls clearance/spacing rules from the corpus) → geometry-analyser (measures equipment pairs in the layout) → compliance-reporter (emits a structured PASS/REVIEW/FAIL JSON report with citations). Used by both SubsGPT's drawer and SBS_AI_Front's panel; keys off analysis_focus to pick clearance categories.

Where Verify Standards persistence lives on the proposal

verifyResult is { report, narrative, verdict, rawText, rawSections, selectedSiteId, ranAt } — the last compliance run. verifyContextGroupId is the picked standards corpus (independent of chatContextGroupId). Restored when the drawer reopens so a verification doesn't need to re-run.