# febryannnn/nexwave-backend architecture

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

- Interactive diagram: https://gitdiagram.com/febryannnn/nexwave-backend
- Repository: https://github.com/febryannnn/nexwave-backend

## Overview

NexWave is a warehouse order batching and picker-routing system. WMS orders enter the API and are grouped into waves by a PPO batching service; waves are routed and assigned to pickers, who retrieve routes and report picking progress through the API. Managers also view active waves and shift summaries. The excerpts document key service interactions, but do not expose every API handler or the full model-loading and scheduled-cycle implementation, so uncertain wiring is omitted.

Main entry points: [`modal_app.py`](https://github.com/febryannnn/nexwave-backend/blob/main/modal_app.py) (API and Scheduler), [`api/services/batching_service.py`](https://github.com/febryannnn/nexwave-backend/blob/main/api/services/batching_service.py) (Wave Batching), [`schema.sql`](https://github.com/febryannnn/nexwave-backend/blob/main/schema.sql) (Warehouse Database), [`api/services/dispatcher.py`](https://github.com/febryannnn/nexwave-backend/blob/main/api/services/dispatcher.py) (Wave Assignment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Order Batching"]
  node_batching["Wave Batching"]
  node_ppo["PPO Model"]
end

subgraph group_routing["Routing Assignment"]
  node_routing_agent["Route Selection<br/>[routing.py]"]
  node_navigation["Warehouse Navigation<br/>[nav.py]"]
  node_dispatcher["Wave Assignment<br/>[dispatcher.py]"]
  node_warehouse_data["Layout Data"]
end

subgraph group_operations["Picker Operations"]
  node_modal["API and Scheduler<br/>[modal_app.py]"]
end

subgraph group_persistence["Data and Identity"]
  node_database[("Warehouse Database<br/>[schema.sql]")]
  node_auth["Supabase Auth"]
end

node_wms(("WMS"))
node_manager(("Manager"))
node_picker(("Picker"))

node_wms -->|"submits orders"| node_modal
node_manager -->|"requests dashboard"| node_modal
node_picker -->|"requests route"| node_modal
node_picker -->|"reports picks"| node_modal
node_modal -->|"batches orders"| node_batching
node_modal -.->|"processes due orders"| node_batching
node_batching -->|"chooses actions"| node_ppo
node_batching -->|"measures distances"| node_navigation
node_batching -->|"updates wave records"| node_database
node_modal -->|"assigns waves"| node_dispatcher
node_dispatcher -->|"selects route"| node_routing_agent
node_routing_agent -->|"compares routes"| node_navigation
node_dispatcher -->|"reads and assigns"| node_database
node_navigation -->|"loads layout"| node_warehouse_data
node_modal -->|"reads and updates"| node_database
node_database -->|"returns records"| node_modal
node_modal -->|"verifies tokens"| node_auth

click node_modal "https://github.com/febryannnn/nexwave-backend/blob/main/modal_app.py"
click node_batching "https://github.com/febryannnn/nexwave-backend/blob/main/api/services/batching_service.py"
click node_ppo "https://github.com/febryannnn/nexwave-backend/blob/main/models/ppo_batching_v10.zip"
click node_routing_agent "https://github.com/febryannnn/nexwave-backend/blob/main/api/ml/routing.py"
click node_navigation "https://github.com/febryannnn/nexwave-backend/blob/main/api/ml/nav.py"
click node_dispatcher "https://github.com/febryannnn/nexwave-backend/blob/main/api/services/dispatcher.py"
click node_warehouse_data "https://github.com/febryannnn/nexwave-backend/tree/main/dataset"
click node_database "https://github.com/febryannnn/nexwave-backend/blob/main/schema.sql"

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_batching,node_ppo toneBlue
class node_routing_agent,node_navigation,node_dispatcher,node_warehouse_data toneAmber
class node_modal toneMint
class node_database,node_auth toneRose
class node_wms,node_manager,node_picker toneIndigo
```

## Components

### Order Batching

- [Wave Batching](https://github.com/febryannnn/nexwave-backend/blob/main/api/services/batching_service.py): `api/services/batching_service.py`
- [PPO Model](https://github.com/febryannnn/nexwave-backend/blob/main/models/ppo_batching_v10.zip): `models/ppo_batching_v10.zip`

### Routing Assignment

- [Route Selection](https://github.com/febryannnn/nexwave-backend/blob/main/api/ml/routing.py): `api/ml/routing.py`
- [Warehouse Navigation](https://github.com/febryannnn/nexwave-backend/blob/main/api/ml/nav.py): `api/ml/nav.py`
- [Wave Assignment](https://github.com/febryannnn/nexwave-backend/blob/main/api/services/dispatcher.py): `api/services/dispatcher.py`
- [Layout Data](https://github.com/febryannnn/nexwave-backend/tree/main/dataset): `dataset`

### Picker Operations

- [API and Scheduler](https://github.com/febryannnn/nexwave-backend/blob/main/modal_app.py): `modal_app.py`

### Data and Identity

- [Warehouse Database](https://github.com/febryannnn/nexwave-backend/blob/main/schema.sql): `schema.sql`
- **Supabase Auth**

### Other components

- **WMS**
- **Manager**
- **Picker**

## Connections

- WMS → API and Scheduler: submits orders
- Manager → API and Scheduler: requests dashboard
- Picker → API and Scheduler: requests route
- Picker → API and Scheduler: reports picks
- API and Scheduler → Wave Batching: batches orders
- API and Scheduler → Wave Batching: processes due orders
- Wave Batching → PPO Model: chooses actions
- Wave Batching → Warehouse Navigation: measures distances
- Wave Batching → Warehouse Database: updates wave records
- API and Scheduler → Wave Assignment: assigns waves
- Wave Assignment → Route Selection: selects route
- Route Selection → Warehouse Navigation: compares routes
- Wave Assignment → Warehouse Database: reads and assigns
- Warehouse Navigation → Layout Data: loads layout
- API and Scheduler → Warehouse Database: reads and updates
- Warehouse Database → API and Scheduler: returns records
- API and Scheduler → Supabase Auth: verifies tokens