Periklean Athens Interactive Atlas

Scholarly interactive web atlas for Periklean Athens with a static frontend (app/) and canonical GIS data (data/).

Repository structure

• data/: source of truth for geometry and evidence metadata.
• app/: Vite + React + TypeScript + MapLibre app.
• archive/: superseded assets and earlier exports.
• BUILD_GUIDE.md: implementation handoff and roadmap.

Quick start

cd app
npm install
npm run dev

The app copies GeoJSON and source metadata from ../data into app/public/data before dev/build.

Validation and build commands

cd app
npm run copy-data
npm run validate-data
npm run typecheck
npm run build

• validate-data enforces data/schema/feature.schema.json against every data/layers/*.geojson feature.
• Build fails if validation fails.
• Static hosting cache headers are configured in app/public/_headers for /data/* and /tiles/*.

Data contract (required feature properties)

Every feature in every layer must include:

• id (kebab-case string, unique within layer)
• name (display string)
• kind (semantic feature type)
• confidence (high | medium | low | working)
• source_ids (string[]; may be empty only when confidence is working)

Adding a new layer

1. Author or update geometry in QGIS (data/qgis/periklean_athens_basemap.gpkg).
2. Export GeoJSON to data/layers/<layer_name>.geojson in EPSG:4326.
3. Ensure each exported feature includes required properties and valid source_ids.
4. If needed, add new sources to data/source_register.csv with stable source_id.
5. Run:
   • cd app
   • npm run validate-data
6. Wire the layer in app code:
   • add filename mapping in app/src/data/loadLayers.ts
   • add source/layer style in app/src/map/layers.ts
   • add toggle UI (if thematic) in app/src/ui/LayerToggle.tsx

Current status

• Data normalization and schema enforcement are in place.
• App scaffold, layer rendering, feature panel with citations, confidence legend, and guided-tour controls are implemented.
• Day 2 baseline uses hosted Carto Positron as the basemap.
• PMTiles basemap is intentionally deferred to Phase 2.

Deploy (static)

Cloudflare Pages

1. Connect repository.
2. Set root directory to app.
3. Build command: npm run build
4. Build output directory: dist
5. Ensure app/public/_headers is included in build output for cache-control rules.

Netlify

1. Connect repository.
2. Set base directory to app.
3. Build command: npm run build
4. Publish directory: app/dist (or dist if base directory is app).
5. app/netlify.toml is included with defaults.