# sebastianolmos/pylondrina architecture

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

- Interactive diagram: https://gitdiagram.com/sebastianolmos/pylondrina
- Repository: https://github.com/sebastianolmos/pylondrina

## Overview

Pylondrina is a Python library implementing the Golondrina mobility-data contract, with an auxiliary web flow viewer. Its principal workflow imports heterogeneous trips, validates and transforms them, builds OD flows, then persists or exports results; persisted flows can be inspected in the viewer. The graph preserves documented trace operations and flow queries as additional branches. Several subsystem links rely on README-level descriptions because those implementations were not excerpted; those links are cited to the README rather than implying source inspection.

Main entry points: [`src/pylondrina/importing.py`](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/importing.py) (Import trips), [`viewer_src/app/main.js`](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/main.js) (Viewer bootstrap), [`src/pylondrina/datasets.py`](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/datasets.py) (Dataset models), [`src/pylondrina/validation.py`](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/validation.py) (Validate trips)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contract["Data contract"]
  node_schema["Schemas<br/>[schema.py]"]
  node_datasets["Dataset models<br/>[datasets.py]"]
  node_sources["Source profiles<br/>[profile.py]"]
end

subgraph group_operations["Mobility operations"]
  node_import_trips["Import trips<br/>[importing.py]"]
  node_validate_trips["Validate trips<br/>[validation.py]"]
  node_fixing["Fix correspondences<br/>[fixing.py]"]
  node_cleaning["Clean trips<br/>[cleaning.py]"]
  node_filtering["Filter datasets<br/>[filtering.py]"]
  node_build_flows["Build OD flows<br/>[flows.py]"]
  node_filter_flows["Filter flows<br/>[flows_filtering.py]"]
  node_trace_import["Import traces"]
  node_trace_validate["Validate traces"]
  node_infer_trips["Infer trips<br/>[inference.py]"]
  node_queries["Flow queries<br/>[flows.py]"]
end

subgraph group_artifacts["Reports and artifacts"]
  node_reports["Operation reports<br/>[reports.py]"]
  node_issues["Issue catalog<br/>[core.py]"]
  node_trip_storage[("Trip bundles<br/>[trips.py]")]
  node_flow_storage[("Flow bundles<br/>[flows.py]")]
  node_flow_export["Flow export<br/>[flows.py]"]
end

subgraph group_viewer["Flow viewer"]
  node_viewer_main["Viewer bootstrap<br/>[main.js]"]
  node_registry_loader["Registry loader"]
  node_dataset_loader["Dataset loader<br/>[loadDatasetData.js]"]
  node_golondrina_loader["Golondrina loader"]
  node_viewer_map["Map rendering<br/>[viewer.js]"]
  node_viewer_overlays["Map overlays<br/>[overlays.js]"]
  node_viewer_state["Viewer state<br/>[state.js]"]
end

node_user(("Analyst"))
node_viewer_user(("Viewer user"))

node_user -->|"supplies data"| node_import_trips
node_import_trips -->|"uses contract"| node_schema
node_import_trips -->|"creates dataset"| node_datasets
node_sources -->|"configures import"| node_import_trips
node_import_trips -->|"validates result"| node_validate_trips
node_validate_trips -->|"checks dataset"| node_datasets
node_validate_trips -->|"returns report"| node_reports
node_import_trips -->|"returns report"| node_reports
node_import_trips -->|"emits issues"| node_issues
node_validate_trips -->|"emits issues"| node_issues
node_user -->|"requests corrections"| node_fixing
node_fixing -->|"corrects data"| node_datasets
node_user -->|"requests cleaning"| node_cleaning
node_cleaning -->|"transforms trips"| node_datasets
node_user -->|"requests filtering"| node_filtering
node_filtering -->|"filters trips"| node_datasets
node_user -->|"builds flows"| node_build_flows
node_build_flows -->|"consumes trips"| node_datasets
node_user -->|"persists trips"| node_trip_storage
node_trip_storage -->|"reads bundles"| node_datasets
node_user -->|"persists flows"| node_flow_storage
node_user -->|"exports flows"| node_flow_export
node_flow_export -->|"records outcome"| node_reports
node_user -->|"filters flows"| node_filter_flows
node_user -->|"queries mappings"| node_queries
node_user -->|"imports traces"| node_trace_import
node_trace_import -->|"validates traces"| node_trace_validate
node_trace_validate -->|"enables inference"| node_infer_trips
node_viewer_user -->|"selects dataset"| node_viewer_main
node_viewer_main -->|"loads registry"| node_registry_loader
node_viewer_main -->|"loads dataset"| node_dataset_loader
node_dataset_loader -.->|"loads Golondrina"| node_golondrina_loader
node_viewer_main -->|"starts viewer"| node_viewer_map
node_viewer_main -->|"sets loaded data"| node_viewer_state
node_viewer_map -->|"reads state"| node_viewer_state
node_viewer_map -->|"updates overlays"| node_viewer_overlays
node_viewer_overlays -->|"reads state"| node_viewer_state
node_registry_loader -.->|"supplies registry"| node_viewer_state
node_viewer_main -.->|"inspects persisted flows"| node_flow_storage

click node_schema "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/schema.py"
click node_datasets "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/datasets.py"
click node_sources "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/sources/profile.py"
click node_import_trips "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/importing.py"
click node_validate_trips "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/validation.py"
click node_fixing "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/fixing.py"
click node_cleaning "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/cleaning.py"
click node_filtering "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/filtering.py"
click node_build_flows "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/flows.py"
click node_filter_flows "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/flows_filtering.py"
click node_trace_import "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/importing_traces.py"
click node_trace_validate "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/validation_traces.py"
click node_infer_trips "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/inference.py"
click node_queries "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/queries/flows.py"
click node_reports "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/reports.py"
click node_issues "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/issues/core.py"
click node_trip_storage "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/io/trips.py"
click node_flow_storage "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/io/flows.py"
click node_flow_export "https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/export/flows.py"
click node_viewer_main "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/main.js"
click node_registry_loader "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadViewerRegistry.js"
click node_dataset_loader "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadDatasetData.js"
click node_golondrina_loader "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadGolondrinaFlowData.js"
click node_viewer_map "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/map/viewer.js"
click node_viewer_overlays "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/ui/overlays.js"
click node_viewer_state "https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/state.js"

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_schema,node_datasets,node_sources,node_viewer_user toneBlue
class node_import_trips,node_validate_trips,node_fixing,node_cleaning,node_filtering,node_build_flows,node_filter_flows,node_trace_import,node_trace_validate,node_infer_trips,node_queries toneAmber
class node_reports,node_issues,node_trip_storage,node_flow_storage,node_flow_export toneMint
class node_viewer_main,node_registry_loader,node_dataset_loader,node_golondrina_loader,node_viewer_map,node_viewer_overlays,node_viewer_state toneRose
class node_user toneIndigo
```

## Components

### Data contract

- [Schemas](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/schema.py): `src/pylondrina/schema.py`
- [Dataset models](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/datasets.py): `src/pylondrina/datasets.py`
- [Source profiles](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/sources/profile.py): `src/pylondrina/sources/profile.py`

### Mobility operations

- [Import trips](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/importing.py): `src/pylondrina/importing.py`
- [Validate trips](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/validation.py): `src/pylondrina/validation.py`
- [Fix correspondences](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/fixing.py): `src/pylondrina/fixing.py`
- [Clean trips](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/cleaning.py): `src/pylondrina/transforms/cleaning.py`
- [Filter datasets](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/filtering.py): `src/pylondrina/transforms/filtering.py`
- [Build OD flows](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/flows.py): `src/pylondrina/transforms/flows.py`
- [Filter flows](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/flows_filtering.py): `src/pylondrina/transforms/flows_filtering.py`
- [Import traces](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/importing_traces.py): `src/pylondrina/importing_traces.py`
- [Validate traces](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/validation_traces.py): `src/pylondrina/validation_traces.py`
- [Infer trips](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/transforms/inference.py): `src/pylondrina/transforms/inference.py`
- [Flow queries](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/queries/flows.py): `src/pylondrina/queries/flows.py`

### Reports and artifacts

- [Operation reports](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/reports.py): `src/pylondrina/reports.py`
- [Issue catalog](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/issues/core.py): `src/pylondrina/issues/core.py`
- [Trip bundles](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/io/trips.py): `src/pylondrina/io/trips.py`
- [Flow bundles](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/io/flows.py): `src/pylondrina/io/flows.py`
- [Flow export](https://github.com/sebastianolmos/pylondrina/blob/main/src/pylondrina/export/flows.py): `src/pylondrina/export/flows.py`

### Flow viewer

- [Viewer bootstrap](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/main.js): `viewer_src/app/main.js`
- [Registry loader](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadViewerRegistry.js): `viewer_src/app/data/loadViewerRegistry.js`
- [Dataset loader](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadDatasetData.js): `viewer_src/app/data/loadDatasetData.js`
- [Golondrina loader](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/data/loadGolondrinaFlowData.js): `viewer_src/app/data/loadGolondrinaFlowData.js`
- [Map rendering](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/map/viewer.js): `viewer_src/app/map/viewer.js`
- [Map overlays](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/ui/overlays.js): `viewer_src/app/ui/overlays.js`
- [Viewer state](https://github.com/sebastianolmos/pylondrina/blob/main/viewer_src/app/state.js): `viewer_src/app/state.js`

### Other components

- **Analyst**
- **Viewer user**

## Connections

- Analyst → Import trips: supplies data (evidence: `README.md`)
- Import trips → Schemas: uses contract (evidence: `src/pylondrina/importing.py`)
- Import trips → Dataset models: creates dataset (evidence: `src/pylondrina/importing.py`)
- Source profiles → Import trips: configures import (evidence: `src/pylondrina/sources/profile.py`)
- Import trips → Validate trips: validates result (evidence: `README.md`)
- Validate trips → Dataset models: checks dataset (evidence: `src/pylondrina/validation.py`)
- Validate trips → Operation reports: returns report (evidence: `README.md`)
- Import trips → Operation reports: returns report (evidence: `src/pylondrina/importing.py`)
- Import trips → Issue catalog: emits issues (evidence: `src/pylondrina/importing.py`)
- Validate trips → Issue catalog: emits issues (evidence: `src/pylondrina/validation.py`)
- Analyst → Fix correspondences: requests corrections (evidence: `README.md`)
- Fix correspondences → Dataset models: corrects data (evidence: `README.md`)
- Analyst → Clean trips: requests cleaning (evidence: `README.md`)
- Clean trips → Dataset models: transforms trips (evidence: `README.md`)
- Analyst → Filter datasets: requests filtering (evidence: `README.md`)
- Filter datasets → Dataset models: filters trips (evidence: `src/pylondrina/transforms/filtering.py`)
- Analyst → Build OD flows: builds flows (evidence: `README.md`)
- Build OD flows → Dataset models: consumes trips (evidence: `README.md`)
- Analyst → Trip bundles: persists trips (evidence: `README.md`)
- Trip bundles → Dataset models: reads bundles (evidence: `src/pylondrina/io/trips.py`)
- Analyst → Flow bundles: persists flows (evidence: `README.md`)
- Analyst → Flow export: exports flows (evidence: `README.md`)
- Flow export → Operation reports: records outcome (evidence: `src/pylondrina/export/flows.py`)
- Analyst → Filter flows: filters flows (evidence: `README.md`)
- Analyst → Flow queries: queries mappings (evidence: `README.md`)
- Analyst → Import traces: imports traces (evidence: `README.md`)
- Import traces → Validate traces: validates traces (evidence: `README.md`)
- Validate traces → Infer trips: enables inference (evidence: `README.md`)
- Viewer user → Viewer bootstrap: selects dataset (evidence: `viewer_src/app/main.js`)
- Viewer bootstrap → Registry loader: loads registry (evidence: `viewer_src/app/main.js`)
- Viewer bootstrap → Dataset loader: loads dataset (evidence: `viewer_src/app/main.js`)
- Dataset loader → Golondrina loader: loads Golondrina
- Viewer bootstrap → Map rendering: starts viewer (evidence: `viewer_src/app/main.js`)
- Viewer bootstrap → Viewer state: sets loaded data (evidence: `viewer_src/app/main.js`)
- Map rendering → Viewer state: reads state (evidence: `viewer_src/app/map/viewer.js`)
- Map rendering → Map overlays: updates overlays (evidence: `viewer_src/app/map/viewer.js`)
- Map overlays → Viewer state: reads state (evidence: `viewer_src/app/ui/overlays.js`)
- Registry loader → Viewer state: supplies registry
- Viewer bootstrap → Flow bundles: inspects persisted flows
