# el-hadj10/transas architecture

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

- Interactive diagram: https://gitdiagram.com/el-hadj10/transas
- Repository: https://github.com/el-hadj10/transas
- Video tour (about a minute): https://gitdiagram.com/el-hadj10/transas/video

## Overview

TransAs is an offline-first Android delivery-route planner. A driver imports or enters parcels, then requests optimization: the UI controller geocodes addresses, obtains road distances (falling back to Haversine), runs the local hierarchical optimizer, and persists the resulting tour. The screens present stops and map context and support delivery status, voice entry, and current-location re-optimization. Edges reflect the provided excerpts, SOURCE INDEX references, and README; some UI service wiring is known only through those references, not full source inspection.

Main entry points: [`ui/screens/safe_screen.py`](https://github.com/el-hadj10/transas/blob/main/ui/screens/safe_screen.py) (Route planner UI), [`ui/controllers/optimize_controller.py`](https://github.com/el-hadj10/transas/blob/main/ui/controllers/optimize_controller.py) (Optimization controller), [`database/db_manager.py`](https://github.com/el-hadj10/transas/blob/main/database/db_manager.py) (SQLite manager), [`ui/screens/main_screen.py`](https://github.com/el-hadj10/transas/blob/main/ui/screens/main_screen.py) (Parcel list)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and screens"]
  node_app_entry["App bootstrap<br/>[main.py]"]
  node_safe_ui["Route planner UI<br/>[safe_screen.py]"]
  node_main_ui["Parcel list<br/>[main_screen.py]"]
  node_import_ui["Import screen<br/>[import_screen.py]"]
  node_map_ui["Map screen<br/>[map_screen.py]"]
  node_parcel_card["Parcel card<br/>[parcel_card.py]"]
  node_route_overview["Route overview<br/>[route_overview.py]"]
end

subgraph group_planning["Route planning"]
  node_controller["Optimization controller"]
  node_geocoder["Address geocoder<br/>[geocoder.py]"]
  node_router["Distance matrix<br/>[router.py]"]
  node_optimizer["Tour optimizer<br/>[optimizer.py]"]
  node_nominatim{{"Nominatim"}}
  node_osrm{{"OSRM"}}
end

subgraph group_data["Local data"]
  node_db_manager["SQLite manager<br/>[db_manager.py]"]
  node_sqlite[("Local database")]
end

subgraph group_field["Field services"]
  node_batch_import["Batch import<br/>[batch_import.py]"]
  node_location["Device location<br/>[location.py]"]
  node_speech["Voice input<br/>[speech.py]"]
  node_tile_map["OSM tile map<br/>[tile_map.py]"]
  node_navigation["Navigation launch<br/>[navigation.py]"]
  node_uri_utils["URI utilities<br/>[uri_utils.py]"]
  node_folium["Map renderer<br/>[folium_renderer.py]"]
end

node_driver(("Driver"))

node_driver -->|"opens app"| node_app_entry
node_app_entry -->|"creates screen"| node_safe_ui
node_app_entry -->|"creates controller"| node_controller
node_app_entry -->|"creates database"| node_db_manager
node_driver -->|"uses planner"| node_safe_ui
node_safe_ui -->|"requests optimization"| node_controller
node_controller -->|"loads and saves tours"| node_db_manager
node_controller -->|"geocodes stops"| node_geocoder
node_controller -->|"requests distances"| node_router
node_controller -->|"optimizes order"| node_optimizer
node_geocoder -->|"queries addresses"| node_nominatim
node_router -->|"requests road matrix"| node_osrm
node_optimizer -.->|"uses distance matrix"| node_router
node_router -.->|"returns distances"| node_optimizer
node_db_manager -->|"reads and writes"| node_sqlite
node_import_ui -->|"stores parcels"| node_db_manager
node_main_ui -->|"loads parcel list"| node_db_manager
node_main_ui -->|"renders stops"| node_parcel_card
node_main_ui -->|"renders route"| node_route_overview
node_main_ui -->|"starts optimization"| node_controller
node_map_ui -->|"loads tour"| node_db_manager
node_map_ui -->|"renders map"| node_folium
node_safe_ui -->|"imports parcels"| node_batch_import
node_safe_ui -->|"gets current position"| node_location
node_safe_ui -->|"accepts dictation"| node_speech
node_safe_ui -->|"renders basemap"| node_tile_map
node_safe_ui -->|"launches navigation"| node_navigation
node_navigation -->|"builds map URI"| node_uri_utils
node_main_ui -->|"builds map URI"| node_uri_utils
node_tile_map -.->|"uses OSM tiles"| node_osrm

click node_app_entry "https://github.com/el-hadj10/transas/blob/main/main.py"
click node_safe_ui "https://github.com/el-hadj10/transas/blob/main/ui/screens/safe_screen.py"
click node_main_ui "https://github.com/el-hadj10/transas/blob/main/ui/screens/main_screen.py"
click node_import_ui "https://github.com/el-hadj10/transas/blob/main/ui/screens/import_screen.py"
click node_map_ui "https://github.com/el-hadj10/transas/blob/main/ui/screens/map_screen.py"
click node_parcel_card "https://github.com/el-hadj10/transas/blob/main/ui/components/parcel_card.py"
click node_route_overview "https://github.com/el-hadj10/transas/blob/main/ui/components/route_overview.py"
click node_controller "https://github.com/el-hadj10/transas/blob/main/ui/controllers/optimize_controller.py"
click node_geocoder "https://github.com/el-hadj10/transas/blob/main/core/geocoder.py"
click node_router "https://github.com/el-hadj10/transas/blob/main/core/router.py"
click node_optimizer "https://github.com/el-hadj10/transas/blob/main/core/optimizer.py"
click node_db_manager "https://github.com/el-hadj10/transas/blob/main/database/db_manager.py"
click node_batch_import "https://github.com/el-hadj10/transas/blob/main/ui/services/batch_import.py"
click node_location "https://github.com/el-hadj10/transas/blob/main/ui/services/location.py"
click node_speech "https://github.com/el-hadj10/transas/blob/main/ui/services/speech.py"
click node_tile_map "https://github.com/el-hadj10/transas/blob/main/ui/services/tile_map.py"
click node_navigation "https://github.com/el-hadj10/transas/blob/main/ui/services/navigation.py"
click node_uri_utils "https://github.com/el-hadj10/transas/blob/main/ui/services/uri_utils.py"
click node_folium "https://github.com/el-hadj10/transas/blob/main/ui/services/folium_renderer.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_entry,node_safe_ui,node_main_ui,node_import_ui,node_map_ui,node_parcel_card,node_route_overview toneBlue
class node_controller,node_geocoder,node_router,node_optimizer,node_nominatim,node_osrm toneAmber
class node_db_manager,node_sqlite toneMint
class node_batch_import,node_location,node_speech,node_tile_map,node_navigation,node_uri_utils,node_folium toneRose
class node_driver toneIndigo
```

## Components

### App and screens

- [App bootstrap](https://github.com/el-hadj10/transas/blob/main/main.py): `main.py`
- [Route planner UI](https://github.com/el-hadj10/transas/blob/main/ui/screens/safe_screen.py): `ui/screens/safe_screen.py`
- [Parcel list](https://github.com/el-hadj10/transas/blob/main/ui/screens/main_screen.py): `ui/screens/main_screen.py`
- [Import screen](https://github.com/el-hadj10/transas/blob/main/ui/screens/import_screen.py): `ui/screens/import_screen.py`
- [Map screen](https://github.com/el-hadj10/transas/blob/main/ui/screens/map_screen.py): `ui/screens/map_screen.py`
- [Parcel card](https://github.com/el-hadj10/transas/blob/main/ui/components/parcel_card.py): `ui/components/parcel_card.py`
- [Route overview](https://github.com/el-hadj10/transas/blob/main/ui/components/route_overview.py): `ui/components/route_overview.py`

### Route planning

- [Optimization controller](https://github.com/el-hadj10/transas/blob/main/ui/controllers/optimize_controller.py): `ui/controllers/optimize_controller.py`
- [Address geocoder](https://github.com/el-hadj10/transas/blob/main/core/geocoder.py): `core/geocoder.py`
- [Distance matrix](https://github.com/el-hadj10/transas/blob/main/core/router.py): `core/router.py`
- [Tour optimizer](https://github.com/el-hadj10/transas/blob/main/core/optimizer.py): `core/optimizer.py`
- **Nominatim**
- **OSRM**

### Local data

- [SQLite manager](https://github.com/el-hadj10/transas/blob/main/database/db_manager.py): `database/db_manager.py`
- **Local database**

### Field services

- [Batch import](https://github.com/el-hadj10/transas/blob/main/ui/services/batch_import.py): `ui/services/batch_import.py`
- [Device location](https://github.com/el-hadj10/transas/blob/main/ui/services/location.py): `ui/services/location.py`
- [Voice input](https://github.com/el-hadj10/transas/blob/main/ui/services/speech.py): `ui/services/speech.py`
- [OSM tile map](https://github.com/el-hadj10/transas/blob/main/ui/services/tile_map.py): `ui/services/tile_map.py`
- [Navigation launch](https://github.com/el-hadj10/transas/blob/main/ui/services/navigation.py): `ui/services/navigation.py`
- [URI utilities](https://github.com/el-hadj10/transas/blob/main/ui/services/uri_utils.py): `ui/services/uri_utils.py`
- [Map renderer](https://github.com/el-hadj10/transas/blob/main/ui/services/folium_renderer.py): `ui/services/folium_renderer.py`

### Other components

- **Driver**

## Connections

- Driver → App bootstrap: opens app (evidence: `README.md`)
- App bootstrap → Route planner UI: creates screen (evidence: `main.py`)
- App bootstrap → Optimization controller: creates controller (evidence: `main.py`)
- App bootstrap → SQLite manager: creates database (evidence: `main.py`)
- Driver → Route planner UI: uses planner (evidence: `README.md`)
- Route planner UI → Optimization controller: requests optimization (evidence: `ui/screens/safe_screen.py`)
- Optimization controller → SQLite manager: loads and saves tours (evidence: `ui/controllers/optimize_controller.py`)
- Optimization controller → Address geocoder: geocodes stops (evidence: `ui/controllers/optimize_controller.py`)
- Optimization controller → Distance matrix: requests distances (evidence: `ui/controllers/optimize_controller.py`)
- Optimization controller → Tour optimizer: optimizes order (evidence: `ui/controllers/optimize_controller.py`)
- Address geocoder → Nominatim: queries addresses (evidence: `README.md`)
- Distance matrix → OSRM: requests road matrix (evidence: `core/router.py`)
- Tour optimizer → Distance matrix: uses distance matrix
- Distance matrix → Tour optimizer: returns distances
- SQLite manager → Local database: reads and writes (evidence: `database/db_manager.py`)
- Import screen → SQLite manager: stores parcels (evidence: `ui/screens/import_screen.py`)
- Parcel list → SQLite manager: loads parcel list (evidence: `ui/screens/main_screen.py`)
- Parcel list → Parcel card: renders stops (evidence: `ui/screens/main_screen.py`)
- Parcel list → Route overview: renders route (evidence: `ui/screens/main_screen.py`)
- Parcel list → Optimization controller: starts optimization (evidence: `ui/screens/main_screen.py`)
- Map screen → SQLite manager: loads tour (evidence: `ui/screens/map_screen.py`)
- Map screen → Map renderer: renders map (evidence: `ui/screens/map_screen.py`)
- Route planner UI → Batch import: imports parcels (evidence: `ui/screens/safe_screen.py`)
- Route planner UI → Device location: gets current position (evidence: `ui/screens/safe_screen.py`)
- Route planner UI → Voice input: accepts dictation (evidence: `ui/screens/safe_screen.py`)
- Route planner UI → OSM tile map: renders basemap (evidence: `ui/screens/safe_screen.py`)
- Route planner UI → Navigation launch: launches navigation (evidence: `ui/screens/safe_screen.py`)
- Navigation launch → URI utilities: builds map URI (evidence: `ui/services/navigation.py`)
- Parcel list → URI utilities: builds map URI (evidence: `ui/screens/main_screen.py`)
- OSM tile map → OSRM: uses OSM tiles
