Design decisions¶
These records explain decisions that are hard to reverse or surprising without context: what was decided, why, and which alternatives were rejected. Read them before proposing to change one of these areas. A new decision gets the next number.
| Record | Decision |
|---|---|
| 0001 | Handlers separate the search key, which finds the files to fetch, from the search geometry, which crops the loaded data. |
| 0002 | The handler base is documented in the API reference, but it is not a stable API for other packages. |
| 0003 | Users import from the top level or a public subpackage, which load lazily. Every other module path is internal. |
| 0004 | A spatial network is held as node and edge tables; networkx and pandana are exports, and edits return a new network. |
| 0005 | A saved spatial network is a folder with a nodes Parquet file, an edges GeoParquet file, and a JSON metadata file. |
| 0006 | OSM extracts are stored by date, and the network built from each is saved uncropped beside it; cropping happens at load. |
| 0007 | OSM extracts are chosen by polygon, with ISO codes only as a fast path and a curated list of multi-country extracts. |
| 0008 | Connecting points to an existing network is a rooted Steiner tree with the existing network as one virtual root, solved by ConnectionPlanner. |