# ragini-create/cognimap architecture

> Architecture diagram of the GitHub repository ragini-create/cognimap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ragini-create/cognimap
- Repository: https://github.com/ragini-create/cognimap

## Overview

Cognimap is an environment-aware navigation app. Users search for places, choose travel modes and stops, request route alternatives, and review route scores alongside environmental and community safety information; they can also report hazards and ask CogniAssist questions. The graph separates the frontend experience, backend route and location services, hazard-report storage, and external providers. Some frontend components and backend handlers are indexed but not excerpted, so their documented capabilities are included while uncertain internal call links are omitted.

Main entry points: [`frontend/src/App.js`](https://github.com/ragini-create/cognimap/blob/main/frontend/src/App.js) (App state and orchestration), [`frontend/src/utils/api.js`](https://github.com/ragini-create/cognimap/blob/main/frontend/src/utils/api.js) (HTTP client), [`backend/server.js`](https://github.com/ragini-create/cognimap/blob/main/backend/server.js) (Express API server), [`backend/routes/route.js`](https://github.com/ragini-create/cognimap/blob/main/backend/routes/route.js) (Route scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Navigation experience"]
  node_app["App state and orchestration<br/>[App.js]"]
  node_search["Place search<br/>[SearchPanel.js]"]
  node_debounce["Search debounce<br/>[useDebounce.js]"]
  node_map["Interactive map<br/>[MapView.js]"]
  node_routecard["Route choices<br/>[RouteCard.js]"]
  node_envpanel["Environmental insights<br/>[EnvPanel.js]"]
  node_reportmodal["Report submission<br/>[ReportModal.js]"]
  node_assistant["CogniAssist chat<br/>[CogniAssist.js]"]
  node_header["Theme controls<br/>[Header.js]"]
  node_api["HTTP client<br/>[api.js]"]
end

subgraph group_backend["Backend services"]
  node_server["Express API server<br/>[server.js]"]
  node_geocode["Geocoding<br/>[geocode.js]"]
  node_routing["Route scoring<br/>[route.js]"]
  node_aqi["AQI endpoint<br/>[aqi.js]"]
  node_chat["Assistant endpoint<br/>[chat.js]"]
end

subgraph group_reports["Road reports"]
  node_reportsapi["Report API<br/>[reports.js]"]
  node_reportmodel[("Report model<br/>[Report.js]")]
end

subgraph group_providers["External providers"]
  node_ors{{"OpenRouteService"}}
  node_weather{{"OpenWeather"}}
  node_nominatim{{"Nominatim"}}
  node_mapbox{{"Mapbox geocoding"}}
  node_gemini{{"Gemini"}}
end

node_traveler(("Traveler"))

node_traveler -->|"chooses places"| node_search
node_traveler -->|"views routes"| node_map
node_traveler -->|"submits hazards"| node_reportmodal
node_app -->|"renders"| node_search
node_app -->|"renders"| node_map
node_app -->|"renders"| node_routecard
node_app -->|"renders"| node_envpanel
node_app -->|"renders"| node_header
node_app -->|"renders"| node_reportmodal
node_search -->|"debounces query"| node_debounce
node_search -->|"requests geocoding"| node_api
node_search -->|"selects places"| node_app
node_app -->|"requests routes"| node_api
node_api -->|"calls API"| node_server
node_server -->|"mounts route API"| node_routing
node_server -->|"mounts geocoding"| node_geocode
node_server -->|"mounts AQI"| node_aqi
node_server -->|"mounts reports"| node_reportsapi
node_server -->|"mounts chat"| node_chat
node_routing -->|"requests routes"| node_ors
node_routing -.->|"fetches conditions"| node_weather
node_routing -->|"counts nearby reports"| node_reportmodel
node_routing -.->|"fetches AQI"| node_aqi
node_geocode -->|"geocodes places"| node_mapbox
node_geocode -->|"fallback geocodes"| node_nominatim
node_reportsapi -->|"reads and writes"| node_reportmodel
node_app -->|"loads reports"| node_api
node_reportmodal -.->|"creates report"| node_api
node_assistant -->|"sends question"| node_api
node_api -->|"posts chat"| node_chat
node_chat -->|"generates answer"| node_gemini
node_map -->|"hosts assistant"| node_assistant

click node_app "https://github.com/ragini-create/cognimap/blob/main/frontend/src/App.js"
click node_search "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/SearchPanel.js"
click node_debounce "https://github.com/ragini-create/cognimap/blob/main/frontend/src/hooks/useDebounce.js"
click node_map "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/MapView.js"
click node_routecard "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/RouteCard.js"
click node_envpanel "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/EnvPanel.js"
click node_reportmodal "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/ReportModal.js"
click node_assistant "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/CogniAssist.js"
click node_header "https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/Header.js"
click node_api "https://github.com/ragini-create/cognimap/blob/main/frontend/src/utils/api.js"
click node_server "https://github.com/ragini-create/cognimap/blob/main/backend/server.js"
click node_geocode "https://github.com/ragini-create/cognimap/blob/main/backend/routes/geocode.js"
click node_routing "https://github.com/ragini-create/cognimap/blob/main/backend/routes/route.js"
click node_aqi "https://github.com/ragini-create/cognimap/blob/main/backend/routes/aqi.js"
click node_reportsapi "https://github.com/ragini-create/cognimap/blob/main/backend/routes/reports.js"
click node_reportmodel "https://github.com/ragini-create/cognimap/blob/main/backend/models/Report.js"
click node_chat "https://github.com/ragini-create/cognimap/blob/main/backend/routes/chat.js"

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_app,node_search,node_debounce,node_map,node_routecard,node_envpanel,node_reportmodal,node_assistant,node_header,node_api toneBlue
class node_server,node_geocode,node_routing,node_aqi,node_chat toneAmber
class node_reportsapi,node_reportmodel toneMint
class node_ors,node_weather,node_nominatim,node_mapbox,node_gemini toneRose
class node_traveler toneIndigo
```

## Components

### Navigation experience

- [App state and orchestration](https://github.com/ragini-create/cognimap/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Place search](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/SearchPanel.js): `frontend/src/components/SearchPanel.js`
- [Search debounce](https://github.com/ragini-create/cognimap/blob/main/frontend/src/hooks/useDebounce.js): `frontend/src/hooks/useDebounce.js`
- [Interactive map](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/MapView.js): `frontend/src/components/MapView.js`
- [Route choices](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/RouteCard.js): `frontend/src/components/RouteCard.js`
- [Environmental insights](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/EnvPanel.js): `frontend/src/components/EnvPanel.js`
- [Report submission](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/ReportModal.js): `frontend/src/components/ReportModal.js`
- [CogniAssist chat](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/CogniAssist.js): `frontend/src/components/CogniAssist.js`
- [Theme controls](https://github.com/ragini-create/cognimap/blob/main/frontend/src/components/Header.js): `frontend/src/components/Header.js`
- [HTTP client](https://github.com/ragini-create/cognimap/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`

### Backend services

- [Express API server](https://github.com/ragini-create/cognimap/blob/main/backend/server.js): `backend/server.js`
- [Geocoding](https://github.com/ragini-create/cognimap/blob/main/backend/routes/geocode.js): `backend/routes/geocode.js`
- [Route scoring](https://github.com/ragini-create/cognimap/blob/main/backend/routes/route.js): `backend/routes/route.js`
- [AQI endpoint](https://github.com/ragini-create/cognimap/blob/main/backend/routes/aqi.js): `backend/routes/aqi.js`
- [Assistant endpoint](https://github.com/ragini-create/cognimap/blob/main/backend/routes/chat.js): `backend/routes/chat.js`

### Road reports

- [Report API](https://github.com/ragini-create/cognimap/blob/main/backend/routes/reports.js): `backend/routes/reports.js`
- [Report model](https://github.com/ragini-create/cognimap/blob/main/backend/models/Report.js): `backend/models/Report.js`

### External providers

- **OpenRouteService**
- **OpenWeather**
- **Nominatim**
- **Mapbox geocoding**
- **Gemini**

### Other components

- **Traveler**

## Connections

- Traveler → Place search: chooses places (evidence: `README.md`)
- Traveler → Interactive map: views routes (evidence: `README.md`)
- Traveler → Report submission: submits hazards (evidence: `README.md`)
- App state and orchestration → Place search: renders (evidence: `frontend/src/App.js`)
- App state and orchestration → Interactive map: renders (evidence: `frontend/src/App.js`)
- App state and orchestration → Route choices: renders (evidence: `frontend/src/App.js`)
- App state and orchestration → Environmental insights: renders (evidence: `frontend/src/App.js`)
- App state and orchestration → Theme controls: renders (evidence: `frontend/src/App.js`)
- App state and orchestration → Report submission: renders (evidence: `frontend/src/App.js`)
- Place search → Search debounce: debounces query (evidence: `frontend/src/components/SearchPanel.js`)
- Place search → HTTP client: requests geocoding (evidence: `frontend/src/components/SearchPanel.js`)
- Place search → App state and orchestration: selects places (evidence: `frontend/src/App.js`)
- App state and orchestration → HTTP client: requests routes (evidence: `frontend/src/App.js`)
- HTTP client → Express API server: calls API (evidence: `frontend/src/utils/api.js`)
- Express API server → Route scoring: mounts route API (evidence: `backend/server.js`)
- Express API server → Geocoding: mounts geocoding (evidence: `backend/server.js`)
- Express API server → AQI endpoint: mounts AQI (evidence: `backend/server.js`)
- Express API server → Report API: mounts reports (evidence: `backend/server.js`)
- Express API server → Assistant endpoint: mounts chat (evidence: `backend/server.js`)
- Route scoring → OpenRouteService: requests routes (evidence: `backend/routes/route.js`)
- Route scoring → OpenWeather: fetches conditions (evidence: `README.md`)
- Route scoring → Report model: counts nearby reports (evidence: `backend/routes/route.js`)
- Route scoring → AQI endpoint: fetches AQI (evidence: `README.md`)
- Geocoding → Mapbox geocoding: geocodes places (evidence: `backend/routes/geocode.js`)
- Geocoding → Nominatim: fallback geocodes (evidence: `backend/routes/geocode.js`)
- Report API → Report model: reads and writes (evidence: `backend/routes/reports.js`)
- App state and orchestration → HTTP client: loads reports (evidence: `frontend/src/App.js`)
- Report submission → HTTP client: creates report (evidence: `README.md`)
- CogniAssist chat → HTTP client: sends question (evidence: `frontend/src/components/CogniAssist.js`)
- HTTP client → Assistant endpoint: posts chat (evidence: `frontend/src/utils/api.js`)
- Assistant endpoint → Gemini: generates answer (evidence: `backend/routes/chat.js`)
- Interactive map → CogniAssist chat: hosts assistant (evidence: `frontend/src/components/MapView.js`)
