# Distribution System — Frontend Plan

## Stack

- **Framework**: Next.js (App Router)
- **UI**: shadcn/ui + Base UI primitives
- **Icons**: Hugeicons (`@hugeicons/react`)
- **Fonts**: Outfit (body), Nunito Sans (headings), Geist Mono (mono)
- **Auth**: Mock context now → real API once backend is ready

---

## Done

| Area | Details |
|---|---|
| Project scaffold | Next.js + shadcn/ui initialised |
| Layout | Dashboard shell with collapsible sidebar, mobile bottom nav |
| Navigation | All module groups and routes defined in `config/nav.ts` |
| Auth context | Role-based permission system (admin / warehouse / sales) with mock users |
| Data table shell | Reusable `DataTable`, `TableToolbar`, `TablePagination` components |
| 404 page | `app/not-found.tsx` with user assurance copy and navigation CTAs |
| API types | Full backend contract in `types/api.ts` — all response shapes, enums, `PaginatedResponse<T>` |
| API client | `lib/api.ts` (axios instance, auth headers, 401 redirect, error helper) + `lib/api/` module functions for all 11 domains |

---

## Module Build-out

Ordered by **data dependency** — each module can only work once the modules above it have data. Each needs: list page → create form → edit form.

### 1. Network — no dependencies
- [x] Regions — list, create, edit
- [x] Routes — list, create, edit *(depends on: Regions)*
- [x] Vehicles — list, create, edit
- [x] Warehouses — list, create, edit

### 2. Catalogue — no dependencies
- [x] Categories — list, create, edit
- [x] Brands — list, create, edit
- [x] UOMs — list, create, edit (with conversion factors)
- [x] Items — list, create, edit *(depends on: Categories, Brands, UOMs)*

### 3. Suppliers — no dependencies
- [x] Suppliers — list, create, edit

### 4. Users & Access — no dependencies
- [x] Roles — list, create, edit (with permission assignment)
- [x] Users — list, create, edit *(depends on: Roles)*

### 5. Stores — depends on: Routes
- [x] Stores — list, create, edit

### 6. Drivers — depends on: Users
- [x] Driver Profiles — list, create, edit
- [x] Compliance — manage enforcement config

### 7. Pricing — depends on: Regions, Items
- [x] Price Lists — list, create, edit
- [x] Schemes — list, create, edit

### 8. Procurement — depends on: Suppliers, Items, Warehouses
- [x] Purchase Orders — list, create, view
- [x] Goods Receipt (GRN) — list, receive against PO

### 9. Operations — depends on: Vehicles, Drivers, Routes, Warehouses
- [x] Rides — list, view, manage status
- [x] Loading Sheets — list, dispatch, receive *(depends on: Rides, Items)*
- [x] Delivery Tasks — list, view *(depends on: Rides, Stores)*

### 10. Sales & Orders — depends on: Stores, Items, Rides
- [x] Sales — list, create, view
- [x] Orders — list, view
- [x] Payments — list, record

### 11. Stock — depends on: all above
- [x] Stock Balances — list, filter by location/item
- [x] Stock Movements — list, filter by type

---

## Pending Infrastructure

- [ ] Real auth — wire login page to backend, store JWT, refresh flow
- [x] API client — typed fetch wrapper with auth headers and error handling
- [x] Toast / notification system — shadcn `toast` component (`Toaster` in root layout, `toast.add` / `toast.promise` API)
- [x] Form validation library — react-hook-form + zod + @hookform/resolvers; shadcn `field` component; `lib/form.ts` barrel; `components/shared/form-field.tsx` reusable Controller wrapper
- [ ] Dashboard — KPI cards and summary widgets (depends on backend)

---

## Conventions

- All collection endpoints must have **pagination** — no exceptions (server-side preferred).
- Pages live in `app/(dashboard)/<module>/page.tsx`.
- Shared UI goes in `components/shared/`, module-specific UI stays co-located with the page.
- Permissions are checked via `useAuth()` — never hard-code role names in pages.