# gokulkrisnaa-n/courier-dispatch-prediction-and-optimization architecture

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

- Interactive diagram: https://gitdiagram.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization
- Repository: https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization

## Overview

Courier Dispatch predicts courier-to-order pickup times, then minimizes total pickup time with one-to-one assignment. Its main workflow is event replay or live event consumption, snapshot construction, batch scoring through the API, and assignment; a separate offline pipeline cleans LaDe data, builds shared features, trains the model, and creates a monitoring baseline. Monitoring capabilities include operational metrics, prediction performance, and feature drift. Paths and wiring follow the README and provided source index; unsampled subsystem details are represented only where documented.

Main entry points: [`src/dispatch/stream/dispatcher.py`](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/dispatcher.py) (Stream dispatcher), [`src/dispatch/api/main.py`](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/api/main.py) (Scoring API), [`src/dispatch/data.py`](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/data.py) (Clean pickup data), [`src/dispatch/train.py`](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline modeling"]
  node_data["Clean pickup data<br/>[data.py]"]
  node_features["Shared features<br/>[features.py]"]
  node_training["Model training<br/>[train.py]"]
  node_config["Shared configuration<br/>[config.py]"]
end

subgraph group_serving["Scoring service"]
  node_model["Prediction model<br/>[model.py]"]
  node_schemas["API contracts<br/>[schemas.py]"]
  node_api["Scoring API<br/>[main.py]"]
end

subgraph group_dispatch["Live dispatch"]
  node_dispatcher["Stream dispatcher<br/>[dispatcher.py]"]
  node_snapshot["Dispatch snapshot<br/>[snapshot.py]"]
  node_assignment["Assignment optimizer<br/>[assignment.py]"]
end

subgraph group_integration["Event transport"]
  node_producer["Event replay producer<br/>[producer.py]"]
  node_bus["Event bus<br/>[bus.py]"]
end

subgraph group_observability["Monitoring"]
  node_reference["Monitoring baseline<br/>[monitoring.py]"]
  node_dashboard["Monitoring dashboard<br/>[dashboard.py]"]
end

node_dataset[("LaDe pickup data")]
node_api_client(("Scoring clients"))
node_broker["Redpanda broker"]

node_dataset -->|"loads and cleans"| node_data
node_data -->|"builds inputs"| node_features
node_features -->|"transforms data"| node_training
node_data -->|"supplies cleaned rows"| node_training
node_training -->|"saves artifact"| node_model
node_training -->|"creates baseline"| node_reference
node_model -->|"builds serving features"| node_features
node_api_client -->|"requests scores"| node_api
node_api -->|"uses contracts"| node_schemas
node_api -->|"predicts pairs"| node_model
node_api -->|"builds snapshot"| node_snapshot
node_api -->|"scores pairs"| node_assignment
node_producer -->|"loads historic data"| node_data
node_producer -->|"publishes events"| node_bus
node_bus -.->|"transports events"| node_broker
node_dispatcher -->|"consumes events"| node_bus
node_dispatcher -->|"maintains state"| node_snapshot
node_dispatcher -->|"requests scoring"| node_api
node_dispatcher -->|"assigns orders"| node_assignment
node_dispatcher -->|"records performance"| node_reference
node_dashboard -->|"shows drift metrics"| node_reference
node_dashboard -->|"shows operations"| node_dispatcher
node_dashboard -->|"shows model status"| node_model
node_data -->|"reads settings"| node_config
node_features -->|"reads feature settings"| node_config
node_training -->|"loads settings"| node_config
node_dispatcher -->|"loads settings"| node_config
node_bus -->|"selects transport"| node_config

click node_data "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/data.py"
click node_features "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/features.py"
click node_training "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/train.py"
click node_model "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/model.py"
click node_config "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/config.py"
click node_schemas "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/api/schemas.py"
click node_api "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/api/main.py"
click node_producer "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/producer.py"
click node_bus "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/bus.py"
click node_dispatcher "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/dispatcher.py"
click node_snapshot "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/snapshot.py"
click node_assignment "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/assignment.py"
click node_reference "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/monitoring.py"
click node_dashboard "https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/dashboard.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_data,node_features,node_training,node_config,node_api_client toneBlue
class node_model,node_schemas,node_api,node_dataset toneAmber
class node_dispatcher,node_snapshot,node_assignment toneMint
class node_producer,node_bus toneRose
class node_reference,node_dashboard,node_broker toneIndigo
```

## Components

### Offline modeling

- [Clean pickup data](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/data.py): `src/dispatch/data.py`
- [Shared features](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/features.py): `src/dispatch/features.py`
- [Model training](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/train.py): `src/dispatch/train.py`
- [Shared configuration](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/config.py): `src/dispatch/config.py`

### Scoring service

- [Prediction model](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/model.py): `src/dispatch/model.py`
- [API contracts](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/api/schemas.py): `src/dispatch/api/schemas.py`
- [Scoring API](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/api/main.py): `src/dispatch/api/main.py`

### Live dispatch

- [Stream dispatcher](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/dispatcher.py): `src/dispatch/stream/dispatcher.py`
- [Dispatch snapshot](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/snapshot.py): `src/dispatch/snapshot.py`
- [Assignment optimizer](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/assignment.py): `src/dispatch/assignment.py`

### Event transport

- [Event replay producer](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/producer.py): `src/dispatch/stream/producer.py`
- [Event bus](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/stream/bus.py): `src/dispatch/stream/bus.py`

### Monitoring

- [Monitoring baseline](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/monitoring.py): `src/dispatch/monitoring.py`
- [Monitoring dashboard](https://github.com/gokulkrisnaa-n/courier-dispatch-prediction-and-optimization/blob/main/src/dispatch/dashboard.py): `src/dispatch/dashboard.py`

### Other components

- **LaDe pickup data**
- **Scoring clients**
- **Redpanda broker**

## Connections

- LaDe pickup data → Clean pickup data: loads and cleans (evidence: `README.md`)
- Clean pickup data → Shared features: builds inputs (evidence: `README.md`)
- Shared features → Model training: transforms data (evidence: `README.md`)
- Clean pickup data → Model training: supplies cleaned rows (evidence: `src/dispatch/train.py`)
- Model training → Prediction model: saves artifact (evidence: `README.md`)
- Model training → Monitoring baseline: creates baseline (evidence: `README.md`)
- Prediction model → Shared features: builds serving features (evidence: `src/dispatch/model.py`)
- Scoring clients → Scoring API: requests scores (evidence: `README.md`)
- Scoring API → API contracts: uses contracts (evidence: `src/dispatch/api/main.py`)
- Scoring API → Prediction model: predicts pairs (evidence: `src/dispatch/api/main.py`)
- Scoring API → Dispatch snapshot: builds snapshot (evidence: `src/dispatch/api/main.py`)
- Scoring API → Assignment optimizer: scores pairs (evidence: `src/dispatch/api/main.py`)
- Event replay producer → Clean pickup data: loads historic data (evidence: `src/dispatch/stream/producer.py`)
- Event replay producer → Event bus: publishes events (evidence: `src/dispatch/stream/producer.py`)
- Event bus → Redpanda broker: transports events (evidence: `README.md`)
- Stream dispatcher → Event bus: consumes events (evidence: `README.md`)
- Stream dispatcher → Dispatch snapshot: maintains state (evidence: `src/dispatch/stream/dispatcher.py`)
- Stream dispatcher → Scoring API: requests scoring (evidence: `README.md`)
- Stream dispatcher → Assignment optimizer: assigns orders (evidence: `src/dispatch/stream/dispatcher.py`)
- Stream dispatcher → Monitoring baseline: records performance (evidence: `src/dispatch/stream/dispatcher.py`)
- Monitoring dashboard → Monitoring baseline: shows drift metrics (evidence: `README.md`)
- Monitoring dashboard → Stream dispatcher: shows operations (evidence: `src/dispatch/dashboard.py`)
- Monitoring dashboard → Prediction model: shows model status (evidence: `src/dispatch/dashboard.py`)
- Clean pickup data → Shared configuration: reads settings (evidence: `src/dispatch/data.py`)
- Shared features → Shared configuration: reads feature settings (evidence: `src/dispatch/features.py`)
- Model training → Shared configuration: loads settings (evidence: `src/dispatch/train.py`)
- Stream dispatcher → Shared configuration: loads settings (evidence: `src/dispatch/stream/dispatcher.py`)
- Event bus → Shared configuration: selects transport (evidence: `src/dispatch/stream/bus.py`)
