How chungywungy/2800-202610-dtc02 works
1. High-level shape
- This is a Node/Express-backed, map-centric web app called Find Your Cool.
- The browser hosts most of the UI and map interaction logic in public/js, while the server exposes page routes and JSON/API routes from routes/.
- The main purpose is to help users explore Vancouver cooling resources and let planners assess heat vulnerability.
2. Runtime and deployment boundary
- server.js is the application entry point.
- The backend is an Express server connected to MongoDB Atlas via mongodbAtlas.js.
- The app is configured through environment variables for port, MongoDB, OpenWeather, ShadeMap, and Claude API access.
3. Frontend composition
- The client is mostly vanilla JavaScript modules rather than a framework-heavy SPA.
- public/index.html is the primary application shell, and public/login.html is a separate auth entry page.
- Shared UI pieces live in public/components/ as reusable custom elements or module-driven widgets such as the navbar, profile panel, loading spinner, speed dial, and temperature container.
4. Map subsystem
- The map experience is built around Leaflet in public/js/mapInit.js and public/js/map.js.
- The map is the central interaction surface: users click locations, toggle layers, and open panels tied to map state.
- The app uses geographic data and layer-specific modules to render and filter neighborhood resources.
5. Map layer modules
- Feature layers are split into separate client modules: trees.js, parks.js, communityCentres.js, washroom.js, water.js, and transit.js.
- This separation suggests each layer can be independently fetched, rendered, and toggled.
- public/data/stops.geojson provides a local transit dataset, while the README indicates the rest of the resource data is sourced from Vancouver open data.
6. Cool Score subsystem
- public/js/score.js implements the Cool Score UI and likely the weighting logic described in the README.
- The score is neighborhood-based and combines counts of water fountains, washrooms, parks, community centres, and transit stops.
- The important data flow is: resource layer counts + user-controlled sliders → weighted score → map filter/visual emphasis by neighborhood.
7. User reports flow
- public/js/report.js handles submitting community reports from the map.
- Logged-in users can create reports at arbitrary map locations; these reports become visible to city-planner accounts.
- On the server side, routes/api.js and/or routes/achievement.js likely persist and expose report-related data through MongoDB.
8. Authentication and role-based access
- Authentication is isolated in routes/auth.js, with public/js/login.js driving the client-side login flow.
- The presence of a separate login.html and public/components/site-profile.js suggests a user identity/profile boundary in the UI.
- The app distinguishes at least two roles that matter architecturally: regular residents and city planners.
9. Weather and live temperature
- public/js/temperature-container.js and likely public/js/map.js coordinate live temperature updates when the user clicks the map.
- The weather data comes from OpenWeather, making it an external enrichment service rather than an internal dataset.
- This is a request/response dependency from the browser or backend to a third-party API, then into a UI temperature panel.
10. AI summary subsystem
- public/js/summaryAI.js drives the planner-facing AI Summary panel.
- The backend uses CLAUDE_API_KEY when available for model-generated summaries; otherwise it falls back to a local heuristic summary, so the summary service has a dual execution path.
- This feature consumes citywide or neighborhood-level report data and produces synthesized planner insight.
11. Achievements and secondary server routes
- routes/achievement.js indicates a gamified or milestone-based backend concern, likely tied to user actions such as reporting or engagement.
- routes/index.js and routes/api.js provide the main page and data endpoints that connect the frontend modules to persistence and external services.
- These route files form the server boundary between static assets and dynamic application behavior.
12. Styling and presentation
- Styling is handled with Tailwind CSS plus daisyUI, configured through tailwind.config.js and public/css/index.css.
- The app also includes branded imagery in public/images/, which suggests a polished landing/background layer but not a separate subsystem.
- Visual components are meant to work consistently across the map, login, summary, and profile interfaces.
13. Key external dependencies in the architecture
- MongoDB Atlas stores app data such as users, reports, and other server-managed records.
- OpenWeather supplies live weather/temperature.
- Claude API generates AI summaries when enabled.
- ShadeMap is listed in env config, implying an additional environmental/geospatial visualization dependency even if it is not obvious from the file tree alone.
14. Primary end-to-end data flow
- User opens the app → frontend initializes map and UI components → map layers load resource data and GeoJSON → score/report/temperature/summary features query backend or third parties → results are rendered back into map panels and overlays.
- The architecture is therefore a browser-led, map-first application with a thin Express API layer, MongoDB persistence, and several external enrichment services.
Main entry points: map.js Map core · index.html App shell · api.js API · server.js Server
Components 29
Frontend
Browser UI, map interactions, and client-side feature modules.
- App shell · Primary browser entry page for the main map experience.
public/index.html - Login page · Separate browser entry page for authentication.
public/login.html - Navbar · Shared top-level navigation and user access affordances.
public/components/site-navbar.js - Profile · User identity and planner/resident profile display.
public/components/site-profile.js - Spinner · Loading state component used across the interface.
public/components/loading-spinner.js - Speed dial · Quick-action launcher for map and panel interactions.
public/components/speed-dial.js - Temp panel · Live temperature display tied to map clicks and weather lookup.
public/components/temperature-container.js - Map init · Initializes the Leaflet map and core map state.
public/js/mapInit.js - Map core · Main map interaction logic, overlays, clicks, and panel coordination.
public/js/map.js - Cool Score · Neighborhood scoring and weighting for cooling resources.
public/js/score.js - Reports · Client-side submission flow for community reports on the map.
public/js/report.js - AI summary · Planner-facing summary panel driven by reports and model/heuristic output.
public/js/summaryAI.js - Login flow · Client-side authentication and login interaction logic.
public/js/login.js - Trees · Tree canopy layer rendered as a separate map module.
public/js/trees.js - Parks · Park resource layer rendered independently on the map.
public/js/parks.js - Centres · Community centre layer used in scoring and exploration.
public/js/communityCentres.js - Washrooms · Public washroom layer used in scoring and exploration.
public/js/washroom.js - Water · Water fountain or refill layer used in scoring and exploration.
public/js/water.js - Transit · Transit layer backed by local GeoJSON stops data.
public/js/transit.js
Backend
Express entrypoint, route handlers, and database wiring.
- Server · Application entrypoint that boots the Express server.
server.js - Pages · Main page routes and app shell delivery.
routes/index.js - API · Primary data endpoints for map, reports, and planner features.
routes/api.js - Auth · Authentication and session-related server routes.
routes/auth.js - Achievements · Secondary server routes for milestones or gamified user actions.
routes/achievement.js
Services
External APIs and persisted data sources used by the app.
- MongoDB · MongoDB Atlas connection used by the server for app data.
mongodbAtlas.js - Stops data · Local transit stop dataset consumed by the transit layer.
public/data/stops.geojson - OpenWeather · Live weather and temperature enrichment service.
- Claude · Model service used for AI summaries when enabled.
- ShadeMap · Environmental/geospatial visualization dependency configured by the app.
Connections 38
- Server → Pages: serves · Bootstraps page delivery routes.
- Server → API: mounts · Exposes JSON and data endpoints.
- Server → Auth: mounts · Exposes authentication endpoints.
- Server → Achievements: mounts · Exposes engagement-related endpoints.
- Server → MongoDB: connects · Uses Atlas for persistence.
- API → MongoDB: reads/writes · Stores and retrieves app records.
- Auth → MongoDB: reads/writes · Persists user and session data.
- Achievements → MongoDB: reads/writes · Stores achievement state.
- Pages → App shell: delivers · Serves the main browser shell.
- Auth → Login page: delivers · Serves the login page.
- App shell → Navbar: loads · Composes shared navigation UI.
- App shell → Profile: loads · Composes user identity UI.
- App shell → Spinner: loads · Uses shared loading state.
- App shell → Speed dial: loads · Adds quick actions to the shell.
- App shell → Temp panel: loads · Adds live temperature UI.
- App shell → Map init: boots · Initializes the map experience.
- Map init → Map core: hands off · Sets up core map interactions.
- Map core → Trees: loads layer · Enables tree resource display.
- Map core → Parks: loads layer · Enables park resource display.
- Map core → Centres: loads layer · Enables community centre display.
- Map core → Washrooms: loads layer · Enables washroom display.
- Map core → Water: loads layer · Enables water resource display.
- Map core → Transit: loads layer · Enables transit display.
- Transit → Stops data: consumes · Uses local GeoJSON stop data.
- Map core → Cool Score: feeds counts · Provides layer counts and neighborhood context.
- Cool Score → API: queries · Retrieves or updates scoring-related data.
- Map core → Reports: opens · Launches reporting from map locations.
- Reports → API: submits · Sends new community reports.
- Map core → Temp panel: updates · Pushes clicked-location temperature state.
- Temp panel → OpenWeather: requests · Fetches live weather and temperature.
- Map core → AI summary: opens · Displays planner insight panel.
- AI summary → API: requests data · Pulls report and summary inputs.
- AI summary → Claude: calls · Uses model-generated summaries when available.
- AI summary → MongoDB: falls back to · Uses stored data for heuristic summaries.
- Map core → ShadeMap: enriches · Uses additional environmental visualization support.
- Login page → Login flow: loads · Starts the client-side auth flow.
- Login flow → Auth: authenticates · Sends login and session requests.
- Profile → API: fetches user data · Displays persisted user and role information.