# samwallflower/safewalk architecture

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

- Interactive diagram: https://gitdiagram.com/samwallflower/safewalk
- Repository: https://github.com/samwallflower/safewalk
- Video tour (about a minute): https://gitdiagram.com/samwallflower/safewalk/video

## Overview

SafeWalk is a Spring API for safety-aware route recommendations, localized incident reporting and heatmaps, and monitored walk sessions with emergency response. Its documented user journey is to request routes, start a walk, share location, and report or vote on incidents; route scoring uses nearby incident severity. Session monitoring can warn on anomalies or trigger emergency handling. The graph includes documented features whose implementation was not sampled, but only shows detailed service wiring where excerpts support it; controller-to-service links are therefore omitted.

Main entry points: [`backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/emergency/EmergencyService.java`](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/emergency/EmergencyService.java) (Emergency protocol), [`backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/anomaly/AnomalyDetectionService.java`](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/anomaly/AnomalyDetectionService.java) (Anomaly detection), [`backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/routing/RoutingService.java`](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/routing/RoutingService.java) (Route scoring), [`backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/notification/NotificationService.java`](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/notification/NotificationService.java) (Live notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_route_api["Routing API"]
  node_incident_api["Incident API"]
  node_vote_api["Voting API"]
  node_walk_api["Walk API"]
  node_emergency_api["Emergency API"]
end

subgraph group_navigation["Routes And Incidents"]
  node_routing["Route scoring"]
  node_incidents["Incident reports"]
  node_votes["Incident voting"]
  node_categories["Incident categories"]
end

subgraph group_sessions["Walk Safety"]
  node_walk_sessions["Walk sessions"]
  node_anomaly["Anomaly detection"]
  node_scheduler["Detection scheduler"]
  node_emergency["Emergency protocol"]
  node_notifications["Live notifications"]
  node_websocket["Walk WebSocket"]
end

subgraph group_persistence["Persistence"]
  node_route_store[("Route records")]
  node_incident_store[("Incident records")]
  node_vote_store[("Vote records")]
  node_session_store[("Session records")]
  node_emergency_store[("Emergency records")]
  node_contact_store[("Contact records")]
end

subgraph group_integrations["Integrations"]
  node_google_client["Maps client"]
  node_google_maps["Google Maps"]
  node_twilio_client["SMS client<br/>[TwilioClient.java]"]
  node_twilio["Twilio SMS"]
end

node_user(("SafeWalk user"))

node_user -->|"requests routes"| node_route_api
node_user -->|"reports incidents"| node_incident_api
node_user -->|"casts votes"| node_vote_api
node_user -->|"manages walks"| node_walk_api
node_user -->|"triggers SOS"| node_emergency_api
node_routing -->|"requests candidates"| node_google_client
node_google_client -->|"queries routes"| node_google_maps
node_routing -->|"reads nearby reports"| node_incident_store
node_routing -->|"saves ranked routes"| node_route_store
node_incidents -->|"reads and writes"| node_incident_store
node_incidents -->|"resolves category"| node_categories
node_votes -->|"updates report counts"| node_incident_store
node_votes -->|"reads and writes"| node_vote_store
node_scheduler -->|"runs detection"| node_anomaly
node_anomaly -->|"loads active sessions"| node_session_store
node_anomaly -->|"triggers anomalies"| node_emergency
node_anomaly -->|"pushes warnings"| node_notifications
node_anomaly -->|"checks connections"| node_websocket
node_walk_sessions -->|"reads and writes"| node_session_store
node_emergency -->|"updates session"| node_session_store
node_emergency -->|"loads contacts"| node_contact_store
node_emergency -->|"records emergency"| node_emergency_store
node_emergency -->|"sends alerts"| node_twilio_client
node_twilio_client -->|"sends SMS"| node_twilio
node_emergency -->|"pushes alert"| node_notifications
node_notifications -->|"publishes messages"| node_websocket

click node_route_api "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/RoutingController.java"
click node_incident_api "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentReportController.java"
click node_vote_api "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentVoteController.java"
click node_walk_api "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/WalkSessionController.java"
click node_emergency_api "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/EmergencyController.java"
click node_routing "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/routing/RoutingService.java"
click node_incidents "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentreport/IncidentReportService.java"
click node_votes "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentvote/IncidentVoteService.java"
click node_categories "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentcategory/IncidentCategoryService.java"
click node_walk_sessions "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/walksession/WalkSessionService.java"
click node_anomaly "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/anomaly/AnomalyDetectionService.java"
click node_scheduler "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/scheduler/AnomalyDetectionScheduler.java"
click node_emergency "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/emergency/EmergencyService.java"
click node_notifications "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/notification/NotificationService.java"
click node_websocket "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/websocket/controller/WalkSessionWebSocketController.java"
click node_google_client "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/googlemaps/GoogleMapsClient.java"
click node_twilio_client "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/twilio/TwilioClient.java"
click node_route_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/RouteRepository.java"
click node_incident_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentReportRepository.java"
click node_vote_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentVoteRepository.java"
click node_session_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/WalkSessionRepository.java"
click node_emergency_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyRepository.java"
click node_contact_store "https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyContactRepository.java"

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_route_api,node_incident_api,node_vote_api,node_walk_api,node_emergency_api,node_user toneBlue
class node_routing,node_incidents,node_votes,node_categories toneAmber
class node_walk_sessions,node_anomaly,node_scheduler,node_emergency,node_notifications,node_websocket toneMint
class node_route_store,node_incident_store,node_vote_store,node_session_store,node_emergency_store,node_contact_store toneRose
class node_google_client,node_google_maps,node_twilio_client,node_twilio toneIndigo
```

## Components

### API Surface

- [Routing API](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/RoutingController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/RoutingController.java`
- [Incident API](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentReportController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentReportController.java`
- [Voting API](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentVoteController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/IncidentVoteController.java`
- [Walk API](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/WalkSessionController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/WalkSessionController.java`
- [Emergency API](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/EmergencyController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/controller/EmergencyController.java`

### Routes And Incidents

- [Route scoring](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/routing/RoutingService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/routing/RoutingService.java`
- [Incident reports](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentreport/IncidentReportService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentreport/IncidentReportService.java`
- [Incident voting](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentvote/IncidentVoteService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentvote/IncidentVoteService.java`
- [Incident categories](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentcategory/IncidentCategoryService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/incidentcategory/IncidentCategoryService.java`

### Walk Safety

- [Walk sessions](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/walksession/WalkSessionService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/walksession/WalkSessionService.java`
- [Anomaly detection](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/anomaly/AnomalyDetectionService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/anomaly/AnomalyDetectionService.java`
- [Detection scheduler](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/scheduler/AnomalyDetectionScheduler.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/scheduler/AnomalyDetectionScheduler.java`
- [Emergency protocol](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/emergency/EmergencyService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/emergency/EmergencyService.java`
- [Live notifications](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/notification/NotificationService.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/service/notification/NotificationService.java`
- [Walk WebSocket](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/websocket/controller/WalkSessionWebSocketController.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/websocket/controller/WalkSessionWebSocketController.java`

### Persistence

- [Route records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/RouteRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/RouteRepository.java`
- [Incident records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentReportRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentReportRepository.java`
- [Vote records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentVoteRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/IncidentVoteRepository.java`
- [Session records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/WalkSessionRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/WalkSessionRepository.java`
- [Emergency records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyRepository.java`
- [Contact records](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyContactRepository.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/repository/EmergencyContactRepository.java`

### Integrations

- [Maps client](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/googlemaps/GoogleMapsClient.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/googlemaps/GoogleMapsClient.java`
- **Google Maps**
- [SMS client](https://github.com/samwallflower/safewalk/blob/main/backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/twilio/TwilioClient.java): `backend/SafeWalk/src/main/java/com/samwallflower/safewalk/integration/twilio/TwilioClient.java`
- **Twilio SMS**

### Other components

- **SafeWalk user**

## Connections

- SafeWalk user → Routing API: requests routes
- SafeWalk user → Incident API: reports incidents
- SafeWalk user → Voting API: casts votes
- SafeWalk user → Walk API: manages walks
- SafeWalk user → Emergency API: triggers SOS
- Route scoring → Maps client: requests candidates
- Maps client → Google Maps: queries routes
- Route scoring → Incident records: reads nearby reports
- Route scoring → Route records: saves ranked routes
- Incident reports → Incident records: reads and writes
- Incident reports → Incident categories: resolves category
- Incident voting → Incident records: updates report counts
- Incident voting → Vote records: reads and writes
- Detection scheduler → Anomaly detection: runs detection
- Anomaly detection → Session records: loads active sessions
- Anomaly detection → Emergency protocol: triggers anomalies
- Anomaly detection → Live notifications: pushes warnings
- Anomaly detection → Walk WebSocket: checks connections
- Walk sessions → Session records: reads and writes
- Emergency protocol → Session records: updates session
- Emergency protocol → Contact records: loads contacts
- Emergency protocol → Emergency records: records emergency
- Emergency protocol → SMS client: sends alerts
- SMS client → Twilio SMS: sends SMS
- Emergency protocol → Live notifications: pushes alert
- Live notifications → Walk WebSocket: publishes messages