# asquare-developer/droppie-laravel-api architecture

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

- Interactive diagram: https://gitdiagram.com/asquare-developer/droppie-laravel-api
- Repository: https://github.com/asquare-developer/droppie-laravel-api

## Overview

Droppie Track is a Laravel route-tracking application. The main workflow is a driver submitting a route with validated Google Place IDs; route management resolves reusable addresses and queues distance calculation, which calls Google Routes and updates route status. Users can browse/filter routes and generate mileage reports. The README also documents web/API authentication, Google OAuth, autocomplete, optional address verification, profile management, and recovery of stuck jobs. Source excerpts confirm route creation, queue dispatch, and Google distance lookup; other branches are included from documented capabilities, with uncertain wiring left unconnected.

Main entry points: [`app/Services/AddressLookupService.php`](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/AddressLookupService.php) (Address lookup), [`app/Services/RouteService.php`](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/RouteService.php) (Route service), [`app/Models/Route.php`](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/Route.php) (Routes), [`app/Jobs/CalculateRouteDistance.php`](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Jobs/CalculateRouteDistance.php) (Distance job)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_route["Route Tracking"]
  node_route_api["Route API"]
  node_route_web["Route workspace"]
  node_route_service["Route service<br/>[RouteService.php]"]
  node_route_store[("Routes<br/>[Route.php]")]
  node_distance_job["Distance job"]
  node_route_status["Distance status<br/>[DistanceStatus.php]"]
  node_route_google["Google Routes"]
  node_dashboard["Route dashboard"]
end

subgraph group_address["Address Services"]
  node_address_api["Address API"]
  node_address_web["Address workspace"]
  node_address_lookup["Address lookup"]
  node_google_address["Google Places"]
  node_address_store[("Address catalog<br/>[Address.php]")]
  node_usage_store[("User address history<br/>[AddressUsage.php]")]
end

subgraph group_identity["Identity and Profile"]
  node_auth_api["API authentication<br/>[AuthController.php]"]
  node_auth_web["Web authentication<br/>[AuthController.php]"]
  node_google_oauth["Google sign-in"]
  node_user_store[("User accounts<br/>[User.php]")]
  node_profile_web["Profile management"]
  node_profile_service["Profile service"]
  node_profile_store[("Profiles and vehicles<br/>[UserProfile.php]")]
end

subgraph group_reports["Mileage Reports"]
  node_reports_web["Report workspace"]
  node_report_service["Mileage report service"]
  node_report_store[("Trip reports<br/>[TripReport.php]")]
  node_report_pdf["PDF generation<br/>[TripReportPdf.php]"]
  node_report_template["Report document"]
end

subgraph group_operations["Queue Operations"]
  node_recovery["Stuck-route recovery"]
  node_scheduler["Laravel scheduler<br/>[console.php]"]
end

node_driver(("Driver"))
node_google_routes{{"Google Routes API"}}
node_google_places{{"Google Places API"}}

node_driver -->|"submits route"| node_route_api
node_driver -.->|"manages routes"| node_route_web
node_route_api -->|"creates or updates"| node_route_service
node_route_web -->|"manages routes"| node_route_service
node_route_service -->|"resolves places"| node_address_lookup
node_route_service -->|"saves route"| node_route_store
node_route_service -->|"dispatches calculation"| node_distance_job
node_distance_job -->|"requests distance"| node_route_google
node_route_google -->|"computes distance"| node_google_routes
node_distance_job -->|"updates status"| node_route_store
node_route_store -->|"casts status"| node_route_status
node_address_api -.->|"looks up addresses"| node_address_lookup
node_address_web -.->|"looks up addresses"| node_address_lookup
node_address_lookup -->|"queries Places"| node_google_address
node_google_address -->|"validates places"| node_google_places
node_address_lookup -->|"resolves records"| node_address_store
node_address_lookup -.->|"tracks user history"| node_usage_store
node_google_address -->|"normalizes address"| node_address_store
node_driver -->|"signs in"| node_auth_api
node_driver -->|"signs in"| node_auth_web
node_auth_api -->|"authenticates users"| node_user_store
node_auth_web -.->|"uses OAuth"| node_google_oauth
node_google_oauth -.->|"links account"| node_user_store
node_profile_web -.->|"updates profile"| node_profile_service
node_profile_service -.->|"persists profile"| node_profile_store
node_driver -.->|"manages profile"| node_profile_web
node_driver -.->|"requests report"| node_reports_web
node_reports_web -->|"generates report"| node_report_service
node_report_service -->|"stores report"| node_report_store
node_reports_web -->|"renders PDF"| node_report_pdf
node_report_pdf -.->|"uses template"| node_report_template
node_driver -.->|"views routes"| node_dashboard
node_scheduler -.->|"runs periodically"| node_recovery
node_recovery -->|"marks stale routes"| node_route_store

click node_route_api "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/RouteController.php"
click node_route_web "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/RouteController.php"
click node_route_service "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/RouteService.php"
click node_route_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/Route.php"
click node_distance_job "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Jobs/CalculateRouteDistance.php"
click node_route_status "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Enums/DistanceStatus.php"
click node_route_google "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/GoogleRouteService.php"
click node_address_api "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/AddressController.php"
click node_address_web "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/AddressController.php"
click node_address_lookup "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/AddressLookupService.php"
click node_google_address "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/GoogleAddressService.php"
click node_address_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/Address.php"
click node_usage_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/AddressUsage.php"
click node_auth_api "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_auth_web "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/AuthController.php"
click node_google_oauth "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/SocialLoginService.php"
click node_user_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/User.php"
click node_profile_web "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/ProfileController.php"
click node_profile_service "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/UserProfileService.php"
click node_profile_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/UserProfile.php"
click node_reports_web "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/RouteReportController.php"
click node_report_service "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/RouteReportService.php"
click node_report_store "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/TripReport.php"
click node_report_pdf "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/TripReportPdf.php"
click node_report_template "https://github.com/asquare-developer/droppie-laravel-api/blob/main/resources/views/pdf/routes-report.blade.php"
click node_dashboard "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/DashboardController.php"
click node_recovery "https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Console/Commands/RecoverStuckRoutes.php"
click node_scheduler "https://github.com/asquare-developer/droppie-laravel-api/blob/main/routes/console.php"

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_route_web,node_route_service,node_route_store,node_distance_job,node_route_status,node_route_google,node_dashboard toneBlue
class node_address_api,node_address_web,node_address_lookup,node_google_address,node_address_store,node_usage_store toneAmber
class node_auth_api,node_auth_web,node_google_oauth,node_user_store,node_profile_web,node_profile_service,node_profile_store,node_google_routes,node_google_places toneMint
class node_reports_web,node_report_service,node_report_store,node_report_pdf,node_report_template toneRose
class node_recovery,node_scheduler,node_driver toneIndigo
```

## Components

### Route Tracking

- [Route API](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/RouteController.php): `app/Http/Controllers/Api/RouteController.php`
- [Route workspace](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/RouteController.php): `app/Http/Controllers/Web/RouteController.php`
- [Route service](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/RouteService.php): `app/Services/RouteService.php`
- [Routes](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/Route.php): `app/Models/Route.php`
- [Distance job](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Jobs/CalculateRouteDistance.php): `app/Jobs/CalculateRouteDistance.php`
- [Distance status](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Enums/DistanceStatus.php): `app/Enums/DistanceStatus.php`
- [Google Routes](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/GoogleRouteService.php): `app/Services/GoogleRouteService.php`
- [Route dashboard](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/DashboardController.php): `app/Http/Controllers/Web/DashboardController.php`

### Address Services

- [Address API](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/AddressController.php): `app/Http/Controllers/Api/AddressController.php`
- [Address workspace](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/AddressController.php): `app/Http/Controllers/Web/AddressController.php`
- [Address lookup](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/AddressLookupService.php): `app/Services/AddressLookupService.php`
- [Google Places](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/GoogleAddressService.php): `app/Services/GoogleAddressService.php`
- [Address catalog](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/Address.php): `app/Models/Address.php`
- [User address history](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/AddressUsage.php): `app/Models/AddressUsage.php`

### Identity and Profile

- [API authentication](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [Web authentication](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/AuthController.php): `app/Http/Controllers/Web/AuthController.php`
- [Google sign-in](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/SocialLoginService.php): `app/Services/SocialLoginService.php`
- [User accounts](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/User.php): `app/Models/User.php`
- [Profile management](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/ProfileController.php): `app/Http/Controllers/Web/ProfileController.php`
- [Profile service](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/UserProfileService.php): `app/Services/UserProfileService.php`
- [Profiles and vehicles](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/UserProfile.php): `app/Models/UserProfile.php`

### Mileage Reports

- [Report workspace](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Http/Controllers/Web/RouteReportController.php): `app/Http/Controllers/Web/RouteReportController.php`
- [Mileage report service](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/RouteReportService.php): `app/Services/RouteReportService.php`
- [Trip reports](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Models/TripReport.php): `app/Models/TripReport.php`
- [PDF generation](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Services/TripReportPdf.php): `app/Services/TripReportPdf.php`
- [Report document](https://github.com/asquare-developer/droppie-laravel-api/blob/main/resources/views/pdf/routes-report.blade.php): `resources/views/pdf/routes-report.blade.php`

### Queue Operations

- [Stuck-route recovery](https://github.com/asquare-developer/droppie-laravel-api/blob/main/app/Console/Commands/RecoverStuckRoutes.php): `app/Console/Commands/RecoverStuckRoutes.php`
- [Laravel scheduler](https://github.com/asquare-developer/droppie-laravel-api/blob/main/routes/console.php): `routes/console.php`

### Other components

- **Driver**
- **Google Routes API**
- **Google Places API**

## Connections

- Driver → Route API: submits route
- Driver → Route workspace: manages routes
- Route API → Route service: creates or updates (evidence: `app/Http/Controllers/Api/RouteController.php`)
- Route workspace → Route service: manages routes (evidence: `app/Http/Controllers/Web/RouteController.php`)
- Route service → Address lookup: resolves places (evidence: `app/Services/RouteService.php`)
- Route service → Routes: saves route (evidence: `app/Services/RouteService.php`)
- Route service → Distance job: dispatches calculation (evidence: `app/Services/RouteService.php`)
- Distance job → Google Routes: requests distance (evidence: `app/Jobs/CalculateRouteDistance.php`)
- Google Routes → Google Routes API: computes distance (evidence: `app/Services/GoogleRouteService.php`)
- Distance job → Routes: updates status (evidence: `app/Jobs/CalculateRouteDistance.php`)
- Routes → Distance status: casts status (evidence: `app/Models/Route.php`)
- Address API → Address lookup: looks up addresses
- Address workspace → Address lookup: looks up addresses
- Address lookup → Google Places: queries Places (evidence: `app/Services/AddressLookupService.php`)
- Google Places → Google Places API: validates places (evidence: `app/Services/GoogleAddressService.php`)
- Address lookup → Address catalog: resolves records (evidence: `app/Services/AddressLookupService.php`)
- Address lookup → User address history: tracks user history
- Google Places → Address catalog: normalizes address (evidence: `app/Services/GoogleAddressService.php`)
- Driver → API authentication: signs in
- Driver → Web authentication: signs in
- API authentication → User accounts: authenticates users (evidence: `app/Http/Controllers/Api/AuthController.php`)
- Web authentication → Google sign-in: uses OAuth
- Google sign-in → User accounts: links account
- Profile management → Profile service: updates profile
- Profile service → Profiles and vehicles: persists profile
- Driver → Profile management: manages profile
- Driver → Report workspace: requests report
- Report workspace → Mileage report service: generates report (evidence: `app/Http/Controllers/Web/RouteReportController.php`)
- Mileage report service → Trip reports: stores report (evidence: `app/Services/RouteReportService.php`)
- Report workspace → PDF generation: renders PDF (evidence: `app/Http/Controllers/Web/RouteReportController.php`)
- PDF generation → Report document: uses template
- Driver → Route dashboard: views routes
- Laravel scheduler → Stuck-route recovery: runs periodically
- Stuck-route recovery → Routes: marks stale routes (evidence: `app/Console/Commands/RecoverStuckRoutes.php`)