# olliefms/ollie architecture

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

- Interactive diagram: https://gitdiagram.com/olliefms/ollie
- Repository: https://github.com/olliefms/ollie

## Overview

ollie is a self-hosted freight TMS: fleet staff manage loads, trips, equipment, and facilities through a Fleet SPA/API or MCP, while drivers execute assigned trips through a mobile portal. Uploaded documents form a separate AI-processing capability, and background workers handle geocoding, routing, and recovery. The graph includes core operational data, auth, events, and both web clients. Several subsystems are represented from README statements and the source index; unsampled internals are not treated as inspected.

Main entry points: [`src/pipeline/worker.rs`](https://github.com/olliefms/ollie/blob/main/src/pipeline/worker.rs) (Background workers), [`src/services/trip_lifecycle.rs`](https://github.com/olliefms/ollie/blob/main/src/services/trip_lifecycle.rs) (Trip lifecycle), [`src/api/fleet_portal`](https://github.com/olliefms/ollie/tree/main/src/api/fleet_portal) (Fleet REST API), [`src/api/trips.rs`](https://github.com/olliefms/ollie/blob/main/src/api/trips.rs) (Trip endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["API surfaces"]
  node_fleet_api["Fleet REST API"]
  node_mcp["Fleet MCP<br/>[mcp.rs]"]
  node_driver_api["Driver portal API"]
  node_oauth["OAuth endpoints"]
end

subgraph group_operations["Fleet operations"]
  node_trip_lifecycle["Trip lifecycle<br/>[trip_lifecycle.rs]"]
  node_trip_api["Trip endpoints<br/>[trips.rs]"]
  node_facility_api["Facility resolution<br/>[facilities.rs]"]
  node_operational_db[("Operational data store<br/>[mod.rs]")]
  node_trip_records["Trip records<br/>[trip_ops.rs]"]
  node_domain_models["Domain models<br/>[trip.rs]"]
  node_event_journal[("Event journal<br/>[mod.rs]")]
end

subgraph group_documents["Documents and AI"]
  node_blob_api["Document endpoints<br/>[blobs.rs]"]
  node_blob_files[("Content-addressed files<br/>[mod.rs]")]
  node_extract_cache[("Extracted-text cache<br/>[extract_store.rs]")]
  node_document_ai["Document AI<br/>[extract.rs]"]
end

subgraph group_platform["Background services"]
  node_workers["Background workers<br/>[worker.rs]"]
  node_geocoding["Facility geocoding<br/>[geocoding.rs]"]
  node_routing["HGV routing<br/>[mod.rs]"]
  node_doctors["Data integrity doctors"]
end

subgraph group_clients["Web clients"]
  node_fleet_spa["Fleet SPA<br/>[app.js]"]
  node_fleet_router["Fleet page router<br/>[router.js]"]
  node_fleet_api_client["Fleet API client<br/>[api.js]"]
  node_driver_pwa["Driver PWA<br/>[app.js]"]
  node_driver_trip_view["Trip detail view<br/>[trip-detail.js]"]
  node_driver_api_client["Driver API client<br/>[api.js]"]
end

node_fleet_staff(("Fleet staff / agents"))
node_drivers(("Drivers"))
node_ollama["Ollama"]
node_lancedb[("LanceDB vectors")]
node_geocoders["Geocoding services"]
node_ors["OpenRouteService"]

node_fleet_staff -->|"uses"| node_fleet_api
node_fleet_staff -->|"uses"| node_mcp
node_drivers -->|"uses"| node_driver_api
node_fleet_api -.->|"routes requests"| node_trip_api
node_trip_api -->|"calls"| node_trip_lifecycle
node_trip_lifecycle -->|"reads and writes"| node_trip_records
node_trip_lifecycle -->|"resolves stops"| node_facility_api
node_trip_records -.->|"persists"| node_operational_db
node_trip_api -->|"uses"| node_domain_models
node_trip_lifecycle -.->|"emits events"| node_event_journal
node_fleet_api -.->|"authenticates"| node_oauth
node_fleet_spa -->|"dispatches pages"| node_fleet_router
node_fleet_spa -->|"uses"| node_fleet_api_client
node_fleet_api_client -.->|"calls"| node_fleet_api
node_driver_pwa -->|"renders"| node_driver_trip_view
node_driver_trip_view -->|"uses"| node_driver_api_client
node_driver_api_client -.->|"calls"| node_driver_api
node_blob_api -->|"stores uploads"| node_blob_files
node_blob_files -->|"queues processing"| node_workers
node_workers -->|"processes documents"| node_document_ai
node_workers -.->|"caches extracted text"| node_extract_cache
node_document_ai -->|"requests summaries and embeddings"| node_ollama
node_document_ai -->|"stores vectors"| node_lancedb
node_workers -.->|"runs geocoding"| node_geocoding
node_geocoding -->|"queries"| node_geocoders
node_workers -.->|"runs routing"| node_routing
node_routing -->|"requests HGV routes"| node_ors
node_workers -.->|"runs repairs"| node_doctors

click node_fleet_api "https://github.com/olliefms/ollie/tree/main/src/api/fleet_portal"
click node_mcp "https://github.com/olliefms/ollie/blob/main/src/api/fleet_portal/mcp.rs"
click node_driver_api "https://github.com/olliefms/ollie/tree/main/src/api/driver_portal"
click node_oauth "https://github.com/olliefms/ollie/tree/main/src/api/oauth"
click node_fleet_spa "https://github.com/olliefms/ollie/blob/main/static/fleet/app.js"
click node_fleet_router "https://github.com/olliefms/ollie/blob/main/static/fleet/router.js"
click node_fleet_api_client "https://github.com/olliefms/ollie/blob/main/static/fleet/utils/api.js"
click node_driver_pwa "https://github.com/olliefms/ollie/blob/main/static/driver/app.js"
click node_driver_trip_view "https://github.com/olliefms/ollie/blob/main/static/driver/pages/trip-detail.js"
click node_driver_api_client "https://github.com/olliefms/ollie/blob/main/static/driver/utils/api.js"
click node_trip_lifecycle "https://github.com/olliefms/ollie/blob/main/src/services/trip_lifecycle.rs"
click node_trip_api "https://github.com/olliefms/ollie/blob/main/src/api/trips.rs"
click node_facility_api "https://github.com/olliefms/ollie/blob/main/src/api/facilities.rs"
click node_operational_db "https://github.com/olliefms/ollie/blob/main/src/db/mod.rs"
click node_trip_records "https://github.com/olliefms/ollie/blob/main/src/db/trip_ops.rs"
click node_domain_models "https://github.com/olliefms/ollie/blob/main/src/models/trip.rs"
click node_event_journal "https://github.com/olliefms/ollie/blob/main/src/events/mod.rs"
click node_blob_api "https://github.com/olliefms/ollie/blob/main/src/api/blobs.rs"
click node_blob_files "https://github.com/olliefms/ollie/blob/main/src/storage/mod.rs"
click node_extract_cache "https://github.com/olliefms/ollie/blob/main/src/storage/extract_store.rs"
click node_document_ai "https://github.com/olliefms/ollie/blob/main/src/ai/extract.rs"
click node_workers "https://github.com/olliefms/ollie/blob/main/src/pipeline/worker.rs"
click node_geocoding "https://github.com/olliefms/ollie/blob/main/src/pipeline/geocoding.rs"
click node_routing "https://github.com/olliefms/ollie/blob/main/src/routing/mod.rs"
click node_doctors "https://github.com/olliefms/ollie/tree/main/src/services/doctors"

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_fleet_api,node_mcp,node_driver_api,node_oauth toneBlue
class node_trip_lifecycle,node_trip_api,node_facility_api,node_operational_db,node_trip_records,node_domain_models,node_event_journal,node_lancedb toneAmber
class node_blob_api,node_blob_files,node_extract_cache,node_document_ai,node_ors toneMint
class node_workers,node_geocoding,node_routing,node_doctors toneRose
class node_fleet_spa,node_fleet_router,node_fleet_api_client,node_driver_pwa,node_driver_trip_view,node_driver_api_client,node_fleet_staff,node_drivers,node_ollama,node_geocoders toneIndigo
```

## Components

### API surfaces

- [Fleet REST API](https://github.com/olliefms/ollie/tree/main/src/api/fleet_portal): `src/api/fleet_portal`
- [Fleet MCP](https://github.com/olliefms/ollie/blob/main/src/api/fleet_portal/mcp.rs): `src/api/fleet_portal/mcp.rs`
- [Driver portal API](https://github.com/olliefms/ollie/tree/main/src/api/driver_portal): `src/api/driver_portal`
- [OAuth endpoints](https://github.com/olliefms/ollie/tree/main/src/api/oauth): `src/api/oauth`

### Fleet operations

- [Trip lifecycle](https://github.com/olliefms/ollie/blob/main/src/services/trip_lifecycle.rs): `src/services/trip_lifecycle.rs`
- [Trip endpoints](https://github.com/olliefms/ollie/blob/main/src/api/trips.rs): `src/api/trips.rs`
- [Facility resolution](https://github.com/olliefms/ollie/blob/main/src/api/facilities.rs): `src/api/facilities.rs`
- [Operational data store](https://github.com/olliefms/ollie/blob/main/src/db/mod.rs): `src/db/mod.rs`
- [Trip records](https://github.com/olliefms/ollie/blob/main/src/db/trip_ops.rs): `src/db/trip_ops.rs`
- [Domain models](https://github.com/olliefms/ollie/blob/main/src/models/trip.rs): `src/models/trip.rs`
- [Event journal](https://github.com/olliefms/ollie/blob/main/src/events/mod.rs): `src/events/mod.rs`

### Documents and AI

- [Document endpoints](https://github.com/olliefms/ollie/blob/main/src/api/blobs.rs): `src/api/blobs.rs`
- [Content-addressed files](https://github.com/olliefms/ollie/blob/main/src/storage/mod.rs): `src/storage/mod.rs`
- [Extracted-text cache](https://github.com/olliefms/ollie/blob/main/src/storage/extract_store.rs): `src/storage/extract_store.rs`
- [Document AI](https://github.com/olliefms/ollie/blob/main/src/ai/extract.rs): `src/ai/extract.rs`

### Background services

- [Background workers](https://github.com/olliefms/ollie/blob/main/src/pipeline/worker.rs): `src/pipeline/worker.rs`
- [Facility geocoding](https://github.com/olliefms/ollie/blob/main/src/pipeline/geocoding.rs): `src/pipeline/geocoding.rs`
- [HGV routing](https://github.com/olliefms/ollie/blob/main/src/routing/mod.rs): `src/routing/mod.rs`
- [Data integrity doctors](https://github.com/olliefms/ollie/tree/main/src/services/doctors): `src/services/doctors`

### Web clients

- [Fleet SPA](https://github.com/olliefms/ollie/blob/main/static/fleet/app.js): `static/fleet/app.js`
- [Fleet page router](https://github.com/olliefms/ollie/blob/main/static/fleet/router.js): `static/fleet/router.js`
- [Fleet API client](https://github.com/olliefms/ollie/blob/main/static/fleet/utils/api.js): `static/fleet/utils/api.js`
- [Driver PWA](https://github.com/olliefms/ollie/blob/main/static/driver/app.js): `static/driver/app.js`
- [Trip detail view](https://github.com/olliefms/ollie/blob/main/static/driver/pages/trip-detail.js): `static/driver/pages/trip-detail.js`
- [Driver API client](https://github.com/olliefms/ollie/blob/main/static/driver/utils/api.js): `static/driver/utils/api.js`

### Other components

- **Fleet staff / agents**
- **Drivers**
- **Ollama**
- **LanceDB vectors**
- **Geocoding services**
- **OpenRouteService**

## Connections

- Fleet staff / agents → Fleet REST API: uses (evidence: `README.md`)
- Fleet staff / agents → Fleet MCP: uses (evidence: `README.md`)
- Drivers → Driver portal API: uses (evidence: `README.md`)
- Fleet REST API → Trip endpoints: routes requests
- Trip endpoints → Trip lifecycle: calls (evidence: `src/api/trips.rs`)
- Trip lifecycle → Trip records: reads and writes (evidence: `src/services/trip_lifecycle.rs`)
- Trip lifecycle → Facility resolution: resolves stops (evidence: `src/services/trip_lifecycle.rs`)
- Trip records → Operational data store: persists (evidence: `src/db/mod.rs`)
- Trip endpoints → Domain models: uses (evidence: `src/api/trips.rs`)
- Trip lifecycle → Event journal: emits events (evidence: `src/services/trip_lifecycle.rs`)
- Fleet REST API → OAuth endpoints: authenticates (evidence: `src/api/oauth/authorize.rs`)
- Fleet SPA → Fleet page router: dispatches pages (evidence: `static/fleet/app.js`)
- Fleet SPA → Fleet API client: uses (evidence: `static/fleet/app.js`)
- Fleet API client → Fleet REST API: calls
- Driver PWA → Trip detail view: renders (evidence: `static/driver/app.js`)
- Trip detail view → Driver API client: uses (evidence: `static/driver/pages/trip-detail.js`)
- Driver API client → Driver portal API: calls
- Document endpoints → Content-addressed files: stores uploads (evidence: `README.md`)
- Content-addressed files → Background workers: queues processing (evidence: `README.md`)
- Background workers → Document AI: processes documents (evidence: `README.md`)
- Background workers → Extracted-text cache: caches extracted text
- Document AI → Ollama: requests summaries and embeddings (evidence: `README.md`)
- Document AI → LanceDB vectors: stores vectors (evidence: `README.md`)
- Background workers → Facility geocoding: runs geocoding
- Facility geocoding → Geocoding services: queries
- Background workers → HGV routing: runs routing
- HGV routing → OpenRouteService: requests HGV routes (evidence: `src/routing/mod.rs`)
- Background workers → Data integrity doctors: runs repairs
