# sel-columbia/networkplanner architecture

> Architecture diagram of the GitHub repository sel-columbia/networkplanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sel-columbia/networkplanner
- Repository: https://github.com/sel-columbia/networkplanner

## Overview

NetworkPlanner is an electricity-infrastructure planning framework whose central web workflow lets users submit scenarios, process them with selectable metric and network models, then retrieve results. The README also documents CLI operation, standalone or distributed processing, and extensible metric and network builders. Source excerpts and the SOURCE INDEX support the main module relationships; some worker and queue wiring is documented only at a high level, so uncertain implementation links are omitted.

Main entry points: [`np/model/__init__.py`](https://github.com/sel-columbia/networkplanner/blob/master/np/model/__init__.py) (Scenario model), [`np/config/routing.py`](https://github.com/sel-columbia/networkplanner/blob/master/np/config/routing.py) (Web routes), [`np/controllers/scenarios.py`](https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/scenarios.py) (Scenario controller), [`np/lib/metric/mvMax5/demand.py`](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax5/demand.py) (Demand models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_routes["Web routes<br/>[routing.py]"]
  node_scenario_controller["Scenario controller<br/>[scenarios.py]"]
  node_people_controller["People controller<br/>[people.py]"]
  node_job_controller["Job and processor views<br/>[jobs.py]"]
end

subgraph group_processing["Scenario processing"]
  node_model["Scenario model<br/>[__init__.py]"]
  node_metric["Metric framework<br/>[__init__.py]"]
  node_demand["Demand models<br/>[demand.py]"]
  node_finance["Finance metrics<br/>[finance.py]"]
  node_demographics["Demographic metrics<br/>[demographics.py]"]
  node_variable_store["Metric variable cache<br/>[variable_store.py]"]
  node_network["Network framework<br/>[__init__.py]"]
  node_kruskal["Kruskal builder<br/>[__init__.py]"]
end

subgraph group_data["Data and persistence"]
  node_dataset[("Scenario datasets<br/>[dataset_store.py]")]
  node_geometry["Geospatial I/O<br/>[geometry_store.py]"]
  node_store["Storage utilities<br/>[store.py]"]
  node_database[("Relational database")]
end

subgraph group_operations["Processing operations"]
  node_worker["Scenario processors<br/>[processor.py]"]
  node_script_process["CLI scenario runner<br/>[script_process.py]"]
  node_rabbitmq["RabbitMQ"]
end

node_planner(("User"))

node_planner -->|"requests pages"| node_routes
node_routes -->|"routes scenarios"| node_scenario_controller
node_routes -->|"routes accounts"| node_people_controller
node_routes -->|"routes jobs"| node_job_controller
node_scenario_controller -->|"submits scenarios"| node_model
node_scenario_controller -->|"selects metric model"| node_metric
node_scenario_controller -->|"selects network model"| node_network
node_model -->|"applies metrics"| node_metric
node_model -.->|"builds network"| node_network
node_metric -.->|"loads model"| node_demand
node_demand -->|"uses finance metrics"| node_finance
node_demand -->|"uses demographic metrics"| node_demographics
node_demand -->|"uses variable cache"| node_variable_store
node_network -->|"supports builder"| node_kruskal
node_model -->|"creates dataset"| node_dataset
node_dataset -->|"uses geospatial I/O"| node_geometry
node_dataset -->|"uses storage helpers"| node_store
node_model -.->|"persists scenarios"| node_database
node_worker -->|"loads model"| node_model
node_script_process -->|"runs scenarios"| node_model
node_rabbitmq -.->|"dispatches work"| node_worker

click node_routes "https://github.com/sel-columbia/networkplanner/blob/master/np/config/routing.py"
click node_scenario_controller "https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/scenarios.py"
click node_people_controller "https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/people.py"
click node_job_controller "https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/jobs.py"
click node_model "https://github.com/sel-columbia/networkplanner/blob/master/np/model/__init__.py"
click node_metric "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/__init__.py"
click node_demand "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax5/demand.py"
click node_finance "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax2/finance.py"
click node_demographics "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax2/demographics.py"
click node_variable_store "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/variable_store.py"
click node_network "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/network/__init__.py"
click node_kruskal "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/network/modKruskal/__init__.py"
click node_dataset "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/dataset_store.py"
click node_geometry "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/geometry_store.py"
click node_store "https://github.com/sel-columbia/networkplanner/blob/master/np/lib/store.py"
click node_worker "https://github.com/sel-columbia/networkplanner/blob/master/utilities/processor.py"
click node_script_process "https://github.com/sel-columbia/networkplanner/blob/master/utilities/script_process.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_scenario_controller,node_people_controller,node_job_controller,node_planner toneBlue
class node_model,node_metric,node_demand,node_finance,node_demographics,node_variable_store,node_network,node_kruskal toneAmber
class node_dataset,node_geometry,node_store,node_database toneMint
class node_worker,node_script_process,node_rabbitmq toneRose
```

## Components

### Web application

- [Web routes](https://github.com/sel-columbia/networkplanner/blob/master/np/config/routing.py): `np/config/routing.py`
- [Scenario controller](https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/scenarios.py): `np/controllers/scenarios.py`
- [People controller](https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/people.py): `np/controllers/people.py`
- [Job and processor views](https://github.com/sel-columbia/networkplanner/blob/master/np/controllers/jobs.py): `np/controllers/jobs.py`

### Scenario processing

- [Scenario model](https://github.com/sel-columbia/networkplanner/blob/master/np/model/__init__.py): `np/model/__init__.py`
- [Metric framework](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/__init__.py): `np/lib/metric/__init__.py`
- [Demand models](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax5/demand.py): `np/lib/metric/mvMax5/demand.py`
- [Finance metrics](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax2/finance.py): `np/lib/metric/mvMax2/finance.py`
- [Demographic metrics](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/metric/mvMax2/demographics.py): `np/lib/metric/mvMax2/demographics.py`
- [Metric variable cache](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/variable_store.py): `np/lib/variable_store.py`
- [Network framework](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/network/__init__.py): `np/lib/network/__init__.py`
- [Kruskal builder](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/network/modKruskal/__init__.py): `np/lib/network/modKruskal/__init__.py`

### Data and persistence

- [Scenario datasets](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/dataset_store.py): `np/lib/dataset_store.py`
- [Geospatial I/O](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/geometry_store.py): `np/lib/geometry_store.py`
- [Storage utilities](https://github.com/sel-columbia/networkplanner/blob/master/np/lib/store.py): `np/lib/store.py`
- **Relational database**

### Processing operations

- [Scenario processors](https://github.com/sel-columbia/networkplanner/blob/master/utilities/processor.py): `utilities/processor.py`
- [CLI scenario runner](https://github.com/sel-columbia/networkplanner/blob/master/utilities/script_process.py): `utilities/script_process.py`
- **RabbitMQ**

### Other components

- **User**

## Connections

- User → Web routes: requests pages (evidence: `np/config/routing.py`)
- Web routes → Scenario controller: routes scenarios (evidence: `np/config/routing.py`)
- Web routes → People controller: routes accounts (evidence: `np/config/routing.py`)
- Web routes → Job and processor views: routes jobs (evidence: `np/config/routing.py`)
- Scenario controller → Scenario model: submits scenarios (evidence: `np/controllers/scenarios.py`)
- Scenario controller → Metric framework: selects metric model (evidence: `np/controllers/scenarios.py`)
- Scenario controller → Network framework: selects network model (evidence: `np/controllers/scenarios.py`)
- Scenario model → Metric framework: applies metrics (evidence: `np/model/__init__.py`)
- Scenario model → Network framework: builds network (evidence: `np/model/__init__.py`)
- Metric framework → Demand models: loads model
- Demand models → Finance metrics: uses finance metrics (evidence: `np/lib/metric/mvMax5/demand.py`)
- Demand models → Demographic metrics: uses demographic metrics (evidence: `np/lib/metric/mvMax5/demand.py`)
- Demand models → Metric variable cache: uses variable cache (evidence: `np/lib/metric/mvMax5/demand.py`)
- Network framework → Kruskal builder: supports builder (evidence: `np/lib/network/modKruskal/__init__.py`)
- Scenario model → Scenario datasets: creates dataset (evidence: `np/model/__init__.py`)
- Scenario datasets → Geospatial I/O: uses geospatial I/O (evidence: `np/lib/dataset_store.py`)
- Scenario datasets → Storage utilities: uses storage helpers (evidence: `np/lib/dataset_store.py`)
- Scenario model → Relational database: persists scenarios
- Scenario processors → Scenario model: loads model (evidence: `utilities/processor.py`)
- CLI scenario runner → Scenario model: runs scenarios (evidence: `utilities/script_process.py`)
- RabbitMQ → Scenario processors: dispatches work