# adidev1512006/poolride-ncr architecture

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

- Interactive diagram: https://gitdiagram.com/adidev1512006/poolride-ncr
- Repository: https://github.com/adidev1512006/poolride-ncr

## Overview

PoolRide NCR is a student cab-pooling optimizer. Its main workflow takes student locations and arrival times plus pooling rules, forms cabs under time-gap and detour constraints, and reports distance, savings, and violations. The Python CLI also compares naive and exact groupings; the browser app offers CSV/paste input and constrained-pooling results. Source excerpts establish the CLI and algorithm calls; browser internals and CSV/model wiring are not sampled, so those relationships are omitted or marked unverified.

Main entry points: [`main.py`](https://github.com/adidev1512006/poolride-ncr/blob/main/main.py) (CLI runner), [`poolride/routing.py`](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/routing.py) (Cab route search), [`index.html`](https://github.com/adidev1512006/poolride-ncr/blob/main/index.html) (Browser app), [`poolride/grouping.py`](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py) (Naive baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_inputdata["Student input<br/>[data_io.py]"]
  node_cli["CLI runner<br/>[main.py]"]
  node_web["Browser app<br/>[index.html]"]
end

subgraph group_domain["Pooling algorithms"]
  node_params["Pooling rules<br/>[config.py]"]
  node_student["Student record<br/>[models.py]"]
  node_greedy["Constrained greedy<br/>[grouping.py]"]
  node_naive["Naive baseline<br/>[grouping.py]"]
  node_exact["Exact solver<br/>[grouping.py]"]
end

subgraph group_calculation["Shared calculations"]
  node_route["Cab route search<br/>[routing.py]"]
  node_distance["Distance calculation<br/>[geo.py]"]
  node_metrics["Results and violations<br/>[metrics.py]"]
end

node_commuter(("Operator"))

node_commuter -->|"runs"| node_cli
node_commuter -->|"uses"| node_web
node_cli -->|"loads CSV"| node_inputdata
node_cli -->|"configures"| node_params
node_cli -->|"runs"| node_greedy
node_cli -->|"runs"| node_naive
node_cli -->|"optionally runs"| node_exact
node_cli -->|"summarizes"| node_metrics
node_greedy -->|"searches routes"| node_route
node_naive -->|"searches routes"| node_route
node_exact -->|"precomputes routes"| node_route
node_route -->|"computes legs"| node_distance
node_naive -->|"measures proximity"| node_distance
node_web -.->|"accepts CSV"| node_inputdata
node_web -.->|"uses constrained pooling"| node_greedy

click node_inputdata "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/data_io.py"
click node_cli "https://github.com/adidev1512006/poolride-ncr/blob/main/main.py"
click node_web "https://github.com/adidev1512006/poolride-ncr/blob/main/index.html"
click node_params "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/config.py"
click node_student "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/models.py"
click node_greedy "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py"
click node_naive "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py"
click node_exact "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py"
click node_route "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/routing.py"
click node_distance "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/geo.py"
click node_metrics "https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/metrics.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_inputdata,node_cli,node_web toneBlue
class node_params,node_student,node_greedy,node_naive,node_exact toneAmber
class node_route,node_distance,node_metrics toneMint
class node_commuter toneIndigo
```

## Components

### User interfaces

- [Student input](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/data_io.py): `poolride/data_io.py`
- [CLI runner](https://github.com/adidev1512006/poolride-ncr/blob/main/main.py): `main.py`
- [Browser app](https://github.com/adidev1512006/poolride-ncr/blob/main/index.html): `index.html`

### Pooling algorithms

- [Pooling rules](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/config.py): `poolride/config.py`
- [Student record](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/models.py): `poolride/models.py`
- [Constrained greedy](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py): `poolride/grouping.py`
- [Naive baseline](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py): `poolride/grouping.py`
- [Exact solver](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/grouping.py): `poolride/grouping.py`

### Shared calculations

- [Cab route search](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/routing.py): `poolride/routing.py`
- [Distance calculation](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/geo.py): `poolride/geo.py`
- [Results and violations](https://github.com/adidev1512006/poolride-ncr/blob/main/poolride/metrics.py): `poolride/metrics.py`

### Other components

- **Operator**

## Connections

- Operator → CLI runner: runs (evidence: `README.md`)
- Operator → Browser app: uses (evidence: `README.md`)
- CLI runner → Student input: loads CSV (evidence: `main.py`)
- CLI runner → Pooling rules: configures (evidence: `main.py`)
- CLI runner → Constrained greedy: runs (evidence: `main.py`)
- CLI runner → Naive baseline: runs (evidence: `main.py`)
- CLI runner → Exact solver: optionally runs (evidence: `main.py`)
- CLI runner → Results and violations: summarizes (evidence: `main.py`)
- Constrained greedy → Cab route search: searches routes (evidence: `poolride/grouping.py`)
- Naive baseline → Cab route search: searches routes (evidence: `poolride/grouping.py`)
- Exact solver → Cab route search: precomputes routes (evidence: `poolride/grouping.py`)
- Cab route search → Distance calculation: computes legs (evidence: `poolride/routing.py`)
- Naive baseline → Distance calculation: measures proximity (evidence: `poolride/grouping.py`)
- Browser app → Student input: accepts CSV (evidence: `README.md`)
- Browser app → Constrained greedy: uses constrained pooling (evidence: `README.md`)