# andrea-salvatore/matera_tour architecture

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

- Interactive diagram: https://gitdiagram.com/andrea-salvatore/matera_tour
- Repository: https://github.com/andrea-salvatore/matera_tour

## Overview

Matera Tour is a Flutter mobile audio guide whose main workflow is to show mapped Matera points of interest, monitor the visitor’s proximity, prompt them to hear a monument’s history, and read descriptions aloud. The README also documents custom map tracking, far-away navigation handoff, background audio introductions, and a welcome notification. The graph uses those documented relationships; Dart implementation excerpts were not provided, so finer call ownership and the wiring of auth/admin features cannot be verified.

Main entry points: [`lib/features/monument_details/presentation/widgets/navigation_offer_sheet.dart`](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/widgets/navigation_offer_sheet.dart) (Navigation Offer), [`lib/shared/widgets/proximity_dialog.dart`](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/shared/widgets/proximity_dialog.dart) (Proximity Prompt), [`lib/features/map/presentation/screens/map_screen.dart`](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/screens/map_screen.dart) (Map Screen), [`lib/features/map/presentation/widgets/map_view.dart`](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/map_view.dart) (Custom Map View)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_map["Map and Monuments"]
  node_map_screen["Map Screen<br/>[map_screen.dart]"]
  node_map_view["Custom Map View<br/>[map_view.dart]"]
  node_monument_markers["Monument Markers"]
  node_preview_sheet["Monument Preview"]
  node_monuments_provider["Monuments Provider"]
  node_monument_repository["Monument Repository"]
  node_monument_data["Monument Data"]
end

subgraph group_proximity["Location and Proximity"]
  node_location_service["Location Service"]
  node_geofencing_service["Geofencing Service"]
  node_geofencing_provider["Geofencing Provider"]
  node_location_provider["Location Provider"]
  node_proximity_prompt["Proximity Prompt"]
end

subgraph group_guide["Audio Guide"]
  node_details_screen["Monument Details"]
  node_tts_provider["TTS Provider<br/>[tts_provider.dart]"]
  node_tts_service["Text to Speech<br/>[tts_service.dart]"]
  node_audio_provider["Audio Player Provider"]
  node_audio_bar["Audio Player"]
end

subgraph group_navigation["Navigation Handoff"]
  node_map_launcher["Map App Launcher"]
  node_navigation_offer["Navigation Offer"]
  node_local_maps(("Native Map App"))
  node_notifications["Welcome Notification"]
end

subgraph group_app["App and Access"]
  node_app_router["App Router<br/>[app_router.dart]"]
  node_auth_provider["Auth Provider<br/>[auth_provider.dart]"]
  node_auth_repository["Mock Auth Repository"]
  node_admin_insert["Admin Monument Entry"]
  node_admin_picker["Admin Map Picker"]
end

node_visitor(("Visitor"))

node_visitor -->|"explores map"| node_map_screen
node_map_screen -->|"displays map"| node_map_view
node_map_view -->|"shows markers"| node_monument_markers
node_visitor -->|"shares GPS location"| node_location_service
node_location_service -->|"provides coordinates"| node_geofencing_service
node_geofencing_service -->|"triggers nearby prompt"| node_proximity_prompt
node_visitor -->|"approaches point"| node_proximity_prompt
node_proximity_prompt -->|"invites listening"| node_details_screen
node_details_screen -->|"requests narration"| node_tts_provider
node_tts_provider -->|"speaks description"| node_tts_service
node_visitor -->|"requests directions"| node_navigation_offer
node_navigation_offer -->|"hands off route"| node_map_launcher
node_map_launcher -->|"opens directions"| node_local_maps
node_navigation_offer -->|"starts introduction"| node_audio_provider
node_audio_provider -.->|"provides playback"| node_audio_bar
node_navigation_offer -->|"schedules welcome"| node_notifications

click node_map_screen "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/screens/map_screen.dart"
click node_map_view "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/map_view.dart"
click node_monument_markers "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/monument_marker_widget.dart"
click node_preview_sheet "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/monument_preview_sheet.dart"
click node_monuments_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/providers/monuments_provider.dart"
click node_monument_repository "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/data/repositories/mock_monument_repository.dart"
click node_monument_data "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/data/mock_monuments.dart"
click node_location_service "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/data/location_service.dart"
click node_geofencing_service "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/data/geofencing_service.dart"
click node_geofencing_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/presentation/providers/geofencing_provider.dart"
click node_location_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/presentation/providers/location_provider.dart"
click node_proximity_prompt "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/shared/widgets/proximity_dialog.dart"
click node_details_screen "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/screens/monument_details_screen.dart"
click node_tts_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/providers/tts_provider.dart"
click node_tts_service "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/tts_service.dart"
click node_audio_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/providers/audio_player_provider.dart"
click node_audio_bar "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/widgets/audio_player_bar.dart"
click node_map_launcher "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/map_launcher_service.dart"
click node_navigation_offer "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/widgets/navigation_offer_sheet.dart"
click node_notifications "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/notification_service.dart"
click node_app_router "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/router/app_router.dart"
click node_auth_provider "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/auth/presentation/providers/auth_provider.dart"
click node_auth_repository "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/auth/data/mock_auth_repository.dart"
click node_admin_insert "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/admin/presentation/admin_insert_screen.dart"
click node_admin_picker "https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/admin/presentation/admin_map_picker_screen.dart"

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_screen,node_map_view,node_monument_markers,node_preview_sheet,node_monuments_provider,node_monument_repository,node_monument_data toneBlue
class node_location_service,node_geofencing_service,node_geofencing_provider,node_location_provider,node_proximity_prompt toneAmber
class node_details_screen,node_tts_provider,node_tts_service,node_audio_provider,node_audio_bar toneMint
class node_map_launcher,node_navigation_offer,node_local_maps,node_notifications toneRose
class node_app_router,node_auth_provider,node_auth_repository,node_admin_insert,node_admin_picker,node_visitor toneIndigo
```

## Components

### Map and Monuments

- [Map Screen](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/screens/map_screen.dart): `lib/features/map/presentation/screens/map_screen.dart`
- [Custom Map View](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/map_view.dart): `lib/features/map/presentation/widgets/map_view.dart`
- [Monument Markers](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/monument_marker_widget.dart): `lib/features/map/presentation/widgets/monument_marker_widget.dart`
- [Monument Preview](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/widgets/monument_preview_sheet.dart): `lib/features/map/presentation/widgets/monument_preview_sheet.dart`
- [Monuments Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/presentation/providers/monuments_provider.dart): `lib/features/map/presentation/providers/monuments_provider.dart`
- [Monument Repository](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/data/repositories/mock_monument_repository.dart): `lib/features/map/data/repositories/mock_monument_repository.dart`
- [Monument Data](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/map/data/mock_monuments.dart): `lib/features/map/data/mock_monuments.dart`

### Location and Proximity

- [Location Service](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/data/location_service.dart): `lib/features/geofencing/data/location_service.dart`
- [Geofencing Service](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/data/geofencing_service.dart): `lib/features/geofencing/data/geofencing_service.dart`
- [Geofencing Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/presentation/providers/geofencing_provider.dart): `lib/features/geofencing/presentation/providers/geofencing_provider.dart`
- [Location Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/geofencing/presentation/providers/location_provider.dart): `lib/features/geofencing/presentation/providers/location_provider.dart`
- [Proximity Prompt](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/shared/widgets/proximity_dialog.dart): `lib/shared/widgets/proximity_dialog.dart`

### Audio Guide

- [Monument Details](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/screens/monument_details_screen.dart): `lib/features/monument_details/presentation/screens/monument_details_screen.dart`
- [TTS Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/providers/tts_provider.dart): `lib/features/monument_details/presentation/providers/tts_provider.dart`
- [Text to Speech](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/tts_service.dart): `lib/core/services/tts_service.dart`
- [Audio Player Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/providers/audio_player_provider.dart): `lib/features/monument_details/presentation/providers/audio_player_provider.dart`
- [Audio Player](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/widgets/audio_player_bar.dart): `lib/features/monument_details/presentation/widgets/audio_player_bar.dart`

### Navigation Handoff

- [Map App Launcher](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/map_launcher_service.dart): `lib/core/services/map_launcher_service.dart`
- [Navigation Offer](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/monument_details/presentation/widgets/navigation_offer_sheet.dart): `lib/features/monument_details/presentation/widgets/navigation_offer_sheet.dart`
- **Native Map App**
- [Welcome Notification](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/services/notification_service.dart): `lib/core/services/notification_service.dart`

### App and Access

- [App Router](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/core/router/app_router.dart): `lib/core/router/app_router.dart`
- [Auth Provider](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/auth/presentation/providers/auth_provider.dart): `lib/features/auth/presentation/providers/auth_provider.dart`
- [Mock Auth Repository](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/auth/data/mock_auth_repository.dart): `lib/features/auth/data/mock_auth_repository.dart`
- [Admin Monument Entry](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/admin/presentation/admin_insert_screen.dart): `lib/features/admin/presentation/admin_insert_screen.dart`
- [Admin Map Picker](https://github.com/andrea-salvatore/matera_tour/blob/main/lib/features/admin/presentation/admin_map_picker_screen.dart): `lib/features/admin/presentation/admin_map_picker_screen.dart`

### Other components

- **Visitor**

## Connections

- Visitor → Map Screen: explores map (evidence: `README.md`)
- Map Screen → Custom Map View: displays map (evidence: `README.md`)
- Custom Map View → Monument Markers: shows markers (evidence: `README.md`)
- Visitor → Location Service: shares GPS location (evidence: `README.md`)
- Location Service → Geofencing Service: provides coordinates (evidence: `README.md`)
- Geofencing Service → Proximity Prompt: triggers nearby prompt (evidence: `README.md`)
- Visitor → Proximity Prompt: approaches point (evidence: `README.md`)
- Proximity Prompt → Monument Details: invites listening (evidence: `README.md`)
- Monument Details → TTS Provider: requests narration (evidence: `README.md`)
- TTS Provider → Text to Speech: speaks description (evidence: `README.md`)
- Visitor → Navigation Offer: requests directions (evidence: `README.md`)
- Navigation Offer → Map App Launcher: hands off route (evidence: `README.md`)
- Map App Launcher → Native Map App: opens directions (evidence: `README.md`)
- Navigation Offer → Audio Player Provider: starts introduction (evidence: `README.md`)
- Audio Player Provider → Audio Player: provides playback
- Navigation Offer → Welcome Notification: schedules welcome (evidence: `README.md`)
