# abhimanyukapoor/saferoute architecture

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

- Interactive diagram: https://gitdiagram.com/abhimanyukapoor/saferoute
- Repository: https://github.com/abhimanyukapoor/saferoute

## Overview

SafeRoute is a mobile-first route-safety analyzer. Its documented user journey is authenticated origin/destination submission, route retrieval and segmentation, per-segment visual and geographic analysis, safety scoring with explanations, and a response for map display. README documents Flutter client behavior, while the provided mobile tree contains only platform runners—not the Dart application—and source excerpts do not show most Go call wiring. I therefore show documented relationships with README evidence and omit unsupported implementation-level edges; ML internals are represented at the service boundary.

Main entry points: [`backend/internal/handlers/analyze.go`](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/handlers/analyze.go) (Analysis handler), [`mobile/saferoute`](https://github.com/abhimanyukapoor/saferoute/tree/master/mobile/saferoute) (Flutter app), [`backend/internal/routes/routes.go`](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/routes/routes.go) (Route registration), [`backend/cmd/api/main.go`](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/cmd/api/main.go) (API startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_app["Flutter app"]
end

subgraph group_backend["Analysis backend"]
  node_api["API startup<br/>[main.go]"]
  node_server["HTTP server<br/>[server.go]"]
  node_routes["Route registration<br/>[routes.go]"]
  node_auth["Token verification<br/>[middleware.go]"]
  node_handler["Analysis handler<br/>[analyze.go]"]
  node_dto["Analysis DTO<br/>[analyze.go]"]
  node_geometry["Polyline segmentation"]
  node_directions["Route directions<br/>[directions.go]"]
  node_streetview["Street View images<br/>[streetview.go]"]
end

subgraph group_signals["Safety signals"]
  node_activity_fetch["Nearby activity data<br/>[activity.go]"]
  node_road_fetch["Road metadata<br/>[roads.go]"]
  node_activity["Activity scoring<br/>[activity.go]"]
  node_roadscore["Road scoring<br/>[roads.go]"]
  node_timescore["Time risk<br/>[time.go]"]
  node_scoring["Safety aggregation<br/>[scoring.go]"]
  node_explain["Safety explanations<br/>[explain.go]"]
end

subgraph group_ml["Visual inference"]
  node_mlclient["ML client<br/>[client.go]"]
  node_mlservice["Visual inference<br/>[main.py]"]
end

node_user(("Traveler"))
node_maps["Google Maps APIs"]
node_firebase["Firebase Auth"]

node_user -->|"sets locations"| node_app
node_app -->|"requests analysis"| node_api
node_app -->|"authenticates with"| node_firebase
node_app -->|"sends ID token"| node_api
node_api -.->|"starts"| node_server
node_server -.->|"registers routes"| node_routes
node_routes -->|"protects endpoint"| node_auth
node_routes -.->|"dispatches analysis"| node_handler
node_auth -->|"verifies token"| node_firebase
node_handler -.->|"returns response"| node_dto
node_handler -->|"fetches routes"| node_directions
node_directions -->|"queries directions"| node_maps
node_handler -->|"segments geometry"| node_geometry
node_handler -->|"requests images"| node_streetview
node_streetview -->|"queries Street View"| node_maps
node_handler -->|"requests activity"| node_activity_fetch
node_activity_fetch -->|"queries Places"| node_maps
node_handler -->|"requests road context"| node_road_fetch
node_road_fetch -->|"queries road data"| node_maps
node_handler -->|"submits images"| node_mlclient
node_mlclient -->|"sends inference request"| node_mlservice
node_mlservice -->|"returns visual scores"| node_mlclient
node_handler -.->|"scores activity"| node_activity
node_handler -.->|"scores road context"| node_roadscore
node_handler -->|"adjusts for time"| node_timescore
node_handler -->|"aggregates safety"| node_scoring
node_handler -->|"builds explanations"| node_explain
node_handler -->|"returns route insights"| node_app
node_app -->|"renders map results"| node_user

click node_app "https://github.com/abhimanyukapoor/saferoute/tree/master/mobile/saferoute"
click node_api "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/cmd/api/main.go"
click node_server "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/server/server.go"
click node_routes "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/routes/routes.go"
click node_auth "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/auth/middleware.go"
click node_handler "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/handlers/analyze.go"
click node_dto "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/dto/analyze.go"
click node_geometry "https://github.com/abhimanyukapoor/saferoute/tree/master/backend/internal/utils"
click node_directions "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/directions.go"
click node_streetview "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/streetview.go"
click node_activity_fetch "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/activity.go"
click node_road_fetch "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/roads.go"
click node_mlclient "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/ml/client.go"
click node_mlservice "https://github.com/abhimanyukapoor/saferoute/blob/master/ml/main.py"
click node_activity "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/activity.go"
click node_roadscore "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/roads.go"
click node_timescore "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/time.go"
click node_scoring "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/scoring.go"
click node_explain "https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/explain.go"

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 toneBlue
class node_api,node_server,node_routes,node_auth,node_handler,node_dto,node_geometry,node_directions,node_streetview toneAmber
class node_activity_fetch,node_road_fetch,node_activity,node_roadscore,node_timescore,node_scoring,node_explain,node_maps toneMint
class node_mlclient,node_mlservice toneRose
class node_user,node_firebase toneIndigo
```

## Components

### Mobile client

- [Flutter app](https://github.com/abhimanyukapoor/saferoute/tree/master/mobile/saferoute): `mobile/saferoute`

### Analysis backend

- [API startup](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/cmd/api/main.go): `backend/cmd/api/main.go`
- [HTTP server](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/server/server.go): `backend/internal/server/server.go`
- [Route registration](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/routes/routes.go): `backend/internal/routes/routes.go`
- [Token verification](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/auth/middleware.go): `backend/internal/auth/middleware.go`
- [Analysis handler](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/handlers/analyze.go): `backend/internal/handlers/analyze.go`
- [Analysis DTO](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/dto/analyze.go): `backend/internal/dto/analyze.go`
- [Polyline segmentation](https://github.com/abhimanyukapoor/saferoute/tree/master/backend/internal/utils): `backend/internal/utils`
- [Route directions](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/directions.go): `backend/internal/maps/directions.go`
- [Street View images](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/streetview.go): `backend/internal/maps/streetview.go`

### Safety signals

- [Nearby activity data](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/activity.go): `backend/internal/maps/activity.go`
- [Road metadata](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/maps/roads.go): `backend/internal/maps/roads.go`
- [Activity scoring](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/activity.go): `backend/internal/safety/activity.go`
- [Road scoring](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/roads.go): `backend/internal/safety/roads.go`
- [Time risk](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/time.go): `backend/internal/safety/time.go`
- [Safety aggregation](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/scoring.go): `backend/internal/safety/scoring.go`
- [Safety explanations](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/safety/explain.go): `backend/internal/safety/explain.go`

### Visual inference

- [ML client](https://github.com/abhimanyukapoor/saferoute/blob/master/backend/internal/ml/client.go): `backend/internal/ml/client.go`
- [Visual inference](https://github.com/abhimanyukapoor/saferoute/blob/master/ml/main.py): `ml/main.py`

### Other components

- **Traveler**
- **Google Maps APIs**
- **Firebase Auth**

## Connections

- Traveler → Flutter app: sets locations
- Flutter app → API startup: requests analysis
- Flutter app → Firebase Auth: authenticates with
- Flutter app → API startup: sends ID token
- API startup → HTTP server: starts
- HTTP server → Route registration: registers routes
- Route registration → Token verification: protects endpoint
- Route registration → Analysis handler: dispatches analysis
- Token verification → Firebase Auth: verifies token
- Analysis handler → Analysis DTO: returns response
- Analysis handler → Route directions: fetches routes
- Route directions → Google Maps APIs: queries directions
- Analysis handler → Polyline segmentation: segments geometry
- Analysis handler → Street View images: requests images
- Street View images → Google Maps APIs: queries Street View
- Analysis handler → Nearby activity data: requests activity
- Nearby activity data → Google Maps APIs: queries Places
- Analysis handler → Road metadata: requests road context
- Road metadata → Google Maps APIs: queries road data
- Analysis handler → ML client: submits images
- ML client → Visual inference: sends inference request
- Visual inference → ML client: returns visual scores
- Analysis handler → Activity scoring: scores activity
- Analysis handler → Road scoring: scores road context
- Analysis handler → Time risk: adjusts for time
- Analysis handler → Safety aggregation: aggregates safety
- Analysis handler → Safety explanations: builds explanations
- Analysis handler → Flutter app: returns route insights
- Flutter app → Traveler: renders map results
