# ahmdlka/nexwave-frontend architecture

> Architecture diagram of the GitHub repository ahmdlka/nexwave-frontend, 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/ahmdlka/nexwave-frontend
- Repository: https://github.com/ahmdlka/nexwave-frontend

## Overview

nexWAVE is a warehouse operations frontend for managers and pickers. Users sign in through Supabase; the landing page routes authenticated users by role to a manager dashboard or operator workflow. Managers review waves, shift summaries and picker progress on a map; operators load assigned routes, confirm picks or report issues, then close a wave. Route visualization uses warehouse map data and route helpers. The README also documents order batching and external actions for pending orders and wave closure. Some dashboard internals were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`app/manager/page.tsx`](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/manager/page.tsx) (Manager dashboard), [`app/operator/page.tsx`](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/operator/page.tsx) (Operator picking), [`lib/supabase.ts`](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/supabase.ts) (Supabase client), [`components/MapViewer.tsx`](https://github.com/ahmdlka/nexwave-frontend/blob/main/components/MapViewer.tsx) (Map viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and UI"]
  node_landing["Landing and role routing<br/>[page.tsx]"]
  node_login["Sign-in<br/>[page.tsx]"]
  node_callback["OAuth callback<br/>[page.tsx]"]
  node_theme["UI theme"]
end

subgraph group_operations["Operations workflows"]
  node_manager["Manager dashboard<br/>[page.tsx]"]
  node_operator["Operator picking<br/>[page.tsx]"]
  node_checklist["Pick checklist logic"]
  node_wavesdata["Dummy wave data<br/>[dummy_waves.json]"]
end

subgraph group_warehouse["Routing and map"]
  node_mapviewer["Map viewer<br/>[MapViewer.tsx]"]
  node_routelegs["Route leg builder<br/>[route-legs.ts]"]
  node_astar["A* pathfinding<br/>[astar.ts]"]
  node_viewport["Map viewport logic<br/>[map-viewport.ts]"]
  node_mapdata["Warehouse map graph"]
end

subgraph group_services["Data and integrations"]
  node_queries["Supabase data queries"]
  node_supabase["Supabase client<br/>[supabase.ts]"]
  node_authdb[("Supabase Auth and PostgreSQL")]
  node_apiutil["Backend HTTP helpers<br/>[api.ts]"]
  node_backend["nexWAVE backend API"]
end

node_user(("Warehouse user"))

node_user -->|"opens"| node_landing
node_user -->|"signs in"| node_login
node_login -->|"authenticates"| node_supabase
node_supabase -->|"uses auth"| node_authdb
node_callback -->|"handles callback"| node_supabase
node_landing -->|"checks session"| node_supabase
node_landing -->|"routes manager"| node_manager
node_landing -->|"routes operator"| node_operator
node_manager -->|"loads operations data"| node_queries
node_manager -->|"renders wave map"| node_mapviewer
node_manager -->|"builds displayed routes"| node_routelegs
node_manager -->|"uses backend helpers"| node_apiutil
node_manager -.->|"processes orders and closes waves"| node_backend
node_operator -->|"loads route and records picks"| node_queries
node_operator -->|"updates pick steps"| node_checklist
node_operator -->|"renders picking route"| node_mapviewer
node_operator -->|"uses backend helpers"| node_apiutil
node_operator -->|"requests next wave"| node_backend
node_queries -->|"queries and updates"| node_supabase
node_supabase -->|"reads and writes"| node_authdb
node_apiutil -.->|"formats requests"| node_backend
node_mapviewer -->|"calculates zoom"| node_viewport
node_mapviewer -->|"renders route legs"| node_routelegs
node_mapviewer -->|"reads map graph"| node_mapdata
node_routelegs -->|"finds leg paths"| node_astar
node_astar -->|"searches graph"| node_mapdata

click node_landing "https://github.com/ahmdlka/nexwave-frontend/blob/main/app/page.tsx"
click node_login "https://github.com/ahmdlka/nexwave-frontend/blob/main/app/login/page.tsx"
click node_callback "https://github.com/ahmdlka/nexwave-frontend/blob/main/app/auth/callback/page.tsx"
click node_manager "https://github.com/ahmdlka/nexwave-frontend/blob/main/app/manager/page.tsx"
click node_operator "https://github.com/ahmdlka/nexwave-frontend/blob/main/app/operator/page.tsx"
click node_mapviewer "https://github.com/ahmdlka/nexwave-frontend/blob/main/components/MapViewer.tsx"
click node_theme "https://github.com/ahmdlka/nexwave-frontend/blob/main/components/MaterialThemeProvider.tsx"
click node_checklist "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/operator-checklist.ts"
click node_queries "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/supabase-queries.ts"
click node_supabase "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/supabase.ts"
click node_apiutil "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/api.ts"
click node_routelegs "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/route-legs.ts"
click node_astar "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/astar.ts"
click node_viewport "https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/map-viewport.ts"
click node_mapdata "https://github.com/ahmdlka/nexwave-frontend/blob/main/data/master_map_data.json"
click node_wavesdata "https://github.com/ahmdlka/nexwave-frontend/blob/main/data/dummy_waves.json"

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_landing,node_login,node_callback,node_theme,node_user toneBlue
class node_manager,node_operator,node_checklist,node_wavesdata toneAmber
class node_mapviewer,node_routelegs,node_astar,node_viewport,node_mapdata toneMint
class node_queries,node_supabase,node_authdb,node_apiutil,node_backend toneRose
```

## Components

### Access and UI

- [Landing and role routing](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/page.tsx): `app/page.tsx`
- [Sign-in](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [OAuth callback](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/auth/callback/page.tsx): `app/auth/callback/page.tsx`
- [UI theme](https://github.com/ahmdlka/nexwave-frontend/blob/main/components/MaterialThemeProvider.tsx): `components/MaterialThemeProvider.tsx`

### Operations workflows

- [Manager dashboard](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/manager/page.tsx): `app/manager/page.tsx`
- [Operator picking](https://github.com/ahmdlka/nexwave-frontend/blob/main/app/operator/page.tsx): `app/operator/page.tsx`
- [Pick checklist logic](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/operator-checklist.ts): `lib/operator-checklist.ts`
- [Dummy wave data](https://github.com/ahmdlka/nexwave-frontend/blob/main/data/dummy_waves.json): `data/dummy_waves.json`

### Routing and map

- [Map viewer](https://github.com/ahmdlka/nexwave-frontend/blob/main/components/MapViewer.tsx): `components/MapViewer.tsx`
- [Route leg builder](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/route-legs.ts): `lib/route-legs.ts`
- [A* pathfinding](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/astar.ts): `lib/astar.ts`
- [Map viewport logic](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/map-viewport.ts): `lib/map-viewport.ts`
- [Warehouse map graph](https://github.com/ahmdlka/nexwave-frontend/blob/main/data/master_map_data.json): `data/master_map_data.json`

### Data and integrations

- [Supabase data queries](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/supabase-queries.ts): `lib/supabase-queries.ts`
- [Supabase client](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/supabase.ts): `lib/supabase.ts`
- **Supabase Auth and PostgreSQL**
- [Backend HTTP helpers](https://github.com/ahmdlka/nexwave-frontend/blob/main/lib/api.ts): `lib/api.ts`
- **nexWAVE backend API**

### Other components

- **Warehouse user**

## Connections

- Warehouse user → Landing and role routing: opens (evidence: `README.md`)
- Warehouse user → Sign-in: signs in (evidence: `README.md`)
- Sign-in → Supabase client: authenticates (evidence: `app/login/page.tsx`)
- Supabase client → Supabase Auth and PostgreSQL: uses auth (evidence: `README.md`)
- OAuth callback → Supabase client: handles callback (evidence: `app/auth/callback/page.tsx`)
- Landing and role routing → Supabase client: checks session (evidence: `app/page.tsx`)
- Landing and role routing → Manager dashboard: routes manager (evidence: `README.md`)
- Landing and role routing → Operator picking: routes operator (evidence: `README.md`)
- Manager dashboard → Supabase data queries: loads operations data (evidence: `app/manager/page.tsx`)
- Manager dashboard → Map viewer: renders wave map (evidence: `app/manager/page.tsx`)
- Manager dashboard → Route leg builder: builds displayed routes (evidence: `app/manager/page.tsx`)
- Manager dashboard → Backend HTTP helpers: uses backend helpers (evidence: `app/manager/page.tsx`)
- Manager dashboard → nexWAVE backend API: processes orders and closes waves (evidence: `README.md`)
- Operator picking → Supabase data queries: loads route and records picks (evidence: `app/operator/page.tsx`)
- Operator picking → Pick checklist logic: updates pick steps (evidence: `app/operator/page.tsx`)
- Operator picking → Map viewer: renders picking route (evidence: `app/operator/page.tsx`)
- Operator picking → Backend HTTP helpers: uses backend helpers (evidence: `app/operator/page.tsx`)
- Operator picking → nexWAVE backend API: requests next wave (evidence: `app/operator/page.tsx`)
- Supabase data queries → Supabase client: queries and updates (evidence: `lib/supabase-queries.ts`)
- Supabase client → Supabase Auth and PostgreSQL: reads and writes (evidence: `README.md`)
- Backend HTTP helpers → nexWAVE backend API: formats requests
- Map viewer → Map viewport logic: calculates zoom (evidence: `components/MapViewer.tsx`)
- Map viewer → Route leg builder: renders route legs (evidence: `components/MapViewer.tsx`)
- Map viewer → Warehouse map graph: reads map graph (evidence: `components/MapViewer.tsx`)
- Route leg builder → A* pathfinding: finds leg paths (evidence: `lib/route-legs.ts`)
- A* pathfinding → Warehouse map graph: searches graph (evidence: `lib/astar.ts`)
