Book 2 · Chapter 11 — Warehouse Special Stores

(Store C · Supreme Store · Overflow Stores · Consumables)

---

1. Purpose (plain language)

Bizwiz's core inventory lives in the main store(s) of each branch (see Ch. 9–10). On top of that, some distributors run secondary / warehouse sub-stores that need their own receive → requisition → issue → stock-take cycle, kept apart from the main quantity-on-hand so the two never get confused. This chapter documents four such "special stores":

Store	What it is (plain language)	Live?
Store C	A single, fixed secondary warehouse that holds its own copy of sellable stock, receives goods, fulfils internal requisitions and does its own stock-takes — parallel to the main store but tracked in a separate stock ledger.	LIVE (older design, 2023)
Supreme Store	A near-identical twin of Store C — a second fixed secondary warehouse with the same receive/requisition/issue/stock-take flow. Store C and Supreme are managed together and hidden together by one setting.	LIVE (twin of Store C; extended 2025)
Overflow Stores	The modern, generalized version of the Store C idea: instead of one fixed store, the distributor can create many named overflow stores, each tied to a main store/branch and assigned to specific storekeepers. This is the intended replacement for Store C + Supreme.	LIVE (newest, 2025-10 → 2025-12)
Consumables	A completely separate module for non-sale internal-use items — fuel and spare parts consumed by the business's own vehicles/equipment, not sold to customers. Has its own catalog, PO lifecycle, receiving, issuance, consumption (incl. vehicle fuelling), transfers and stock adjustments.	LIVE (newest of all, 2026-01)

Why they exist — the business need:

• Store C / Supreme Store exist because some distributors physically hold sellable stock in more than one warehouse and want each secondary warehouse to have its own controlled inflow (Receive), internal demand (Requisition), fulfilment (Issue) and count (Stock Take), with a separate stock pool from the main store. Store C came first; Supreme Store was added as an identical second warehouse.
• Overflow Stores exist because the fixed "one Store C + one Supreme" model didn't scale — distributors needed an arbitrary number of extra warehouses, each with its own storekeeper. Overflow Stores generalize the same lifecycle into a data-driven list of stores. The platform setting that hides Store C + Supreme explicitly states the reason: "Removes duplication of functions as the same is implemented in overflow stores."
• Consumables exist because fuel and spare parts are not part of the sellable catalog — they are bought, stocked and consumed internally (e.g. fuelling delivery vehicles, servicing equipment). Mixing them into the sales inventory would pollute stock valuations and sales reporting, so they get their own module with a consumption-oriented lifecycle.

---

2. Users & roles (permissions)

All permissions live in app/Permissions/Inventory.php under the Inventory module tree. Role 1 (super-admin) always sees everything; everyone else is gated per-node. Nav visibility for Store C / Supreme is additionally gated by the HIDE_STORE_C_AND_SUPREME_STORE_ON_SIDEBAR setting.

Store C — store-c node (Inventory.php:468)

Sub-node	Model key	Permissions
Section	store-c	view
Maintain Items	store-c-inventory	view, edit, adjustment, delete
Receive	store-c-receive	view, add, edit, edit-values
Requisitions	store-c-requisitions	view, add
Issue Fulfillments	store-c-issue	view, edit, processed
Stock Take	store-c-stock-take	view

Supreme Store — supreme-store node (Inventory.php:552)

Identical shape to Store C (supreme-store-inventory, -receive, -requisitions, -issue, -stock-take). Stock Take here additionally has add and freeze permissions (Inventory.php:593-600).

Overflow Stores — overflow-stores node (Inventory.php:603)

Sub-node	Model key	Permissions
Section (Manage Stores)	overflow-stores	view, add, edit, delete
Inventory	overflow-inventory	view, adjust
Receive	overflow-receive	view, add
Requisitions	overflow-requisitions	view, add
Issue Fulfillments	overflow-issue	view, edit
Stock Take	overflow-stock-take	view, add, freeze, variance

Per-storekeeper assignment (unique to Overflow): Each overflow store can be assigned specific storekeepers via the wa_overflow_store_user pivot table (WaOverflowStore::storekeepers(), app/Model/WaOverflowStore.php:51-54). The sidebar shows a user all active overflow stores if they hold a broad overflow permission or are role 1; otherwise it falls back to only the stores they are explicitly assigned to (overflow_stores.blade.php:29-39). OverflowStoreController@getUsersByLocation populates the assignable-users picker filtered by the store's location.

Consumables — consumables node (Inventory.php:1037)

A large permission subtree: consumables-maintain (categories, items), consumables-purchasing (new / approval / receive / received), and consumables-manage (opening-balances, receiving, issuance, confirm-fueling, consumption, transfers, stock-adjustments, stock-levels, movement-history). Consumable Advance Payments are gated separately under Account Payables (AccountPayables.php:111).

The hide setting

Setting::hideStoreCandSupremeStore() reads HIDE_STORE_C_AND_SUPREME_STORE_ON_SIDEBAR (app/Model/Setting.php:39-42). Seeded default '0' (shown), CLIENT-MANAGED, module Inventory (SettingsSeeder.php:1321-1332). When 1, both the Store C and Supreme Store sidebar sections are suppressed (storec.blade.php:5,69) — the flavor is expected to use Overflow Stores instead.

---

3. Processes — each store's mini-lifecycle

Every special store implements the same four-step warehouse loop. The essential difference is which stock ledger holds its quantity-on-hand, and how many instances of the store can exist.

3.1 Store C

flowchart LR
    A[Maintain Items<br/>store-c-issue.inventoryItems] --> B[Receive<br/>StoreCReceiveController]
    B -->|writes wa_stock_moves_C +| C[wa_store_c_receives / _items]
    D[Requisition<br/>StoreCRequisitionController] -->|wa_store_c_requisitions / _items| E[Issue Fulfillment<br/>StoreCIssueController]
    E -->|wa_stock_moves_C out| F[Processed Requisition]
    G[Stock Take<br/>StoreCStockTakeController] -->|freeze + count| H[Variance report]

• Maintain Items — curate which inventory items exist in Store C, with archive/un-archive and manual stock adjustment (store-c-issue.inventoryItems, .archivedinventoryItems, .inventory-manage-stock; web.php:1623-1629).
• Receive — bring goods into Store C; writes header/lines to wa_store_c_receives / wa_store_c_receives_items and an inbound movement to wa_stock_moves_C (web.php:1604).
• Requisition — an internal request for stock from Store C; header/lines in wa_store_c_requisitions / wa_store_c_requisition_items, with approval rows in wa_store_c_req_permissions. Supports a route-based variant (route_id added 2025-03, create2/store2, web.php:1617-1621).
• Issue Fulfillment — fulfil an approved requisition; writes outbound wa_stock_moves_C; completed ones appear under Processed Requisition (web.php:1622).
• Stock Take — freeze → count → variance. Uses the newer store_c_stock_freezes / store_c_stock_freeze_items / store_c_stock_counts tables (2025-11) via StoreCStockTakeController (web.php:1641-1649). Legacy freeze tables wa_stock_check_freeze_c also exist (WaStockCheckFreezeC).

3.2 Supreme Store — the twin

Supreme Store is a structural clone of Store C. Every route, controller and permission is mirrored 1:1 with a supreme-store prefix (web.php:1655-1692), and its models (WaSupremeStoreReceive, WaSupremeStoreRequisition, etc.) mirror the Store C ones. Its quantity-on-hand ledger is wa_stock_moves_supreme (model WaStockMoveSupreme, migration 2025-03). Stock-take uses supreme_store_stock_freezes / _items / supreme_store_stock_counts (2025-11).

Shared plumbing note: the wa_stock_moves_C table carries FK columns for both Store C and Supreme (wa_store_c_receive_id, wa_store_c_requisitions_id, wa_supreme_store_receive_id, wa_supreme_store_requisitions_id — migration create_wa_stock_moves_C_table.php:42-45), and wa_stock_moves_supreme mirrors the same four columns. The two stores were clearly built as a pair.

3.3 Overflow Stores — the generalized model

flowchart TB
    subgraph Setup
      S[Manage Stores<br/>OverflowStoreController] -->|wa_overflow_stores<br/>name, code, main_store_id| ST[Assign storekeepers<br/>wa_overflow_store_user]
    end
    subgraph "Per store {overflow_store_id}"
      R[Receive] --> RQ[Requisitions] --> IS[Issue Fulfillment] --> STK[Stock Take]
      INV[Inventory / adjust]
    end
    S --> R

• Unlike Store C/Supreme, Overflow supports many stores. Each wa_overflow_stores row has name, code, main_store_id (→ WaLocationAndStore) and is_active (WaOverflowStore.php:9-26). A storekeeper_id column was later added (migration 2025-11-24) alongside the many-to-many wa_overflow_store_user pivot (2025-12-01).
• Every operation route is scoped by {overflow_store_id} (web.php:1705-1748) — receive, requisitions, issue, inventory (with per-item stock-card and adjust), and stock-take (freeze/count/variance with PDF exports).
• Quantity-on-hand ledger: wa_overflow_stock_moves (WaOverflowStockMove). Stock-take uses overflow_stock_freezes / _items / overflow_stock_counts (2025-11) via OverflowStockTakeController; an OldOverflowStockTakeController and legacy wa_overflow_stock_takes / _items predate it.
• Source & destination (code-proven): Overflow Receive draws from the main store — the item picker computes main-store availability net of all overflow balances so goods can't be double-allocated (OverflowReceiveController@inventoryItems:128-136), then writes a positive wa_overflow_stock_moves row. Issue fulfils a requisition to one of three destination types — another store (to_store_id), a route (route_id), or a route customer (wa_route_customer_id) — writing a negative move (OverflowIssueController@update:250-278); a wa_internal_requisition_id link (migration 2025-05-14) ties customer-order issues back to the sales requisition. Requisitions are approval-gated via wa_overflow_req_permissions; all writes use lockForUpdate().

3.4 Consumables — the internal-consumption module

flowchart LR
    PO[Purchasing PO<br/>new→approve→receive] --> REC[Receiving<br/>consumable_receipts]
    OB[Opening Balances] --> MOV
    REC -->|+| MOV[consumable_movements<br/>ledger]
    MOV -->|-| ISS[Issuance]
    MOV -->|-| CON[Consumption<br/>+ vehicle fuel]
    ISS --> CF[Confirm Fueling]
    MOV --> TR[Transfers<br/>between centers]
    MOV --> ADJ[Stock Adjustments]
    REC --> INV[Supplier Invoicing<br/>→ payables]

• Catalog — Consumable items grouped by ConsumableCategory; can be serialized (is_serialized, ConsumableSerialNumber). Separate from the sales WaInventoryItem catalog.
• Purchasing — a full PO lifecycle (ConsumablePurchaseOrder): new-order → pending-approval (approve/reject) → pending-receive (ConsumablesPurchasingController, inventory.php:254-278).
• Receiving — consumable_receipts / _items; feeds consumable_movements. Can be invoiced to suppliers (SupplierConsumableInvoice) and paid via ConsumableAdvancePayment.
• Issuance vs Consumption vs Confirm Fueling (code-proven):
• Issuance hands stock out to a vehicle/person — captures vehicle_id, driver_id, delivery_schedule_id, mileage_reading; writes a negative consumable_movements row and can be reversed (reversed_at).
• Consumption records actual usage/depletion against a ConsumableConsumptionReason (e.g. spillage, maintenance; some reasons force notes via requires_notes); its own header/items with vehicle + mileage feed the vehicle fuel report.
• Confirm Fueling is a mid-step approval gate — a manager confirms an issued fuel document was actually delivered, stamping confirmed_at / confirmed_by on the movement.
• The ledger of record is consumable_movements, keyed per branch_id, with a signed_quantity set by movement_type: positive for Receive / TransferIn / Reversal / OpeningBalance, negative for Issue / TransferOut / Consumption. Stock-on-hand = SUM(signed_quantity) per consumable per branch (Consumable.php:67-71). Transfers (ConsumableTransfer: Pending→InTransit→Received), Stock Adjustments (2026-09), and Opening Balances batches complete the lifecycle. GL posting services exist for purchasing, usage, opening-balance and stock-adjustment; supplier invoices route to Accounts Payable (wa_supp_trans_id).

---

4. Tables touched & key data

Store C (migrations dated 2023-09-08, freeze tables 2025-11)

• wa_store_c_receives, wa_store_c_receives_items
• wa_store_c_requisitions, wa_store_c_requisition_items, wa_store_c_req_permissions
• wa_stock_moves_C — Store C quantity-on-hand ledger (also carries Supreme FKs)
• store_c_stock_freezes, store_c_stock_freeze_items, store_c_stock_counts (new stock-take)
• Legacy: wa_stock_check_freeze_c (+item), wa_stock_count_c

Supreme Store (2023-09-08; stock-move 2025-03; freezes 2025-11)

• wa_supreme_store_receives, wa_supreme_store_receives_items
• wa_supreme_store_requisitions, wa_supreme_store_requisition_items, wa_supreme_store_req_permissions
• wa_stock_moves_supreme — Supreme quantity-on-hand ledger
• supreme_store_stock_freezes, supreme_store_stock_freeze_items, supreme_store_stock_counts

Overflow Stores (2025-10 → 2025-12)

• wa_overflow_stores (name, code, main_store_id, storekeeper_id, is_active)
• wa_overflow_store_user (storekeeper pivot)
• wa_overflow_receives (+items), wa_overflow_requisitions (+items, issue_no), wa_overflow_req_permissions
• wa_overflow_stock_moves — Overflow quantity-on-hand ledger
• wa_overflow_stock_takes (+items) — legacy; overflow_stock_freezes / _items / overflow_stock_counts — current

Consumables (2026-01)

• consumables, consumable_categories
• consumable_purchase_orders (+items)
• consumable_receipts (+items), supplier_consumable_invoices (+items)
• consumable_issuances, consumable_consumptions (+items, vehicle fields), consumable_consumption_reasons
• consumable_transfers (+items), consumable_stock_adjustments (+items), consumable_opening_balance_*
• consumable_movements — consumable ledger of record
• consumable_serial_numbers (+transfers)
• GRN link: add_petty_cash_consumable_check_to_wa_grns (2025-09)

Each special store keys its stock rows to wa_inventory_item_id and wa_location_and_store_id (see WaStockMoveC relations, WaStockMoveC.php:14-24), so they reuse the main inventory item catalog and location list while keeping quantities in a separate ledger.

---

5. Interactions with other modules

• Main inventory (QOH, Ch. 9) — the netting model (code-proven): Store C, Supreme and Overflow all reference the same WaInventoryItem catalog and WaLocationAndStore locations, but hold their own stock ledgers (wa_stock_moves_C, wa_stock_moves_supreme, wa_overflow_stock_moves), distinct from the main wa_stock_moves. Crucially they are not fully independent pools with their own opening balances — instead, main-store available quantity is computed by subtracting the special ledgers: main_available = SUM(wa_stock_moves) − SUM(wa_stock_moves_C) − SUM(wa_stock_moves_supreme) − SUM(wa_overflow_stock_moves) (helpers getItemAvailableQuantity_C / _supreme; StoreCReceiveController:138-148, SupremeStoreReceiveController:136-146, OverflowReceiveController:128-136). So receiving into a special store carves reserved stock out of the same physical inventory without double-counting; issuing from it ships to the destination and does not return to main. Consumables is the exception — a genuinely separate catalog/ledger with its own opening balances, not netted against sales QOH.
• Transfers / internal requisitions (Ch. 10): each special store has its own requisition/issue tables (*_req_permissions, *_requisitions), independent of the branch-level Ferry / Internal Requisition flow. The storec.blade.php sidebar renders "Ferry Requisition" (n-internal-requisitions.*) next to Store C but that is the Ch. 10 inter-branch flow, not part of Store C.
• GRN: Consumables integrate with GRNs via add_petty_cash_consumable_check_to_wa_grns. (Whether Store C/Supreme/Overflow Receive generate GRNs — confirm in §7.)
• Overflow main_store_id explicitly ties each overflow store back to a parent WaLocationAndStore, i.e. each overflow warehouse belongs to a branch/main store.
• Accounting: Consumables' SupplierConsumableInvoice and ConsumableAdvancePayment connect to Account Payables (AccountPayables.php:111).

---

6. Alternatives & variants

• Store C + Supreme vs Overflow — the migration story. Store C (2023) and Supreme (2023, stock-move added 2025-03) are the fixed two-warehouse design. Overflow Stores (2025-10+) is the data-driven many-warehouse redesign that supersedes them. The HIDE_STORE_C_AND_SUPREME_STORE_ON_SIDEBAR setting is the switch a flavor flips to retire the old pair once it has moved to Overflow — the seed comment says so verbatim: "Removes duplication of functions as the same is implemented in overflow stores" (SettingsSeeder.php:1329).
• Per-flavor enablement: HIDE_STORE_C_AND_SUPREME_STORE_ON_SIDEBAR is CLIENT-MANAGED, default shown ('0'). Flavors on the old model keep Store C/Supreme; flavors migrated to Overflow set it to 1. Overflow visibility is purely permission- and storekeeper-assignment-driven, with no equivalent global hide flag.
• Per-store differences: Supreme's Stock Take carries extra freeze permission; Overflow's Stock Take adds freeze + variance and PDF exports, and Overflow Inventory adds per-store adjust + stock-card. Store C is the leanest (view-only stock take at the permission level).
• Consumables is orthogonal to all three — a distinct module for non-sale items, enabled by its own consumables permission tree rather than the store-hide flag.

---

7. Open questions to confirm

CODE-PROVEN (verified this pass): - ✅ Store C is LIVE — full route set (web.php:1598-1649), controllers (StoreCReceiveController, StoreCRequisitionController, StoreCIssueController, StoreCStockTakeController), models and migrations (2023 + 2025-11 stock-take refresh). Actively maintained. - ✅ Supreme Store is LIVE — a 1:1 twin of Store C with its own routes (web.php:1655-1692), controllers, models (WaStockMoveSupreme, migration 2025-03), and 2025-11 stock-take tables. Not vestigial. - ✅ Overflow Stores is LIVE and the newest of the three warehouse stores — full CRUD + per-store scoped lifecycle (web.php:1701-1748), 7 controllers, ~10 tables built out 2025-10 → 2025-12, storekeeper pivot 2025-12-01. This is the go-forward design. - ✅ Consumables is LIVE — the largest and newest module (2026-01 migrations), full PO→receive→issue→consume→transfer lifecycle in ConsumablesController / ConsumablesPurchasingController, ~20 models. Definitely active. - ✅ Each special store keeps its own stock-move ledger separate from main wa_stock_moves. - ✅ The hide setting exists to retire Store C + Supreme in favor of Overflow. - ✅ Netting model confirmed — main-store available qty = main ledger minus the C/Supreme/Overflow ledgers (helpers getItemAvailableQuantity_C / _supreme; OverflowReceiveController:128-136). Reserved stock is carved from the same physical inventory, not double-counted. Consumables is the exception (independent catalog + opening balances). - ✅ Overflow source/destination confirmed — Receive draws from main store; Issue fulfils an approved requisition to a store / route / route-customer, with wa_internal_requisition_id tying customer issues to the sales requisition. - ✅ Consumables Issuance vs Consumption vs Confirm-Fueling confirmed — issuance = outbound to vehicle/person (reversible); consumption = actual usage against a reason; confirm-fueling = manager sign-off stamping confirmed_at. consumable_movements.signed_quantity sign set by movement type.

INFERENCES (still open — confirm with devs): - ⚠️ Store C / Supreme Receive source — Overflow provably draws from main store, but whether Store C/Supreme Receive originates from a supplier, a GRN, or a main-store transfer wasn't nailed to a single write path; the netting proves it reduces main availability, but the upstream document is unconfirmed. - ⚠️ Store C "route-based requisition" (create2/store2, route_id, added 2025-03) — exact use (van-sales route fulfilment?) still unconfirmed, though it mirrors Overflow's route/route-customer destinations. - ⚠️ Whether any flavor runs Store C/Supreme and Overflow simultaneously (mid-migration), and how availability nets when both are active for the same item.

Not dead: none of the four is vestigial. The only "retirement" is the optional hiding of Store C + Supreme where a flavor has adopted Overflow. StoreCStockTakeController_backup.php and OldOverflowStockTakeController.php are superseded backups, not the live path.

---

8. Source references

• Sidebar: resources/views/admin/includes/sidebar_includes/storec.blade.php:5,69 (Store C + Supreme, hide-gated); .../overflow_stores.blade.php:29-39 (storekeeper fallback); .../inventory.blade.php:1090-1187 (Consumables section).
• Setting: app/Model/Setting.php:39-42; database/seeds/SettingsSeeder.php:1321-1332 (esp. line 1329 comment).
• Permissions: app/Permissions/Inventory.php:468 (Store C), :552 (Supreme), :603 (Overflow), :1037 (Consumables); app/Permissions/AccountPayables.php:111 (Consumable advance payments).
• Routes: routes/web.php:1598-1649 (Store C), :1655-1692 (Supreme), :1701-1748 (Overflow); routes/modules/inventory.php:127-278 (Consumables + Purchasing).
• Controllers: app/Http/Controllers/Admin/StoreC*Controller.php, SupremeStore*Controller.php, Overflow*Controller.php, ConsumablesController.php, ConsumablesPurchasingController.php, ConsumableAdvancePaymentController.php.
• Models: app/Model/WaOverflowStore.php:9-54 (main_store_id + storekeepers pivot); app/Model/WaStockMoveC.php:8-24; WaStockMoveSupreme, WaOverflowStockMove; app/Models/Consumable*.php, StoreCStock*.php, SupremeStoreStock*.php, OverflowStock*.php.
• Key migrations: ..._create_wa_stock_moves_C_table.php:42-45 (shared C/Supreme FKs); 2025_03_26_..._create_wa_stock_move_supremes_table.php; 2025_10_16_..._create_wa_overflow_stores_table.php; 2025_12_01_..._create_wa_overflow_store_user_pivot_table.php; 2026_01_16_..._create_consumables_table.php; 2025_09_10_..._add_petty_cash_consumable_check_to_wa_grns.php.