# furrer-stefan/zobaroute architecture

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

- Interactive diagram: https://gitdiagram.com/furrer-stefan/zobaroute
- Repository: https://github.com/furrer-stefan/zobaroute

## Overview

ZoBaRoute turns an uploaded Excel order list into geocoded, team-balanced delivery routes and provides PDF/GPX exports. The main user workflow runs through a five-step React wizard, backed by an Express API and PostgreSQL. The README documents four optimization phases; those stages are shown as distinct domain components, though their individual implementation details were not sampled. Edges rely on the excerpts, SOURCE INDEX references, and README; unsampled internals are not inferred beyond documented capabilities.

Main entry points: [`frontend/src/App.jsx`](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/App.jsx) (Wizard shell), [`backend/src/controllers/routeController.js`](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/routeController.js) (Route and export API), [`frontend/src/services/routeApiService.js`](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/services/routeApiService.js) (Endpoint functions), [`backend/src/routes/index.js`](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/routes/index.js) (API routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Wizard interface"]
  node_app["Wizard shell<br/>[App.jsx]"]
  node_step1["Order import"]
  node_step2["Address review"]
  node_step3["Team setup"]
  node_step4["Route calculation"]
  node_step5["Route export"]
  node_wizard["Wizard state<br/>[useWizard.js]"]
  node_routeapi["Endpoint functions<br/>[routeApiService.js]"]
  node_http["HTTP client<br/>[api.js]"]
end

subgraph group_api["API orchestration"]
  node_server["Express server<br/>[app.js]"]
  node_router["API routing<br/>[index.js]"]
  node_importctl["Order and geocode API"]
  node_routectl["Route and export API<br/>[routeController.js]"]
  node_datactl["Session reset API<br/>[dataController.js]"]
  node_healthctl["Health check"]
end

subgraph group_domain["Route domain"]
  node_parser["Excel parsing"]
  node_validation["Order validation"]
  node_geocoding["Address geocoding"]
  node_geoadapter["Geocoding adapter"]
  node_geoq["Rate-limited queue"]
  node_mockgeo["Mock geocoder"]
  node_optimizer["Route optimizer"]
  node_clustering["Team clustering"]
  node_balancing["Cluster balancing"]
  node_sequencing["Stop sequencing"]
  node_routing["Distance matrix<br/>[routingAdapter.js]"]
  node_pdf["PDF exporter<br/>[pdfExporter.js]"]
  node_gpx["GPX exporter<br/>[gpxExporter.js]"]
end

subgraph group_storage["Persistence and services"]
  node_orders["Order repository<br/>[orderRepository.js]"]
  node_routes["Route repository<br/>[routeRepository.js]"]
  node_dbpool["PostgreSQL pool<br/>[connection.js]"]
  node_database[("Application database<br/>[schema.sql]")]
end

node_user(("Route planner"))
node_geoext{{"geo.admin.ch"}}

node_user -->|"uses"| node_app
node_app -->|"tracks steps"| node_wizard
node_app -->|"renders"| node_step1
node_app -->|"renders"| node_step2
node_app -->|"renders"| node_step3
node_app -->|"renders"| node_step4
node_app -->|"renders"| node_step5
node_step1 -->|"calls"| node_routeapi
node_step2 -->|"calls"| node_routeapi
node_step3 -->|"calls"| node_routeapi
node_step4 -->|"calls"| node_routeapi
node_step5 -->|"calls"| node_routeapi
node_routeapi -->|"uses"| node_http
node_routeapi -->|"requests"| node_router
node_server -->|"mounts"| node_router
node_router -->|"routes requests"| node_importctl
node_router -->|"routes requests"| node_routectl
node_router -->|"routes requests"| node_datactl
node_router -->|"routes requests"| node_healthctl
node_importctl -->|"parses upload"| node_parser
node_importctl -->|"validates orders"| node_validation
node_importctl -->|"reads and writes"| node_orders
node_importctl -->|"starts geocoding"| node_geocoding
node_geocoding -->|"uses"| node_geoadapter
node_geocoding -->|"queues requests"| node_geoq
node_geoadapter -->|"queries addresses"| node_geoext
node_routectl -->|"loads orders"| node_orders
node_routectl -->|"calculates routes"| node_optimizer
node_optimizer -->|"clusters stops"| node_clustering
node_optimizer -->|"balances teams"| node_balancing
node_optimizer -->|"optimizes order"| node_sequencing
node_optimizer -->|"requests distances"| node_routing
node_routectl -->|"saves and reads"| node_routes
node_routectl -->|"builds PDF"| node_pdf
node_routectl -->|"builds GPX"| node_gpx
node_routectl -->|"loads export route"| node_routes
node_datactl -->|"clears data"| node_orders
node_healthctl -->|"checks connection"| node_dbpool
node_orders -->|"queries"| node_dbpool
node_routes -->|"queries"| node_dbpool
node_dbpool -->|"connects"| node_database
node_geocoding -.->|"optional adapter"| node_mockgeo

click node_app "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/App.jsx"
click node_step1 "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step1ImportPage.jsx"
click node_step2 "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step2ValidationPage.jsx"
click node_step3 "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step3ConfigurationPage.jsx"
click node_step4 "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step4CalculationPage.jsx"
click node_step5 "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step5ExportPage.jsx"
click node_wizard "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/hooks/useWizard.js"
click node_routeapi "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/services/routeApiService.js"
click node_http "https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/app.js"
click node_router "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/routes/index.js"
click node_importctl "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/importController.js"
click node_routectl "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/routeController.js"
click node_datactl "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/dataController.js"
click node_healthctl "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/healthController.js"
click node_parser "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/excelParserService.js"
click node_validation "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/validationService.js"
click node_geocoding "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/geocodingService.js"
click node_geoadapter "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/geocodingAdapter.js"
click node_geoq "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/rateLimiterQueue.js"
click node_mockgeo "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/mockGeocodingAdapter.js"
click node_optimizer "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js"
click node_clustering "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js"
click node_balancing "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js"
click node_sequencing "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js"
click node_routing "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/routingAdapter.js"
click node_orders "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/repositories/orderRepository.js"
click node_routes "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/repositories/routeRepository.js"
click node_dbpool "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/db/connection.js"
click node_database "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/db/schema.sql"
click node_pdf "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/exporters/pdfExporter.js"
click node_gpx "https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/exporters/gpxExporter.js"

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_step1,node_step2,node_step3,node_step4,node_step5,node_wizard,node_routeapi,node_http toneBlue
class node_server,node_router,node_importctl,node_routectl,node_datactl,node_healthctl toneAmber
class node_parser,node_validation,node_geocoding,node_geoadapter,node_geoq,node_mockgeo,node_optimizer,node_clustering,node_balancing,node_sequencing,node_routing,node_pdf,node_gpx,node_user toneMint
class node_orders,node_routes,node_dbpool,node_database toneRose
class node_geoext toneIndigo
```

## Components

### Wizard interface

- [Wizard shell](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Order import](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step1ImportPage.jsx): `frontend/src/pages/Step1ImportPage.jsx`
- [Address review](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step2ValidationPage.jsx): `frontend/src/pages/Step2ValidationPage.jsx`
- [Team setup](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step3ConfigurationPage.jsx): `frontend/src/pages/Step3ConfigurationPage.jsx`
- [Route calculation](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step4CalculationPage.jsx): `frontend/src/pages/Step4CalculationPage.jsx`
- [Route export](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/pages/Step5ExportPage.jsx): `frontend/src/pages/Step5ExportPage.jsx`
- [Wizard state](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/hooks/useWizard.js): `frontend/src/hooks/useWizard.js`
- [Endpoint functions](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/services/routeApiService.js): `frontend/src/services/routeApiService.js`
- [HTTP client](https://github.com/furrer-stefan/zobaroute/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API orchestration

- [Express server](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/app.js): `backend/src/app.js`
- [API routing](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`
- [Order and geocode API](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/importController.js): `backend/src/controllers/importController.js`
- [Route and export API](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/routeController.js): `backend/src/controllers/routeController.js`
- [Session reset API](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/dataController.js): `backend/src/controllers/dataController.js`
- [Health check](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/controllers/healthController.js): `backend/src/controllers/healthController.js`

### Route domain

- [Excel parsing](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/excelParserService.js): `backend/src/services/excelParserService.js`
- [Order validation](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/validationService.js): `backend/src/services/validationService.js`
- [Address geocoding](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/geocodingService.js): `backend/src/services/geocodingService.js`
- [Geocoding adapter](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/geocodingAdapter.js): `backend/src/adapters/geocodingAdapter.js`
- [Rate-limited queue](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/rateLimiterQueue.js): `backend/src/adapters/rateLimiterQueue.js`
- [Mock geocoder](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/mockGeocodingAdapter.js): `backend/src/adapters/mockGeocodingAdapter.js`
- [Route optimizer](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js): `backend/src/services/routeOptimizerService.js`
- [Team clustering](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js): `backend/src/services/routeOptimizerService.js`
- [Cluster balancing](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js): `backend/src/services/routeOptimizerService.js`
- [Stop sequencing](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/services/routeOptimizerService.js): `backend/src/services/routeOptimizerService.js`
- [Distance matrix](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/adapters/routingAdapter.js): `backend/src/adapters/routingAdapter.js`
- [PDF exporter](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/exporters/pdfExporter.js): `backend/src/exporters/pdfExporter.js`
- [GPX exporter](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/exporters/gpxExporter.js): `backend/src/exporters/gpxExporter.js`

### Persistence and services

- [Order repository](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/repositories/orderRepository.js): `backend/src/repositories/orderRepository.js`
- [Route repository](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/repositories/routeRepository.js): `backend/src/repositories/routeRepository.js`
- [PostgreSQL pool](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/db/connection.js): `backend/src/db/connection.js`
- [Application database](https://github.com/furrer-stefan/zobaroute/blob/main/backend/src/db/schema.sql): `backend/src/db/schema.sql`

### Other components

- **Route planner**
- **geo.admin.ch**

## Connections

- Route planner → Wizard shell: uses (evidence: `README.md`)
- Wizard shell → Wizard state: tracks steps (evidence: `frontend/src/App.jsx`)
- Wizard shell → Order import: renders (evidence: `frontend/src/App.jsx`)
- Wizard shell → Address review: renders (evidence: `frontend/src/App.jsx`)
- Wizard shell → Team setup: renders (evidence: `frontend/src/App.jsx`)
- Wizard shell → Route calculation: renders (evidence: `frontend/src/App.jsx`)
- Wizard shell → Route export: renders (evidence: `frontend/src/App.jsx`)
- Order import → Endpoint functions: calls (evidence: `frontend/src/pages/Step1ImportPage.jsx`)
- Address review → Endpoint functions: calls (evidence: `frontend/src/pages/Step2ValidationPage.jsx`)
- Team setup → Endpoint functions: calls (evidence: `frontend/src/pages/Step3ConfigurationPage.jsx`)
- Route calculation → Endpoint functions: calls (evidence: `frontend/src/pages/Step4CalculationPage.jsx`)
- Route export → Endpoint functions: calls (evidence: `frontend/src/pages/Step5ExportPage.jsx`)
- Endpoint functions → HTTP client: uses (evidence: `frontend/src/services/routeApiService.js`)
- Endpoint functions → API routing: requests (evidence: `README.md`)
- Express server → API routing: mounts (evidence: `backend/src/app.js`)
- API routing → Order and geocode API: routes requests (evidence: `backend/src/routes/index.js`)
- API routing → Route and export API: routes requests (evidence: `backend/src/routes/index.js`)
- API routing → Session reset API: routes requests (evidence: `backend/src/routes/index.js`)
- API routing → Health check: routes requests (evidence: `backend/src/routes/index.js`)
- Order and geocode API → Excel parsing: parses upload (evidence: `backend/src/controllers/importController.js`)
- Order and geocode API → Order validation: validates orders (evidence: `backend/src/controllers/importController.js`)
- Order and geocode API → Order repository: reads and writes (evidence: `backend/src/controllers/importController.js`)
- Order and geocode API → Address geocoding: starts geocoding (evidence: `backend/src/controllers/importController.js`)
- Address geocoding → Geocoding adapter: uses (evidence: `backend/src/services/geocodingService.js`)
- Address geocoding → Rate-limited queue: queues requests (evidence: `backend/src/services/geocodingService.js`)
- Geocoding adapter → geo.admin.ch: queries addresses (evidence: `README.md`)
- Route and export API → Order repository: loads orders (evidence: `backend/src/controllers/routeController.js`)
- Route and export API → Route optimizer: calculates routes (evidence: `backend/src/controllers/routeController.js`)
- Route optimizer → Team clustering: clusters stops (evidence: `README.md`)
- Route optimizer → Cluster balancing: balances teams (evidence: `README.md`)
- Route optimizer → Stop sequencing: optimizes order (evidence: `README.md`)
- Route optimizer → Distance matrix: requests distances (evidence: `backend/src/services/routeOptimizerService.js`)
- Route and export API → Route repository: saves and reads (evidence: `backend/src/controllers/routeController.js`)
- Route and export API → PDF exporter: builds PDF (evidence: `backend/src/controllers/routeController.js`)
- Route and export API → GPX exporter: builds GPX (evidence: `backend/src/controllers/routeController.js`)
- Route and export API → Route repository: loads export route (evidence: `backend/src/controllers/routeController.js`)
- Session reset API → Order repository: clears data (evidence: `backend/src/controllers/dataController.js`)
- Health check → PostgreSQL pool: checks connection (evidence: `backend/src/controllers/healthController.js`)
- Order repository → PostgreSQL pool: queries (evidence: `backend/src/repositories/orderRepository.js`)
- Route repository → PostgreSQL pool: queries (evidence: `backend/src/repositories/routeRepository.js`)
- PostgreSQL pool → Application database: connects (evidence: `README.md`)
- Address geocoding → Mock geocoder: optional adapter
