# c2g-dev/city2graph architecture

> Architecture diagram of the GitHub repository c2g-dev/city2graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/c2g-dev/city2graph
- Repository: https://github.com/c2g-dev/city2graph

## Overview

City2Graph is a pure-Python geospatial graph-construction library. Its architecture is centered on transforming geographic tabular data into graph objects that can be consumed by spatial analysis workflows, NetworkX, and optionally PyTorch Geometric.

1. Core package boundary  
   The `city2graph/` package is the runtime library. `__init__.py` exposes the public API, while the domain modules underneath implement different graph-generation strategies. There is no server or service layer; the repo is a library plus docs/tests.

2. Shared graph model and conversion layer  
   `base.py` and `graph.py` appear to define the shared internal graph abstractions and common conversion/normalization logic. This is the main boundary between geospatial inputs and graph outputs, and it is where a diagram should place the “core representation” of nodes, edges, attributes, and graph metadata.

3. Spatial data helpers  
   `data.py` and `utils.py` provide supporting functions for loading, validating, and transforming inputs, plus general utilities reused across the domain modules. These are the glue layer used before or after graph construction.

4. Proximity and contiguity subsystem  
   `proximity.py` builds graphs from spatial closeness and adjacency relationships. Based on the README, this includes proximity-based graph generation, multi-center distance filtering, and layered isochrone-style relationships. This subsystem likely accepts GeoPandas geometries and emits edge lists/graphs.

5. Morphology subsystem  
   `morphology.py` handles graphs derived from urban form features such as buildings or other morphological entities. The docs include an example for building graphs from Overture Maps, which suggests this module operates on parcel/building-style geospatial layers and constructs morphology-driven connectivity.

6. Transportation subsystem  
   `transportation.py` is the transit-network branch. The README specifically calls out GTFS feeds queried through DuckDB, so this module is the main bridge from transport schedule data to graph structures for route/service/accessibility analysis.

7. Mobility subsystem  
   `mobility.py` models movement flows such as OD matrices, bike-sharing, migration, and pedestrian flows. This subsystem converts mobility matrices or flow tables into graph representations, distinct from purely spatial adjacency graphs.

8. Metapath / heterogeneous-graph augmentation  
   `metapath.py` adds higher-level graph logic for heterogeneous or multi-relational analysis. The notebook `add_metapaths.ipynb` indicates this module enriches existing graphs with metapath-based relationships for downstream GNN or network analysis.

9. External technology boundaries  
   The library integrates with GeoPandas for geospatial inputs, NetworkX for graph operations, and PyTorch Geometric for tensor/ML workflows. PyTorch/PyG are optional extras, which creates a clear boundary between general graph construction and GNN-specific consumption.

10. Package distribution and environment  
   `pyproject.toml`, `uv.lock`, `Dockerfile`, and `docker-compose.yml` define packaging and reproducible development environments. The README also shows install extras for CPU/CUDA variants, so deployment is mostly via Python packaging rather than a separate runtime.

11. Documentation and examples as first-class architecture  
   `docs/` contains MkDocs-based documentation, API references for each module, and notebook examples for the main workflows: proximity graphs, OD matrices, GTFS, metapaths, and morphology. This indicates the library is designed around user-driven notebook experimentation as much as scripted use.

12. Test structure and quality gates  
   `tests/` mirrors the domain modules with unit tests for each subsystem plus fixtures in `tests/data/`. GitHub Actions workflows run build/test/deploy/documentation jobs, and pre-commit/Ruff are used as quality gates. This suggests the architecture is intentionally modular, with each graph-building domain verified independently.

A good architecture diagram for this repo should show: geospatial/mobility/transit inputs on the left; the shared core graph model in the center; domain-specific constructors around it; and export paths to NetworkX/PyTorch Geometric on the right, with docs/tests/CI as supporting system boundaries.

Main entry points: [`city2graph/base.py`](https://github.com/c2g-dev/city2graph/blob/main/city2graph/base.py) (Core model), [`tests/test_graph.py`](https://github.com/c2g-dev/city2graph/blob/main/tests/test_graph.py) (Tests), [`city2graph/__init__.py`](https://github.com/c2g-dev/city2graph/blob/main/city2graph/__init__.py) (Public API), [`docs/examples/index.md`](https://github.com/c2g-dev/city2graph/blob/main/docs/examples/index.md) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_n1["Public API<br/>package entrypoint<br/>[__init__.py]"]
  node_n2["Core model<br/>graph abstraction<br/>[base.py]"]
  node_n3["Graph ops<br/>conversion layer<br/>[graph.py]"]
  node_n4["Data helpers<br/>input prep<br/>[data.py]"]
  node_n5["Utilities<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_domains["Graph builders"]
  node_n6["Proximity<br/>spatial graph builder<br/>[proximity.py]"]
  node_n7["Morphology<br/>urban form builder<br/>[morphology.py]"]
  node_n8["Transportation<br/>transit graph builder<br/>[transportation.py]"]
  node_n9["Mobility<br/>flow graph builder<br/>[mobility.py]"]
  node_n10["Metapaths<br/>heterogeneous augmentation<br/>[metapath.py]"]
end

subgraph group_integrations["External integrations"]
  node_n11[("GeoPandas<br/>geospatial input")]
  node_n12[("GTFS/DuckDB<br/>transit source")]
  node_n13[("Flow tables<br/>mobility source")]
  node_n14(("NetworkX<br/>graph runtime"))
  node_n15(("PyG<br/>ml tensor target"))
end

subgraph group_support["Support system"]
  node_n16["Docs<br/>documentation<br/>[index.md]"]
  node_n17["Examples<br/>notebooks<br/>[index.md]"]
  node_n18["Tests<br/>test suite<br/>[test_graph.py]"]
  node_n19["CI/CD<br/>automation<br/>[test.yml]"]
end

node_n11 -->|"prepare"| node_n4
node_n12 -->|"prepare"| node_n4
node_n13 -->|"prepare"| node_n4
node_n4 -->|"normalize"| node_n2
node_n5 -->|"support"| node_n2
node_n2 -->|"convert"| node_n3
node_n6 -->|"build"| node_n2
node_n7 -->|"build"| node_n2
node_n8 -->|"build"| node_n2
node_n9 -->|"build"| node_n2
node_n10 -->|"augment"| node_n2
node_n3 -->|"export"| node_n14
node_n3 -->|"export"| node_n15
node_n1 -->|"expose"| node_n6
node_n1 -->|"expose"| node_n7
node_n1 -->|"expose"| node_n8
node_n1 -->|"expose"| node_n9
node_n1 -->|"expose"| node_n10
node_n16 -.->|"document"| node_n1
node_n17 -.->|"demonstrate"| node_n6
node_n17 -.->|"demonstrate"| node_n8
node_n17 -.->|"demonstrate"| node_n9
node_n17 -.->|"demonstrate"| node_n10
node_n18 -.->|"verify"| node_n2
node_n18 -.->|"verify"| node_n6
node_n18 -.->|"verify"| node_n7
node_n18 -.->|"verify"| node_n8
node_n18 -.->|"verify"| node_n9
node_n18 -.->|"verify"| node_n10
node_n19 -.->|"publish"| node_n16
node_n19 -.->|"run"| node_n18

click node_n1 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/__init__.py"
click node_n2 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/base.py"
click node_n3 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/graph.py"
click node_n4 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/data.py"
click node_n5 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/utils.py"
click node_n6 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/proximity.py"
click node_n7 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/morphology.py"
click node_n8 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/transportation.py"
click node_n9 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/mobility.py"
click node_n10 "https://github.com/c2g-dev/city2graph/blob/main/city2graph/metapath.py"
click node_n16 "https://github.com/c2g-dev/city2graph/blob/main/docs/index.md"
click node_n17 "https://github.com/c2g-dev/city2graph/blob/main/docs/examples/index.md"
click node_n18 "https://github.com/c2g-dev/city2graph/blob/main/tests/test_graph.py"
click node_n19 "https://github.com/c2g-dev/city2graph/blob/main/.github/workflows/test.yml"

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_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n6,node_n7,node_n8,node_n9,node_n10 toneAmber
class node_n11,node_n12,node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18,node_n19 toneRose
```

## Components

### Core library

Public API, shared model, and conversion layer.

- [Public API](https://github.com/c2g-dev/city2graph/blob/main/city2graph/__init__.py): package entrypoint · Exports the main user-facing constructors and symbols. · `city2graph/__init__.py`
- [Core model](https://github.com/c2g-dev/city2graph/blob/main/city2graph/base.py): graph abstraction · Shared internal representation for nodes, edges, and graph metadata. · `city2graph/base.py`
- [Graph ops](https://github.com/c2g-dev/city2graph/blob/main/city2graph/graph.py): conversion layer · Common graph normalization, conversion, and interoperability logic. · `city2graph/graph.py`
- [Data helpers](https://github.com/c2g-dev/city2graph/blob/main/city2graph/data.py): input prep · Loading, validation, and transformation helpers for geospatial inputs. · `city2graph/data.py`
- [Utilities](https://github.com/c2g-dev/city2graph/blob/main/city2graph/utils.py): shared helpers · General reusable helper functions used across the package. · `city2graph/utils.py`

### Graph builders

Domain-specific constructors for different geospatial and mobility workflows.

- [Proximity](https://github.com/c2g-dev/city2graph/blob/main/city2graph/proximity.py): spatial graph builder · Builds graphs from closeness, adjacency, and distance-based relationships. · `city2graph/proximity.py`
- [Morphology](https://github.com/c2g-dev/city2graph/blob/main/city2graph/morphology.py): urban form builder · Constructs graphs from buildings and other morphological geospatial layers. · `city2graph/morphology.py`
- [Transportation](https://github.com/c2g-dev/city2graph/blob/main/city2graph/transportation.py): transit graph builder · Transforms GTFS-style transit data into graph structures for analysis. · `city2graph/transportation.py`
- [Mobility](https://github.com/c2g-dev/city2graph/blob/main/city2graph/mobility.py): flow graph builder · Converts OD matrices and movement flows into graph representations. · `city2graph/mobility.py`
- [Metapaths](https://github.com/c2g-dev/city2graph/blob/main/city2graph/metapath.py): heterogeneous augmentation · Adds metapath-based relationships for heterogeneous graph analysis. · `city2graph/metapath.py`

### External integrations

Third-party graph and geospatial ecosystems used by the library.

- **GeoPandas**: geospatial input · Primary geospatial dataframe and geometry source for graph construction.
- **GTFS/DuckDB**: transit source · Transit schedule and route data queried through DuckDB.
- **Flow tables**: mobility source · OD matrices, bike-share, migration, and pedestrian flow inputs.
- **NetworkX**: graph runtime · Core graph library used as a downstream graph consumer.
- **PyG**: ml tensor target · Optional PyTorch Geometric export path for GNN workflows.

### Support system

Documentation, tests, packaging, and CI around the library.

- [Docs](https://github.com/c2g-dev/city2graph/blob/main/docs/index.md): documentation · MkDocs documentation and notebooks for the main workflows. · `docs/index.md`
- [Examples](https://github.com/c2g-dev/city2graph/blob/main/docs/examples/index.md): notebooks · Workflow examples for proximity, morphology, GTFS, mobility, and metapaths. · `docs/examples/index.md`
- [Tests](https://github.com/c2g-dev/city2graph/blob/main/tests/test_graph.py): test suite · Module-level tests and fixtures covering the main graph builders. · `tests/test_graph.py`
- [CI/CD](https://github.com/c2g-dev/city2graph/blob/main/.github/workflows/test.yml): automation · GitHub Actions, packaging, and release/deployment automation. · `.github/workflows/test.yml`

## Connections

- GeoPandas → Data helpers: prepare · Geospatial tabular inputs are validated and normalized before graph building.
- GTFS/DuckDB → Data helpers: prepare · Transit source data is loaded and shaped for the transportation pipeline.
- Flow tables → Data helpers: prepare · Flow tables are cleaned and reshaped into graph-ready records.
- Data helpers → Core model: normalize · Input helpers feed the shared graph model boundary.
- Utilities → Core model: support · Utilities assist graph model creation and manipulation.
- Core model → Graph ops: convert · The core representation is converted into interoperable graph objects.
- Proximity → Core model: build · Proximity relationships are expressed through the shared graph model.
- Morphology → Core model: build · Morphology-derived connectivity is mapped into the core representation.
- Transportation → Core model: build · Transit data is transformed into graph objects via the shared model.
- Mobility → Core model: build · Mobility flows are turned into graph structures using the common model.
- Metapaths → Core model: augment · Metapath relationships extend the shared graph representation.
- Graph ops → NetworkX: export · Graphs can be consumed by NetworkX workflows.
- Graph ops → PyG: export · Graphs can optionally be exported for PyTorch Geometric.
- Public API → Proximity: expose · The public API surfaces the proximity builder.
- Public API → Morphology: expose · The public API surfaces the morphology builder.
- Public API → Transportation: expose · The public API surfaces the transportation builder.
- Public API → Mobility: expose · The public API surfaces the mobility builder.
- Public API → Metapaths: expose · The public API surfaces metapath augmentation tools.
- Docs → Public API: document · Docs describe the public API and module boundaries.
- Examples → Proximity: demonstrate · Examples show the proximity workflow in notebooks.
- Examples → Transportation: demonstrate · Examples show the GTFS workflow in notebooks.
- Examples → Mobility: demonstrate · Examples show the mobility workflow in notebooks.
- Examples → Metapaths: demonstrate · Examples show metapath enrichment in notebooks.
- Tests → Core model: verify · Tests cover the shared graph model and conversions.
- Tests → Proximity: verify · Tests cover proximity graph generation.
- Tests → Morphology: verify · Tests cover morphology graph generation.
- Tests → Transportation: verify · Tests cover transportation graph generation.
- Tests → Mobility: verify · Tests cover mobility graph generation.
- Tests → Metapaths: verify · Tests cover metapath augmentation.
- CI/CD → Docs: publish · Automation builds and publishes the documentation site.
- CI/CD → Tests: run · Automation runs the test suite and quality gates.
