# aadi-tya-24/citypulse. architecture

> Architecture diagram of the GitHub repository aadi-tya-24/citypulse., generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aadi-tya-24/citypulse.
- Repository: https://github.com/aadi-tya-24/citypulse.

## Overview

CityPulse serves a civic dashboard: users select a city or route, inspect per-area conditions and alerts, and can submit reports or trigger demos. The documented pipeline normalizes feeds, detects anomalies and coincident signals, scores area health, and produces alerts and summaries that reach REST and Socket.IO clients. The excerpts show route ownership for selected API and feed operations; other documented capabilities are represented at their enclosing source paths, with uncertain internal wiring omitted.

Main entry points: [`public/index.html`](https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html) (Map and dashboard UI), [`server/index.js`](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js) (REST endpoints), [`server/engine.js`](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js) (Anomaly analysis), [`server/config.js`](https://github.com/aadi-tya-24/citypulse./blob/main/server/config.js) (Zones and thresholds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["City and feeds"]
  node_config["Zones and thresholds<br/>[config.js]"]
  node_feeds["Feed polling and simulation<br/>[index.js]"]
  node_cityroute["City and route selection<br/>[index.js]"]
  node_reports["Report consensus<br/>[index.js]"]
end

subgraph group_analytics["Civic analytics"]
  node_normalize["Feed normalization<br/>[engine.js]"]
  node_anomaly["Anomaly analysis<br/>[engine.js]"]
  node_correlation["Signal correlation<br/>[engine.js]"]
  node_health["Area health scoring<br/>[engine.js]"]
  node_alerts["Alert rules<br/>[engine.js]"]
  node_summaries["Plain-language summaries<br/>[index.js]"]
end

subgraph group_service["API and live delivery"]
  node_api["REST endpoints<br/>[index.js]"]
  node_live["Socket.IO state<br/>[index.js]"]
  node_state["Current state and history<br/>[index.js]"]
end

subgraph group_experience["Dashboard experience"]
  node_dashboard["Map and dashboard UI<br/>[index.html]"]
  node_routeinfo["Route and commute results<br/>[index.html]"]
  node_reportui["Report and demo controls<br/>[index.html]"]
end

node_resident(("Dashboard user"))
node_browsergeo(("Browser geolocation"))
node_openmeteo{{"Open-Meteo"}}
node_openweather{{"OpenWeatherMap"}}
node_osrm{{"OSRM routes"}}
node_osm{{"OpenStreetMap services"}}
node_gemini{{"Gemini summaries"}}

node_config -->|"configures"| node_feeds
node_config -->|"sets windows"| node_normalize
node_config -->|"sets weights"| node_anomaly
node_feeds -->|"fetches weather"| node_openmeteo
node_feeds -.->|"tries weather"| node_openweather
node_feeds -.->|"looks up areas"| node_osm
node_cityroute -->|"requests routes"| node_osrm
node_feeds -->|"supplies readings"| node_normalize
node_normalize -->|"normalizes readings"| node_anomaly
node_anomaly -->|"scores signals"| node_correlation
node_anomaly -->|"scores factors"| node_health
node_anomaly -->|"checks rules"| node_alerts
node_anomaly -->|"supplies analysis"| node_summaries
node_summaries -.->|"requests wording"| node_gemini
node_reports -->|"triggers update"| node_feeds
node_api -->|"records reports"| node_reports
node_api -->|"sets city or route"| node_cityroute
node_api -->|"reads state"| node_state
node_state -->|"emits updates"| node_live
node_api -->|"serves data"| node_dashboard
node_live -->|"pushes state"| node_dashboard
node_resident -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api
node_dashboard -->|"connects"| node_live
node_browsergeo -->|"provides location"| node_api
node_dashboard -->|"shows results"| node_routeinfo
node_dashboard -->|"shows controls"| node_reportui
node_reportui -->|"submits actions"| node_api

click node_config "https://github.com/aadi-tya-24/citypulse./blob/main/server/config.js"
click node_feeds "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_cityroute "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_reports "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_normalize "https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js"
click node_anomaly "https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js"
click node_correlation "https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js"
click node_health "https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js"
click node_alerts "https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js"
click node_summaries "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_api "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_live "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_state "https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js"
click node_dashboard "https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html"
click node_routeinfo "https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html"
click node_reportui "https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html"

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_config,node_feeds,node_cityroute,node_reports,node_resident,node_browsergeo toneBlue
class node_normalize,node_anomaly,node_correlation,node_health,node_alerts,node_summaries toneAmber
class node_api,node_live,node_state,node_osrm toneMint
class node_dashboard,node_routeinfo,node_reportui toneRose
class node_openmeteo,node_openweather,node_osm,node_gemini toneIndigo
```

## Components

### City and feeds

- [Zones and thresholds](https://github.com/aadi-tya-24/citypulse./blob/main/server/config.js): `server/config.js`
- [Feed polling and simulation](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`
- [City and route selection](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`
- [Report consensus](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`

### Civic analytics

- [Feed normalization](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js): `server/engine.js`
- [Anomaly analysis](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js): `server/engine.js`
- [Signal correlation](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js): `server/engine.js`
- [Area health scoring](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js): `server/engine.js`
- [Alert rules](https://github.com/aadi-tya-24/citypulse./blob/main/server/engine.js): `server/engine.js`
- [Plain-language summaries](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`

### API and live delivery

- [REST endpoints](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`
- [Socket.IO state](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`
- [Current state and history](https://github.com/aadi-tya-24/citypulse./blob/main/server/index.js): `server/index.js`

### Dashboard experience

- [Map and dashboard UI](https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html): `public/index.html`
- [Route and commute results](https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html): `public/index.html`
- [Report and demo controls](https://github.com/aadi-tya-24/citypulse./blob/main/public/index.html): `public/index.html`

### Other components

- **Dashboard user**
- **Browser geolocation**
- **Open-Meteo**
- **OpenWeatherMap**
- **OSRM routes**
- **OpenStreetMap services**
- **Gemini summaries**

## Connections

- Zones and thresholds → Feed polling and simulation: configures
- Zones and thresholds → Feed normalization: sets windows
- Zones and thresholds → Anomaly analysis: sets weights
- Feed polling and simulation → Open-Meteo: fetches weather
- Feed polling and simulation → OpenWeatherMap: tries weather
- Feed polling and simulation → OpenStreetMap services: looks up areas
- City and route selection → OSRM routes: requests routes
- Feed polling and simulation → Feed normalization: supplies readings
- Feed normalization → Anomaly analysis: normalizes readings
- Anomaly analysis → Signal correlation: scores signals
- Anomaly analysis → Area health scoring: scores factors
- Anomaly analysis → Alert rules: checks rules
- Anomaly analysis → Plain-language summaries: supplies analysis
- Plain-language summaries → Gemini summaries: requests wording
- Report consensus → Feed polling and simulation: triggers update
- REST endpoints → Report consensus: records reports
- REST endpoints → City and route selection: sets city or route
- REST endpoints → Current state and history: reads state
- Current state and history → Socket.IO state: emits updates
- REST endpoints → Map and dashboard UI: serves data
- Socket.IO state → Map and dashboard UI: pushes state
- Dashboard user → Map and dashboard UI: uses
- Map and dashboard UI → REST endpoints: requests data
- Map and dashboard UI → Socket.IO state: connects
- Browser geolocation → REST endpoints: provides location
- Map and dashboard UI → Route and commute results: shows results
- Map and dashboard UI → Report and demo controls: shows controls
- Report and demo controls → REST endpoints: submits actions