# praneel-sketch/idp-c architecture

> Architecture diagram of the GitHub repository praneel-sketch/idp-c, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/praneel-sketch/idp-c
- Repository: https://github.com/praneel-sketch/idp-c

## Overview

CityChange is an Earth-observation analysis product: users select a region, then inspect a dated, evidence-qualified account of its land-cover history in a web map or API. The main workflow acquires annual observations, normalizes land classes, detects persistent events, models trajectories and confidence, and publishes summaries and map layers. Separate branches provide anomaly and pattern analysis, imagery for visual verification, and cross-product validation. The graph follows documented capabilities and sampled entry points; detailed internal call wiring is limited where pipeline and server excerpts are incomplete.

Main entry points: [`citychange/pipeline.py`](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/pipeline.py) (Analysis orchestrator), [`citychange/server.py`](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/server.py) (Web API), [`frontend/js/app.js`](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/frontend/js/app.js) (Time Machine UI), [`citychange/datasets/io_annual_lulc.py`](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/io_annual_lulc.py) (Annual LULC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Time Machine UI<br/>[app.js]"]
  node_server["Web API<br/>[server.py]"]
end

subgraph group_acquisition["Observation acquisition"]
  node_io_lulc["Annual LULC<br/>[io_annual_lulc.py]"]
  node_landstate["Canonical land states<br/>[landstate.py]"]
end

subgraph group_intelligence["Change intelligence"]
  node_events["Dated events<br/>[events.py]"]
  node_analysis["Change patterns<br/>[analysis.py]"]
  node_trajectory["Trajectories and rarity<br/>[trajectory.py]"]
  node_confidence["Evidence confidence<br/>[confidence.py]"]
end

subgraph group_evidence["Evidence and validation"]
  node_worldcover["WorldCover comparison<br/>[esa_worldcover.py]"]
  node_validation["Cross-product validation<br/>[validation.py]"]
  node_sentinel["Before/after imagery<br/>[sentinel2.py]"]
  node_benchmark["Region benchmarks<br/>[benchmark.py]"]
end

subgraph group_delivery["Analysis delivery"]
  node_pipeline["Analysis orchestrator<br/>[pipeline.py]"]
  node_report["Grounded summaries<br/>[report.py]"]
  node_overlays["Map overlays<br/>[overlays.py]"]
  node_tiles["Map tiles<br/>[tiles.py]"]
  node_bundle["Analysis bundle"]
end

node_user(("Map user"))
node_nominatim(("Nominatim"))
node_io_cloud(("Public LULC COGs"))
node_stac(("Earth Search STAC"))

node_user -->|"selects region"| node_frontend
node_frontend -->|"requests analysis"| node_server
node_server -->|"runs analysis"| node_pipeline
node_frontend -->|"fetches results"| node_server
node_server -.->|"geocodes query"| node_nominatim
node_pipeline -->|"acquires annual grids"| node_io_lulc
node_io_lulc -->|"reads windows"| node_io_cloud
node_pipeline -->|"remaps classes"| node_landstate
node_pipeline -->|"extracts events"| node_events
node_pipeline -->|"computes patterns"| node_analysis
node_pipeline -->|"models histories"| node_trajectory
node_pipeline -->|"scores evidence"| node_confidence
node_pipeline -->|"builds summary"| node_report
node_pipeline -->|"renders layers"| node_overlays
node_pipeline -->|"writes outputs"| node_bundle
node_server -->|"reads bundles"| node_bundle
node_server -->|"serves API data"| node_frontend
node_pipeline -.->|"requests evidence chips"| node_sentinel
node_sentinel -.->|"searches scenes"| node_stac
node_pipeline -.->|"validates results"| node_validation
node_validation -->|"compares observations"| node_worldcover
node_benchmark -->|"runs regions"| node_pipeline
node_frontend -->|"requests map layers"| node_tiles

click node_frontend "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/frontend/js/app.js"
click node_server "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/server.py"
click node_pipeline "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/pipeline.py"
click node_io_lulc "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/io_annual_lulc.py"
click node_landstate "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/landstate.py"
click node_events "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/events.py"
click node_analysis "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/analysis.py"
click node_trajectory "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/trajectory.py"
click node_confidence "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/confidence.py"
click node_worldcover "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/esa_worldcover.py"
click node_validation "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/validation.py"
click node_sentinel "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/sentinel2.py"
click node_report "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/report.py"
click node_overlays "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/overlays.py"
click node_tiles "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/tiles.py"
click node_bundle "https://github.com/praneel-sketch/idp-c/tree/claude/citychange-init-0rjbgb/data"
click node_benchmark "https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/benchmark.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_frontend,node_server,node_user toneBlue
class node_io_lulc,node_landstate toneAmber
class node_events,node_analysis,node_trajectory,node_confidence toneMint
class node_worldcover,node_validation,node_sentinel,node_benchmark toneRose
class node_pipeline,node_report,node_overlays,node_tiles,node_bundle,node_nominatim,node_io_cloud,node_stac toneIndigo
```

## Components

### User experience

- [Time Machine UI](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/frontend/js/app.js): `frontend/js/app.js`
- [Web API](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/server.py): `citychange/server.py`

### Observation acquisition

- [Annual LULC](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/io_annual_lulc.py): `citychange/datasets/io_annual_lulc.py`
- [Canonical land states](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/landstate.py): `citychange/landstate.py`

### Change intelligence

- [Dated events](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/events.py): `citychange/events.py`
- [Change patterns](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/analysis.py): `citychange/analysis.py`
- [Trajectories and rarity](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/trajectory.py): `citychange/trajectory.py`
- [Evidence confidence](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/confidence.py): `citychange/confidence.py`

### Evidence and validation

- [WorldCover comparison](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/esa_worldcover.py): `citychange/datasets/esa_worldcover.py`
- [Cross-product validation](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/validation.py): `citychange/validation.py`
- [Before/after imagery](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/datasets/sentinel2.py): `citychange/datasets/sentinel2.py`
- [Region benchmarks](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/benchmark.py): `citychange/benchmark.py`

### Analysis delivery

- [Analysis orchestrator](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/pipeline.py): `citychange/pipeline.py`
- [Grounded summaries](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/report.py): `citychange/report.py`
- [Map overlays](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/overlays.py): `citychange/overlays.py`
- [Map tiles](https://github.com/praneel-sketch/idp-c/blob/claude/citychange-init-0rjbgb/citychange/tiles.py): `citychange/tiles.py`
- [Analysis bundle](https://github.com/praneel-sketch/idp-c/tree/claude/citychange-init-0rjbgb/data): `data`

### Other components

- **Map user**
- **Nominatim**
- **Public LULC COGs**
- **Earth Search STAC**

## Connections

- Map user → Time Machine UI: selects region
- Time Machine UI → Web API: requests analysis
- Web API → Analysis orchestrator: runs analysis
- Time Machine UI → Web API: fetches results
- Web API → Nominatim: geocodes query
- Analysis orchestrator → Annual LULC: acquires annual grids
- Annual LULC → Public LULC COGs: reads windows
- Analysis orchestrator → Canonical land states: remaps classes
- Analysis orchestrator → Dated events: extracts events
- Analysis orchestrator → Change patterns: computes patterns
- Analysis orchestrator → Trajectories and rarity: models histories
- Analysis orchestrator → Evidence confidence: scores evidence
- Analysis orchestrator → Grounded summaries: builds summary
- Analysis orchestrator → Map overlays: renders layers
- Analysis orchestrator → Analysis bundle: writes outputs
- Web API → Analysis bundle: reads bundles
- Web API → Time Machine UI: serves API data
- Analysis orchestrator → Before/after imagery: requests evidence chips
- Before/after imagery → Earth Search STAC: searches scenes
- Analysis orchestrator → Cross-product validation: validates results
- Cross-product validation → WorldCover comparison: compares observations
- Region benchmarks → Analysis orchestrator: runs regions
- Time Machine UI → Map tiles: requests map layers