WFDASH-WEBAPP/APP_CAPABILITIES.md

# WFDASH — Westcott Fasteners Dashboard

## Overview

WFDASH is a Next.js (App Router) + PocketBase application for **Westcott Fasteners**, a fastener supply business. It manages the complete **quote-to-cash lifecycle** for industrial fastener orders — from inbound RFQ emails through pricing, supplier procurement, collection, delivery, and invoicing.

The system is operator-centric, built for the office team who process dozens of quotes and orders daily. It replaces manual spreadsheet/email workflows with structured pipelines, real-time dashboards, and automation via n8n workflows.

---

## Core Domains

### 1. **Quotes Pipeline** (`/quotes`, `/sprint`)
**Inbound RFQ → Processing → Approval → Send → Follow-up**

| Feature | Description |
|---------|-------------|
| **Email Intake** | n8n webhook receives inbound RFQ emails, extracts items via AI, creates quotes in PocketBase. Idempotent on `Message-ID`. |
| **Sprint (/sprint)** | Item-level work queue. Operators **claim individual line items** (30-min soft TTL), price them, and save — the item then drops off the list. Replaces "claim whole quote" bottleneck. |
| **Categories** | Admin-managed categories (JEI, TOOLS, FASTENERS, OIL, HUSQVARNA, UNKNOWN) with brand/supplier/keyword match rules. Items auto-bucket or land in UNKNOWN for review. |
| **AI Pricing** | n8n AI agent reads supplier price lists, matches SKUs, writes `cost_price` + `selling_price` with `pricing_source="ai"` or `"catalogue"`. Operator reviews before saving. |
| **Quote Statuses** | `new → claimed → processed → approval_pending → approved → emailed → complete` (also `rejected`, `problem`, `cancelled`, `mail_failed`, `follow_up`) |
| **Approvals** | Dedicated `/quotes/approvals` page for quotes needing sign-off. |
| **PDF Generation** | Branded quote PDFs (CNL / ISHERWOOD letterhead) with supplier authorization letters. |
| **Email Send** | Modal with CC/BCC, custom subject/body, attachment picker. Status flips to `sending` → n8n sends via SMTP → callback records `emailed` or `mail_failed`. Retry supported. |
| **Follow-ups** | Per-quote `follow_up_due` date; dashboard widget flags overdue. |
| **Customer Replies** | Inbound replies tracked via `quote_replies` collection; shows "Replied" chip on quote row. |
| **Templates** | Reusable quote scaffolding; "Create from template" spawns a real quote. |

---

### 2. **Orders** (`/orders`, `/orders/new`, `/orders/[id]`)
**Quote → Order → Line Items → Delivery → Invoice**

| Feature | Description |
|---------|-------------|
| **Create from Quote** | One-click converts a quote to an order, copying all line items. Atomic order number generation (`ORD-YYYY-MM-NNN`) via server-side counter — continues sequence across month boundaries, concurrency-safe. |
| **Order List** | Collapsible cards grouped by **item status tabs**: New, Processing, Collection Pool, Collected, Delivered, Cancelled. Search spans order #, company, customer, item description, or price. |
| **Item Status Lifecycle** | `pending → processed → po_generated → collection_pool → assigned → collected → stock_verified → picking → ready_delivery → delivered` (terminal). Also `ready_invoice`, `invoiced`, `stock_booked`, `cancelled`. |
| **Quote Matching** | Auto-links order to quote via exact match on quote_number / reference / RFQ / external_number. Suggests a "potential quote" when fuzzy. |
| **Repair Orders** | `is_repair_order` flag for non-standard jobs. |

---

### 3. **Operations / Collection** (`/collection-pool`, `/collection-map`, `/collection-confirm`)
**Supplier Collection → Driver Assignment → Confirmation**

| Page | Purpose |
|------|---------|
| **Collection Pool** | Supplier-grouped view of items in `collection_pool` or `assigned` status. Per-row "Assign driver" + per-supplier bulk assign. Shows PO #, supplier, age, ready-for-collection flag. |
| **Collection Map** | Leaflet map with supplier markers clustered by proximity. Click a cluster → see items → assign driver inline. |
| **Collection Confirm** | Driver-facing (mobile) — scan/confirm collection, marks items `collected`. |

---

### 4. **Invoicing** (`/invoicing`)
**Delivery Note → QuickBooks Invoice → Print**

| Feature | Description |
|---------|-------------|
| **To Invoice Tab** | Orders grouped by order number where at least one item is `ready_invoice`. Per-line qty/price overrides for the QB payload. |
| **QuickBooks Integration** | Modal picks QB company (CNL / ISHERWOOD), searches QB customers via n8n webhook, builds invoice payload, POSTs to n8n → QB. Returns PDF URL stored on `order_items.qb_invoice_pdf`. |
| **Delivery Notes** | Parallel flow: mark lines `delivery_note` status, auto-generates `DN{YYMMDD}NN` number. Same line editor (include/exclude, qty/price override). |
| **Invoiced Tab** | Two sections: **Today's Unprinted** (grouped by invoice #, print badges) + **All Invoiced** (searchable history). Print tracking (printedAt, printedBy, printCount) stored in `order_item_details.print` JSON. |
| **PDF Print** | Server-rendered React-PDF → streamed back. One-click print for single or bulk (today's batch). |

---

### 5. **Stock Management** (`/stock`, `/stock/[id]`, `/stock-orders`)
**Inventory → Surplus Booking → Stock Orders → Ledger**

| Feature | Description |
|---------|-------------|
| **Stock Items** | SKU, name, unit, location, current_qty, min_qty, supplier. Status badge: OK / Low / Critical / Inactive. |
| **Stock Ledger** | Immutable append-only ledger (`stock_ledger`) with signed `change_qty` and `reason` (`purchase_surplus`, `stock_order`, `customer_fulfillment`, `adjustment`, `return`). `current_qty` denormalized for fast reads. |
| **Surplus Booking** | When a supplier delivers more than ordered, operator splits the line: customer qty → order, surplus qty → stock. Creates `stock_ledger` entry (`reason=purchase_surplus`) + links `order_item.surplus_qty` + `stock_booked_from`. |
| **Stock Orders (v2)** | Pure stock replenishment: `SP-YYYYMMDDNN` number, multi-line, status `draft → sent → received → cancelled`. Receive flow books ledger + updates `current_qty` per line. |
| **Fulfilment from Stock** | `/api/v1/stock/fulfill` — books out qty from stock for a customer order, creates ledger entry (`reason=customer_fulfillment`). |

---

### 6. **Pricelist / Catalogue** (`/pricelist`)
**Raw Uploads → AI Extraction → Structured Catalogue**

| Tab | Purpose |
|-----|---------|
| **Raw Uploads** | Drag-drop PDF/CSV/TXT/images (≤50 MB). Optional supplier link, status, **free-text notes for AI** (e.g. "Brand is JEI. Apply 30% markup. ZAR excl. VAT."). Upload creates `raw_price_list` row; n8n workflow picks up, extracts, writes to `price_list`. |
| **Catalogue** | Searchable `price_list` table: SKU, normalised SKU, description, category, brand, supplier, cost/selling/markup, stock_qty, rich `specifications` JSON (diameter, length, material, synonyms). `search_text` column enables fuzzy/synonym search. |

---

### 7. **Purchase Orders** (embedded in Orders flow)
**PO Generation → Email → Supplier Reply Tracking**

- Created from order items grouped by supplier.
- Versioned PDFs stored on `purchase_orders.documents` array + `documents_history`.
- Email modal (to/cc/bcc, HTML+text body, attachment picker) → n8n sends → callback records `email_message_id`, `last_reply_at`, `supplier_reply_preview`.
- Stale PO detection (`purchase-orders/stale` endpoint).

---

### 8. **Delivery Notes** (`/delivery-notes`)
**Generated from delivered order items**

- Auto-numbered `DN{YYMMDD}NN`.
- Status: `draft → ready → delivered → cancelled`.
- Linked to order + company + customer.
- Printable PDF (shares invoice print pipeline).

---

### 9. **Repairs** (`/repairs`)
**Lightweight repair job tracker**

- Repair number auto-generated.
- Status: `new → assessing → quoted → approved → in_progress → completed → cancelled`.
- Links to customer / company / order (optional).
- Item description + fault description + notes.

---

### 10. **Companies / Customers / Suppliers** (`/companies`, `/customers`, `/suppliers`)
**Master data management**

- **Companies**: name, address, email, tel, VAT, reg number, **geo-coordinates** (for map).
- **Customers**: name, emails (primary/alt/buyer), company relation, rep (user), delivery coordinates, description.
- **Suppliers**: name, email, number, address, supply_tags (for category matching), coordinates, closing time.

---

### 11. **Dashboard** (`/dashboard`)
**Real-time KPIs & Charts**

| Widget | Data |
|--------|------|
| KPI Cards | Customers, Active Quotes, Orders This Month, Revenue (sparkline per card) |
| Concentric Rings | Quote pipeline depth (New / Claimed / Approved / Processed) |
| Orders Trend | New vs Fulfilled (8 weeks, stacked bars) |
| Status Mix | Quote distribution (progress bars) |
| Growth Trends | Customers vs Orders (12 weeks, area chart) |
| Approval Rate | Radial gauge (Approved / Active) |
| Activity Pulse | Multi-line (Customers / Quotes / Orders velocity) |
| Quote Pipeline | Donut chart (all non-template quotes) |
| Top Customers | Horizontal bars by quote volume |
| Follow-ups Due | Clickable cards → quote detail |

**Real-time**: PocketBase subscriptions on `customers`, `quotes`, `orders` → auto-refresh.

---

### 12. **Settings** (`/settings`)
- Theme picker (light/dark/system) with CSS variables.
- Developer identity switcher (for local multi-user testing).

---

## Automation & Integrations (n8n)

| Workflow | Trigger | Action |
|----------|---------|--------|
| **Email Intake** | Inbound email (IMAP/webhook) | Parse → AI extract items → Create quote + items + attachments |
| **Quote Outbound** | Quote status = `sending` | Render PDF → SMTP send → Callback `recordSendOutcome` |
| **Supplier RFQ** | Sprint bulk "Email suppliers" | Group by supplier → Send RFQ → Track `outbound_message_id` |
| **Supplier Reply Monitor** | Inbound email with `In-Reply-To` matching PO/quote | Update `supplier_replied_at`, `supplier_reply_count` |
| **Price List Ingest** | New `raw_price_list` row | AI extract → Write `price_list` rows → Update `log_summary` |
| **QuickBooks Invoice** | Invoicing modal submit | Build QB payload → QB API → Return PDF URL |
| **PO Stale Alert** | Scheduled | Find POs without reply > N days → Notify |

---

## Technical Architecture

| Layer | Technology |
|-------|------------|
| **Frontend** | Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS |
| **Backend** | PocketBase (Go) — auth, real-time, file storage, admin UI |
| **Automation** | n8n (self-hosted) — workflows, AI agents, webhooks |
| **Charts** | Custom SVG (no Chart.js/Recharts) — sparklines, bars, donuts, radial, area, concentric |
| **PDF** | `@react-pdf/renderer` (server-side in API routes) |
| **Maps** | Leaflet + OpenStreetMap |
| **Auth** | PocketBase auth (email/password), cookie-based session via middleware |
| **Real-time** | PocketBase `subscribe("*", callback)` on collections |
| **API** | Next.js Route Handlers (`/api/v1/...`) + PocketBase SDK (server) |

---

## Key Design Patterns

1. **Item-Level Workflows** — Not quote/order level. Sprint, Collection Pool, Invoicing all operate on `order_items` / `quote_items` rows.
2. **Optimistic UI + Real-time** — Local state updates immediately; PB subscriptions reconcile.
3. **Server-Side Number Generation** — Atomic counters (`quote_counters`, `order_counters`) prevent collisions.
4. **Idempotency** — Email intake dedups on `Message-ID`; quote/PO sends record outbound `Message-ID` for bounce matching.
5. **Human-in-the-Loop AI** — AI writes `pricing_source="ai"` + zero prices; operator must claim, review, save.
6. **JSON Audit Fields** — `order_item_details`, `quote_item.pricing_notes`, `print` metadata stored as JSON on the row — no extra collections for append-only logs.
7. **Per-User Color Coding** — `claimed_by` / `rep` → deterministic hue (OKLCH) for row tinting + avatar chips.
8. **Working-Day SLA** — `isOlderThanWorkingDays()` excludes weekends; dashboard ages quotes in working days.

---

## Data Model Highlights (PocketBase Collections)

| Collection | Purpose |
|------------|---------|
| `quotes` | Quote header (number, customer, company, status, email thread, PDF, follow-up) |
| `quote_items` | Line items (description, qty, cost/sell/markup, supplier, claim_status, pricing_source, category) |
| `quote_attachments` | Inbound RFQ files + generated PDFs + outbound attachments |
| `quote_replies` | Customer email replies (thread) |
| `orders` | Order header (number, company, customer, quote link, rep, invoiced flag) |
| `order_items` | Line items (status lifecycle, supplier, PO link, in_stock, surplus_qty, pricing audit) |
| `purchase_orders` | Supplier POs (versioned PDFs, email payload, supplier replies) |
| `collection_pool` | Driver assignment queue (links order_item + supplier + driver) |
| `stock_items` | Inventory master (SKU, qty, min, location, supplier) |
| `stock_ledger` | Immutable movements (signed qty, reason, reference) |
| `stock_purchases` | Stock replenishment orders |
| `price_list` | Structured catalogue (AI-extracted) |
| `raw_price_list` | Uploaded supplier files awaiting extraction |
| `categories` | Admin-managed buckets for sprint (match_brands, match_supplier_tags, match_keywords) |
| `delivery_notes` | Delivery note header |
| `delivery_note_items` | Line items on delivery note |
| `repairs` | Repair jobs |
| `companies` / `customers` / `suppliers` | Master data |
| `users` (auth) | Operators + drivers |

---

## Pages / Routes Summary

| Route | Purpose |
|-------|---------|
| `/dashboard` | KPI dashboard |
| `/quotes` | Quote list (tabs: New, Claimed, Pending Approval, Completed, Email Failed, Problem, All, Templates) |
| `/quotes/[id]` | Quote detail (items, pricing, PDF, email, approvals) |
| `/quotes/[id]/process` | Sprint-style item processing for a single quote |
| `/quotes/approvals` | Approval queue |
| `/sprint` | Global item-level pricing queue (by category) |
| `/orders` | Order list (item-status tabs) |
| `/orders/new` | Create order (from quote or blank) |
| `/orders/[id]` | Order detail (items, status transitions, PO, delivery, invoice) |
| `/orders/assign` | Legacy driver assign (hidden from nav) |
| `/invoicing` | To Invoice / Invoiced (QB + delivery notes + print) |
| `/collection-pool` | Supplier collection queue + bulk assign |
| `/collection-map` | Map view of suppliers |
| `/collection-confirm` | Mobile driver confirmation |
| `/stock` | Stock list + low-stock filter |
| `/stock/[id]` | Stock detail + ledger + adjustments |
| `/stock-orders` | Stock replenishment orders |
| `/pricelist` | Raw uploads + Catalogue tabs |
| `/suppliers` | Supplier CRUD |
| `/companies` | Company CRUD |
| `/customers` | Customer CRUD |
| `/repairs` | Repair job tracker |
| `/delivery-notes` | Delivery note list |
| `/settings` | Theme, dev identity |

---

## API Endpoints (Key)

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/v1/quotes/[id]/pdf` | GET | Render quote PDF |
| `/api/v1/quotes/[id]/send-email` | POST | Validate + queue outbound send |
| `/api/v1/quotes/[id]/retry-email` | POST | Retry failed send |
| `/api/v1/quotes/[id]/create-from-template` | POST | Spawn quote from template |
| `/api/v1/orders/from-quote` | POST | Convert quote → order |
| `/api/v1/order-items/[id]/status` | PATCH | Transition item status |
| `/api/v1/invoicing/customers` | GET/POST | QB customer search/create |
| `/api/v1/stock/items` | GET/POST | Stock CRUD |
| `/api/v1/stock/items/[id]/adjust` | POST | Manual qty adjustment + ledger |
| `/api/v1/stock/fulfill` | POST | Book out stock for customer order |
| `/api/v1/stock/surplus-book` | POST | Book surplus from collection |
| `/api/v1/stock/purchases` | GET/POST | Stock orders CRUD |
| `/api/v1/stock/purchases/[id]/receive` | POST | Receive stock order lines |
| `/api/v1/sprint/items/[id]/claim` | POST | Race-safe 30-min claim |
| `/api/v1/sprint/items/[id]/attachments/upload` | POST | Upload pricing proof |
| `/api/v1/purchase-orders/[id]/send-email` | POST | Send PO to supplier |
| `/api/v1/purchase-orders/[id]/pdf` | GET | Render PO PDF |
| `/api/v1/files/[collection]/[recordId]/[filename]` | GET | Stream PocketBase file |

---

## Deployment Notes

- **PocketBase** runs separately (Docker/binary). App connects via `NEXT_PUBLIC_POCKETBASE_URL`.
- **n8n** runs separately; webhooks configured in n8n point to `/api/v1/...` routes.
- **Files** served via PocketBase `/api/files/...` — proxied through Next.js route for auth if needed.
- **Environment**: `NEXT_PUBLIC_POCKETBASE_URL`, `POCKETBASE_ADMIN_EMAIL`, `POCKETBASE_ADMIN_PASSWORD` (for server SDK).

---

## Summary

WFDASH is a **complete operational ERP** for a fastener distributor, covering:

1. **Quote intake** (email → AI → structured quote)
2. **Item-level pricing** (Sprint claim/price/save)
3. **Order management** (quote → order → multi-status item lifecycle)
4. **Supplier procurement** (PO generation, email, reply tracking)
5. **Collection logistics** (pool → map → driver assign → confirm)
6. **Inventory** (stock items, ledger, surplus booking, stock orders)
7. **Invoicing** (delivery notes + QuickBooks + PDF print)
8. **Catalogue** (raw uploads → AI extraction → searchable price list)
9. **Repairs** (lightweight job tracker)
10. **Real-time dashboard** (KPIs, charts, follow-ups)

Built for **speed, auditability, and operator ergonomics** — every screen is a work queue, not a CRUD form.