PathFound City Explorer

A standalone reference implementation showing how PathFound.me uses Google Maps 3D and the Places UI Kit to help teens explore cities where they might live.

Photorealistic 3D fly-throughs, cinematic camera orbits, interactive POI markers, radar-chart fit visualizations — all in vanilla HTML/CSS/JS with zero build tools.

Quick Start

# Any static file server works. Examples:
python3 -m http.server 8000
# or
npx serve .

Then open http://localhost:8000 in Chrome (3D Maps requires WebGL2 and a decent GPU).

Note: The app uses a Google Maps Demo Key that is rate-limited and domain-restricted. For production, swap in your own key in index.html.

What It Does

1. Loading screen animates while the Maps API boots
2. US overview — the 3D globe zooms to a dramatic continental view
3. City selector sidebar lists 6 curated cities with match scores, blurbs, and animated match bars
4. Cinematic fly-to — selecting a city triggers a smooth flyCameraTo animation at a dramatic tilt angle
5. City comparison card slides in with population, cost of living, walkability, climate, vibe tags, and top industries
6. "Your Fit" radar chart — a pure-SVG spider chart showing how the city matches across 6 dimensions
7. POI markers appear on the 3D map (universities, cafes, parks, libraries, music venues, coworking)
8. POI category filters toggle marker visibility by type
9. City Tour orbit — a 360° flyCameraAround cinematic orbit of the city center
10. Mobile-responsive — sidebar becomes a bottom sheet on screens under 768px

Architecture

pathfound/
├── index.html        — Entry point, loads Google Maps API + app modules
├── css/
│   └── style.css     — Dark theme, responsive layout, animations, radar chart
├── js/
│   ├── app.js        — Bootstrap, coordinates modules, loading flow
│   ├── cities.js     — City data: coords, stats, match scores, fit values, POIs
│   ├── map.js        — 3D map init, flyCameraTo, flyCameraAround, POI markers
│   └── ui.js         — Sidebar, detail card, radar chart, POI filters, toasts
├── README.md         — This file
└── SPEC.md           — Original spec

Module Responsibilities

File	What it does
cities.js	Exports a CITIES array with coordinates, camera presets, hardcoded stats, radar-chart fit scores, and POI locations. Also exports PROFILE (simulated user), POI_CATEGORIES, FIT_LABELS, and FIT_KEYS. In production, this data comes from the PathFound assessment engine.
map.js	Wraps the gmp-map-3d custom element. Exposes flyToCity() for cinematic camera moves, tourCity() for orbits, renderPOIMarkers() for placing styled markers, and clearMarkers() for cleanup.
ui.js	Renders: profile badge, sidebar city list with animated match bars, city detail card (stats, climate, vibes, industries), SVG radar chart with glow effects, POI category filter toggles, POI click toasts, loading/welcome screens, and mobile bottom-sheet behavior.
app.js	Glues modules together. Manages the boot sequence: loading screen → Maps API init → UI render → auto-select top city. Provides the handleCityChange hook for future Places API integration.

Google Maps APIs Used

• Maps JavaScript API (3D Maps) — gmp-map-3d element for photorealistic 3D rendering
• flyCameraTo — smooth animated camera transitions between cities
• flyCameraAround — 360° cinematic orbit tours
• gmp-marker-3d — custom-styled POI markers with emoji icons, extruded above the terrain
• Places UI Kit — library loaded and ready for gmp-place-details-compact integration

Design Decisions

• No build tools — vanilla HTML/CSS/JS with ES modules. Opens in any browser, easy to read and integrate.
• Pure SVG radar chart — no charting library needed. Radial gradient fill + glow filter for visual polish.
• Dark theme (#0a0f1a bg, #00D4FF accent) — pairs dramatically with the photorealistic 3D map tiles.
• Backdrop-blur glass panels — detail overlay uses backdrop-filter: blur(16px) for a modern frosted-glass look.
• Mobile-responsive — sidebar becomes a draggable bottom sheet on screens under 768px.
• Loading screen — covers the ~2s Maps API boot time so the user sees a branded experience, not a blank page.
• POI markers — uses gmp-marker-3d with custom template slots for category-colored emoji markers.

Swapping In Real Data

1. City data — Replace the CITIES array in cities.js with an API call to your PathFound backend. Keep the same object shape (the contract is documented in the file).
2. Match scores & fit values — Currently hardcoded. Wire these to the PathFound assessment engine output.
3. User profile — Replace the PROFILE export with real assessment results.
4. API key — Replace the demo key in index.html with a production key that has Maps JavaScript API, Map Tiles API, and Places API enabled.
5. POIs — The handleCityChange callback in app.js is the hook for loading live Places results. Use gmp-place-details-compact and gmp-place-nearby-search from the Places UI Kit.
6. Real-time data — Climate, cost of living, walkability scores can come from third-party APIs (BLS, Walk Score, OpenWeather).

Browser Requirements

• Chrome 111+ (or any Chromium browser with WebGL2)
• A GPU that supports photorealistic 3D tiles
• Internet connection (maps tiles stream from Google)

License

Internal reference implementation for PathFound.me.