# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Identity **Project Name:** Aradhya Enterprises ERP **Production Domain:** https://erp.aradhyaenterprise.com **Purpose:** Standalone ERP and business management system for Aradhya Enterprises. **Important:** This project is completely separate from LumoraOS. --- ## Commands **Install:** ```bash composer install npm install cp .env.example .env && php artisan key:generate php artisan migrate ``` **Local dev:** This app runs under XAMPP Apache directly, not `php artisan serve`. `public/build` is a static compiled snapshot — after any Blade/CSS/JS change, run `npm run build`, or keep `npm run dev` running in the background while editing views. (Laravel's own `composer run dev` — concurrent server + queue listener + logs + Vite — also works if you're not relying on XAMPP.) **Tests:** ```bash php artisan test # full suite (composer test also works) php artisan test --filter=TestName # single test method/class php artisan test tests/Feature/ProfileTest.php # single file ``` Tests run against in-memory SQLite (`phpunit.xml`), independent of local dev's MySQL — don't assume identical behavior across the two for anything touching raw SQL or date handling (see the Sprint 7 date-range bug further down for a concrete example of this biting). Only Breeze's default scaffolding (`tests/Feature/Auth/*`, `ProfileTest`, `ExampleTest`) is committed; every sprint's real feature/permission verification below was done with temporary `Livewire::test()` suites that were discarded once they passed, per this project's stated convention. Don't assume feature coverage exists beyond what's actually in `tests/`. **Lint/format:** `vendor/bin/pint` (Laravel Pint, default ruleset — no `pint.json` in this repo). **Queue & scheduler:** Notifications (`app/Notifications/*`) are `ShouldQueue`; run `php artisan queue:work` locally to actually process them instead of leaving them queued. `bootstrap/app.php`'s `withSchedule()` runs `app:generate-business-alerts` (low/out-of-stock, expiring batches, overdue balances) and `spatie/laravel-backup`'s `backup:clean`/`backup:run` daily — run `php artisan schedule:work` to exercise them locally. **Seeders:** `php artisan db:seed --class=RolePermissionSeeder` (roles/permissions), `--class=AdminUserSeeder` (Super Admin login from `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD` in `.env`), `--class=DemoDataSeeder`. **Backups:** `php artisan backup:run`, `php artisan backup:list` (spatie/laravel-backup; excludes `.env` and `storage/`). **CI** (`.gitlab-ci.yml`): pushes on any branch run `composer install`, `npm ci`, `npm run build`, `php artisan test` against a fresh SQLite `.env`. Pushes to `master` additionally deploy over SSH/rsync to the production host (see `DEPLOYMENT.md`). --- ## Architecture **Stack:** Laravel 13 + Livewire 4 (classic class+view components, not Volt) + Blade + Tailwind v3 + Alpine.js — Livewire's bundled Alpine instance only, never add a second `import Alpine from 'alpinejs'` or it double-initializes. Auth is Laravel Breeze's classic `blade` stack (plain controllers); everything past login is Livewire. **One Livewire component per module, not Index+Form.** Each module under `app/Livewire/{Module}/` (Products, Categories, Suppliers, Customers, Warehouses, Users, Roles, Inventory, Purchases, Sales, Reports, Assistant, Search, Notifications, Settings) is typically a single `{Module}Index` component handling list + search + pagination + a create/edit modal + delete — there's no separate Form component unless the editor genuinely needs a full page. Purchases (`PurchaseOrderForm`/`PurchaseOrderShow`) and Sales (`SaleForm`/`SaleShow`) are the deliberate exceptions, because a dynamic repeating line-item editor doesn't fit a small modal. **All writes go through a `Services` layer** (`app/Services/*.php`), never directly from a Livewire component or controller: `InventoryService` (the sole write path for `stock_balances`/`stock_movements` — `recordMovement()` is the core primitive every stock-affecting action funnels through), `PurchaseService`, `SalesService`, `WarehouseAccessService`, `NotificationService`, plus `Services/Import/*` (Excel import pipeline) and `Services/Ai/*` (the business assistant). A new stock-affecting feature should be a thin wrapper around `InventoryService::recordMovement()`, not a new write path. **Inventory is ledger-based, not a mutable stock field.** `stock_movements` rows are immutable (the model throws on `updating`/`deleting`) and `stock_balances.average_cost` is real, stateful weighted-average-cost state — recalculated only when a movement has `quantity > 0 AND unit_cost !== null`. A positive adjustment/return with no cost given deliberately leaves the average untouched, and every negative movement (sale, transfer-out, cancellation) leaves it untouched too, per the "historical cost must not change on consumption" rule below. **Authorization is `spatie/laravel-permission`, enforced in layers**: `permission:*` route middleware (`routes/web.php`), `abort_unless(auth()->user()->can(...))`/`@can` inside components, and a `Gate::before` Super Admin bypass. `Dashboard` is gated per-widget rather than per-page, since it's the mandatory post-login landing page every role must be able to open. Warehouse-level restriction is a separate, cross-cutting concern layered on top via `WarehouseAccessService::accessibleWarehouseIds()`/`canAccess()` — it must be called explicitly in any component that lists or writes warehouse-scoped data; it is not automatic, and several modules were found missing it during the Sprint 10 security audit (see below). **The AI business assistant (`/assistant`, `app/Services/Ai/`) is a tool-use loop, not chat-with-raw-DB-access.** `AssistantService` drives up to 5 rounds of tool calls against `AnthropicClient` (a plain `Http`-facade wrapper around the Anthropic Messages API — no SDK dependency) using `BusinessToolService`'s 13 fixed JSON-schema tools. Each tool does its own permission/warehouse check and reuses the *same* query a human-facing page already uses (e.g. `getInventory` reuses `InventoryReport`'s query), so the assistant's numbers cannot drift from what's shown on screen. Configured via `config/ai.php` / `ANTHROPIC_API_KEY`; the app is fully functional with no key set (`AnthropicClient::isConfigured()` gates a degraded UI state instead of throwing). **Excel import (`app/Services/Import/`) never touches inventory directly.** `SevenDaysNaturalParser` (positional column mapping, not header-text matching — the real supplier file's header has a typo) → `ProductMatcher` (exact → fuzzy `similar_text()` → new; fuzzy matches are suggestions only, never auto-merged) → staged into `import_batches`/`import_batch_rows` tables → user reviews/edits the preview → `ImportService::confirm()` reads only from those staged DB rows and creates a normal `PurchaseOrder` through `PurchaseService`, unmodified. A second supplier format should follow this same stage-then-confirm shape rather than writing directly from the upload handler. **Everything below this point is this project's running memory/decision log**, written and updated sprint-by-sprint by whichever agent built each feature. It records *why* things are shaped the way they are — including several real bugs that were found and fixed along the way — and should be read before making a structural change to a module it covers, then updated in the same style (a dated, narrative entry, not a rewrite of history) after any change significant enough that a future session would need the same context. --- ## Core Product Goal Build a modern, simple, fast and intelligent ERP covering: **Purchase → Inventory → Sales → Payments → Profit → Reports** The system should be easier to use than a traditional ERP and should provide intelligent search, complete business history and optional AI-powered business insights. --- ## Technology - Laravel - PHP 8.3+ - MySQL - Blade - Livewire - Tailwind CSS - Alpine.js - Redis where required - Laravel Excel / PhpSpreadsheet - Queues for heavy/background work - HTTPS in production --- ## Core Architecture Principles 1. Follow Laravel conventions. 2. Keep controllers thin. 3. Put business logic in Services. 4. Use Form Requests for validation. 5. Use Policies/Permissions for authorization. 6. Use database transactions for inventory and financial operations. 7. Preserve historical transaction accuracy. 8. Never silently delete historical stock transactions. 9. Avoid unnecessary dependencies. 10. Prefer maintainability over over-engineering. 11. Write tests for important workflows. 12. Do not make destructive changes without review. --- ## Inventory Principle Inventory is **ledger based**. Every stock change must create a stock movement. Examples: - Purchase: positive quantity - Sale: negative quantity - Customer return: positive quantity - Supplier return: negative quantity - Adjustment: positive/negative - Transfer: negative from source, positive to destination - Opening stock: positive Never treat a manually editable stock field as the authoritative source of truth. Historical inventory movements must remain auditable. --- ## Purchase Workflow The standard purchase workflow is: **Supplier Order → Purchase Order → Goods Receipt → Stock Increase → Supplier Payable** An order and a receipt are different concepts. Partial receiving must be supported. Example: ```text Ordered: 100 Received: 80 Pending: 20 ``` Only received quantity should increase inventory. --- ## Excel Import The first real-world supplier format is the **7 Days Natural** Excel order. Current file: `rate list-7 days-pdf00.xlsx` Known columns: - S.NO - PRODUCT NAME - UNIT - Box Qty - MRP - SS-with gst - Dist-with gst - Retailer-with gst - End customer - Order - Value Initial mapping: - Order → purchase quantity - SS-with gst → purchase cost - MRP → MRP - Dist-with gst → distributor price - Retailer-with gst → retailer price - End customer → customer selling price The Excel Value column should be validated against: `quantity × purchase cost` Do not blindly trust the Excel total. --- ## Excel Import Safety Rule Uploading an Excel file must **not** immediately change inventory. Required workflow: ```text Upload ↓ Validate ↓ Product Matching ↓ Preview ↓ User Confirmation ↓ Purchase Created ↓ Goods Received ↓ Inventory Updated ``` The preview must identify: - Existing products - New products - Possible duplicates - Invalid rows - Quantity - Purchase cost - Calculated value - Existing stock - Projected stock The user must be able to correct matching and quantities before confirmation. --- ## Product Matching Matching priority: 1. SKU 2. Barcode 3. Supplier product code 4. Normalized product name 5. Fuzzy name matching 6. Manual confirmation Normalize: - case - spaces - hyphens - harmless leading symbols Example: `-VITAMIN C CREAM 100GM` and `Vitamin C Cream 100Gm` should be recognized as a likely match. Never automatically merge low-confidence matches. --- ## User Management User management is a first-class module. Support: - Users - Roles - Permissions - Active/inactive users - Password management - Login activity - Audit logs - Warehouse-level access Initial roles: - Super Admin - Admin - Manager - Purchase Manager - Sales Manager - Inventory Manager - Sales User - Inventory User - Accounts User Permissions should be granular. Examples: ```text products.view products.create products.update products.delete purchases.view purchases.create purchases.update purchases.receive purchases.cancel sales.view sales.create sales.update sales.cancel sales.return inventory.view inventory.adjust inventory.transfer reports.view reports.export users.manage roles.manage ``` AI must respect exactly the same permissions as the logged-in user. --- ## Warehouse Access Design the authorization system to support warehouse-level permissions. Example: A user assigned to Warehouse A must not automatically see or modify Warehouse B inventory. This should be implemented through authorization policies/services, not scattered hardcoded checks. --- ## Main Modules ### Products Maintain: - SKU - Barcode - Product name - Category - Brand - Unit - Box quantity - MRP - Purchase price - Distributor price - Retailer price - Selling price - GST rate - Reorder level - Minimum stock - Maximum stock - Batch tracking - Expiry tracking - Active status - Notes ### Suppliers Maintain supplier information, purchase history, balances and payments. ### Customers Maintain customer information, sales history, balances and payments. ### Purchases - Purchase orders - Purchase items - Goods receipt - Partial receipt - Supplier balances - Supplier returns ### Sales - Sales - Sales items - Invoices - Payments - Customer returns - Customer balances ### Inventory - Stock balances - Stock movements - Adjustments - Transfers - Batches - Expiry ### Reports - Stock - Purchases - Sales - Profit - Inventory valuation - Product profitability - Fast-moving products - Slow-moving products - Dead stock - Low stock - Expiring stock - Supplier purchases - Customer sales - Receivables - Payables --- ## Inventory Valuation Initially use **Weighted Average Cost**. Formula: ```text new_average_cost = ( existing_stock × existing_average_cost + received_quantity × received_unit_cost ) / ( existing_stock + received_quantity ) ``` Historical sales must retain the unit cost used at the time of sale. Changing the product master purchase price must never alter historical transactions. --- ## Sales Principle When a confirmed sale occurs: ```text Stock decreases ↓ COGS calculated ↓ Revenue recorded ↓ Gross profit calculated ``` Default policy: **Negative stock is not allowed.** --- ## GST Invoicing Added 2026-08-26. Replaces manual rate-typing on sales with tier-driven, GST-correct invoicing. ### Price tiers The supplier rate list quotes four tiers and **every one is GST-inclusive**: `SS-with gst` / `Dist-with gst` / `Retailer-with gst` / `End customer`. The importer stores these verbatim into `products.distributor_price`, `retailer_price`, `selling_price`. `SaleItem.unit_price` is **tax-exclusive** — tax is added on top. So a tier price must be divided by `(1 + gst_rate)` before it reaches a sale line. `PricingService` owns that conversion; the `prices_include_gst` setting turns it off if prices are ever stored exclusive instead. `Customer.type` picks the tier: `distributor`/`wholesale` → distributor price, `retailer` → retailer price, anything else → selling price. Falls through to the next non-zero tier so a product missing its distributor price never invoices at zero. ### Tax computation `GstService` rules: 1. **Place of supply decides the split.** `Setting company_state_code` vs `Customer.state_code` — same code is CGST + SGST at half the rate each, different is IGST at the full rate. Missing either code falls back to intra-state, since charging IGST wrongly is the costlier error. 2. **Tax rounds once per rate bucket**, never per line. Line-level rounding then summing drifts from what the buyer's accounting produces. `apportion()` pushes each bucket's tax back onto its lines proportionally and gives the residue to the largest line, so `sale_items` always add up to the invoice totals. 3. **Round off** to the whole rupee, stored on `sales.round_off`. GST rates are per product (`products.gst_rate`) — shampoos, gummies and soaps are 5%, most cosmetics 18%. Never assume a flat rate across an invoice. ### Invoice numbering `InvoiceNumberService` issues `PREFIX/YY-YY/NNN` per Indian financial year (April–March), incrementing `invoice_series` under a row lock. This replaced deriving the number from `sales.id` after insert, which wrote the literal `'PENDING'` into a UNIQUE column and collided whenever two sales were created at once. ### Screens - `/sales/quick` (`QuickInvoice`) — quantity-first: pick customer and warehouse, then enter quantities against a stock-aware product list. Rates, GST and the split are all derived; nothing is typed. Blocks saving while any line exceeds stock. - `/sales/create` (`SaleForm`) — unchanged manual form, but now prefills the **customer's tier** rather than always the end-customer price, and reprices when the customer changes. - `/sales/{sale}/invoice` — printable GST tax invoice with rate-wise tax summary, amount in words, bank block and declaration, all driven by settings. ### Not done yet - `products.hsn_code` is still unpopulated for all 138 products in the real tenant data (invoices print "—" until it's filled) - the tooling to fix this in bulk now exists (Products page: HSN column/filter + multi-select "Set HSN code" action, 2026-09-07 entry below), but entering the actual codes is a business data-entry task, not something to guess at in code. - E-invoice / IRN generation is not implemented. - E-way bill / GSP integration not implemented (parked 2026-10-13). Idea: supplier e-way bills generated against our GSTIN currently only surface as an SMS from NIC-GSTN; no way in the ERP to see or reconcile them against Purchase Orders. Two integration paths: direct NIC e-way bill API (free, but needs invoice-volume threshold + static IP whitelisting + digital cert) or a GSP/ASP provider (ClearTax, Masters India, Alankit, Cygnet - paid, much faster to integrate). Planned shape: a scheduled job polls "e-way bills against my GSTIN", matches each to a PO by supplier GSTIN + value + date, and flags unmatched ones in a new GST reconciliation report. --- ## Batch and Expiry The system should support batch and expiry tracking because products may include cosmetics and supplements. Support: - Batch number - Manufacturing date - Expiry date - Purchase cost - Quantity - Warehouse Alerts: - Expired - Expiring within 30 days - Expiring within 60 days - Expiring within 90 days --- ## Global Intelligent Search A global search should be available throughout the authenticated application. Users should be able to search naturally: - `Vitamin C Cream` - `orders from 7 Days Natural` - `what did we purchase last month?` - `show all sales of Vitamin C Cream` - `which products are low in stock?` - `what did we buy from 7 Days Natural in August?` - `show unpaid customers` - `which products are selling fastest?` - `show purchases above ₹20,000` - `when did we last purchase De-Tan Cream?` - `show complete history of Vitamin C Cream` Search should return actual database-backed results. --- ## Entity History Major entities should have a timeline/history: - Product - Supplier - Customer - Purchase - Sale - Payment - Stock - User - Batch A product history should show: - Purchases - Sales - Returns - Adjustments - Price changes - Stock changes - Supplier - Customers - Relevant audit activity History must come from actual transactions/audit logs. --- ## AI Principles AI is an **optional intelligence layer**. The ERP must remain fully functional when AI is unavailable. AI should improve: - Search - Business questions - Analysis - Reorder recommendations - Product insights - Supplier insights - Customer insights - Profit analysis - Inventory risk analysis AI must never become the source of truth for financial or inventory data. --- ## AI Safety / Architecture Never give an LLM unrestricted database access. Use controlled application tools/services: ```text searchProducts() searchPurchases() searchSales() getInventory() getProductHistory() getSupplierHistory() getCustomerHistory() getProfitReport() getLowStockProducts() getExpiringProducts() getOutstandingBalances() ``` Architecture: ```text User ↓ AI Query Parser ↓ Intent / Entity Detection ↓ Authorized Application Tools ↓ Database / Reporting Services ↓ Structured Result ↓ AI Explanation ↓ User ``` AI must never execute arbitrary model-generated SQL. AI must obey user and warehouse permissions. AI responses involving business data must be based on real database results. AI must never invent financial numbers. --- ## AI Audit Log AI usage where appropriate: - user - query - detected intent - tools called - filters - result metadata - timestamp - duration - success/failure Do not store sensitive information unnecessarily. --- ## Intelligent UX The application should feel like a modern SaaS product, not a traditional complicated ERP. UX principles: - Simple - Fast - Clear - Responsive - Search-first - Minimal clicks - Good empty states - Good loading states - Good validation messages - Keyboard friendly Global search should support `/` and/or `Ctrl/Cmd + K`. --- ## Command Palette Common actions should be available from a command palette: - New Sale - New Purchase - Add Product - Add Customer - Add Supplier - Import Excel - Receive Stock - Stock Adjustment - Low Stock - Expiring Products - Reports - Settings --- ## Notifications In-app notifications may include: - Low stock - Out of stock - Expiry approaching - Customer payment overdue - Supplier payment due - Import completed - Import errors - Purchase received - Important price changes Notifications should link directly to the relevant record. --- ## Dashboard Dashboard should eventually show: - Today's sales - Today's purchases - Today's gross profit - Inventory value - Total products - Total units - Low stock - Out of stock - Fast-moving products - Slow-moving products - Customer receivables - Supplier payables - Recent purchases - Recent sales - Intelligent business insights Insights must be clickable and backed by actual records. --- ## Development Roadmap ### Sprint 1 Foundation, authentication, users, roles, permissions, products, categories, suppliers, customers, warehouses and settings. ### Sprint 2 Inventory ledger, balances, stock movements, adjustments and weighted average valuation. ### Sprint 3 Purchases, purchase orders, receiving, partial receiving and supplier balances. ### Sprint 4 7 Days Natural Excel import, product matching, validation, preview, duplicate detection and confirmation. ### Sprint 5 Sales, invoices, payments, stock deduction, COGS and profit. ### Sprint 6 Returns, batches, expiry and barcode. ### Sprint 7 Reports, dashboards and Excel exports. ### Sprint 8 Global intelligent search, entity history, command palette and notifications. ### Sprint 9 AI search, controlled business tools and permission-aware business assistant. ### Sprint 10 Security, performance, backups, deployment and production hardening. --- ## Sprint Status (updated 2026-08-18) **Sprint 1: COMPLETE.** Foundation, authentication, users, roles, permissions, products, categories, suppliers, customers, warehouses, settings — all built and verified end-to-end (CRUD + permission gating tested in-browser for every module, including a restricted-role login confirming sidebar visibility and direct-URL 403 enforcement both work). **Sprint 2: COMPLETE.** Inventory ledger, stock balances, movements, adjustments, transfers, and weighted-average valuation — built and verified end-to-end, including the actual weighted-average math (blended cost on receipts, unchanged cost on reductions, transfer cost carry-over), the negative-stock guard, the one-time opening-stock guard, and warehouse-scoped visibility (a user restricted to one warehouse sees only that warehouse in every dropdown/filter, and a role without `inventory.transfer` never sees the Transfer button). **Sprint 3: COMPLETE.** Purchase orders (dynamic line items, live tax/total computation), goods receipt with partial receiving, PO status lifecycle (open → partially_received → received / cancelled), and supplier balances with payment recording — built and verified end-to-end. The receiving flow calls `InventoryService::recordMovement()` with `type: 'purchase'` exactly as Sprint 2 was designed for, confirming that design choice. Verified with real numbers: a 2-line PO (100 @ ₹15 + 40 @ ₹25, mixed 18%/5% GST) computed to the exact expected total (₹2,820), a partial receipt of 60/100 on one line correctly left the PO `partially_received` and put exactly 60 units in inventory at the right cost, receiving the remainder flipped it to `received` and hid the Receive button, and supplier balance tracked correctly through a payment (₹2,500 owed → ₹1,500 after a ₹1,000 payment), matching everywhere it's shown (supplier detail page and the supplier list column). **Sprint 4: COMPLETE.** 7 Days Natural Excel import — upload, positional parsing, product matching (exact/fuzzy/new), an editable preview, and confirmation into a real Purchase Order via Sprint 3's `PurchaseService`, unmodified. Verified against the **actual** `rate list-7 days-pdf00.xlsx` file (117 real product rows): parsed correctly, 14 zero-order catalog rows auto-excluded, a manual in-preview correction (skipping one row) was correctly honored at confirm time (102 line items, not 103), the resulting PO's total exactly matched the source file's own SUMPRODUCT total independently, and inventory stayed untouched after PO creation — confirming the Safety Rule end to end. **Sprint 5: COMPLETE.** Sales, invoices, payments, stock deduction, COGS, and profit — built and verified. Unlike Purchases (two-step order→receipt), a sale is a single immediate transaction: no `SaleOrder`/`Receipt` split, no partial-fulfillment status chain — `Sale` *is* the invoice (`invoice_number` assigned post-insert, same pattern as `po_number`), and its status is just `completed`/`cancelled`. Verified via `tinker` with real numbers (5 units @ ₹80, 18% tax, COGS captured from a ₹50 average cost): subtotal ₹400, tax ₹72, total ₹472, cost_total ₹250, profit_total ₹150 — all matched exactly; stock correctly dropped 20→15 with average cost unchanged (per the Sprint 2 rule for negative movements); an oversell (999 units against 15 in stock) was rejected by `InventoryService`'s existing negative-stock guard with the whole transaction rolled back atomically (zero orphan `Sale` row); cancelling restored stock to 20 via a `sale_cancel` movement and correctly zeroed the customer's `soldValue()`. Browser JS was blocked in this sandbox's preview browser (`ERR_BLOCKED_BY_CLIENT` on `livewire.js`/`app.js` — an environment limitation, not an app bug; server-rendered HTML, routing, and permission-gated rendering all confirmed correct up to that point), so the Livewire component layer itself (`SaleForm`'s product-price prefill and live subtotal/tax/COGS/profit computeds, `SaleForm::save()`, `SaleShow::cancel()`, `CustomerShow`'s payment form) was instead verified with a temporary `Livewire::test()`-based PHPUnit run (22 assertions, since discarded — this project keeps no committed Feature tests, matching Sprints 1-4's tinker/browser-only convention) plus a second temporary run confirming permission gating (a role with `sales.view`+`sales.create` but not `sales.cancel` sees the sale but not the Cancel button; a role with no permissions gets a 403 on `/sales`). **Sprint 6: COMPLETE.** Customer/supplier returns, batch tracking with expiry alerts, and keyboard-wedge barcode quick-add — built and verified. Batches are additive to Sprint 2's costing model, not a replacement: `stock_balances.average_cost` (product+warehouse) stays the sole costing source of truth; `product_batches` is a parallel ledger for quantity/expiry that also happens to carry its own weighted-average `unit_cost`, which `SalesService::createSale()` now reads for COGS *instead of* the warehouse-blended average whenever a specific batch is selected — more precise, since two batches of the same product can carry different costs. `InventoryService::recordMovement()` gained one new optional `?ProductBatch $batch` param (no new write path), locking and updating the batch's own quantity in the same transaction as the warehouse balance, with its own independent negative-stock guard. Verified via `tinker` (22 checks, all passing) with a product split across two batches (20 @ ₹50 expiring in 10 days, 30 @ ₹55 expiring in 90 days — warehouse blended average correctly came to ₹53): selling 15 from the near-expiry batch depleted *that batch* to 5 while the other batch's 30 stayed untouched, and the `SaleItem`'s COGS came from the batch's own ₹50, not the ₹53 blend; oversold the near-expiry batch by 10 while the warehouse total (35) would have allowed it, and the batch-level guard correctly rejected it anyway; a customer return of 5 restored the batch to 10 and correctly netted `Customer::soldValue()`; a supplier return against the other batch correctly depleted it and netted `Supplier::receivedValue()`; `ProductBatch::expired()`/`expiringWithin(30)` scopes correctly bucketed batches at various expiry dates. Same environment limitation as Sprint 5 (sandbox browser blocks `livewire.js`/`app.js`) meant the UI layer was verified via a temporary `Livewire::test()` suite instead (6 isolated test methods, 33 assertions, since discarded) covering barcode quick-add on both `SaleForm`/`PurchaseOrderForm`, the batch `` in the action modals. No new scoping mechanism was needed. **Key implementation decisions from Sprint 1:** - **Auth stack:** Laravel Breeze's `blade` stack (plain controllers, not the Volt-based `livewire` stack) + `livewire/livewire` (v4) installed separately for CRUD screens, using classic two-file class+view components in `app/Livewire/{Module}/`. Auth stays traditional MVC; CRUD screens are Livewire. - **One component per module, not Index+Form.** Each module (Products, Categories, Suppliers, Customers, Warehouses, Users, Roles) is a single `{Module}Index` Livewire component handling list + search + pagination + a create/edit modal + delete, rather than a separate Form component. Zero parent-child Livewire event coordination needed; same UX, less moving parts. Settings is a single non-list `GeneralSettings` component (key-value form only). - **No Policies, no per-module Services for Sprint 1.** Authorization is flat `spatie/laravel-permission` checks (`@can` in Blade, `abort_unless(auth()->user()->can(...))` in component actions, `permission:` route middleware). There's no per-record ownership logic yet, so Policies would be premature. The one Service that exists is `App\Services\WarehouseAccessService` — a deliberate exception to centralize the cross-cutting warehouse-scoping concern ahead of Sprint 2, per the "not scattered hardcoded checks" rule. - **Products/Categories/Warehouses `unique` validation excludes soft-deleted rows** — added `->whereNull('deleted_at')` to every `Rule::unique()` on those tables. Laravel's `unique` rule checks the raw table, bypassing Eloquent's SoftDeletingScope, so without this a soft-deleted "Main Warehouse" would permanently block ever creating another warehouse with that name. Caught live during browser testing, not a hypothetical. - **Tailwind ended up on v3, not v4.** The project was scaffolded fresh with Tailwind v4 (`@tailwindcss/vite`), but `breeze:install blade` overwrote `vite.config.js`, `resources/css/app.css`, and added `tailwind.config.js`/`postcss.config.js` for v3. Kept as-is (functional, officially supported combination) rather than fighting the scaffolding back to v4. - **Alpine.js is Livewire's bundled instance only.** Breeze's default `resources/js/app.js` used to separately import and start Alpine, which conflicted with Livewire v4's own bundled Alpine (`Detected multiple instances of Alpine running` console warning). Removed the separate import/start — Livewire's `@livewireScripts` is now the sole Alpine source for the whole app, including plain `x-data` usage in Blade components (sidebar mobile toggle, dropdown, modal). - **Shared layout:** `resources/views/layouts/app.blade.php` (Livewire's `component_layout` config already pointed here by default) now contains the sidebar+topbar shell, used by both Breeze pages (dashboard, profile) and every routed Livewire component. Sidebar links are guarded with `Route::has($link['route'])` — matters during incremental development so an unbuilt module's route doesn't 500 the entire sidebar for every other page. - **Local dev needs `npm run build` after Blade/CSS changes**, or run `npm run dev` in the background while actively changing views — the compiled `public/build` CSS is a static snapshot from whenever `npm run build` last ran, since this project is served by XAMPP Apache directly rather than `php artisan serve`. - **Seeded Super Admin login:** credentials in `.env` as `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD` (defaults: `admin@aradhyaenterprise.com` / `Aradhya@2026`), created by `AdminUserSeeder`. --- ## Post-Roadmap Fixes **2026-09-29 (later same day) — Near-miss: almost overwrote an already-correct seeder from a month earlier because prior art wasn't checked first.** The user supplied the actual master "7 Days Natural" rate list (117 products, "rate list-7 days.pdf" - the file claude.md's own "Excel Import" section already describes) and asked for a seed script covering whatever's still missing locally. Without first checking whether this had already been done, a brand-new `SevenDaysNaturalRateListSeeder` was written from scratch, transcribing all 117 rows raw from the PDF, and run against the local aradhya tenant. **`git status` immediately flagged the new file as `M` (modified), not untracked** - a `SevenDaysNaturalRateListSeeder` already existed, committed 2026-08-27 (`2906e7d feat(products): seed 7 Days Natural rate list catalog (117 items)`), and it was materially better than the just-written replacement: - Cross-referenced GST rates against a real invoice via a companion `ReproduceInvoiceAe0001Seeder` (Shampoo/Gummies at 5%, everything else 18%) - the freshly written version left every `gst_rate` at 0, since the rate list itself has no GST column and nothing else was checked against. - Populated `box_quantity`, explicitly for `OrderPlannerService`/Smart Order Builder to allocate against - a real downstream need the from-scratch rewrite didn't know existed. - Normalized names (Title Case, leading "-" stripped) and matched existing products case-insensitively via `update()` on a match - keeping the catalog corrected on re-run, rather than the rewrite's raw-PDF-formatting names (`"- STRETCH MARK CREAM 100GM"`, ALL CAPS) plus `firstOrCreate` (leave-alone on any match). **And the original had already been run against this exact local database** - all 117 products were present with the `notes = 'Seeded from 7 Days Natural rate list.'` marker and correct `box_quantity`/`gst_rate`, confirmed by querying before touching anything further. The task the user asked for was already fully done a month earlier; there was nothing left to build. Because the rewrite's raw-formatted names didn't match the original's cleaned-up names even case-insensitively (a leading "-" or ALL-CAPS vs Title Case defeats a plain case-insensitive compare), running it had already created **51 genuine duplicate products** (ids 190-240, all `notes IS NULL`, all timestamped to that one run) before this was caught. Reverted the seeder file (`git checkout --`) and deleted exactly those 51 rows by id range + the `notes IS NULL` marker, verified back to the pre-existing correct state (117 rate-list products + the 50 from the invoice-derived seeder two entries below + other base data = 189 total, matching what was there before this detour started). **The lesson, for next time**: check for existing seeders/prior art (`git log --follow` on the file path being about to write, or at minimum a `Glob`/directory listing of `database/seeders/`) before writing a new one from a user-supplied document - especially when the request is phrased as "add the products from this file," which reads like a fresh task but may already have been solved. No code change resulted from this entry; it exists purely as the record of the near-miss and the cleanup, per this log's own stated purpose. **2026-09-30 — Notifications module completed: full inbox page, cached + visibility-aware polling, and a real bug fix — the daily alert command never ran inside a tenant.** Sprint 8 shipped the bell dropdown and nine `database`-channel notification classes; the spec's "Notifications" module never got a page of its own. User asked to finish it using **local caching + polling instead of Node/websockets** (no Redis, no socket server on this host). - **`/notifications` (`NotificationIndex`, route `notifications.index`)** — the signed-in user's own inbox: All/Unread/Read, type filter, text search, mark read/unread, delete, Mark all read, Clear read (never touches unread), page-size selector. Deliberately *not* permission-gated (every role has an inbox); every query goes through `auth()->user()->notifications()`, so a foreign id is simply a no-op (covered by a test). Sidebar link added; the bell gained "View all notifications". - **Polling:** `wire:poll.visible.30s` on bell and page — hidden tabs stop polling. A closed bell no longer queries the list at all (only the count); the list loads when opened. If a poll sees the unread count *rise* it dispatches `notification-arrived`, which shows a 6s toast. - **Local cache** (`NotificationService::unreadCount()`/`forgetUnreadCount()`): unread count per user, 60s TTL, invalidated immediately by a `NotificationSent` listener (`ForgetUnreadNotificationCount`, auto-discovered) and by every read/unread/delete action. **The store is built with `Cache::build(['driver' => 'file', ...])`, not `Cache::store()`, on purpose:** stancl's `CacheTenancyBootstrapper` forces cache *tags* onto every named store, and file/database drivers don't support tags (this is the same root cause as the 2026-09-02 "does not support tagging" incident, and `.env` here has `CACHE_STORE=array`, which caches nothing across requests). `build()` is a real method on the base manager so it bypasses the tag-forcing `__call`. The path is under `storage_path()`, which the filesystem bootstrapper already suffixes per tenant (verified in tinker: `storage/tenant/framework/cache/notifications`), and the tenant key is also in the cache key. If this app ever moves to Redis, this can become a plain tagged `Cache::remember`. - **Bug fixed: `app:generate-business-alerts` did nothing for tenants.** The scheduler runs on the central connection, where none of the ERP tables exist (since the Sprint 11 split). The command now detects "not in a tenant" and walks every `isUsable()` tenant itself (one tenant failing is reported and skipped, not fatal). It still works unchanged under `tenants:run` and in tests. **Not yet exercised against real tenant data** — running it creates real queued notifications, so it was left for the user to trigger: `php artisan app:generate-business-alerts`. - **Also fixed:** low/out-of-stock alerts were sent to every `inventory.view` user regardless of warehouse restriction, leaking other warehouses' stock levels; now filtered through `WarehouseAccessService::canAccess()` (tested). - Tests: `tests/Feature/NotificationInboxTest.php` (10 tests); full suite 382/382. The suite disables tenancy bootstrappers, so the tenant-cache behaviour above was checked separately in tinker. - Not done: user notification preferences/muting, email/push delivery, per-day digest. **2026-09-29 — Import Order preview's Match column is now the same searchable picker as everywhere else; a real "7 Days" product catalog seeder for local dev.** Two small, unrelated fixes requested together after the PDF parser fix above went live: 1. **The Match dropdown in `ImportWizard`'s preview table was a plain HTML ``); a column that's genuinely open-ended text (name, phone, product/customer/supplier lookup by name) stays free text. Concretely: `Customer.typeFilter`/`statusFilter`, `Supplier/Warehouse/Category.statusFilter`, `Product.categoryFilter`/`statusFilter`/`stockFilter`, `User.roleFilter`/`statusFilter`, `Sale/PurchaseOrder/SaleQuotation.statusFilter`, `Batch.expiryFilter` all became dropdowns with the query switched from `LIKE '%...%'` back to an exact `=` match (a dropdown only ever emits a canonical value, so LIKE's partial-match flexibility was never buying anything there and only risked a false-positive substring match). `Batch/StockBalance/StockMovement.warehouseFilter` and `StockMovement.productFilter` specifically went back to the pre-existing `` combobox rather than a plain ``/text box would have been a real UX downgrade for a 100+-SKU product list, not just a test failure to silence. **One structural bug the second correction's test failures surfaced, invisible until then: the entire filter row lived inside the table, which never rendered at all on a genuinely empty list** (`@if ($x->isEmpty()) @else ...@endif` skips the whole table, header row included, whenever there are zero records - not just zero *matching* records). `SearchableSelectRolloutTest` caught this by seeding no data at all and asserting the filter markup was present; the bug reasoning applied identically to all 12 converted pages, not just the 3 the test happened to cover, since every one of them shared the same `@if(empty) ... @else
@endif` shape. Fixed everywhere by restructuring to the standard pattern: `
` (both rows, unconditional) `@forelse ($items as $item) ...@empty @endforelse
`, with the pagination bar below wrapped in `@if ($items->isNotEmpty())`. This is a genuine UX fix, not just test-satisfying: before it, filtering a list down to zero results left no way to see or clear the active filter without a full page reload, since the "Clear" button lived in the now-vanished header row. **Verified per-page throughout, then as one pass at the end.** Three background sub-agents were used for the bulk of the mechanical page-by-page conversion (Suppliers/Warehouses/Categories; Products/Users; Sales/Purchase Orders/Sale Quotations), with the Inventory pages (Batches/Stock Balances/Stock Movements) and Customers done directly as the hand-verified reference implementation the agents were told to mirror exactly. Two of the three agents hit a session rate limit mid-task and stopped with their assigned pages only partially finished (code written, `pint`/tests never run) - both were resumed and finished directly rather than re-dispatched. One unrelated but real bug surfaced and was fixed while converting `StockMovementIndex`: `orderBy($column, $sortDirection)` alone isn't a stable sort when two rows tie on that column (e.g. two stock movements recorded in the same second), so a secondary `orderBy('id', $sortDirection)` tiebreaker was added - proven necessary by reverting the surrounding change and confirming the "defaults to newest first" test only failed with the tiebreaker absent, not because of anything else in the same edit. Full suite: **238/238 passing, 770 assertions** (up from 226/746 before this entry). Nothing pushed to `master` - all of the above is local only, pending review. **Same-day follow-up, twice: every dropdown filter converted from a native ``, unwieldy once there are more than a handful of categories to scroll through; switched to the same `x-searchable-select` component already used for Warehouse. Second round: "rest two still looking tight" (Status, Stock level) - a native `` has no blank option, so the browser silently rendered "+ New Product" as selected while the bound Livewire property stayed `''`; `confirmImport()`'s `(int) $state['select_value']` then silently turned that blank string into `0`, a product id that doesn't exist, and the `matched_product_id` foreign key rejected it. **Fix pre-seeds `select_value` with the top fuzzy candidate** (`(string) $candidates[0]['product_id']`) instead of leaving it blank - mirrors how `SmartSalesParser` already seeds a fuzzy line's `product_id` elsewhere in this app, so a fuzzy row now starts pointing at the same best-guess match the buyer sees highlighted, still theirs to override via the dropdown. `confirmImport()`'s cast was hardened regardless of this fix's root cause: `select_value` is now only ever trusted as `'skip'` or a genuine positive numeric id, anything else (blank, non-numeric, a stale value from an older component instance) falls back to `'new'` rather than reaching `(int)` at all - the fix closes the reported crash, the hardening closes the whole class of it. Separately wrapped the confirm flow's row-updates-then-`ImportService::confirm()` sequence in one `DB::transaction()` - previously two unguarded steps, so a failure partway through could leave earlier rows in the batch already committed with no purchase order ever created, an inconsistent half-applied import with no way back except starting over. **Verified with a new `tests/Feature/ImportWizardTest.php` (2 tests)**: a real fuzzy-matched row (a typo'd product name scoring above `ProductMatcher`'s threshold) confirms cleanly using the pre-seeded candidate, reuses the existing product rather than creating a duplicate, and writes the correct ordered quantity to the resulting `PurchaseOrder`; a second test forces `select_value` blank directly (simulating any other path that could still produce one, not just the one this fix closes) and asserts `confirmImport()` still never writes an invalid product id. Full suite: **318/318 passing** (up from 316/977 - two new tests, assertion count in the same run as the entry below). Nothing pushed to `master`. **2026-09-07 — Smart Purchase Order Builder gains a free-text paste-order entry, completing the paste-order pattern across all three write paths it now exists on (Sales since 2026-09-02, Quotations since 2026-09-05, Purchases here).** Until now `SmartOrderBuilder` only had the budget-first path (tick products, name a target spend, `OrderPlannerService::plan()` proposes quantities) - a buyer who already has the order written out (their own shorthand list, or a supplier's WhatsApp message) had no faster way in than typing it line by line into the plain `PurchaseOrderForm`. **`SmartSalesParser` is reused for the new `placeOrder()` entry point almost unchanged** - the same reasoning already established when Quotations got this treatment: the parser has nothing sale-specific in it, it fuzzy-matches free text against the product catalog generically, the same way `ProductMatcher` already serves both the Excel-import pipeline and Sales. **One real bug in it surfaced by this reuse, not before**: `extractQuantity()`'s regex has a trailing optional unit group, and a line with no unit typed at all (a purchase-side shorthand like "Beard softner cream 40" - Sales/Quotations text nearly always carries a unit, purchase text often doesn't) makes PHP's `preg_match` omit `$m['unit']` from the match array entirely rather than setting it to `''`; the old `$m['unit'] !== ''` check assumed it was always at least present, and the previous two callers' real-world input just never happened to exercise the omitted-key case. Fixed with an `isset`-safe `! empty($m['unit'])` check - a one-line fix to shared, already-tested code, caught by the new caller's test data rather than a regression in the old ones. The two entry points (`placeOrder()` from pasted text, `plan()` from a ticked budget list) now converge on one shared shape: both replace `$draftLines` wholesale and open the same review modal, rather than the component carrying two parallel line-list representations. `$lines`/`$planned` were renamed/restructured to `$draftLines`/`$showModal` to hold the richer per-line shape a parsed row needs (`raw_text`, `status`, `candidates`) that a planned row never did - the planned path just maps its output into the same shape with `status: 'auto'` and no candidates, so one `pricedDraftLines()`/`unresolvedCount()` pair now gates Generate for either origin, instead of one gate per path. **The review modal gained line-level editing that the budget path never needed**: `addLine()`/`removeLine()` for a manually added or dropped row, `pickCandidate()` to accept one of a fuzzy row's suggestions without opening the searchable-select, and a `reviewSearch` filter (`visibleLineIndices()`, a pure navigation computed property - it never reorders or drops a row, only which are shown) for a long pasted order. `unresolvedCount()` (a line missing a resolved product or a positive quantity) blocks Generate with a named error rather than silently dropping unresolved lines, the same "review before commit" discipline Smart Sales Entry established. The box-stepper (`addBox`/`removeBox`) keeps working identically on a freshly-parsed line, since it only ever reads `product_id`/`quantity` off whichever row it's given, regardless of which entry point produced it - `targetAmount` was correspondingly dropped from `rules()`/`validationAttributes()` since it's now only relevant to the budget path, not a form-wide requirement. **Verified with 3 new tests added to `tests/Feature/SmartPurchaseOrderTest.php`** (now 18 tests total for this feature): pasting two shorthand lines parses and generates a correct `PurchaseOrder` with the right quantities; a line with no catalog match blocks Generate with a `draftLines` error and zero orders created, then resolves once a fallback product is picked via the dropdown and generates successfully; the box stepper still rounds a hand-typed partial-box quantity up to a full box on a parsed (not planned) line, proving the shared stepper logic doesn't assume its line came from `plan()`. Full suite: **321/321 passing, 1006 assertions** (up from 318 after the Import Wizard fix above). Nothing pushed to `master`. **2026-09-07 — AI business assistant: retrofit test coverage for the entire subsystem, closing a gap flagged twice already (Sprint 9's own "provably unaffected" claim, then explicitly re-flagged and left unfixed on the day the two newest tools were added).** With every canonical "Not done yet" item now either done (HSN tooling) or blocked on the user (E-invoice needs real GST-portal credentials, the last remaining flagged gap), this was the next concretely-scoped, fully buildable item: `AssistantService`, `BusinessToolService`'s original 11 tools, and `AssistantChat` had zero automated coverage despite being live, real code a user can hit today. **No real Anthropic API call is ever made** - `Http::fake()` stands in for `api.anthropic.com`, shaped exactly like the real Messages API's `content`/`stop_reason` contract `AnthropicClient`/`AssistantService` already parse (a `tool_use` block with `id`/`name`/`input`, or a plain `text` block with `stop_reason: 'end_turn'`), so the tool-use loop itself is exercised end to end without needing `ANTHROPIC_API_KEY` set anywhere, live or in CI. **New `tests/Feature/AssistantServiceTest.php` (7 tests) covers the loop mechanics** `BusinessToolServiceTest.php` was never scoped to prove: the degraded no-API-key path returns the configured message without an HTTP call ever being made (`Http::assertNothingSent()` - the literal claim Sprint 9 asserted without a test); a plain text reply short-circuits after one round; a `tool_use` round genuinely calls the real `BusinessToolService::searchProducts()` (not a stub) and the next request's `tool_result` content is asserted to carry that real product's name and count; a tool a user lacks permission for returns its denial message as a normal `tool_result` rather than throwing; an unrecognised tool name from the API is reported back as `"Unknown tool: ..."` rather than crashing (`AssistantService::callTool()`'s `method_exists` guard, untested until now); hitting the 5-round cap (`MAX_TOOL_ROUNDS`) without a final answer returns the "wasn't able to finish" fallback; a failed API response surfaces as the `AiUnavailableException` message, not a raw HTTP error; and conversation history is forwarded ahead of the new question in the exact order `AssistantChat::send()` builds it. Every case also asserts what landed in `ai_queries` (`success`, `intent` from the first tool called) - the audit trail this subsystem's whole design depends on for after-the-fact review, also untested before this. **New `tests/Feature/AssistantChatTest.php` (9 tests) covers the Livewire layer**: `mount()` 403s without `ai.use` (component-level and route-level, both checked separately per this project's defense-in-depth convention); `isAvailable()` reflects the configured/unconfigured state correctly; a blank question adds nothing and calls nothing; a real question appends both turns and clears the input; tool names called are deduplicated on the assistant's turn; a second question forwards the first turn as history; and the 20-per-minute `RateLimiter` throttle (`ai-assistant:{userId}`, previously untested) genuinely blocks a 21st call from ever reaching `AssistantService` - asserted via `Http::assertSentCount(20)` after 21 attempts, not just the throttle message's text. **`tests/Feature/BusinessToolServiceTest.php` extended from 8 tests (searchSaleOrders/searchQuotations only) to 19**, one permission-denial-plus-correctness group per remaining tool: `searchProducts` (name/SKU/barcode), `searchPurchases`/`searchSales` (term/status-or-minTotal/date-range, each reconciled against a real `PurchaseOrder`/`Sale` created through the real service), `getInventory`/`getLowStockProducts`/`getExpiringProducts` (all three proven warehouse-scoped with a two-warehouse fixture - a restricted user's tool call must not see the other warehouse's stock, the same rule every human-facing inventory page already enforces), `getProductHistory`/`getSupplierHistory`/`getCustomerHistory` (not-found handling plus a reconciled balance/movement), `getProfitReport` (defaults to this month, reconciles against a real sale's stored `subtotal`/`profit_total`), and `getOutstandingBalances` (its two independent permission checks proven separately - a Purchase Manager sees `payables` but the `receivables` key is absent entirely, not just empty, and vice versa for a Sales Manager). **Deliberately not touched**: `AssistantChat`'s Blade view (typing indicator, message bubbles) and a genuine live-API round trip remain unexercised - the former is presentation-only with nothing to assert beyond what render() already proves by not throwing, the latter still needs a real `ANTHROPIC_API_KEY`, the same dependency that made this a documented gap rather than a bug in the first place. Full suite: **348/348 passing, 1116 assertions** (up from 321/1006, +27 tests across the three files above). Nothing pushed to `master`. **2026-09-07 — This whole session's accumulated work (everything above from 2026-09-05 onward) pushed to `master` as one commit, and a real production deployment gap found and fixed in the same sitting: `deploy_production` in `.gitlab-ci.yml` never ran `tenants:migrate`.** **The gap**: the deploy script's only database steps were central `php artisan migrate --force` and a plain `php artisan db:seed --class=RolePermissionSeeder --force`, with no tenant-context step at all. This app is one central database plus one separate physical database per tenant (`config('tenancy.database')`), and `RolePermissionSeeder` calls `Role::findOrCreate()`/`Permission::findOrCreate()` against whichever connection is active - it was written to run inside a tenant's own database (exactly how `TenantBootstrapper::runSeeders()` already runs it, wrapped in `$tenant->run(...)`, at first-provisioning time), not the central one. Run centrally the way the deploy script called it, it was seeding permission/role rows into a database no tenant's users ever authenticate against - a silent no-op for every deploy since this pipeline existed. Two consequences, both real: (1) every tenant migration this session added (`sale_quotations`, the Supplier Bill columns, `sale_orders`, `delivery_challans`, `converted_sale_order_id`) would have gone live in code without their tables existing in any production tenant database - the exact `Table doesn't exist` incident already hit once before, 2026-09-05, and fixed by hand that time; (2) every permission this project has ever added to `RolePermissionSeeder` across every sprint - `quotations.*`, `sale_orders.*`, `ai.use`, and everything before - has likely never actually been synced into an *existing* tenant's database by any deploy, only into a brand-new tenant at the moment it's provisioned (which runs the seeder file's current contents fresh, so a new signup today is unaffected). **Fix**: two lines in `.gitlab-ci.yml`, right after the existing central `migrate --force` - ``` php artisan tenants:migrate; php artisan tenants:seed --class=RolePermissionSeeder --force; ``` `tenants:migrate` needs no flags here - `config/tenancy.php`'s `migration_parameters` already bakes in `--force => true` and the correct tenant migration path, and it iterates every tenant in the central `tenants` table automatically (no hardcoded tenant list to keep in sync as new tenants sign up). `tenants:seed --class=RolePermissionSeeder --force` is the direct stancl/tenancy equivalent of what `TenantBootstrapper` already does manually via `$tenant->run()` - runs the seeder inside every tenant's own connection instead of the central one. Because `RolePermissionSeeder` is fully idempotent (`findOrCreate` throughout) and seeds the seeder file's *entire* current permission list every time, not just what changed, this single fix is retroactive: the next deploy will backfill every historically-missing tenant migration and every historically-unsynced permission in one pass, not only this session's new ones - confirmed locally by running both commands against both real local tenants (`tenants:migrate` reported "Nothing to migrate" - already caught up locally from this session's manual runs - and `tenants:seed` completed cleanly with no errors on either). **`PlanSeeder` was deliberately left as a plain central `db:seed`** - its own docblock states it runs against the central database only (the plan catalogue is a platform-level concept, not a per-tenant one), so wrapping it in `tenants:seed` would have been the same class of context mistake in the opposite direction. **Not verified end-to-end**: the actual production SSH deploy step itself was not (and cannot be, from here) executed - this fix is verified by running the exact same two artisan commands locally against real tenant databases and by reading `config/tenancy.php`/`TenantBootstrapper.php` to confirm the command choice matches this app's own established tenant-seeding pattern, not by observing a live deploy. Worth watching the next production deploy's pipeline log for these two new lines succeeding. **2026-11-13 — One invoice may carry products of more than one brand (user decision: one bill to the customer, not one invoice per brand).** Smart Sales Entry refused a 7 Days Natural + Trycone order with "This document mixes products from different brands". The user was offered "split into one invoice per brand" or "one invoice, both brands" and chose the second. **This changes the 2026-10-17 rule "a document belongs to exactly one brand" for sales (invoices) only**; quotations, sale orders, delivery challans, purchases and supplier returns still refuse to mix brands (`BrandContext::resolveForProducts`). - **Data:** a mixed invoice has `sales.brand_id = NULL`; every line keeps its brand in `sale_items.brand_id` (migration `2026_11_13_100000`, backfilled from the invoice's brand). `sale_items.round_off_share` carries the invoice's rupee round-off on its largest line (0 elsewhere), so each brand's lines add up to exactly the billed total. `SaleItem::creating` gives a line written without a brand its invoice's brand (challan invoices write lines directly). **Any one-time data fix that inserts `sale_items` with `DB::table()` must set `brand_id` itself**, or the GST and profit reports lose that line in a brand view. - **Rule: documents appear under every brand they contain; money counts only each brand's lines.** `Sale::scopeForBrand` lists a mixed invoice under each of its brands (sales list, search, dashboard, GST B2B, sales report). `SalesFigures` (brand filter or per-brand breakdown), `PartyBalanceService` (what a customer owes a brand), GST rate/HSN/B2C summaries and profit by product count a mixed invoice by its lines; one-brand invoices still use the invoice's own totals, so existing figures did not move. Profit report BA salary: a mixed invoice counts with that brand's part of its total. - **Tally export** with a brand picked lists only that brand's own invoices (`Sale::forBrandOnly`) and says how many mixed invoices were left out: a mixed invoice is one voucher and is exported only under All brands, so it can never be imported twice. - **Credit notes stay one brand:** `SalesService::createReturns()` makes one credit note per brand when returned lines span brands (the sale page uses it); `createReturn()` refuses mixed lines. - **Access:** `BrandContext::authorizeSale()` - a user limited to some brands may open/print a mixed invoice if it has one of their brands, and edit it only with all of them. The sale form also lists products already on the invoice, so editing a mixed invoice with one brand picked keeps the other brand's lines. - **Payments stay per brand** (unchanged): the sale page shows "Brands on this invoice" with each brand's part, and the customer's payment is recorded against each brand for its part. Not built: one payment split across brands automatically. - Tests: `tests/Feature/MixedBrandSaleTest.php` (Smart Sales Entry end to end, parts adding up to the rounded total, figures, receivables, GST, Tally, returns, access). Locally the suite needs an app key (no `.env` here): `APP_KEY=base64:... php vendor/bin/phpunit`; full-page tests also need `public/build` (or a temporary `public/hot`). **2026-11-13 — Stock transfers can be deleted** (user request): a Delete button on the transfers list and on the transfer page (`inventory.transfer` permission, both warehouses accessible). `StockTransferService::deleteBatch()` reverses every line - out of the destination, back into the source at the line's cost - then removes the lines and the batch, all in one transaction. The stock history keeps the transfer and its reversal (notes "Transfer STB-... deleted"), unlike a sale delete, because earlier edits leave movements pointing at removed lines, so a transfer's own history cannot be found and dropped reliably. If the destination has since sold or moved the goods, nothing changes and the reason is shown. An issued challan number is not reused. Editing keeps its own order (destination debited only after the edited lines are credited, 2026-11-01 fix); delete uses `reverseLines()`. Tests: `tests/Feature/StockTransferDeleteTest.php`. **2026-11-13 — Smart Sales Entry "Build from Prompt" adds only sellable products** (user request): products with no stock at the warehouse, or no rate for the customer's tier (`PricingService::priceLine()` unit price 0, the same test as the review window's "no selling price" warning), are left out whatever the instruction's scope ("every product" used to include zero-stock ones), and a quantity above the stock is cut to the stock. The review window says what was left out (`promptNote`, names of the unpriced ones). Test in `SmartSalesEntryPromptTest`. **2026-11-14 — Build from Prompt: target amount across several categories, with a quantity of its own for some groups** (user request: "create a order target amount 30000 Add items Creams,Shampoo,Scrubs,Lip Balm,Perfume, 1 each perfume set"). The parsers (AI `SalesOrderPromptParser` and the regex `HeuristicSalesOrderPromptParser`, one result shape via `SalesOrderPromptParser::normalize()`) now also return `target_amount`, `category_names` (all named) and `fixed_quantities` ([name, quantity]). `SmartSalesEntry::buildFromPrompt()`: fixed groups get their quantity (a category of exactly that name, else products with those words in their name - "perfume gift" - else a category the phrase mentions - "perfume set" = Perfume); the rest of the target is shared over the named categories (all products if none) by `SalesOrderPlanner` (same quantity of each, closest to the amount, valued at the customer's listed price with GST - the Target amount mode's rule); without a target a flat "N each" applies. Category names are matched ignoring plurals and by containment ("Lip Balm" = Balm). Stock/rate exclusions and stock caps as before; the review note gives the planned value and what was left out. The regex parser keeps the old reading of "Order 3 pieces each of Creams in stock" (3 each, category Creams) unless the sentence has an amount or a list. Template "Target amount from categories" replaced "Every product, ignore stock level" (zero-stock products are always left out now). **2026-11-14 — Smart Sales Entry lists only products in stock** (user request). `SmartSalesEntry::stockOnHand()` = pieces per product at the chosen warehouse (before one is chosen: across the user's warehouses). The review window's product dropdown (plus products already on a line), its "Check match" alternatives, the By amount picker and the Grid (its "In stock only" tickbox removed; a product with a quantity already typed stays, so it can be cleared; category tabs with nothing in stock are hidden) show only those. Each review line shows its stock ("Stock 12", red "Only 4 in stock" / "No stock" when the lines of that product ask for more); Confirm is disabled and `confirmSale()` refuses while any line is short (`overStockProductIds()`), instead of the save failing on negative stock. The paste matcher (SmartSalesParser, shared with quotations) still matches every product, so a line can land on an out-of-stock product - the red badge says so and the in-stock alternatives are offered. Tests in `SmartSalesEntryTest`. **2026-11-14 — Switching brand in the header no longer reloads the page** (user report: a half-entered sale was emptied). `BrandSwitcher::updatedBrandId()` sets the brand and dispatches `brand-switched`; the switcher's view then calls `$refresh` on every Livewire component inside `
` (the page body - the bell and the command palette in the layout are left alone), so they re-render under the new brand with their state kept (what was typed or picked, filters). A page whose body is not Livewire is reloaded as before. This relies on components reading the brand while rendering or acting, never only in `mount()` (checked 2026-11-14: the only mount-time uses are access checks on show pages) - keep it that way. Tests in `BrandAccessTest`. **2026-11-14 — Smart Sales Entry "Grid" mode** (user request: an Excel-like grid, category selection changes the grid, keep updating quantities). Fourth tab next to Paste / By amount / Plain English. Category chips (with a count of lines typed in each) and a name/SKU search narrow the rows; "In stock only" (on by default) never hides a product that already has a quantity. Columns: #, product, category, stock at the chosen warehouse, the customer's rate (listed, with GST), qty, amount. Qty cells use a plain deferred `wire:model` on `gridQuantities.{id}`: typing stays in the browser and reaches the server with the next request, so a reply never overwrites a cell being typed in (`updatedGridQuantities()` saves as typed and must not rewrite the array). Totals, row amounts and chip counts are worked out in the browser (Alpine, from rates/categories handed over by the `grid()` computed; the block is keyed by customer so rates refresh). Enter/↓/↑ move between qty cells; a qty above stock turns red. Quantities are kept in the session per workspace and person (`gridSessionKey()`), so switching category or reloading loses nothing; Review order (`reviewGrid()`) fills the usual review window (lines marked `(grid)`, by category then name) and a confirmed sale built from the grid clears it. Tests in `SmartSalesEntryTest` (grid_*). **2026-11-14 — "Copy list" in the Smart Sales Entry review window** (user request): copies the lines as order text, one ` pc` per line (`SmartSalesEntry::draftAsText()`, edits included; a line still without a product keeps what was typed), so the next order with the same items and pieces is one paste. Catalog names make every pasted line an exact match. Test in `SmartSalesEntryTest`. **Deploy note (2026-11-13):** `deploy/deploy.sh` backs up only the database named in `.env` (the central `aradhyaenterpris_erp`); each company's data is in its own `aradhyaenterpris_` database, which it does not back up. Back those up by hand before a deploy until the script covers them. --- ## Current Business Context The initial business has approximately 100+ product SKUs and an inventory purchase target around ₹3 lakh. The existing supplier order is maintained in Excel. The ERP should replace manual inventory tracking and make supplier order uploads a fast, reliable workflow. The goal is not to build a huge ERP immediately. Start with: **Inventory + Purchase + Sales + Payments + Profit + Reports** Then add intelligent search and AI. --- ## Deployment Production: `https://erp.aradhyaenterprisecom` Expected architecture: ```text Cloudflare / SSL ↓ Nginx ↓ Laravel ↓ PHP-FPM ↓ MySQL ↓ Redis ``` Never expose MySQL publicly. Use environment variables for production credentials. --- ## Project Memory Rules Claude should remember and update: - Important architecture decisions - Database design decisions - Business rules - Completed sprints - Current sprint - Pending work - Known issues - Security decisions - UX decisions - Deployment decisions - Important supplier/import rules Do not store temporary debugging details as long-term memory. When a new decision changes an existing rule, update project memory and clearly identify the new decision. --- ## Current Development Rule Before beginning a major implementation: 1. Inspect the existing code. 2. Inspect the relevant database structure. 3. Identify affected modules. 4. Explain the implementation approach when significant. 5. Implement incrementally. 6. Run relevant tests. 7. Verify no regression. 8. Update project memory with important decisions. Never assume an existing implementation without inspecting it first. --- ## Project Vision The long-term ERP experience should follow: **SEARCH → UNDERSTAND → ACT → HISTORY → INSIGHT** The ERP remains deterministic and reliable underneath. AI enhances discovery and decision-making without controlling core transactions. The most important priorities are: **Simple + Fast + Reliable + Secure + Auditable + Intelligent + Easy Excel Import**