# montassartayachi/smartroute architecture

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

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

## Overview

SmartRoute is a Flask logistics backend whose central workflow generates daily delivery missions: select eligible deliveries, cluster them geographically, assign drivers and vehicle capacity, order pickup/delivery stops, refine route estimates, and persist missions while updating delivery assignments. It also exposes delivery, authentication, tracking, route, and optimization-configuration APIs. The mission pipeline is documented in the README; source-index references support several module links, but unsampled implementations are not inferred beyond those references.

Main entry points: [`app/main.py`](https://github.com/montassartayachi/smartroute/blob/backend/app/main.py) (Flask application), [`app/services/mission_service.py`](https://github.com/montassartayachi/smartroute/blob/backend/app/services/mission_service.py) (Mission orchestration), [`app/routers/missions.py`](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/missions.py) (Mission routes), [`app/db/mongodb.py`](https://github.com/montassartayachi/smartroute/blob/backend/app/db/mongodb.py) (MongoDB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP and access"]
  node_app["Flask application<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_deliveries_api["Delivery routes<br/>[deliveries.py]"]
  node_missions_api["Mission routes<br/>[missions.py]"]
  node_admin_api["Optimization settings routes"]
  node_tracking_api["Tracking routes<br/>[tracking.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_access["Request access checks<br/>[dependencies.py]"]
  node_socket["Socket.IO service<br/>[socket_manager.py]"]
end

subgraph group_planning["Mission planning"]
  node_mission_service["Mission orchestration<br/>[mission_service.py]"]
  node_clustering["Geographic clustering"]
  node_driver_assignment["Driver assignment"]
  node_settings["Optimization settings"]
end

subgraph group_routing["Optimization"]
  node_capacity["Capacity allocation"]
  node_assignment_algorithms["Assignment strategies"]
  node_route_optimizer["Route ordering<br/>[route_optimizer.py]"]
  node_route_strategies["Route strategies"]
  node_nearest_neighbor["Nearest neighbor"]
  node_route_refiner["Route refinement<br/>[route_refiner.py]"]
  node_osm["OSRM routing"]
end

subgraph group_data["Domain and persistence"]
  node_delivery_service["Delivery management"]
  node_mission_model["Mission model<br/>[mission.py]"]
  node_delivery_schema["Delivery API schema<br/>[delivery.py]"]
  node_database[("MongoDB<br/>[mongodb.py]")]
  node_db_init["Database initialization<br/>[init_db.py]"]
end

node_operator(("Dispatcher"))
node_osrm_service["OSRM service"]

node_operator -->|"sends requests"| node_app
node_app -->|"connects to"| node_database
node_app -->|"initializes"| node_db_init
node_app -->|"registers"| node_missions_api
node_app -->|"registers"| node_deliveries_api
node_app -->|"registers"| node_auth
node_app -->|"registers"| node_admin_api
node_app -->|"registers"| node_tracking_api
node_app -->|"initializes"| node_socket
node_auth -->|"calls"| node_auth_service
node_missions_api -->|"calls"| node_mission_service
node_missions_api -->|"calls"| node_settings
node_missions_api -->|"calls"| node_clustering
node_missions_api -->|"calls"| node_driver_assignment
node_missions_api -->|"calls"| node_capacity
node_deliveries_api -->|"calls"| node_delivery_service
node_deliveries_api -->|"validates with"| node_delivery_schema
node_tracking_api -->|"uses"| node_socket
node_admin_api -->|"calls"| node_settings
node_mission_service -->|"clusters deliveries"| node_clustering
node_mission_service -->|"assigns drivers"| node_driver_assignment
node_mission_service -->|"allocates capacity"| node_capacity
node_capacity -->|"executes strategy"| node_assignment_algorithms
node_clustering -->|"reads settings"| node_settings
node_clustering -->|"stores region geometry"| node_database
node_mission_service -->|"orders route"| node_route_optimizer
node_route_optimizer -->|"uses strategy"| node_route_strategies
node_route_strategies -->|"falls back to"| node_nearest_neighbor
node_route_strategies -->|"refines with"| node_route_refiner
node_mission_service -->|"requests road route"| node_osm
node_osm -.->|"calls"| node_osrm_service
node_mission_service -->|"builds mission"| node_mission_model
node_mission_service -->|"persists missions"| node_database
node_mission_service -->|"marks deliveries assigned"| node_database
node_delivery_service -->|"reads and updates"| node_database
node_settings -->|"resolves strategy"| node_assignment_algorithms
node_settings -->|"stores settings"| node_database
node_app -.->|"uses request guards"| node_access

click node_app "https://github.com/montassartayachi/smartroute/blob/backend/app/main.py"
click node_auth "https://github.com/montassartayachi/smartroute/blob/backend/app/routers/auth.py"
click node_deliveries_api "https://github.com/montassartayachi/smartroute/blob/backend/app/routers/deliveries.py"
click node_missions_api "https://github.com/montassartayachi/smartroute/blob/backend/app/routers/missions.py"
click node_admin_api "https://github.com/montassartayachi/smartroute/blob/backend/app/routers/admin_optimization.py"
click node_tracking_api "https://github.com/montassartayachi/smartroute/blob/backend/app/routers/tracking.py"
click node_auth_service "https://github.com/montassartayachi/smartroute/blob/backend/app/services/auth_service.py"
click node_access "https://github.com/montassartayachi/smartroute/blob/backend/app/dependencies.py"
click node_delivery_service "https://github.com/montassartayachi/smartroute/blob/backend/app/services/delivery_service.py"
click node_mission_service "https://github.com/montassartayachi/smartroute/blob/backend/app/services/mission_service.py"
click node_clustering "https://github.com/montassartayachi/smartroute/blob/backend/app/services/clustering_service.py"
click node_driver_assignment "https://github.com/montassartayachi/smartroute/blob/backend/app/services/driver_assignment_service.py"
click node_capacity "https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/capacity_optimizer.py"
click node_assignment_algorithms "https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/assignment_algorithms.py"
click node_route_optimizer "https://github.com/montassartayachi/smartroute/blob/backend/app/services/route_optimizer.py"
click node_route_strategies "https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/route_strategies.py"
click node_nearest_neighbor "https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/nearest_neighbor.py"
click node_route_refiner "https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/route_refiner.py"
click node_osm "https://github.com/montassartayachi/smartroute/blob/backend/app/services/osm_routing_service.py"
click node_settings "https://github.com/montassartayachi/smartroute/blob/backend/app/services/optimization_settings_service.py"
click node_mission_model "https://github.com/montassartayachi/smartroute/blob/backend/app/models/mission.py"
click node_delivery_schema "https://github.com/montassartayachi/smartroute/blob/backend/app/schemas/delivery.py"
click node_database "https://github.com/montassartayachi/smartroute/blob/backend/app/db/mongodb.py"
click node_db_init "https://github.com/montassartayachi/smartroute/blob/backend/app/db/init_db.py"
click node_socket "https://github.com/montassartayachi/smartroute/blob/backend/app/socket_manager.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_app,node_auth,node_deliveries_api,node_missions_api,node_admin_api,node_tracking_api,node_auth_service,node_access,node_socket toneBlue
class node_mission_service,node_clustering,node_driver_assignment,node_settings toneAmber
class node_capacity,node_assignment_algorithms,node_route_optimizer,node_route_strategies,node_nearest_neighbor,node_route_refiner,node_osm toneMint
class node_delivery_service,node_mission_model,node_delivery_schema,node_database,node_db_init toneRose
class node_operator,node_osrm_service toneIndigo
```

## Components

### HTTP and access

- [Flask application](https://github.com/montassartayachi/smartroute/blob/backend/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/auth.py): `app/routers/auth.py`
- [Delivery routes](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/deliveries.py): `app/routers/deliveries.py`
- [Mission routes](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/missions.py): `app/routers/missions.py`
- [Optimization settings routes](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/admin_optimization.py): `app/routers/admin_optimization.py`
- [Tracking routes](https://github.com/montassartayachi/smartroute/blob/backend/app/routers/tracking.py): `app/routers/tracking.py`
- [Authentication service](https://github.com/montassartayachi/smartroute/blob/backend/app/services/auth_service.py): `app/services/auth_service.py`
- [Request access checks](https://github.com/montassartayachi/smartroute/blob/backend/app/dependencies.py): `app/dependencies.py`
- [Socket.IO service](https://github.com/montassartayachi/smartroute/blob/backend/app/socket_manager.py): `app/socket_manager.py`

### Mission planning

- [Mission orchestration](https://github.com/montassartayachi/smartroute/blob/backend/app/services/mission_service.py): `app/services/mission_service.py`
- [Geographic clustering](https://github.com/montassartayachi/smartroute/blob/backend/app/services/clustering_service.py): `app/services/clustering_service.py`
- [Driver assignment](https://github.com/montassartayachi/smartroute/blob/backend/app/services/driver_assignment_service.py): `app/services/driver_assignment_service.py`
- [Optimization settings](https://github.com/montassartayachi/smartroute/blob/backend/app/services/optimization_settings_service.py): `app/services/optimization_settings_service.py`

### Optimization

- [Capacity allocation](https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/capacity_optimizer.py): `app/algorithms/capacity_optimizer.py`
- [Assignment strategies](https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/assignment_algorithms.py): `app/algorithms/assignment_algorithms.py`
- [Route ordering](https://github.com/montassartayachi/smartroute/blob/backend/app/services/route_optimizer.py): `app/services/route_optimizer.py`
- [Route strategies](https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/route_strategies.py): `app/algorithms/route_strategies.py`
- [Nearest neighbor](https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/nearest_neighbor.py): `app/algorithms/nearest_neighbor.py`
- [Route refinement](https://github.com/montassartayachi/smartroute/blob/backend/app/algorithms/route_refiner.py): `app/algorithms/route_refiner.py`
- [OSRM routing](https://github.com/montassartayachi/smartroute/blob/backend/app/services/osm_routing_service.py): `app/services/osm_routing_service.py`

### Domain and persistence

- [Delivery management](https://github.com/montassartayachi/smartroute/blob/backend/app/services/delivery_service.py): `app/services/delivery_service.py`
- [Mission model](https://github.com/montassartayachi/smartroute/blob/backend/app/models/mission.py): `app/models/mission.py`
- [Delivery API schema](https://github.com/montassartayachi/smartroute/blob/backend/app/schemas/delivery.py): `app/schemas/delivery.py`
- [MongoDB](https://github.com/montassartayachi/smartroute/blob/backend/app/db/mongodb.py): `app/db/mongodb.py`
- [Database initialization](https://github.com/montassartayachi/smartroute/blob/backend/app/db/init_db.py): `app/db/init_db.py`

### Other components

- **Dispatcher**
- **OSRM service**

## Connections

- Dispatcher → Flask application: sends requests (evidence: `app/main.py`)
- Flask application → MongoDB: connects to (evidence: `app/main.py`)
- Flask application → Database initialization: initializes (evidence: `app/main.py`)
- Flask application → Mission routes: registers (evidence: `app/main.py`)
- Flask application → Delivery routes: registers (evidence: `app/main.py`)
- Flask application → Authentication routes: registers (evidence: `app/main.py`)
- Flask application → Optimization settings routes: registers (evidence: `app/main.py`)
- Flask application → Tracking routes: registers (evidence: `app/main.py`)
- Flask application → Socket.IO service: initializes (evidence: `app/main.py`)
- Authentication routes → Authentication service: calls (evidence: `app/routers/auth.py`)
- Mission routes → Mission orchestration: calls (evidence: `app/routers/missions.py`)
- Mission routes → Optimization settings: calls (evidence: `app/routers/missions.py`)
- Mission routes → Geographic clustering: calls (evidence: `app/routers/missions.py`)
- Mission routes → Driver assignment: calls (evidence: `app/routers/missions.py`)
- Mission routes → Capacity allocation: calls (evidence: `app/routers/missions.py`)
- Delivery routes → Delivery management: calls (evidence: `app/routers/deliveries.py`)
- Delivery routes → Delivery API schema: validates with (evidence: `app/routers/deliveries.py`)
- Tracking routes → Socket.IO service: uses (evidence: `app/routers/tracking.py`)
- Optimization settings routes → Optimization settings: calls (evidence: `app/routers/admin_optimization.py`)
- Mission orchestration → Geographic clustering: clusters deliveries (evidence: `app/services/mission_service.py`)
- Mission orchestration → Driver assignment: assigns drivers (evidence: `app/services/mission_service.py`)
- Mission orchestration → Capacity allocation: allocates capacity (evidence: `app/services/mission_service.py`)
- Capacity allocation → Assignment strategies: executes strategy (evidence: `app/algorithms/capacity_optimizer.py`)
- Geographic clustering → Optimization settings: reads settings (evidence: `app/services/clustering_service.py`)
- Geographic clustering → MongoDB: stores region geometry
- Mission orchestration → Route ordering: orders route (evidence: `app/services/mission_service.py`)
- Route ordering → Route strategies: uses strategy (evidence: `app/services/mission_service.py`)
- Route strategies → Nearest neighbor: falls back to (evidence: `app/algorithms/route_strategies.py`)
- Route strategies → Route refinement: refines with (evidence: `app/algorithms/route_strategies.py`)
- Mission orchestration → OSRM routing: requests road route (evidence: `app/services/mission_service.py`)
- OSRM routing → OSRM service: calls
- Mission orchestration → Mission model: builds mission (evidence: `app/services/mission_service.py`)
- Mission orchestration → MongoDB: persists missions (evidence: `app/services/mission_service.py`)
- Mission orchestration → MongoDB: marks deliveries assigned (evidence: `app/services/mission_service.py`)
- Delivery management → MongoDB: reads and updates (evidence: `app/services/delivery_service.py`)
- Optimization settings → Assignment strategies: resolves strategy (evidence: `app/services/optimization_settings_service.py`)
- Optimization settings → MongoDB: stores settings (evidence: `app/services/optimization_settings_service.py`)
- Flask application → Request access checks: uses request guards
