# beksanoff/smart-city-ai architecture

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

- Interactive diagram: https://gitdiagram.com/beksanoff/smart-city-ai
- Repository: https://github.com/beksanoff/smart-city-ai

## Overview

Smart City AI Core monitors current Almaty conditions, predicts conditions for a user-selected date, and presents historical patterns plus a seven-day forecast. The main workflow runs from the React interface through the Go API to Python prediction/analytics logic, which uses a trained model and historical CSV; the Go backend also gathers live weather and traffic data and persists live snapshots and prediction logs. README statements establish several cross-service links; unsampled implementation details are left unconnected or shown as unverified.

Main entry points: [`backend-go/internal/delivery/http`](https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/delivery/http) (HTTP API), [`frontend-react/src/App.tsx`](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/App.tsx) (Application shell), [`ml-python/services/logic.py`](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/logic.py) (Prediction and analytics), [`frontend-react/src/services/api.ts`](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/services/api.ts) (Frontend API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_live_widgets["Live widgets"]
  node_planner["Trip planner<br/>[TripPlanner.tsx]"]
  node_analytics_ui["Analytics dashboard"]
  node_map["Almaty map<br/>[AlmatyMap.tsx]"]
  node_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_backend["Go backend"]
  node_http["HTTP API"]
  node_live_services["Live data services"]
  node_dashboard_service["Dashboard assembly"]
  node_traffic_service["Traffic service<br/>[traffic_service.go]"]
  node_weather_service["Weather service<br/>[weather_service.go]"]
  node_ml_bridge["ML bridge<br/>[ml_bridge.go]"]
  node_domain["Domain contracts"]
  node_postgres["PostgreSQL repository<br/>[postgres.go]"]
end

subgraph group_ml["Prediction and analytics"]
  node_ml_api["Python ML API<br/>[main.py]"]
  node_prediction_logic["Prediction and analytics<br/>[logic.py]"]
  node_model["AQI and traffic models<br/>[ml_model.py]"]
  node_forecast["Weather forecasts<br/>[forecast.py]"]
  node_history[("Historical dataset<br/>[almaty_history.csv]")]
end

subgraph group_external["External data and services"]
  node_weather_provider["Open-Meteo"]
  node_traffic_provider["TomTom"]
  node_map_provider["Yandex Maps"]
  node_groq["Groq"]
end

node_user(("City user"))
node_database[("PostgreSQL")]

node_user -->|"uses"| node_app
node_app -->|"shows"| node_live_widgets
node_app -.->|"shows"| node_planner
node_app -->|"shows"| node_analytics_ui
node_live_widgets -.->|"requests live data"| node_api
node_planner -->|"submits forecast"| node_api
node_analytics_ui -.->|"requests analytics"| node_api
node_app -.->|"displays"| node_map
node_map -->|"loads map and traffic"| node_map_provider
node_api -->|"calls endpoints"| node_http
node_http -.->|"assembles dashboard"| node_dashboard_service
node_http -.->|"serves live data"| node_live_services
node_live_services -.->|"handles weather"| node_weather_service
node_live_services -.->|"handles traffic"| node_traffic_service
node_dashboard_service -.->|"collects weather"| node_weather_service
node_dashboard_service -.->|"collects traffic"| node_traffic_service
node_http -->|"proxies AI requests"| node_ml_bridge
node_ml_bridge -->|"calls ML service"| node_ml_api
node_http -.->|"persists records"| node_postgres
node_postgres -->|"reads and writes"| node_database
node_http -.->|"uses contracts"| node_domain
node_ml_api -->|"dispatches requests"| node_prediction_logic
node_prediction_logic -->|"computes predictions"| node_model
node_prediction_logic -->|"gets forecasts"| node_forecast
node_prediction_logic -->|"reads history"| node_history
node_prediction_logic -->|"generates explanation"| node_groq
node_weather_service -->|"gets live weather"| node_weather_provider
node_traffic_service -->|"gets live traffic"| node_traffic_provider
node_forecast -->|"gets forecast"| node_weather_provider

click node_app "https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/App.tsx"
click node_live_widgets "https://github.com/beksanoff/smart-city-ai/tree/main/frontend-react/src/components/dashboard"
click node_planner "https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/dashboard/TripPlanner.tsx"
click node_analytics_ui "https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/analytics/AnalyticsDashboard.tsx"
click node_map "https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/map/AlmatyMap.tsx"
click node_api "https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/services/api.ts"
click node_http "https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/delivery/http"
click node_live_services "https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/service"
click node_dashboard_service "https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/dashboard_service.go"
click node_traffic_service "https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/traffic_service.go"
click node_weather_service "https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/weather_service.go"
click node_ml_bridge "https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/ml_bridge.go"
click node_domain "https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/domain"
click node_postgres "https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/repository/postgres/postgres.go"
click node_ml_api "https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/main.py"
click node_prediction_logic "https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/logic.py"
click node_model "https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/ml_model.py"
click node_forecast "https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/forecast.py"
click node_history "https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/data/almaty_history.csv"

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_live_widgets,node_planner,node_analytics_ui,node_map,node_api,node_user toneBlue
class node_http,node_live_services,node_dashboard_service,node_traffic_service,node_weather_service,node_ml_bridge,node_domain,node_postgres,node_database toneAmber
class node_ml_api,node_prediction_logic,node_model,node_forecast,node_history toneMint
class node_weather_provider,node_traffic_provider,node_map_provider,node_groq toneRose
```

## Components

### React interface

- [Application shell](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/App.tsx): `frontend-react/src/App.tsx`
- [Live widgets](https://github.com/beksanoff/smart-city-ai/tree/main/frontend-react/src/components/dashboard): `frontend-react/src/components/dashboard`
- [Trip planner](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/dashboard/TripPlanner.tsx): `frontend-react/src/components/dashboard/TripPlanner.tsx`
- [Analytics dashboard](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/analytics/AnalyticsDashboard.tsx): `frontend-react/src/components/analytics/AnalyticsDashboard.tsx`
- [Almaty map](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/components/map/AlmatyMap.tsx): `frontend-react/src/components/map/AlmatyMap.tsx`
- [Frontend API client](https://github.com/beksanoff/smart-city-ai/blob/main/frontend-react/src/services/api.ts): `frontend-react/src/services/api.ts`

### Go backend

- [HTTP API](https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/delivery/http): `backend-go/internal/delivery/http`
- [Live data services](https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/service): `backend-go/internal/service`
- [Dashboard assembly](https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/dashboard_service.go): `backend-go/internal/service/dashboard_service.go`
- [Traffic service](https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/traffic_service.go): `backend-go/internal/service/traffic_service.go`
- [Weather service](https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/weather_service.go): `backend-go/internal/service/weather_service.go`
- [ML bridge](https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/service/ml_bridge.go): `backend-go/internal/service/ml_bridge.go`
- [Domain contracts](https://github.com/beksanoff/smart-city-ai/tree/main/backend-go/internal/domain): `backend-go/internal/domain`
- [PostgreSQL repository](https://github.com/beksanoff/smart-city-ai/blob/main/backend-go/internal/repository/postgres/postgres.go): `backend-go/internal/repository/postgres/postgres.go`

### Prediction and analytics

- [Python ML API](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/main.py): `ml-python/main.py`
- [Prediction and analytics](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/logic.py): `ml-python/services/logic.py`
- [AQI and traffic models](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/ml_model.py): `ml-python/services/ml_model.py`
- [Weather forecasts](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/services/forecast.py): `ml-python/services/forecast.py`
- [Historical dataset](https://github.com/beksanoff/smart-city-ai/blob/main/ml-python/data/almaty_history.csv): `ml-python/data/almaty_history.csv`

### External data and services

- **Open-Meteo**
- **TomTom**
- **Yandex Maps**
- **Groq**

### Other components

- **City user**
- **PostgreSQL**

## Connections

- City user → Application shell: uses (evidence: `README.md`)
- Application shell → Live widgets: shows (evidence: `frontend-react/src/App.tsx`)
- Application shell → Trip planner: shows (evidence: `frontend-react/src/App.tsx`)
- Application shell → Analytics dashboard: shows (evidence: `frontend-react/src/App.tsx`)
- Live widgets → Frontend API client: requests live data (evidence: `frontend-react/src/components/dashboard/TripPlanner.tsx`)
- Trip planner → Frontend API client: submits forecast (evidence: `frontend-react/src/components/dashboard/TripPlanner.tsx`)
- Analytics dashboard → Frontend API client: requests analytics (evidence: `frontend-react/src/components/analytics/AnalyticsDashboard.tsx`)
- Application shell → Almaty map: displays (evidence: `frontend-react/src/App.tsx`)
- Almaty map → Yandex Maps: loads map and traffic (evidence: `README.md`)
- Frontend API client → HTTP API: calls endpoints (evidence: `README.md`)
- HTTP API → Dashboard assembly: assembles dashboard
- HTTP API → Live data services: serves live data
- Live data services → Weather service: handles weather
- Live data services → Traffic service: handles traffic
- Dashboard assembly → Weather service: collects weather
- Dashboard assembly → Traffic service: collects traffic
- HTTP API → ML bridge: proxies AI requests (evidence: `README.md`)
- ML bridge → Python ML API: calls ML service (evidence: `README.md`)
- HTTP API → PostgreSQL repository: persists records
- PostgreSQL repository → PostgreSQL: reads and writes (evidence: `README.md`)
- HTTP API → Domain contracts: uses contracts
- Python ML API → Prediction and analytics: dispatches requests (evidence: `ml-python/main.py`)
- Prediction and analytics → AQI and traffic models: computes predictions (evidence: `ml-python/services/logic.py`)
- Prediction and analytics → Weather forecasts: gets forecasts (evidence: `ml-python/services/logic.py`)
- Prediction and analytics → Historical dataset: reads history (evidence: `README.md`)
- Prediction and analytics → Groq: generates explanation (evidence: `README.md`)
- Weather service → Open-Meteo: gets live weather (evidence: `README.md`)
- Traffic service → TomTom: gets live traffic (evidence: `README.md`)
- Weather forecasts → Open-Meteo: gets forecast (evidence: `README.md`)
