# loomaimarketing-create/safehour architecture

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

- Interactive diagram: https://gitdiagram.com/loomaimarketing-create/safehour
- Repository: https://github.com/loomaimarketing-create/safehour

## Overview

SafeHour is a city-safety intelligence and navigation MVP. Its implemented user workflow selects a city in the map UI, requests city-specific incidents from FastAPI, fetches and normalizes public records through source adapters, deduplicates them, and displays historical incidents on a map. Chicago also has a sync path that persists records to Supabase. Discovery and schema checks, risk scoring, hourly aggregation, personalization, and safety-aware routing are distinct product capabilities, but the sampled runtime does not establish their full implementations or connections; those uncertain links are omitted or marked unverified.

Main entry points: [`backend/app/main.py`](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/main.py) (FastAPI endpoints), [`backend/app/ingestion/runner.py`](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/runner.py) (Chicago sync), [`backend/app/ingestion/normalize.py`](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/normalize.py) (Normalize records), [`backend/app/sources/chicago.py`](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/chicago.py) (Chicago adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Map experience"]
  node_map_ui["Incident map<br/>[App.jsx]"]
  node_routing["Safety-aware routing"]
  node_personalization["Personalization"]
end

subgraph group_api["API and discovery"]
  node_fastapi["FastAPI endpoints<br/>[main.py]"]
  node_source_discovery["Source discovery<br/>[discover.py]"]
  node_source_registry["Source registry<br/>[registry.py]"]
  node_schema_detection["Schema detection<br/>[schema_detector.py]"]
  node_risk_scoring["Risk scoring<br/>[risk.py]"]
  node_hourly_aggregation["Hourly aggregation"]
end

subgraph group_ingestion["Incident ingestion"]
  node_ingest_runner["Chicago sync<br/>[runner.py]"]
  node_normalization["Normalize records<br/>[normalize.py]"]
  node_deduplication["Deduplicate records<br/>[dedupe.py]"]
  node_quality["Quality reporting<br/>[quality.py]"]
  node_incident_model["Incident model<br/>[models.py]"]
end

subgraph group_sources["Data sources"]
  node_adapter_contract["Adapter contract<br/>[base.py]"]
  node_chicago_adapter["Chicago adapter<br/>[chicago.py]"]
  node_nyc_adapter["NYC adapter<br/>[nyc.py]"]
  node_la_adapter["Los Angeles adapter<br/>[la.py]"]
  node_socrata_client["Socrata client<br/>[socrata.py]"]
end

subgraph group_storage["Persistence"]
  node_supabase_client["Supabase client<br/>[db.py]"]
  node_postgres[("Supabase / Postgres<br/>[schema.sql]")]
end

node_user(("City explorer"))
node_socrata["Socrata open data"]
node_map_tiles["OpenStreetMap tiles"]

node_user -->|"selects city"| node_map_ui
node_map_ui -->|"requests incidents"| node_fastapi
node_fastapi -->|"creates adapter"| node_chicago_adapter
node_fastapi -->|"creates adapter"| node_nyc_adapter
node_fastapi -->|"creates adapter"| node_la_adapter
node_fastapi -->|"fetches normalized"| node_normalization
node_fastapi -->|"deduplicates"| node_deduplication
node_fastapi -->|"reports quality"| node_quality
node_fastapi -->|"lists sources"| node_source_discovery
node_source_discovery -->|"reads registry"| node_source_registry
node_ingest_runner -->|"creates adapter"| node_chicago_adapter
node_ingest_runner -->|"fetches normalized"| node_normalization
node_ingest_runner -->|"deduplicates"| node_deduplication
node_ingest_runner -->|"reports quality"| node_quality
node_normalization -->|"calls adapter"| node_adapter_contract
node_normalization -->|"returns incidents"| node_incident_model
node_chicago_adapter -->|"implements"| node_adapter_contract
node_nyc_adapter -->|"implements"| node_adapter_contract
node_la_adapter -->|"implements"| node_adapter_contract
node_chicago_adapter -->|"queries dataset"| node_socrata_client
node_nyc_adapter -->|"queries dataset"| node_socrata_client
node_la_adapter -->|"queries dataset"| node_socrata_client
node_socrata_client -->|"fetches records"| node_socrata
node_ingest_runner -->|"upserts incidents"| node_supabase_client
node_supabase_client -->|"connects to store"| node_postgres
node_map_ui -->|"loads tiles"| node_map_tiles
node_fastapi -->|"runs Chicago sync"| node_ingest_runner
node_risk_scoring -.-> node_hourly_aggregation
node_routing -.-> node_risk_scoring
node_personalization -.-> node_risk_scoring

click node_map_ui "https://github.com/loomaimarketing-create/safehour/blob/main/frontend/src/App.jsx"
click node_fastapi "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/main.py"
click node_source_discovery "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/discover.py"
click node_source_registry "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/registry.py"
click node_schema_detection "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/schema_detector.py"
click node_ingest_runner "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/runner.py"
click node_normalization "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/normalize.py"
click node_deduplication "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/dedupe.py"
click node_quality "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/quality.py"
click node_incident_model "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/models.py"
click node_adapter_contract "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/base.py"
click node_chicago_adapter "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/chicago.py"
click node_nyc_adapter "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/nyc.py"
click node_la_adapter "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/la.py"
click node_socrata_client "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/socrata.py"
click node_risk_scoring "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/risk.py"
click node_hourly_aggregation "https://github.com/loomaimarketing-create/safehour/tree/main/backend/app"
click node_routing "https://github.com/loomaimarketing-create/safehour/tree/main/frontend/src"
click node_personalization "https://github.com/loomaimarketing-create/safehour/tree/main/frontend/src"
click node_supabase_client "https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/db.py"
click node_postgres "https://github.com/loomaimarketing-create/safehour/blob/main/database/schema.sql"

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_map_ui,node_routing,node_personalization toneBlue
class node_fastapi,node_source_discovery,node_source_registry,node_schema_detection,node_risk_scoring,node_hourly_aggregation toneAmber
class node_ingest_runner,node_normalization,node_deduplication,node_quality,node_incident_model toneMint
class node_adapter_contract,node_chicago_adapter,node_nyc_adapter,node_la_adapter,node_socrata_client toneRose
class node_supabase_client,node_postgres,node_user,node_socrata,node_map_tiles toneIndigo
```

## Components

### Map experience

- [Incident map](https://github.com/loomaimarketing-create/safehour/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Safety-aware routing](https://github.com/loomaimarketing-create/safehour/tree/main/frontend/src): `frontend/src`
- [Personalization](https://github.com/loomaimarketing-create/safehour/tree/main/frontend/src): `frontend/src`

### API and discovery

- [FastAPI endpoints](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/main.py): `backend/app/main.py`
- [Source discovery](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/discover.py): `backend/app/discovery/discover.py`
- [Source registry](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/registry.py): `backend/app/discovery/registry.py`
- [Schema detection](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/discovery/schema_detector.py): `backend/app/discovery/schema_detector.py`
- [Risk scoring](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/risk.py): `backend/app/risk.py`
- [Hourly aggregation](https://github.com/loomaimarketing-create/safehour/tree/main/backend/app): `backend/app`

### Incident ingestion

- [Chicago sync](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/runner.py): `backend/app/ingestion/runner.py`
- [Normalize records](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/normalize.py): `backend/app/ingestion/normalize.py`
- [Deduplicate records](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/dedupe.py): `backend/app/ingestion/dedupe.py`
- [Quality reporting](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/ingestion/quality.py): `backend/app/ingestion/quality.py`
- [Incident model](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/models.py): `backend/app/models.py`

### Data sources

- [Adapter contract](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/base.py): `backend/app/sources/base.py`
- [Chicago adapter](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/chicago.py): `backend/app/sources/chicago.py`
- [NYC adapter](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/nyc.py): `backend/app/sources/nyc.py`
- [Los Angeles adapter](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/la.py): `backend/app/sources/la.py`
- [Socrata client](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/sources/socrata.py): `backend/app/sources/socrata.py`

### Persistence

- [Supabase client](https://github.com/loomaimarketing-create/safehour/blob/main/backend/app/db.py): `backend/app/db.py`
- [Supabase / Postgres](https://github.com/loomaimarketing-create/safehour/blob/main/database/schema.sql): `database/schema.sql`

### Other components

- **City explorer**
- **Socrata open data**
- **OpenStreetMap tiles**

## Connections

- City explorer → Incident map: selects city (evidence: `frontend/src/App.jsx`)
- Incident map → FastAPI endpoints: requests incidents (evidence: `frontend/src/App.jsx`)
- FastAPI endpoints → Chicago adapter: creates adapter (evidence: `backend/app/main.py`)
- FastAPI endpoints → NYC adapter: creates adapter (evidence: `backend/app/main.py`)
- FastAPI endpoints → Los Angeles adapter: creates adapter (evidence: `backend/app/main.py`)
- FastAPI endpoints → Normalize records: fetches normalized (evidence: `backend/app/main.py`)
- FastAPI endpoints → Deduplicate records: deduplicates (evidence: `backend/app/main.py`)
- FastAPI endpoints → Quality reporting: reports quality (evidence: `backend/app/main.py`)
- FastAPI endpoints → Source discovery: lists sources (evidence: `backend/app/main.py`)
- Source discovery → Source registry: reads registry (evidence: `backend/app/discovery/discover.py`)
- Chicago sync → Chicago adapter: creates adapter (evidence: `backend/app/ingestion/runner.py`)
- Chicago sync → Normalize records: fetches normalized (evidence: `backend/app/ingestion/runner.py`)
- Chicago sync → Deduplicate records: deduplicates (evidence: `backend/app/ingestion/runner.py`)
- Chicago sync → Quality reporting: reports quality (evidence: `backend/app/ingestion/runner.py`)
- Normalize records → Adapter contract: calls adapter (evidence: `backend/app/ingestion/normalize.py`)
- Normalize records → Incident model: returns incidents (evidence: `backend/app/ingestion/normalize.py`)
- Chicago adapter → Adapter contract: implements (evidence: `backend/app/sources/chicago.py`)
- NYC adapter → Adapter contract: implements (evidence: `backend/app/sources/nyc.py`)
- Los Angeles adapter → Adapter contract: implements (evidence: `backend/app/sources/la.py`)
- Chicago adapter → Socrata client: queries dataset (evidence: `backend/app/sources/chicago.py`)
- NYC adapter → Socrata client: queries dataset (evidence: `backend/app/sources/nyc.py`)
- Los Angeles adapter → Socrata client: queries dataset (evidence: `backend/app/sources/la.py`)
- Socrata client → Socrata open data: fetches records (evidence: `backend/app/sources/socrata.py`)
- Chicago sync → Supabase client: upserts incidents (evidence: `backend/app/ingestion/runner.py`)
- Supabase client → Supabase / Postgres: connects to store (evidence: `backend/app/db.py`)
- Incident map → OpenStreetMap tiles: loads tiles (evidence: `frontend/src/App.jsx`)
- FastAPI endpoints → Chicago sync: runs Chicago sync (evidence: `backend/app/main.py`)
- Risk scoring → Hourly aggregation
- Safety-aware routing → Risk scoring
- Personalization → Risk scoring
