Urban Context Analysis

A lightweight urban context analysis MVP for point- or project-boundary-based XL / L / M fact sheets.

Click a location, upload a project boundary, or draw one on the map; then inspect structured indicators, switch scale, and export the result as data or graphics.

At a glance

Area	What it does
XL	City and region context: districts, demographics, housing, rents, and FUA-ready references.
L	Neighbourhood or project-area context: land use, green and blue space, transit access, station-axis evidence, tree canopy proxy, and development hints.
M	Streetscape context: street segment, trees, building massing, sun/shadow hints, and section SVG.

Stack	Details
Front end	TypeScript, React, Vite, MapLibre GL JS
Analysis	Deterministic structured indicators from local and live geodata
Exports	JSON, CSV, GeoJSON, GPKG, SVG, PNG, Markdown, HTML, Ollama report
Data strategy	Preprocessed local sources first, live Overpass/Nominatim as optional enrichment

Current build status

Last checked locally on 2026-07-26.

Check	Status	Notes
npm run validate	Passing	Runs the 15-stage contract/build gate followed by deterministic desktop and mobile Chromium regressions.
npm run validate:contracts	Passing	Typecheck, benchmark runtime and ingestion, KPI, project-area, spatial-area, scenario, timing, semantic coverage, data-access, polygon-compaction, UI, data-release, deployment, and slim-build checks pass from fresh temporary staging.
npm run test:e2e	Passing	Point, city/multipart project fixtures, rectangle/polygon drawing, XL/L/M, scenario, JSON/Ollama-fallback export, external-API outage, console-error, and 390/1,440 px overflow contracts pass.
Slim production build	Passing	MapLibre, React, GeoPackage, and application chunks remain split; the validation artifact excludes canonical geodata.
Data release	Passing locally	uca-data-f2908a8e5313e3aa: 9,377 immutable assets / 1,583,124,437 bytes; representative access stays below the declared request, transfer, and shard limits.
Semantic city promotion	Blocked	Munich passes; Frankfurt and Rosenheim remain below declared Urban Atlas/Overture municipality/FUA coverage gates.
KPI contract	Passing	Schema 0.4.0 keeps one analysis context, excludes fallback buffers and driving from the composite, and serializes the active scenario.
GPKG / ZIP export	Passing	GeoPackage is loaded on demand; ZIP includes a standalone manifest, CSV, HTML, provenance, and editable graphics.
Dependency audit	Passing	npm audit --omit=dev reports zero vulnerabilities.

Current implementation notes:

• The map fullscreen control targets the whole workspace so the inspector remains available in fullscreen.
• The workspace includes a resizable map/inspector split and an expanded fullscreen-style layout.
• GeoPackage export preserves full raw feature properties in properties_json; only a bounded, prioritized subset is materialized as typed SQLite columns.
• sql.js and its WASM payload are deferred until a user requests GPKG, so they are not part of the initial application chunk.
• Ollama report export remains local-first and falls back to deterministic Markdown when Ollama is unavailable.

What you can do

• Select a point on the map or search for a place.
• Upload a WGS84 GeoJSON Polygon / MultiPolygon, close a drawn polygon, or draw a rectangle to define a project boundary up to 5 km diagonally.
• Switch between XL, L, and M without losing the selected location.
• Review KPI-first local quality, Tree Canopy, Station Axis, and benchmark indicators before raw modules, then choose a reproducible KPI strategy or adjust its weights.
• Toggle analytical layers for 3D, trees, sun, section, and green.
• Use the map-first direct workflow for immediate analysis.
• Export the structured result, not just a screenshot.

Run locally

Der getrennte synthetische Ausprobieren-Testbereich wird mit npm run dev:verplant:local aktiviert und benötigt die lokale Plattform-API. Start, Paket-Snapshot, Prüfnachweise und aktuelle Dateizugriffs-/Git-Blocker. Der normale Release-Build und bestehende Fallakten aktivieren diesen Testmodus nicht.

npm install
npm run dev

Open http://127.0.0.1:5173.

Useful checks

npm run validate
npm run validate:contracts
npm run test:e2e
npm run typecheck
npm run build
npm run test:timing
npm run test:project-area
npm run test:spatial-area
npm run test:benchmark
npm run test:data-release
npm run test:polygon-compaction
npm run test:data-access-profile

Use npm run validate before a release or handoff. It first executes the deterministic contract/build gate, then starts the repository Playwright suite at 1,440 px and 390 px. Browser requests are stubbed for repeatability; live service checks remain separate from this release contract. The timing evidence matrix includes Munich point/project contexts, Frankfurt, Rosenheim, an offline API run, and a dissolved multipart boundary.

npm run validate:ui remains available as the focused design-system guardrail.

Inspect runtime timings

The application records bounded, local-only performance evidence without external telemetry. After loading the app and running an analysis, inspect it in the browser console:

window.__UCA_PERFORMANCE__

The snapshot contains app-ready time, the latest analysis marks, and at most 20 export events. Analysis marks cover local lookup start/completion, first usable structured result, and live-enrichment completion. The first-usable mark records structured-result delivery; it is not a browser-paint metric.

Analysis-local timings are also serialized in analysis provenance and export manifests. Runtime history and prior export activity are deliberately excluded from manifests so identical analysis inputs remain reproducible.

Configuration

The app uses a local Vite dev/preview server with built-in /api proxies for Nominatim search and Overpass queries. Public Nominatim search is submit-only rather than autocomplete, and successful results are cached locally.

Optional Ollama report settings:

VITE_OLLAMA_BASE_URL=http://localhost:11434
VITE_OLLAMA_MODEL=llama3.1
VITE_REPORT_LANGUAGE=en
VITE_OLLAMA_TIMEOUT_MS=120000

Optional routed walking/cycling/driving catchments use the server-side local proxy:

OPENROUTESERVICE_API_KEY=your_server_only_key

Do not use a VITE_ prefix for this credential; client-visible environment variables are bundled into browser code.

If Ollama is unavailable, deterministic Markdown export still works.

For local credentials, copy .env.example to .env.local. Keep .env.local out of Git; it may contain CDSE S3 keys for Urban Atlas preprocessing or other preprocessing-only credentials. The satellite background uses the registered Esri raster source and does not require a Google Maps tile key or session.

Data and analysis

The project is designed around a mandatory source registry in src/lib/data/sourceRegistry.ts. Every indicator, layer, and export path references those source IDs.

Key characteristics:

• analysis is deterministic and traceable to structured inputs;
• when present, a canonical WGS84 project boundary replaces the default 500 m L-scale radius for feature filtering and area-normalized indicators;
• the boundary's representative interior point remains the anchor for XL administrative context and M street-segment analysis;
• live Overpass requests are cached and recorded in provenance;
• Nominatim geocoding is optional and failure never blocks coordinate-based analysis;
• analysis reads bounded preprocessed coverage and does not download or rewrite large point caches during a click;
• production builds omit generated point-cache and duplicate cache-manifest paths while retaining the canonical sharded datasets required at runtime;
• production may set UCA_INCLUDE_GEODATA=false and VITE_GEODATA_BASE_URL so the approximately 5.4 MB UI and immutable geodata release deploy independently;
• canonical polygon shards carry stable source-part/fragment provenance; invalid source geometry is repaired explicitly through GDAL MakeValid(LINEWORK) and every compacted fragment is OGR topology-validated;
• the fact sheet is built from structured JSON, not free-form generated text;
• confidence and caveat fields are always exposed;
• KPI schema version, active strategy, weights, score, classification, and evidence availability are serializable through analysis results and export manifests.

The boundary workflow dissolves uploaded overlaps, filters evidence to one context, and uses the dissolved project area as the denominator. Land-use and green polygons are clipped and dissolved exactly in the browser-scale context. Urban Atlas owns baseline coverage; OSM contributes only in uncovered areas, with deterministic family precedence removing double counting.

Scenario drawing supports proposed transit stops, bike-share stations, streets, green edges, and public spaces. These features remain a separate user-proposal layer and export; the application does not infer KPI impact until a documented scenario-effect model is implemented.

Local CSVs in src/lib/data/csv/ are schema-compatible MVP samples. Replace them with authoritative preprocessing outputs when you move beyond the prototype stage.

Repository layout

• src/app holds the application shell.
• src/components/map contains map interaction, scale switching, and layer toggles.
• src/lib/projectArea validates and serializes uploaded or drawn project boundaries.
• src/components/factsheet renders the structured fact sheet.
• src/lib/analysis computes XL / L / M indicators and overlays.
• src/lib/export creates JSON, CSV, GeoJSON, SVG, PNG, Markdown, HTML, and GPKG exports.
• src/lib/ollama wraps local report generation with a deterministic fallback.
• docs/ contains the methods, indicators, and data source notes.

Documentation

• Data sources
• Methods
• Indicators
• Geodata release contract
• Data coverage audit
• Product plan

Status

This repository is an exploratory MVP, not a planning-law or feasibility engine.

It is intentionally lightweight: the goal is a fast map-first workflow with structured geodata, visible provenance, and modular exports.

License

No license file is included yet. Treat the repository as source-visible but not reusable by default until a license is added.

Contributing

If you extend the analysis model, keep the changes deterministic and traceable:

• add new sources to src/lib/data/sourceRegistry.ts;
• keep provenance and caveats on every indicator;
• update the matching docs when the workflow changes;
• prefer preprocessed open data over repeated public API calls.

verplant-Produktvariante (20.09.2026)

npm run build:verplant erzeugt dist-verplant/ für /ausprobieren/app/. Die Standardvariante bleibt UCA. Implementiert sind Wer/Wo/Was, getrennte Projekt-/Kontextgeometrien, explore/project_check, deterministische Perspektiven, append-only Durchläufe und getrennte Arbeitsstände sowie JSON/Markdown/HTML/ZIP. Ohne Datenhost bleibt die Demo mit sichtbaren Datenlücken nutzbar; das ist keine Abdeckungsfreigabe. Lokale KI ist optional und darf ausschließlich vorhandene Prüffragen auswählen.

• Architektur, Verträge, Invalidierung und Folgepakete
• Statische Integration und Build
• Geprüfte Referenz-Repositories
• Tatsächlich ausgeführte Prüfungen

npm run test:verplant prüft die neuen Verträge und ist zusätzlich in validate:contracts eingebunden. Playwright und Mobilprüfung wurden für diese Umsetzung auf ausdrücklichen Wunsch nicht abgeschlossen; die bestehende Suite bleibt erhalten. Das fremde Repository hompage_mockup wurde nicht verändert.