# cahcai/geo architecture

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

- Interactive diagram: https://gitdiagram.com/cahcai/geo
- Repository: https://github.com/cahcai/geo

## Overview

GeoPortal is a full-stack HCAI geospatial-data portal. Analysts use the React interface to search healthcare and district data, upload workbooks, and manage coordinate overrides; downstream clients use the REST API. The API combines geocoding, spatial lookup, override management, and API-key controls, with data persisted in Django models. The README documents several capabilities whose detailed implementation was not sampled, so those links are shown as documented rather than inferred from unseen code.

Main entry points: [`Geo/api/routers.py`](https://github.com/cahcai/geo/blob/main/Geo/api/routers.py) (API endpoints), [`react-front-end-wip/Geo_app/src/App.tsx`](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/App.tsx) (Portal app), [`Geo/api/models.py`](https://github.com/cahcai/geo/blob/main/Geo/api/models.py) (Portal data models), [`react-front-end-wip/Geo_app/src/components/HpsaSearch.tsx`](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/HpsaSearch.tsx) (HPSA search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Portal interface"]
  node_app["Portal app<br/>[App.tsx]"]
  node_hpsa["HPSA search<br/>[HpsaSearch.tsx]"]
  node_facilities["Facility search"]
  node_map["Map viewer<br/>[MapViewer.tsx]"]
  node_admin["Admin dashboard<br/>[AdminDashboard.tsx]"]
  node_overrides_ui["Override editor<br/>[CordOverride.tsx]"]
  node_login["Login<br/>[Login.tsx]"]
  node_api_ref["API reference<br/>[APIReference.tsx]"]
  node_theme["Theme state<br/>[ThemeContext.tsx]"]
end

subgraph group_api["API and access"]
  node_api_router["API endpoints<br/>[routers.py]"]
  node_auth["API-key auth<br/>[auth.py]"]
  node_key_admin["Key management"]
end

subgraph group_geo["Geospatial services"]
  node_geocode["Address geocoding<br/>[geocoding.py]"]
  node_spatial["Spatial lookup<br/>[routers.py]"]
  node_workbook["Workbook upload<br/>[routers.py]"]
end

subgraph group_data["Domain data"]
  node_model["Portal data models<br/>[models.py]"]
  node_redis[("Redis cache<br/>[cache.py]")]
end

node_analyst(("HCAI analyst"))
node_client(("API client"))
node_azure["Azure Maps"]
node_db[("Spatial database")]

node_analyst -->|"uses"| node_app
node_client -->|"calls API"| node_api_router
node_app -->|"renders"| node_hpsa
node_app -->|"renders"| node_facilities
node_app -->|"renders"| node_map
node_app -->|"renders"| node_admin
node_app -->|"renders"| node_overrides_ui
node_app -->|"renders"| node_login
node_app -->|"renders"| node_api_ref
node_app -->|"wraps with"| node_theme
node_api_router -->|"imports auth"| node_auth
node_api_router -->|"uses models"| node_model
node_api_router -->|"uses cache"| node_redis
node_api_router -->|"dispatches"| node_spatial
node_api_router -->|"accepts uploads"| node_workbook
node_api_router -->|"geocodes addresses"| node_geocode
node_geocode -->|"queries"| node_azure
node_api_router -->|"queries maps"| node_azure
node_api_router -->|"queries and writes"| node_db
node_model -->|"maps entities"| node_db
node_redis -.->|"caches lookups"| node_db
node_key_admin -->|"generates keys"| node_model
node_auth -->|"checks keys"| node_model
node_hpsa -.->|"searches API"| node_api_router
node_facilities -.->|"searches API"| node_api_router
node_map -.->|"requests map data"| node_api_router
node_admin -.->|"manages usage"| node_api_router
node_overrides_ui -.->|"edits overrides"| node_api_router
node_login -.->|"authenticates"| node_api_router
node_api_ref -.->|"documents API"| node_client

click node_app "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/App.tsx"
click node_hpsa "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/HpsaSearch.tsx"
click node_facilities "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/LicensedHealthcareFacilities.tsx"
click node_map "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/MapViewer.tsx"
click node_admin "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/AdminDashboard.tsx"
click node_overrides_ui "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/CordOverride.tsx"
click node_login "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/Login.tsx"
click node_api_ref "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/APIReference.tsx"
click node_api_router "https://github.com/cahcai/geo/blob/main/Geo/api/routers.py"
click node_auth "https://github.com/cahcai/geo/blob/main/Geo/api/auth.py"
click node_key_admin "https://github.com/cahcai/geo/blob/main/Geo/api/management/commands/generate_api_key.py"
click node_geocode "https://github.com/cahcai/geo/blob/main/GIS%20API/geocoding.py"
click node_spatial "https://github.com/cahcai/geo/blob/main/Geo/api/routers.py"
click node_workbook "https://github.com/cahcai/geo/blob/main/Geo/api/routers.py"
click node_model "https://github.com/cahcai/geo/blob/main/Geo/api/models.py"
click node_redis "https://github.com/cahcai/geo/blob/main/Geo/Geo/cache.py"
click node_theme "https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/utils/ThemeContext.tsx"

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_hpsa,node_facilities,node_map,node_admin,node_overrides_ui,node_login,node_api_ref,node_theme,node_client toneBlue
class node_api_router,node_auth,node_key_admin,node_db toneAmber
class node_geocode,node_spatial,node_workbook toneMint
class node_model,node_redis toneRose
class node_analyst,node_azure toneIndigo
```

## Components

### Portal interface

- [Portal app](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/App.tsx): `react-front-end-wip/Geo_app/src/App.tsx`
- [HPSA search](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/HpsaSearch.tsx): `react-front-end-wip/Geo_app/src/components/HpsaSearch.tsx`
- [Facility search](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/LicensedHealthcareFacilities.tsx): `react-front-end-wip/Geo_app/src/components/LicensedHealthcareFacilities.tsx`
- [Map viewer](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/MapViewer.tsx): `react-front-end-wip/Geo_app/src/components/MapViewer.tsx`
- [Admin dashboard](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/AdminDashboard.tsx): `react-front-end-wip/Geo_app/src/components/AdminDashboard.tsx`
- [Override editor](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/CordOverride.tsx): `react-front-end-wip/Geo_app/src/components/CordOverride.tsx`
- [Login](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/Login.tsx): `react-front-end-wip/Geo_app/src/components/Login.tsx`
- [API reference](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/components/APIReference.tsx): `react-front-end-wip/Geo_app/src/components/APIReference.tsx`
- [Theme state](https://github.com/cahcai/geo/blob/main/react-front-end-wip/Geo_app/src/utils/ThemeContext.tsx): `react-front-end-wip/Geo_app/src/utils/ThemeContext.tsx`

### API and access

- [API endpoints](https://github.com/cahcai/geo/blob/main/Geo/api/routers.py): `Geo/api/routers.py`
- [API-key auth](https://github.com/cahcai/geo/blob/main/Geo/api/auth.py): `Geo/api/auth.py`
- [Key management](https://github.com/cahcai/geo/blob/main/Geo/api/management/commands/generate_api_key.py): `Geo/api/management/commands/generate_api_key.py`

### Geospatial services

- [Address geocoding](https://github.com/cahcai/geo/blob/main/GIS%20API/geocoding.py): `GIS API/geocoding.py`
- [Spatial lookup](https://github.com/cahcai/geo/blob/main/Geo/api/routers.py): `Geo/api/routers.py`
- [Workbook upload](https://github.com/cahcai/geo/blob/main/Geo/api/routers.py): `Geo/api/routers.py`

### Domain data

- [Portal data models](https://github.com/cahcai/geo/blob/main/Geo/api/models.py): `Geo/api/models.py`
- [Redis cache](https://github.com/cahcai/geo/blob/main/Geo/Geo/cache.py): `Geo/Geo/cache.py`

### Other components

- **HCAI analyst**
- **API client**
- **Azure Maps**
- **Spatial database**

## Connections

- HCAI analyst → Portal app: uses
- API client → API endpoints: calls API
- Portal app → HPSA search: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Facility search: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Map viewer: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Admin dashboard: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Override editor: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Login: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → API reference: renders (evidence: `react-front-end-wip/Geo_app/src/App.tsx`)
- Portal app → Theme state: wraps with (evidence: `react-front-end-wip/Geo_app/src/main.tsx`)
- API endpoints → API-key auth: imports auth (evidence: `Geo/api/routers.py`)
- API endpoints → Portal data models: uses models (evidence: `Geo/api/routers.py`)
- API endpoints → Redis cache: uses cache (evidence: `Geo/api/routers.py`)
- API endpoints → Spatial lookup: dispatches (evidence: `Geo/api/routers.py`)
- API endpoints → Workbook upload: accepts uploads (evidence: `Geo/api/routers.py`)
- API endpoints → Address geocoding: geocodes addresses
- Address geocoding → Azure Maps: queries
- API endpoints → Azure Maps: queries maps (evidence: `Geo/api/routers.py`)
- API endpoints → Spatial database: queries and writes (evidence: `Geo/api/routers.py`)
- Portal data models → Spatial database: maps entities (evidence: `Geo/api/models.py`)
- Redis cache → Spatial database: caches lookups
- Key management → Portal data models: generates keys (evidence: `Geo/api/management/commands/generate_api_key.py`)
- API-key auth → Portal data models: checks keys (evidence: `Geo/api/auth.py`)
- HPSA search → API endpoints: searches API
- Facility search → API endpoints: searches API
- Map viewer → API endpoints: requests map data
- Admin dashboard → API endpoints: manages usage
- Override editor → API endpoints: edits overrides
- Login → API endpoints: authenticates
- API reference → API client: documents API
