# sapirshenkor/citystrata architecture

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

- Interactive diagram: https://gitdiagram.com/sapirshenkor/citystrata
- Repository: https://github.com/sapirshenkor/citystrata

## Overview

CityStrata is an evacuation-planning decision-support platform: users explore urban data, submit family or community needs, and receive map-based relocation recommendations. The documented flow combines macro cluster matching, tactical spatial/vector analysis, and a grounded report. The graph also preserves the family listing, municipal analytics, and POI/hotel management branches. Relationships for unsampled endpoint and frontend subsystems follow explicit README capabilities or router references; internal details not shown in excerpts are kept at subsystem level.

Main entry points: [`frontend/src/services/api.js`](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/services/api.js) (API client), [`backend/app/core/database.py`](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/core/database.py) (Database connection pool), [`backend/app/api/router.py`](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/router.py) (API routes), [`backend/app/api/endpoints/property_listings.py`](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/property_listings.py) (Family and listing APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Planning experience"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_map["Interactive map<br/>[MapApp.tsx]"]
  node_mapdata["Map data queries<br/>[useMapData.ts]"]
  node_recommendui["Recommendation panel"]
  node_familyportal["Family portal"]
  node_familyqueries["Family queries"]
  node_municipality["Municipal dashboard"]
  node_poimanage["POI management"]
  node_hotelmanage["Hotel management"]
  node_httpclient["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_fastapi["API application<br/>[main.py]"]
  node_routes["API routes<br/>[router.py]"]
  node_authapi["Authentication API<br/>[auth.py]"]
  node_auth["Identity and roles<br/>[auth.py]"]
  node_recordsapi["Family and listing APIs"]
  node_mapapi["Urban data APIs"]
  node_matchingapi["Recommendation API<br/>[matching.py]"]
end

subgraph group_analysis["Recommendation intelligence"]
  node_tacticalservice["Tactical pipeline service"]
  node_macro["Macro cluster matching<br/>[matchingAgent.py]"]
  node_clustering["Urban clustering<br/>[clustering.py]"]
  node_tacticalagent["Tactical agents<br/>[tactical_agent.py]"]
  node_familyagent["Family agent<br/>[family_agent.py]"]
  node_multiagent["Community agent"]
  node_mcptools["Spatial and vector tools<br/>[mcp_server.py]"]
end

subgraph group_data["Urban data and records"]
  node_postgres[("Spatial and vector database")]
  node_dbpool["Database connection pool<br/>[database.py]"]
  node_authservice["Supabase authentication"]
  node_profiles["Family and community records"]
  node_poi["POI and urban records<br/>[poi_generic.py]"]
  node_listing["Property listings"]
end

node_planner(("Planner or family"))

node_planner -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_map
node_webapp -->|"routes to"| node_familyportal
node_planner -.->|"submits needs"| node_recommendui
node_map -.->|"loads layers"| node_mapdata
node_mapdata -->|"requests data"| node_httpclient
node_familyportal -->|"loads records"| node_familyqueries
node_familyqueries -->|"requests records"| node_httpclient
node_recommendui -.->|"requests recommendations"| node_httpclient
node_municipality -.->|"loads analytics"| node_httpclient
node_poimanage -.->|"manages POIs"| node_httpclient
node_hotelmanage -.->|"manages hotels"| node_httpclient
node_httpclient -.->|"REST requests"| node_fastapi
node_fastapi -->|"initializes pool"| node_dbpool
node_fastapi -->|"mounts routes"| node_routes
node_routes -->|"registers"| node_authapi
node_routes -->|"registers"| node_recordsapi
node_routes -->|"registers"| node_mapapi
node_routes -->|"registers"| node_matchingapi
node_authapi -->|"authenticates"| node_authservice
node_authapi -->|"reads and writes"| node_dbpool
node_auth -->|"validates token"| node_authservice
node_auth -->|"loads user"| node_dbpool
node_recordsapi -->|"checks access"| node_auth
node_recordsapi -->|"reads and writes"| node_dbpool
node_dbpool -->|"connects"| node_postgres
node_mapapi -.->|"queries urban data"| node_dbpool
node_matchingapi -.->|"selects cluster"| node_macro
node_matchingapi -.->|"starts tactical run"| node_tacticalservice
node_macro -.->|"uses cluster profiles"| node_postgres
node_tacticalservice -->|"delegates pipeline"| node_tacticalagent
node_tacticalagent -->|"dispatches family run"| node_familyagent
node_tacticalagent -->|"dispatches community run"| node_multiagent
node_familyagent -.->|"uses tools"| node_mcptools
node_multiagent -.->|"uses tools"| node_mcptools
node_mcptools -.->|"queries spatial and vector data"| node_postgres
node_clustering -.->|"clusters area features"| node_postgres
node_recordsapi -.->|"persists profiles"| node_profiles
node_recordsapi -.->|"persists listings"| node_listing
node_mapapi -.->|"serves urban layers"| node_poi
node_familyagent -.->|"persists report"| node_postgres
node_multiagent -.->|"persists report"| node_postgres

click node_webapp "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/App.jsx"
click node_map "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/MapApp.tsx"
click node_mapdata "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/hooks/useMapData.ts"
click node_recommendui "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/components/Recommendations/RecommendationsPanel.jsx"
click node_familyportal "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/family_portal/FamilyDashboard.tsx"
click node_familyqueries "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/family_portal/hooks/useFamilyQueries.ts"
click node_municipality "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/user_dashboard/DashboardContainer.tsx"
click node_poimanage "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/poi_management/PointOfInterestManagement.tsx"
click node_hotelmanage "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/hotels_management/HotelManagementPage.tsx"
click node_httpclient "https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/main.py"
click node_routes "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/router.py"
click node_authapi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/auth.py"
click node_auth "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/core/auth.py"
click node_recordsapi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/property_listings.py"
click node_mapapi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/statistical_areas.py"
click node_matchingapi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/matching.py"
click node_tacticalservice "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/services/tactical_pipeline.py"
click node_macro "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/agents/matchingAgent.py"
click node_clustering "https://github.com/sapirshenkor/citystrata/blob/main/backend/ML/clustering.py"
click node_tacticalagent "https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/tactical_agent.py"
click node_familyagent "https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/family_agent.py"
click node_multiagent "https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/multi_family_agent.py"
click node_mcptools "https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/mcp_server.py"
click node_dbpool "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/core/database.py"
click node_profiles "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/evacuee_family_profiles.py"
click node_poi "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/poi_generic.py"
click node_listing "https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/property_listing.py"

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_webapp,node_map,node_mapdata,node_recommendui,node_familyportal,node_familyqueries,node_municipality,node_poimanage,node_hotelmanage,node_httpclient toneBlue
class node_fastapi,node_routes,node_authapi,node_auth,node_recordsapi,node_mapapi,node_matchingapi toneAmber
class node_tacticalservice,node_macro,node_clustering,node_tacticalagent,node_familyagent,node_multiagent,node_mcptools toneMint
class node_postgres,node_dbpool,node_authservice,node_profiles,node_poi,node_listing toneRose
class node_planner toneIndigo
```

## Components

### Planning experience

- [Web application](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Interactive map](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/MapApp.tsx): `frontend/src/MapApp.tsx`
- [Map data queries](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/hooks/useMapData.ts): `frontend/src/hooks/useMapData.ts`
- [Recommendation panel](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/components/Recommendations/RecommendationsPanel.jsx): `frontend/src/components/Recommendations/RecommendationsPanel.jsx`
- [Family portal](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/family_portal/FamilyDashboard.tsx): `frontend/src/family_portal/FamilyDashboard.tsx`
- [Family queries](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/family_portal/hooks/useFamilyQueries.ts): `frontend/src/family_portal/hooks/useFamilyQueries.ts`
- [Municipal dashboard](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/user_dashboard/DashboardContainer.tsx): `frontend/src/user_dashboard/DashboardContainer.tsx`
- [POI management](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/poi_management/PointOfInterestManagement.tsx): `frontend/src/poi_management/PointOfInterestManagement.tsx`
- [Hotel management](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/hotels_management/HotelManagementPage.tsx): `frontend/src/hotels_management/HotelManagementPage.tsx`
- [API client](https://github.com/sapirshenkor/citystrata/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and access

- [API application](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication API](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/auth.py): `backend/app/api/endpoints/auth.py`
- [Identity and roles](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Family and listing APIs](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/property_listings.py): `backend/app/api/endpoints/property_listings.py`
- [Urban data APIs](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/statistical_areas.py): `backend/app/api/endpoints/statistical_areas.py`
- [Recommendation API](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/api/endpoints/matching.py): `backend/app/api/endpoints/matching.py`

### Recommendation intelligence

- [Tactical pipeline service](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/services/tactical_pipeline.py): `backend/app/services/tactical_pipeline.py`
- [Macro cluster matching](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/agents/matchingAgent.py): `backend/app/agents/matchingAgent.py`
- [Urban clustering](https://github.com/sapirshenkor/citystrata/blob/main/backend/ML/clustering.py): `backend/ML/clustering.py`
- [Tactical agents](https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/tactical_agent.py): `backend/mcp/tactical_agent.py`
- [Family agent](https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/family_agent.py): `backend/mcp/family_agent.py`
- [Community agent](https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/multi_family_agent.py): `backend/mcp/multi_family_agent.py`
- [Spatial and vector tools](https://github.com/sapirshenkor/citystrata/blob/main/backend/mcp/mcp_server.py): `backend/mcp/mcp_server.py`

### Urban data and records

- **Spatial and vector database**
- [Database connection pool](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Supabase authentication**
- [Family and community records](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/evacuee_family_profiles.py): `backend/app/models/evacuee_family_profiles.py`
- [POI and urban records](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/poi_generic.py): `backend/app/models/poi_generic.py`
- [Property listings](https://github.com/sapirshenkor/citystrata/blob/main/backend/app/models/property_listing.py): `backend/app/models/property_listing.py`

### Other components

- **Planner or family**

## Connections

- Planner or family → Web application: uses
- Web application → Interactive map: routes to (evidence: `frontend/src/App.jsx`)
- Web application → Family portal: routes to (evidence: `frontend/src/App.jsx`)
- Planner or family → Recommendation panel: submits needs
- Interactive map → Map data queries: loads layers
- Map data queries → API client: requests data (evidence: `frontend/src/hooks/useMapData.ts`)
- Family portal → Family queries: loads records (evidence: `frontend/src/family_portal/hooks/useFamilyQueries.ts`)
- Family queries → API client: requests records (evidence: `frontend/src/family_portal/hooks/useFamilyQueries.ts`)
- Recommendation panel → API client: requests recommendations
- Municipal dashboard → API client: loads analytics
- POI management → API client: manages POIs
- Hotel management → API client: manages hotels
- API client → API application: REST requests
- API application → Database connection pool: initializes pool (evidence: `backend/app/main.py`)
- API application → API routes: mounts routes (evidence: `backend/app/main.py`)
- API routes → Authentication API: registers (evidence: `backend/app/api/router.py`)
- API routes → Family and listing APIs: registers (evidence: `backend/app/api/router.py`)
- API routes → Urban data APIs: registers (evidence: `backend/app/api/router.py`)
- API routes → Recommendation API: registers (evidence: `backend/app/api/router.py`)
- Authentication API → Supabase authentication: authenticates (evidence: `backend/app/api/endpoints/auth.py`)
- Authentication API → Database connection pool: reads and writes (evidence: `backend/app/api/endpoints/auth.py`)
- Identity and roles → Supabase authentication: validates token (evidence: `backend/app/core/auth.py`)
- Identity and roles → Database connection pool: loads user (evidence: `backend/app/core/auth.py`)
- Family and listing APIs → Identity and roles: checks access (evidence: `backend/app/api/endpoints/property_listings.py`)
- Family and listing APIs → Database connection pool: reads and writes (evidence: `backend/app/api/endpoints/property_listings.py`)
- Database connection pool → Spatial and vector database: connects (evidence: `backend/app/core/database.py`)
- Urban data APIs → Database connection pool: queries urban data
- Recommendation API → Macro cluster matching: selects cluster
- Recommendation API → Tactical pipeline service: starts tactical run
- Macro cluster matching → Spatial and vector database: uses cluster profiles
- Tactical pipeline service → Tactical agents: delegates pipeline (evidence: `backend/app/services/tactical_pipeline.py`)
- Tactical agents → Family agent: dispatches family run (evidence: `backend/mcp/tactical_agent.py`)
- Tactical agents → Community agent: dispatches community run (evidence: `backend/mcp/tactical_agent.py`)
- Family agent → Spatial and vector tools: uses tools
- Community agent → Spatial and vector tools: uses tools
- Spatial and vector tools → Spatial and vector database: queries spatial and vector data
- Urban clustering → Spatial and vector database: clusters area features
- Family and listing APIs → Family and community records: persists profiles
- Family and listing APIs → Property listings: persists listings (evidence: `backend/app/api/endpoints/property_listings.py`)
- Urban data APIs → POI and urban records: serves urban layers
- Family agent → Spatial and vector database: persists report
- Community agent → Spatial and vector database: persists report
