# afolabi-adesina-m/smart-shield-ai architecture

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

- Interactive diagram: https://gitdiagram.com/afolabi-adesina-m/smart-shield-ai
- Repository: https://github.com/afolabi-adesina-m/smart-shield-ai

## Overview

Smart-Shield AI combines multimodal highway-risk scoring with a desktop and mobile map experience for route safety, speed guidance, and related driving features. The principal flow is a driver choosing a route, the demo obtaining directions and scoring candidates, and the interface presenting ranked routes and live road guidance. The README also documents address search, practice-test loops, speed limits, street and exit rules, fleet trip scoring, and installable/offline map-shell support. Some backend modules are named in the README or engine inventory but were not sampled, so their internal wiring is shown only where documented.

Main entry points: [`demo/api_server.py`](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/api_server.py) (Desktop API server), [`demo/mobile_server.py`](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/mobile_server.py) (Mobile server), [`demo/static/js/app.js`](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/static/js/app.js) (Desktop map UI), [`mobile/App.tsx`](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/App.tsx) (Mobile app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Map clients"]
  node_desktop["Desktop map UI<br/>[app.js]"]
  node_mobile["Mobile app<br/>[App.tsx]"]
  node_mobileapi["Mobile API client<br/>[api.ts]"]
  node_pwa["Offline map shell<br/>[pwa_routes.py]"]
end

subgraph group_server["Demo services"]
  node_api["Desktop API server<br/>[api_server.py]"]
  node_mobile_server["Mobile server<br/>[mobile_server.py]"]
  node_directions["Route directions"]
  node_geocode["Address search"]
end

subgraph group_scoring["Safety scoring"]
  node_route_score["Route scoring"]
  node_nlp["NLP alerts<br/>[Live_alerts.py]"]
  node_vision["Vision conditions<br/>[Live_cameras.py]"]
  node_tabular["Collision risk"]
end

subgraph group_guidance["Driving guidance"]
  node_speed["Speed limits"]
  node_road_rules["Street exit rules"]
  node_weather["Live weather<br/>[Live_weather.py]"]
  node_fleet["Fleet scoring<br/>[fleetLogic.ts]"]
  node_practice["Test prep loops<br/>[road_preview.py]"]
end

subgraph group_integrations["External services"]
  node_routing_service["Routing service"]
  node_osm["OpenStreetMap"]
  node_overpass["Overpass API"]
end

node_driver(("Driver"))
node_driver_result["Route and guidance"]

node_driver -->|"chooses route"| node_desktop
node_driver -->|"chooses route"| node_mobile
node_desktop -->|"requests routes"| node_api
node_mobile -->|"requests data"| node_mobileapi
node_mobileapi -->|"calls API"| node_mobile_server
node_api -->|"gets directions"| node_directions
node_api -->|"geocodes places"| node_geocode
node_directions -->|"requests routes"| node_routing_service
node_geocode -.->|"looks up places"| node_osm
node_api -->|"scores routes"| node_route_score
node_route_score -->|"uses alerts"| node_nlp
node_route_score -->|"uses conditions"| node_vision
node_route_score -->|"uses risk model"| node_tabular
node_api -->|"gets speed guidance"| node_speed
node_speed -->|"looks up limits"| node_overpass
node_api -->|"gets road context"| node_road_rules
node_mobile_server -->|"scores routes"| node_route_score
node_mobile_server -->|"gets speed guidance"| node_speed
node_mobile_server -->|"gets road context"| node_road_rules
node_mobile_server -->|"gets weather"| node_weather
node_mobile_server -->|"scores fleet trips"| node_fleet
node_api -->|"builds practice loop"| node_practice
node_desktop -->|"loads app shell"| node_pwa
node_desktop -->|"presents results"| node_driver_result
node_mobile -->|"presents results"| node_driver_result

click node_desktop "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/static/js/app.js"
click node_mobile "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/App.tsx"
click node_mobileapi "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/src/api.ts"
click node_api "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/api_server.py"
click node_mobile_server "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/mobile_server.py"
click node_directions "https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/demo"
click node_geocode "https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/demo"
click node_nlp "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_alerts.py"
click node_vision "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_cameras.py"
click node_tabular "https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/src"
click node_weather "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_weather.py"
click node_fleet "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/src/fleetLogic.ts"
click node_practice "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/road_preview.py"
click node_pwa "https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/pwa_routes.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_desktop,node_mobile,node_mobileapi,node_pwa toneBlue
class node_api,node_mobile_server,node_directions,node_geocode toneAmber
class node_route_score,node_nlp,node_vision,node_tabular,node_driver_result toneMint
class node_speed,node_road_rules,node_weather,node_fleet,node_practice toneRose
class node_routing_service,node_osm,node_overpass,node_driver toneIndigo
```

## Components

### Map clients

- [Desktop map UI](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/static/js/app.js): `demo/static/js/app.js`
- [Mobile app](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/App.tsx): `mobile/App.tsx`
- [Mobile API client](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/src/api.ts): `mobile/src/api.ts`
- [Offline map shell](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/pwa_routes.py): `demo/pwa_routes.py`

### Demo services

- [Desktop API server](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/api_server.py): `demo/api_server.py`
- [Mobile server](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/mobile_server.py): `demo/mobile_server.py`
- [Route directions](https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/demo): `demo`
- [Address search](https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/demo): `demo`

### Safety scoring

- **Route scoring**
- [NLP alerts](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_alerts.py): `src/Live_alerts.py`
- [Vision conditions](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_cameras.py): `src/Live_cameras.py`
- [Collision risk](https://github.com/afolabi-adesina-m/smart-shield-ai/tree/master/src): `src`

### Driving guidance

- **Speed limits**
- **Street exit rules**
- [Live weather](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/src/Live_weather.py): `src/Live_weather.py`
- [Fleet scoring](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/mobile/src/fleetLogic.ts): `mobile/src/fleetLogic.ts`
- [Test prep loops](https://github.com/afolabi-adesina-m/smart-shield-ai/blob/master/demo/road_preview.py): `demo/road_preview.py`

### External services

- **Routing service**
- **OpenStreetMap**
- **Overpass API**

### Other components

- **Driver**
- **Route and guidance**

## Connections

- Driver → Desktop map UI: chooses route
- Driver → Mobile app: chooses route
- Desktop map UI → Desktop API server: requests routes
- Mobile app → Mobile API client: requests data
- Mobile API client → Mobile server: calls API
- Desktop API server → Route directions: gets directions
- Desktop API server → Address search: geocodes places
- Route directions → Routing service: requests routes
- Address search → OpenStreetMap: looks up places
- Desktop API server → Route scoring: scores routes
- Route scoring → NLP alerts: uses alerts
- Route scoring → Vision conditions: uses conditions
- Route scoring → Collision risk: uses risk model
- Desktop API server → Speed limits: gets speed guidance
- Speed limits → Overpass API: looks up limits
- Desktop API server → Street exit rules: gets road context
- Mobile server → Route scoring: scores routes
- Mobile server → Speed limits: gets speed guidance
- Mobile server → Street exit rules: gets road context
- Mobile server → Live weather: gets weather
- Mobile server → Fleet scoring: scores fleet trips
- Desktop API server → Test prep loops: builds practice loop
- Desktop map UI → Offline map shell: loads app shell
- Desktop map UI → Route and guidance: presents results
- Mobile app → Route and guidance: presents results