# Transportationer — 15-Minute City Analyzer

A web application for analyzing urban accessibility through the lens of the 15-minute city concept. Shows a heatmap indicating distance to locations of interest across 5 categories: **Service & Trade**, **Transport**, **Work & School**, **Culture & Community**, and **Recreation**.

## Architecture

```
Browser (Next.js / React)
  ├── MapLibre GL JS (map + canvas heatmap / isochrone overlay)
  └── API calls → Next.js API routes

Next.js App Server
  ├── Public API: /api/cities /api/tiles /api/stats /api/location-score /api/isochrones
  ├── Admin API: /api/admin/** (auth-protected)
  ├── PostgreSQL + PostGIS (POIs, grid points, precomputed scores)
  └── Valkey (API response cache, BullMQ queues)

BullMQ Worker (pipeline queue, concurrency 8)
  ├── refresh-city     → orchestrates full ingest via FlowProducer
  ├── download-pbf     → streams OSM PBF from Geofabrik
  ├── extract-pois     → osmium filter + osm2pgsql flex → raw_pois
  ├── build-valhalla   → clips PBF, builds Valhalla routing tiles
  ├── generate-grid    → PostGIS 200 m hex grid → grid_points
  ├── compute-scores   → two-phase orchestrator (see Scoring below)
  └── compute-routing  → Valhalla matrix → grid_poi_details
                         (15 parallel jobs: 3 modes × 5 categories)

BullMQ Worker (valhalla queue, concurrency 1)
  └── build-valhalla   → runs valhalla_build_tiles, manages valhalla_service

Valhalla (child process of valhalla worker)
  ├── sources_to_targets matrix → compute-routing jobs
  └── isochrones endpoint       → user click → /api/isochrones

Protomaps → self-hosted map tiles (PMTiles)
```

## Quick Start

### 1. Configure environment

```bash
cp .env.example .env
# Edit .env with strong passwords

# Generate admin password hash
node -e "require('bcryptjs').hash('yourpassword', 12).then(console.log)"
# Paste result as ADMIN_PASSWORD_HASH in .env
```

### 2. Start services

```bash
docker compose up -d
```

### 3. Add a city

Open [http://localhost:3000/admin](http://localhost:3000/admin), log in, click **Add City**, browse Geofabrik regions (e.g. `europe/germany/berlin`), and start ingestion. Progress is shown live.

Processing time:
- Small city (< 100k pop): ~5–15 minutes
- Large city (1M+ pop): ~30–90 minutes

### 4. Explore

Open [http://localhost:3000](http://localhost:3000) and select your city.

## Map Tiles

By default the app uses CartoDB Positron (CDN). For fully offline operation, download a PMTiles file for your region:

```bash
# Example: download Berlin region tiles
wget https://maps.protomaps.com/builds/berlin.pmtiles -O apps/web/public/tiles/region.pmtiles
# Then switch to the PMTiles style:
cp apps/web/public/tiles/style.pmtiles.json apps/web/public/tiles/style.json
```

## Development

```bash
npm install
npm run dev               # Next.js dev server on :3000
npm run worker:dev        # BullMQ worker with hot reload
```

Required local services: PostgreSQL+PostGIS, Valkey. Easiest via:

```bash
docker compose up postgres valkey -d
```

## Category Definitions

| Category | OSM Sources |
|----------|-------------|
| Service & Trade | supermarkets, shops, restaurants, pharmacies, banks, cafés |
| Transport | bus stops, metro, tram, train stations, bike share, car share |
| Work & School | offices, coworking, schools, kindergartens, universities |
| Culture & Community | libraries, hospitals, clinics, museums, theatres, community centres |
| Recreation | parks, playgrounds, sports centres, gyms, green spaces |

## Scoring

### Data pipeline

For each grid point (200 m hexagonal spacing) the pipeline runs in two phases:

**Phase 1 — Routing** (15 parallel jobs: 3 modes × 5 categories)

A PostGIS KNN lateral join (`<->` operator) finds the 6 nearest POIs in the category for each grid point. Those POI coordinates are passed to Valhalla's `sources_to_targets` matrix API to obtain real network travel times for the requested travel mode (walking, cycling, driving). The nearest POI per subcategory is persisted to `grid_poi_details`.

**Phase 2 — Score aggregation**

Scores are precomputed for every combination of:
- 5 thresholds: 5, 10, 15, 20, 30 minutes
- 3 travel modes: walking, cycling, driving
- 5 profiles: Universal, Young Family, Senior, Young Professional, Student

### Scoring formula

Each subcategory *i* within a category contributes a sigmoid score:

```
sigmoid(t, T) = 1 / (1 + exp(4 × (t − T) / T))
```

Where `t` is the Valhalla travel time in seconds and `T` is the threshold in seconds. The sigmoid equals 0.5 exactly at the threshold and approaches 1 for very short times.

The category score combines subcategories via a complement-product, weighted by per-profile subcategory importance weights `w_i ∈ [0, 1]`:

```
category_score = 1 − ∏ (1 − w_i × sigmoid(t_i, T))
```

This captures diversity of coverage: reaching one supermarket near you already yields a high score, but having a pharmacy, bakery, and bank nearby as well pushes the score higher.

### Profiles

Each profile carries two sets of weights:

- **Category weights** (used as slider presets in the UI, range 0–2): how much relative importance each of the 5 categories gets in the composite score.
- **Subcategory weights** (used during score computation, range 0–1): how much a specific subcategory contributes to its category score.

| Profile | Focus |
|---------|-------|
| Universal | Balanced across all resident types |
| Young Family | Schools, playgrounds, healthcare, daily shopping |
| Senior | Healthcare, local services, accessible green space, transit |
| Young Professional | Rapid transit, fitness, dining, coworking |
| Student | University, library, cafés, transit, budget services |

### Composite score

The composite shown on the heatmap is a weighted average of the 5 category scores. Category weights come from the selected profile but can be adjusted freely in the UI. All scores are precomputed — changing the profile or weights only triggers a client-side re-blend with no server round-trip.