# chungywungy/2800-202610-dtc02 architecture

> Architecture diagram of the GitHub repository chungywungy/2800-202610-dtc02, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chungywungy/2800-202610-dtc02
- Repository: https://github.com/chungywungy/2800-202610-dtc02

## Overview

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: [`public/js/map.js`](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/map.js) (Map core), [`public/index.html`](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/index.html) (App shell), [`routes/api.js`](https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/api.js) (API), [`server.js`](https://github.com/chungywungy/2800-202610-dtc02/blob/main/server.js) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_index_html["App shell<br/>client shell<br/>[index.html]"]
  node_login_html["Login page<br/>client shell<br/>[login.html]"]
  node_navbar["Navbar<br/>ui component<br/>[site-navbar.js]"]
  node_profile["Profile<br/>ui component<br/>[site-profile.js]"]
  node_spinner(("Spinner<br/>ui component<br/>[loading-spinner.js]"))
  node_speed_dial(("Speed dial<br/>ui component<br/>[speed-dial.js]"))
  node_temp_panel["Temp panel<br/>ui component"]
  node_map_init["Map init<br/>leaflet bootstrap<br/>[mapInit.js]"]
  node_map_core["Map core<br/>map controller<br/>[map.js]"]
  node_score_ui{{"Cool Score<br/>scoring ui<br/>[score.js]"}}
  node_report_ui["Reports<br/>reporting ui<br/>[report.js]"]
  node_summary_ai["AI summary<br/>planner insight<br/>[summaryAI.js]"]
  node_login_js["Login flow<br/>auth client<br/>[login.js]"]
  node_trees["Trees<br/>map layer<br/>[trees.js]"]
  node_parks["Parks<br/>map layer<br/>[parks.js]"]
  node_centres["Centres<br/>map layer"]
  node_washrooms["Washrooms<br/>map layer<br/>[washroom.js]"]
  node_water["Water<br/>map layer<br/>[water.js]"]
  node_transit["Transit<br/>map layer<br/>[transit.js]"]
end

subgraph group_backend["Backend"]
  node_server["Server<br/>express app<br/>[server.js]"]
  node_routes_index["Pages<br/>page routes<br/>[index.js]"]
  node_routes_api["API<br/>[api.js]"]
  node_routes_auth["Auth<br/>login routes<br/>[auth.js]"]
  node_routes_achievement["Achievements<br/>engagement routes<br/>[achievement.js]"]
end

subgraph group_services["Services"]
  node_mongodb[("MongoDB<br/>persistence<br/>[mongodbAtlas.js]")]
  node_stops_data["Stops data<br/>geojson data<br/>[stops.geojson]"]
  node_weather_api[("OpenWeather<br/>external api")]
  node_claude_api[("Claude<br/>external api")]
  node_shademap[("ShadeMap<br/>external api")]
end

node_server -->|"serves"| node_routes_index
node_server -->|"mounts"| node_routes_api
node_server -->|"mounts"| node_routes_auth
node_server -->|"mounts"| node_routes_achievement
node_server -->|"connects"| node_mongodb
node_routes_api -->|"reads/writes"| node_mongodb
node_routes_auth -->|"reads/writes"| node_mongodb
node_routes_achievement -->|"reads/writes"| node_mongodb
node_routes_index -->|"delivers"| node_index_html
node_routes_auth -->|"delivers"| node_login_html
node_index_html -->|"loads"| node_navbar
node_index_html -->|"loads"| node_profile
node_index_html -->|"loads"| node_spinner
node_index_html -->|"loads"| node_speed_dial
node_index_html -->|"loads"| node_temp_panel
node_index_html -->|"boots"| node_map_init
node_map_init -->|"hands off"| node_map_core
node_map_core -->|"loads layer"| node_trees
node_map_core -->|"loads layer"| node_parks
node_map_core -->|"loads layer"| node_centres
node_map_core -->|"loads layer"| node_washrooms
node_map_core -->|"loads layer"| node_water
node_map_core -->|"loads layer"| node_transit
node_transit -->|"consumes"| node_stops_data
node_map_core -->|"feeds counts"| node_score_ui
node_score_ui -->|"queries"| node_routes_api
node_map_core -->|"opens"| node_report_ui
node_report_ui -->|"submits"| node_routes_api
node_map_core -->|"updates"| node_temp_panel
node_temp_panel -->|"requests"| node_weather_api
node_map_core -->|"opens"| node_summary_ai
node_summary_ai -->|"requests data"| node_routes_api
node_summary_ai -->|"calls"| node_claude_api
node_summary_ai -->|"falls back to"| node_mongodb
node_map_core -->|"enriches"| node_shademap
node_login_html -->|"loads"| node_login_js
node_login_js -->|"authenticates"| node_routes_auth
node_profile -->|"fetches user data"| node_routes_api

click node_server "https://github.com/chungywungy/2800-202610-dtc02/blob/main/server.js"
click node_routes_index "https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/index.js"
click node_routes_api "https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/api.js"
click node_routes_auth "https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/auth.js"
click node_routes_achievement "https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/achievement.js"
click node_mongodb "https://github.com/chungywungy/2800-202610-dtc02/blob/main/mongodbAtlas.js"
click node_index_html "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/index.html"
click node_login_html "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/login.html"
click node_navbar "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/site-navbar.js"
click node_profile "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/site-profile.js"
click node_spinner "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/loading-spinner.js"
click node_speed_dial "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/speed-dial.js"
click node_temp_panel "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/temperature-container.js"
click node_map_init "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/mapInit.js"
click node_map_core "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/map.js"
click node_score_ui "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/score.js"
click node_report_ui "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/report.js"
click node_summary_ai "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/summaryAI.js"
click node_login_js "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/login.js"
click node_trees "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/trees.js"
click node_parks "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/parks.js"
click node_centres "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/communityCentres.js"
click node_washrooms "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/washroom.js"
click node_water "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/water.js"
click node_transit "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/transit.js"
click node_stops_data "https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/data/stops.geojson"

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_index_html,node_login_html,node_navbar,node_profile,node_spinner,node_speed_dial,node_temp_panel,node_map_init,node_map_core,node_score_ui,node_report_ui,node_summary_ai,node_login_js,node_trees,node_parks,node_centres,node_washrooms,node_water,node_transit toneBlue
class node_server,node_routes_index,node_routes_api,node_routes_auth,node_routes_achievement toneAmber
class node_mongodb,node_stops_data,node_weather_api,node_claude_api,node_shademap toneMint
```

## Components

### Frontend

Browser UI, map interactions, and client-side feature modules.

- [App shell](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/index.html): client shell · Primary browser entry page for the main map experience. · `public/index.html`
- [Login page](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/login.html): client shell · Separate browser entry page for authentication. · `public/login.html`
- [Navbar](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/site-navbar.js): ui component · Shared top-level navigation and user access affordances. · `public/components/site-navbar.js`
- [Profile](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/site-profile.js): ui component · User identity and planner/resident profile display. · `public/components/site-profile.js`
- [Spinner](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/loading-spinner.js): ui component · Loading state component used across the interface. · `public/components/loading-spinner.js`
- [Speed dial](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/speed-dial.js): ui component · Quick-action launcher for map and panel interactions. · `public/components/speed-dial.js`
- [Temp panel](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/components/temperature-container.js): ui component · Live temperature display tied to map clicks and weather lookup. · `public/components/temperature-container.js`
- [Map init](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/mapInit.js): leaflet bootstrap · Initializes the Leaflet map and core map state. · `public/js/mapInit.js`
- [Map core](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/map.js): map controller · Main map interaction logic, overlays, clicks, and panel coordination. · `public/js/map.js`
- [Cool Score](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/score.js): scoring ui · Neighborhood scoring and weighting for cooling resources. · `public/js/score.js`
- [Reports](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/report.js): reporting ui · Client-side submission flow for community reports on the map. · `public/js/report.js`
- [AI summary](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/summaryAI.js): planner insight · Planner-facing summary panel driven by reports and model/heuristic output. · `public/js/summaryAI.js`
- [Login flow](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/login.js): auth client · Client-side authentication and login interaction logic. · `public/js/login.js`
- [Trees](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/trees.js): map layer · Tree canopy layer rendered as a separate map module. · `public/js/trees.js`
- [Parks](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/parks.js): map layer · Park resource layer rendered independently on the map. · `public/js/parks.js`
- [Centres](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/communityCentres.js): map layer · Community centre layer used in scoring and exploration. · `public/js/communityCentres.js`
- [Washrooms](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/washroom.js): map layer · Public washroom layer used in scoring and exploration. · `public/js/washroom.js`
- [Water](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/water.js): map layer · Water fountain or refill layer used in scoring and exploration. · `public/js/water.js`
- [Transit](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/js/transit.js): map layer · Transit layer backed by local GeoJSON stops data. · `public/js/transit.js`

### Backend

Express entrypoint, route handlers, and database wiring.

- [Server](https://github.com/chungywungy/2800-202610-dtc02/blob/main/server.js): express app · Application entrypoint that boots the Express server. · `server.js`
- [Pages](https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/index.js): page routes · Main page routes and app shell delivery. · `routes/index.js`
- [API](https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/api.js): json api · Primary data endpoints for map, reports, and planner features. · `routes/api.js`
- [Auth](https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/auth.js): login routes · Authentication and session-related server routes. · `routes/auth.js`
- [Achievements](https://github.com/chungywungy/2800-202610-dtc02/blob/main/routes/achievement.js): engagement routes · Secondary server routes for milestones or gamified user actions. · `routes/achievement.js`

### Services

External APIs and persisted data sources used by the app.

- [MongoDB](https://github.com/chungywungy/2800-202610-dtc02/blob/main/mongodbAtlas.js): persistence · MongoDB Atlas connection used by the server for app data. · `mongodbAtlas.js`
- [Stops data](https://github.com/chungywungy/2800-202610-dtc02/blob/main/public/data/stops.geojson): geojson data · Local transit stop dataset consumed by the transit layer. · `public/data/stops.geojson`
- **OpenWeather**: external api · Live weather and temperature enrichment service.
- **Claude**: external api · Model service used for AI summaries when enabled.
- **ShadeMap**: external api · Environmental/geospatial visualization dependency configured by the app.

## Connections

- 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.
