Feature/UI

.github/workflows/pull_request_tests.yml

@@ -1,6 +1,9 @@
 name: Pytest
 
-on: pull_request
+on:
+  push:
+    branches: [feature/ui]
+  pull_request:
 
 jobs:
   test:

.github/workflows/tests.yml

@@ -2,7 +2,7 @@ name: Tests
 
 on:
   push:
-    branches: [main, develop]
+    branches: [main, develop, feature/ui]
   pull_request:
     branches: [main, develop]
 

.gitignore

@@ -164,3 +164,13 @@ cache
 
 # macOS Finder metadata
 .DS_Store
+
+# Research papers (PDFs not tracked)
+.papers/
+
+# Local OSM PBF dumps (large binaries — do not commit)
+.dump/
+
+# GATES build artifacts (generated distribution systems)
+gates_system_*.json
+gates_system_*_time_series/

README.md

@@ -12,6 +12,7 @@ A Python framework for building synthetic power distribution feeder models from
 - **Phase Balancing** — Automatically balance phases across distribution transformers
 - **Voltage Mapping** — Assign voltage levels throughout the distribution network based on transformer topology
 - **Visualization** — Built-in Plotly-based plotting for parcels, networks, and phase/voltage overlays
+- **Interactive UI Studio** — Browser-based workflow for parcel fetch, clustering, strategy selection, graph build, and side-by-side comparisons
 - **Simulator Export** — Write models to OpenDSS, CYME, Synergi, and other simulators via Grid Data Models
 
 ## Installation
@@ -42,10 +43,30 @@ pip install -e ".[doc]"
 # MCP server (AI agent integration)
 pip install -e ".[mcp]"
 
+# UI API + browser studio
+pip install -e ".[ui]"
+
 # Everything
-pip install -e ".[dev,doc,mcp]"
+pip install -e ".[dev,doc,mcp,ui]"
+```
+
+## UI Studio
+
+NREL-shift includes a FastAPI-backed UI that exposes core modeling workflows through a browser interface.
+
+```bash
+pip install -e ".[ui]"
+shift-ui-server
 ```
 
+Open `http://127.0.0.1:8000` to access the UI. The first vertical slice includes:
+
+- map-assisted source selection,
+- parcel fetch and clustering,
+- routing/secondary strategy selection,
+- graph build and strategy comparison,
+- mapper/system build endpoints ready for UI wiring.
+
 ## Quick Start
 
 The typical workflow has four stages: **fetch data → build graph → configure mappers → build system**.
@@ -167,6 +188,7 @@ These guides walk through individual stages of the workflow:
 | [Mapping Voltages](./docs/usage/mapping_voltages.md) | Assigning voltage levels via transformer topology |
 | [Mapping Equipment](./docs/usage/mapping_equipment.md) | Mapping loads, sources, and catalog equipment |
 | [Building a System](./docs/usage/building_system.md) | Assembling the final distribution system model |
+| [UI Studio](./docs/usage/ui_studio.md) | Running and using the browser-based UI/API workflow |
 
 ### MCP Server (AI Agent Integration)
 

docs/_config.yml

@@ -7,12 +7,16 @@ execute:
 
 only_build_toc_files: true
 
+bibtex_bibfiles:
+  - references.bib
+
 sphinx:
   extra_extensions:
     - sphinx.ext.autodoc
     - sphinx.ext.autosummary
     - sphinx.ext.napoleon
     - sphinxcontrib.autodoc_pydantic
+    - sphinxcontrib.bibtex
   config:
     autodoc_member_order: bysource
     autoclass_content: both

docs/_toc.yml

@@ -1,6 +1,9 @@
 format: jb-book
 root: index
 parts:
+  - caption: What's New
+    chapters:
+      - file: new_features
   - caption: User Guides
     chapters:
       - file: example/example
@@ -14,6 +17,7 @@ parts:
           - file: usage/mapping_voltages
           - file: usage/mapping_equipment
           - file: usage/building_system
+          - file: usage/ui_studio
   - caption: API Reference
     chapters:
       - file: references/index
@@ -22,6 +26,8 @@ parts:
           - file: references/dist_graph
           - file: references/openstreet_graph
           - file: references/prsg
+          - file: references/routing_strategies
+          - file: references/secondary_strategies
           - file: references/phase_mapper
           - file: references/voltage_mapper
           - file: references/equipment_mapper