# Dictionary

## Database Standards

## Required Fields
- **created_by**: Every table should have this field, linked to the user ID of the creator.
- **updated_by**: Every table should have this field, linked to the user ID of the last updater.
- **is_active**: A boolean field, typically set to `true` by default, used for soft-deactivation or status tracking.
- **hashkey**: string (300), unique. A unique identifier for every record, typically generated by `App\Listeners\ModelSavingListener` using `Str::uuid() . Str::random(100)`.

## Audit Fields & Eloquent Events
- **Audit Fields**: `created_by` and `updated_by` are critical for audit trails across all modules.
- **ModelSavingListener**: `app/Listeners/ModelSavingListener.php` automatically populates `hashkey`, `created_by`, and `updated_by` for Eloquent models during the `Saving` event.
- **Raw DB Bypass**: Using `DB::table(...)->insert()` or `update()` **bypasses** Eloquent events and listeners.
- **Manual Requirement**: When using raw DB queries for performance (e.g., in `PosController.php`), you **MUST** manually include `created_by` or `updated_by` (using `Auth::id()`) and `updated_at`/`created_at` (using `now()`) in the data array to maintain data integrity and audit trails.



## UI Standards
- **Buttons and Inputs**: Prefer `.rounded-pill` for a modern, premium look unless otherwise specified.
- **Form Spacing**: Use `d-flex gap-2` or `mb-3` to ensure interactive elements are not too close, especially on mobile views.
- **Form Controls**: Standardize on `form-control` and `form-select` with `rounded-pill`.
- **Empty States**: When a list or dataset is empty, provide a centered, clear message (e.g., "No records found") and an icon (using `fad` or `fas` with `text-muted` and `opacity-2`) to guide the user.
- **Avatars**: For user profile pictures, if a custom photo is not provided (`photourl`), use `https://ui-avatars.com/api/` with the user's name as a dynamic fallback. This ensures a premium, personalized look even without an uploaded image. Avoid relying on local static placeholders like `avatar.png`.
- **Glassmorphism**: Use `backdrop-filter: blur(15px);` and `background-color: rgba(var(--bg-card-rgb), 0.7);` for floating headers and overlay components. A utility class `.glass-card` is available in `app.js` for consistent application.
- **Dark Mode Surface Isolation**: For a modern "seamless" look, avoid forced backgrounds on navigation items and service buttons (`li`, `a`). Instead, use subtle drop-shadows and icon contrast filters (`brightness`, `contrast`) to maintain hierarchy.
- **Scoped Dark Mode**: When fixing dark mode in Vue components with `<style scoped>`, use `:global(.dark-mode) .selector` to ensure styles are correctly applied when the `dark-mode` class is on the `body`.
- **Theme Variables**: Use global CSS variables defined in `app.js` (e.g., `--bg-primary`, `--bg-card`, `--text-primary`, `--accent-color`) for consistent theme-aware styling.
- **Administrative Icon Standards**: For high-density administrative dashboards (like `UltimateConsole.vue`), standardize on the following Font Awesome sizes for visual hierarchy:
    - **Navigation Icons**: `fa-lg` to provide better target recognition.
    - **Dashboard Stat Cards**: `fa-2x` to fill the visual container and provide focus.
    - **Primary Action Buttons**: `fa-lg` (e.g., `fas fa-paper-plane fa-lg`) within buttons for a premium feel.
    - **Main Dashboard Logo**: `fa-4x` for a bold, centered focus on primary consoles.
    - **Bulk Tool Icons**: `fa-2x` to accentuate the tool's category and provide clear differentiation.
    - **Table Actions**: `fa-lg` for critical row-level controls (Download, Delete, Edit).
- **Dark Mode Scoped Fixes**: Use `:global(.dark-mode) .selector` or theme variables (e.g., `var(--bg-primary)`) to override hardcoded colors in Vue `<style scoped>` blocks. Remove `text-dark` and `bg-white` classes where theming is required.
- **Ultimate Console Premium Header**: The administrative header uses a deep, multi-stop radial gradient (`#020617` base) with mesh highlights and intensified glassmorphism for stats pills (`badge-pill-premium`). This ensures a "Power User" feel that distinguishes administrative zones from standard user interfaces.
- **Header Action Buttons**: Use `.btn-glass-premium` for auxiliary header actions (e.g., Refresh, Filter) within colored headers. This style uses backdrop blur and subtle transparency for a sophisticated, modern look without clashing with the header background.
- **Responsive Table Actions**: 
    - **Container**: Use `d-flex flex-wrap gap-1` instead of `btn-group` in table action columns to prevent horizontal scrolling.
    - **Text Labels**: Use `.d-none .d-lg-inline` for text labels within buttons (e.g., `<span class="d-none d-lg-inline">Manage</span>`) to save space on smaller screens while keeping the icon visible.
    - **Min Width**: Apply `style="min-width: 150px;"` (or appropriate value) to the container to ensure enough space for at least a few icons without excessive wrapping.
- **Sticky Headers**: For configuration-heavy or high-density administrative pages (e.g., `SystemSettings.vue`, `UltimateConsole.vue`), use `sticky-top` on the primary header. This ensures critical actions like "Save" or "Back" remain accessible while scrolling through long forms. **CRITICAL**: Because the application uses a fixed `TopHeader`, you **MUST** provide an explicit `top` offset (e.g., `top: 66px;` or `top: var(--header-height, 66px);`) and a high `z-index` (e.g., `1020`) to ensure the sticky element sticks *below* the global navigation bar rather than being hidden behind it. Adjust sidebar `top` values accordingly (e.g., `13rem` to `18rem` depending on header height) to prevent overlap.


## Layout & Responsiveness
- **Max Width**: The application uses a dynamic maximum width for the main layout, controlled by the CSS variable `--layout-max-width`.
- **Default Width**: `1440px` (Modern Desktop/Tablet Landscape).
- **Mobile Behavior**: On screens smaller than the max width, the layout automatically scales to 100% width.
- **Centering**: The `body` and fixed elements (`TopHeader`, `BottomNav`) are centered using `margin: 0 auto`.
- **Full Width Mode**: The `.is-full-width` class on the `body` overrides the max-width to `none`, allowing components like the POS to utilize the entire screen.
- **Implementation**: Managed globally in `resources/js/app.js` via an injected `<style>` tag, and supported by `:global` overrides in scoped components.

## Migration Standards (Hypervel/Hyperf)
- **DO NOT use Illuminate classes** in migrations. This project runs on Hypervel (Hyperf + Swoole), not Laravel. Using `Illuminate\Database\Migrations\Migration`, `Illuminate\Database\Schema\Blueprint`, or `Illuminate\Support\Facades\Schema` will cause fatal class-not-found errors at runtime.
- **Correct imports for all migrations**:
  ```php
  use Hyperf\Database\Schema\Blueprint;
  use Hypervel\Database\Migrations\Migration;
  use Hypervel\Support\Facades\Schema;
  ```
- **Why**: Hypervel wraps Hyperf's database layer. The `Illuminate` namespace does not exist in this project. The Hypervel `Migration` class provides proper coroutine-context-aware connection resolution via `ApplicationContext`.
- **Commands**: `php artisan migrate`, `php artisan migrate:rollback`, `php artisan migrate:fresh`, etc. work identically to Laravel.

# Development Requirements

## 1. API / Web Route Permissions
- For every new function exposed through an API or web route:
  - Add a corresponding permission in `UserPermissions` and `UserActions`.
  - Ensure the permission is validated before granting access to the function.

### Route file scope (important)
- **`routes/api.php`** is intentionally minimal. It only registers: `IndexController@index`, `RemoteLogoutController@logout`, and `Market\ActivityController` (`/activity/recent`, `/activity/search`).
- **Products, users, stores, POS, cart, cooperatives, admin, settings, landing pages, etc. are ALL defined in `routes/web.php`** — not `api.php`. Despite paths like `/api/pos/...`, `/api/public/...`, or `/admin/users/list` appearing throughout the codebase, these are web routes (Inertia/session-auth based), not REST API routes.
- When searching for product/user/store endpoints, grep `routes/web.php` first. Do not assume `/api/*` paths live in `routes/api.php`.

## 2. Vue Routing
- For every new page:
  - Add a corresponding entry in `VueRouteMap`.
  - Ensure the route is properly registered and accessible via the application's routing system.
- Pages are using vue not blade. Blade pages are legacy code and must not be modified but can be a source of    investigation

- **Direct Page Access**: Pages such as **view** or **edit** must include one of the following in the URL:
  - `h=<HASH_KEY>`  
  - `e=<ENCODED_PAYLOAD>`
  - URL Format: `/page-name--h:HASHKEY` or `/page-name--e:PAYLOAD`
  - **Product Context**: When a product is accessed from a store context (e.g., in `BuyViewProductMarket` or `ManageProductAdmin`), use an encoded payload (`--e:`) containing `product_hashkey` and `store_hashkey` to ensure context persistence and allow direct URL access.

- This ensures that:
  - Pages can be accessed directly via URL.
  - Functionality remains intact even without navigation state.

## POS Access Keys
- **Terminal Name**: A descriptive name for a POS terminal (e.g., "Counter 1").
- **Access Key**: A unique key used to authenticate a POS terminal without a traditional login.
- **Target File**: `resources/js/Pages/PosAccessKeys.vue` - Main management interface for POS access keys.
- **Store Hash**: The hashkey of the store associated with the access key.
- **Store Name**: Displayed in `PosMain.vue`, retrieved from `posStore.activeSession.store.name` or `posStore.todayStats.store_name`.

## Sharing Protocols
- **Web Share API**: Used for sharing content (text, URLs) via the device's native sharing dialog. Supported on most modern mobile browsers.

## Market Enums
- **TransactionFlow**: Categorizes transactions into `INCOME` (1), `EXPENSE` (-1), or `NEUTRAL` (0).
- **ProductTransactionType**: Defines specific transaction events (e.g., `ONLINE_SALE`, `PURCHASE`) which map to a `TransactionFlow`.
- **Add Transaction Page**: `resources/js/Pages/AddTransaction.vue` - Interface for manually recording global or store-specific transactions.

## Customer Management
- **Table**: `cst` (Customers)
- **Key Fields**: `hashkey`, `name`, `store_id`, `user_id`.
- **Suggestions**: Handled in `PosMain.vue` via `/api/pos/get-customers`. Employs a **Stale-While-Revalidate** pattern: immediate results from Pinia/LocalStorage cache while background fetching latest from the server.
- **Session Lifecycle**: Transactions are completed in `confirmComplete`. Upon success, the session is reset, but the terminal identity (`pos_access_key` and captured `storeHash`) is preserved. A new session is then automatically started via `posStore.startNewSession` to ensure a seamless "customer-after-customer" checkout flow. To support this, `pos_sessions` allows multiple records per `pos_access_key` (removed unique constraint).
- **Quick Select**: Displays the last 3 recently used customers as quick-pick buttons when the customer name input is empty/focused. This provides immediate selection without searching.
- **Cache**: Persisted in `localStorage` under `pos_cached_customers`.

## Routing Architecture
- **VueRouteMap**: `app/Http/Controllers/Support/VueRouteMap.php` - Centralized mapping for Vue components to routes.
- **SPA Routing**: Catch-all route in `web.php` maps to `VueRouteMap::handleSpa()`.
- **Navigation**: Uses `useNavigate` composable. Pagenames should match Vue component names (PascalCase).
- **Initial State**: `app.js` initializes history state on load using `window.history.replaceState` to ensure back/forward navigation works for the entry page.
- **Prop Extraction**: The backend automatically extracts hash/payload tokens and provides them as `target`, `hashkey`, and `id` props to the rendered Vue component.
- **URL Flexibility**: The SPA router (`VueRouteMap::handleSpa`) is robust against hyphen and case discrepancies in the URL slug. It automatically matches unhyphenated slugs (e.g., `/viewstoremarket`) and misaligned casing to their correct components (e.g., `ViewStoreMarket`) defined in the map.
- **Common Mappings**:
    - `/user-list` -> `UserList.vue`
    - `/manage-products` -> `ManageProductsAdmin.vue`
    - `/manage-product-admin` -> `ManageProductAdmin.vue`

## Missing/Future Modules
- **Shipments**: `ShipmentList.vue` - For logistics and product tracking. Handled by `ShipmentController.php`.
- **Farmer Management**: `FarmerProfileEdit.vue` - For registering farmer profiles. Handled by `FarmerController.php`.
- **Verification Dashboard**: `VerificationDashboard.vue` - For admin review of farmer profiles. Handled by `FarmerController.php`.

## Groups & Associations
- **Module**: `Groups`
- **Tables**: `groups`, `group_members`
- **Architecture**: A generic container for various member organizations.
- **Group Types**: Dynamic (COOPERATIVE, ASSOCIATION, NGO, etc.) defined in `system_settings` under `group_types`.
- **Key Fields**: `hashkey`, `name`, `type`, `description`.
- **Membership**: Linked via `group_members` pivot table with `role` and `membership_type`.

- **Property Management**: `ListProperties.vue` - Interface for managing properties.
- **Referrals**: `ListReferrals.vue` - Interface for managing property referrals and leads.
- **Accounting**: Handles financial tracking and reporting.
  - **Tables**: `accounts`, `account_transactions`
  - **Controller**: `AccountingController.php`
  - **Pages**: 
    - `AccountingDashboard.vue` (`/accounting-dashboard`) - Tree and Leaf views.
    - `ListReports.vue` (`/list-reports`) - Transaction list and summaries.
  - **Endpoints**: 
    - `POST /admin/accounting/reports` - Fetches recent transactions.
    - `POST /admin/accounting/tree` - Hierarchical account tree.
    - `POST /admin/accounting/leaf` - Flat list of leaf accounts.

## Server Configuration Notes
- **Nginx Headers**: Large JWT tokens and complex data trees (like accounting) require increased header and proxy buffers in Nginx.
  - `large_client_header_buffers 4 32k;`
  - `proxy_buffer_size 32k;`
  - `proxy_buffers 8 64k;`
- **POST Requests**: Production environments (Nginx/WAF) may reject empty POST bodies with a 400 error. A global Axios interceptor in `app.js` ensures all POST requests carry at least an empty object `{}`.

## Shipment & Logistics
- **Module**: `Shipment`
- **Key Fields**: `hashkey`, `transaction_id`, `courier_id`, `status`, `tracking_number`.
- **Statuses**: `PENDING`, `PICKED_UP`, `IN_TRANSIT`, `DELIVERED`, `FAILED`, `RETURNED`.
- **Target Files**: `ai-docs/modules/shipment_module.md`

## Farmer Management
- **Module**: `FarmerProfile`
- **Key Fields**: `hashkey`, `user_id`, `organization_id`, `verification_status`.
- **Verification Statuses**: `UNVERIFIED`, `PENDING`, `VERIFIED`, `REJECTED`.
- **Target Files**: `ai-docs/modules/farmer_management_module.md`

## Redis Configuration
- **Connection**: `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`.
- **Authentication**: `REDIS_AUTH` or `REDIS_PASSWORD`.
- **Support**: Empty passwords are supported by setting `REDIS_AUTH=` in `.env`. The configuration uses `(?: null)` logic to handle empty strings correctly.
- **Config Files**: `config/database.php` and `config/autoload/redis.php`.

## Query Caching (Redis)
- **Helper**: `App\Http\Controllers\Helpers\CacheHelper.php`
- **Key Format**: `querycache:[queryhash]++++[parameterhash]`
- **Methods**:
    - `get_cache($query, $params = [])`: Fetches from cache via `Cache` facade. Supports SQL strings or Builder objects.
    - `set_cache($query, $data, $params = [], $ttl = 86400)`: Sets in cache via `Cache` facade inside a **fire-and-forget** coroutine.
    - `erase_cache($query, $params = [])`: Deletes the specific cache key using `Cache::forget`.
- **Implementation**: Uses `Hypervel\Support\Facades\Cache` for better integration with the application's caching layer.
- **Async Logic**: `set_cache` uses `Hyperf\Coroutine\Coroutine::create` to return responses immediately without waiting for cache network I/O.
- **TTL**: Default is 1 day (86400 seconds).

## User Settings & UI Persistence
- **Composable**: `resources/js/composables/useUserSettings.js`
- **Controller**: `app/Http/Controllers/Market/UserSettingsController.php`
- **Frontend Sync**: Handled via `uiStore.syncSettings(settings)` which is called after `userStore.fetchCurrentUser()` in `app.js`.
- **Purpose**: Dynamically store and retrieve user-specific UI preferences in the `users.settings` JSON column.
- **Key Settings**:
    - `pos_layout`: `landscape` or `regular`. Controls the split-screen behavior in `PosMain.vue`.
    - `dark_mode`: Boolean. Globally toggles the application's dark theme by applying the `.dark-mode` class to the `body`.
    - `pos_sound_effects`: (Future) Boolean to toggle audible feedback during scanning.

## Global Theme & Dark Mode
- **Class**: `.dark-mode` - Applied to the `<body>` element.
- **Persistence**: Saved in the `users.settings` JSON column. Included in initial user data fetch via `AccountSettingsPageController@listDetails`.
- **Implementation**: Handled via state in `uiStore` and a global reactive `watch` in `app.js` with `{ immediate: true }`.
- **UI Toggle**: Located in `AccountSettings.vue`, calls `/UserSettings/Update`.
- **Color Overrides**: Global text color overrides for dark mode are defined in `app.js` and apply to standard typography tags (`h1-h6`, `span`, `p`, `label`, `i`) and generic `div` elements, ensuring uniform color contrast across the application.


## POS & Terminal Management (Advanced)
- **"Start New Session" requires store context**: `startNewSessionSilently` (in `usePosSession.js`) guards against calling the API when both `storeHash` and `access_key` are absent. When neither is available (e.g. navigating to `/pos-main` without a URL hash or stored key), it sets `posStore.error` and returns false instead of hitting `/api/pos/start`. `PosController::startSession` now returns 422 (not 404) when no store can be resolved, with a descriptive message. `posStore.error` is surfaced in the cart area of `PosMain.vue`.
- **Landscape Mode**: Optimized for tablet/desktop usage with a split product/cart view.
- **QR/Barcode Scanner**: Integrated via `html5-qrcode` in `PosMain.vue`. Supports scanning product hashkeys, barcodes, or store-specific QR codes.
- **Session Auto-Start & Access Keys**: POS sessions are automatically restarted after completion. To prevent authorization failures, the system distinguishes between permanent terminal access keys (`PK-` prefix, stored in `pos_access_keys`) and temporary session-specific random tokens. The frontend (`pos.js`) ensures only valid terminal keys are persisted to `localStorage` (via `PosMain.vue`), and the backend (`PosController.php`) now allows authenticated users to start a session by specifying a `store_hash` even if an invalid or unrecognized `access_key` is present in the request payload. This prevents 401 errors caused by session-specific tokens being used as terminal credentials.
- **Clear All**: A "Clear All Items" feature is available in `PosMain.vue` and `pos.js` which performs a bulk deletion of all transactions in the current session via `/api/pos/clear`. This includes a database update and a session archive entry for auditing.


### File Uploads
- **Route**: `POST /File/Upload/{category}` → `FilesMainController::UploadFilefromRequest` ([app/Http/Controllers/FilesMainController.php](app/Http/Controllers/FilesMainController.php)).
- **Permission scoping**: gated by `canUploadCategory($category)` — allows anyone with `UploadAllFiles` (ULTIMATE / SUPER_OPERATOR). For `ProductMarket`, also allows roles with `CreateProductForOwnStore` or `AddProducttoOwnStore` via `ProductPermissions::isActionAllowed` (covers STORE_OWNER, STORE_MANAGER, OPERATOR). All other categories require `UploadAllFiles`.
- **Frontend**: `resources/js/composables/useFileUpload.js` posts to `/File/Upload/${category}`. The `CreateProductStoreOwner` wizard uses `category: 'ProductMarket'`.

### RBAC & Permissions Logic
- **Core Controller**: `app/Http/Controllers/Helpers/Permissions/UserPermissions.php`
- **Actions Enum**: `app/Enums/UserActions.php` (Currently defines 103 user actions).
- **Default Permissions**: ULTIMATE users are automatically granted all actions defined in `UserActions::cases()`.
- **Roles Method**: `UserPermissions::roles()` defines the default permission mapping per user type.
- **Roles with No Target User**: `UserPermissions::$RoleswithNoTargetUser` is a collection for actions that don't target a specific user (e.g., `ViewAllUserTypes`, `ViewShipments`, `UltimateConsole`).
- **User Types**: `ULTIMATE` (all access), `SUPER_OPERATOR` (most management), `OPERATOR` (limited operational access), `COORDINATOR`, `SUPPLIER_OVERSEER`, `WHOLESALE_BUYER`, `SUPPLIER`, `STORE_OWNER`, `STORE_MANAGER`, `USER`, `RIDER`, `AUDIT`, `POS_TERMINAL`.
- **Allowed User Types (Creation Hierarchy)**: Defined in `UserPermissions::UserTypeService::getAllowedUserTypes()`.
    - **ULTIMATE**: Can manage ALL types.
- **SUPER_OPERATOR**: management of all entities except ULTIMATE accounts. Includes global store and POS key management. Now includes `ViewAccountingReports` and `ManageAccounting` to allow access to the Accounting Dashboard.
- **OPERATOR**: management of multiple stores, farmers, and logistics (Shipments/POS Reports). Now includes global store and product management, POS access keys, and accounting management (`ViewAccountingReports`, `ManageAccounting`).
    - **STORE_OWNER**: Can manage `STORE_MANAGER`, `RIDER`, `POS_TERMINAL`.
    - **RIDER**: Has no default management permissions.

## User Management
- **Create User**: 
    - **Validation**: All required fields (`mobile_number`, `username`, `name`, `fullname`, `type`, `password`) must show real-time validation status.
    - **Field Conflicts**: Conflicts (e.g., "Mobile number already taken" or "Username already taken") must be checked via API and displayed as inline error messages.
    - **Type Selection**: Filtered based on the current user's `acct_type` via `UserTypeService::getAllowedUserTypes()`.
    - **UX**: The "Create Account" button should remain visible but disabled until all requirements are met. A "Remaining Requirements" summary box should appear if the user has started filling the form but missed some fields.
- **Table**: `users`
- **Controller**: `app/Http/Controllers/UserManagement/CreateUserControllerUltimate.php`
- **Page**: `resources/js/Pages/CreateUser.vue`
- **User List API**: `/admin/users/list` returns an object `{ success: true, users: [...] }` containing all visible descendants of the current user.

## Cooperative & User Profile
- **UserInfo**: Detailed personal information for users (firstname, lastname, bank details, addresses). Linked to `users` via `user_id`.
  - **Table**: `user_infos`
  - **Edit Page**: `resources/js/Pages/UserInfoEdit.vue`
- **Navigation Fix (April 2026)**: Accessing the profile without a `target` prop now defaults to the currently logged-in user's profile by fetching the hashkey from the Pinia store.
- **Cooperative**: An organization of type `COOPERATIVE`. Users are linked via `cooperative_members`. Data is stored in the `organizations` table.
  - **Key Fields**: `registration_number` (CDA COR), `cin` (Cooperative Identification Number), `tin` (BIR TIN), `cooperative_type`, `cooperative_category`, `registration_date`, `contact_person`, `contact_number`, `contact_email`, `compliance_status`.
  - **Types**: Credit, Consumer, Producer, Marketing, Service, Multi-purpose, Advocacy, Agrarian Reform, Cooperative Bank, Dairy, Education, Electric, Financial Service, Fishermen, Health Service, Housing, Insurance, Transport, Water Service, Workers.
  - **Categories**: Micro (Assets <= P3M), Small (Assets > P3M to P15M), Medium (Assets > P15M to P100M), Large (Assets > P100M).
  - **Member Table**: `cooperative_members`
  - **List Page**: `resources/js/Pages/CooperativeList.vue`
  - **Create Page**: `resources/js/Pages/CreateCooperative.vue`
  - **Detail Page**: `resources/js/Pages/CooperativeDetail.vue`
  - **Model**: `app/Models/Market/Organization.php`
  - **Controller**: `app/Http/Controllers/Market/CooperativeController.php`

## Home Store Owner Dashboard
- **Component**: `resources/js/Pages/Fragments/Home/HomeStoreOwner.vue` - Used by `Home.vue` for `STORE_OWNER` accounts.
- **Balance Card Stats**: `transactions_today_no` (count) and `cash_flow_today_php` (signed `SUM(amount * flow)` for today, scoped to stores where the user is owner or in `store_managers`). Plus `my_stores_no` (count of stores owned by the current user).
- **Backend**: Stats are added to `GET /home-data` (`routes/web.php`), scoped by store ownership for non-Big3.
- **Buttons**: Create Store (opens a yes/no chooser modal — "Quick Create" calls `POST /Store/AutoCreate`, "Custom Create" navigates to `CreateStore.vue` with store-owner-only fields hidden), Import Products (`BatchAddProducts`), New Product (`CreateProductStoreOwner` — wizard-style flow, see below), My Products (`ManageProductsAdmin` — backend `listProducts_Admin` already scopes non-Big3 to products created by the user + descendants), POS Keys (`PosAccessKeys`).
- **Store Owner Create Product Flow** (`CreateProductStoreOwner.vue`): 4-step wizard tailored for store owners (replaces `CreateProductUltimate` on the Store Owner home). On mount, fetches `/Admin/Stores/Selectable`; if empty, opens a `yesNoModal` directing the user to `CreateStore` and blocks. Step 1: live fuzzy search via `/Products/Admin/FuzzySearch`; user picks an existing global product, OR clicks "My product is not listed — Create new" to enter Step 2-new. Step 2 (existing): description override (per-store). Step 2 (new): full global product form (name/desc/category/subcategory/price/unit/available/barcode/photos). Step 3: multi-select stores from the selectable list. Step 4: per-store rows with editable `price` and `available` (defaults seeded from global). Submit: for "new" mode, first `POST /Products/Admin/New/` with `TargetStore` = first selected store (required because store owners lack `CreateProductGlobal`), then iterate every selected store and `POST /Products/AssignToStore/` passing `target`, `TargetStore`, `price`, `available`, `description`. **`AssignProductToOwnStore` now upserts the pivot** (`updateExistingPivot` if already attached, else `attach`) and accepts an optional `description` field written to the `prd_str` pivot.
- **Auto-Create Store**: `StoreController@autoCreate` → `POST /Store/AutoCreate`. Quick path used by the Store Owner home's "Quick Create" choice. Creates a store with sensible defaults and self-assigns owner/manager + a `store_managers` row.
- **CreateStore for STORE_OWNER**:
    - Hidden fields: Store Owner dropdown, Internal Remarks, Linked Cooperatives, Store Status. Owner is forced to the current user; status forced to `active`; remarks cleared.
    - Additional Store Managers list: only shown when descendants of the current user with `acct_type = STORE_MANAGER` exist. Backend (`StoreController@store`) re-validates that each submitted manager hashkey is both a descendant AND a STORE_MANAGER — anything else is silently dropped.
    - Self-assignment: STORE_OWNER is automatically inserted into `store_managers` for the new store, in addition to `owner_id`/`manager_id`.
    - Name uniqueness: `stores.name` is validated `unique` globally. Violations return 422 with message "A store with this name already exists. Please choose a different name."
    - RBAC: only Big3 + STORE_OWNER may hit `POST /Store/New`; STORE_MANAGER cannot create (only edit assigned stores).
- **User list filter (`POST /admin/user/list/numbers/hash`)**: accepts an optional `type` (string or array of `acct_type` values, e.g. `"store manager"`) to restrict the descendants-only result set. Response now includes `acct_type` per row.
- **Route Map Adjustments**: `/manage-stores`, `/batch-add-products`, and `/manage-products` now allow `store owner` (and `store manager` for `/manage-stores` and `/manage-products`) so the Store Owner home buttons land on accessible pages.
- **`/create-product-store-owner` route**: mapped in `VueRouteMap.php` → `CreateProductStoreOwner`, allowed for `ult`, `super operator`, `operator`, `store owner`, `store manager`. Required so direct URL-bar access / page reload works (in-app navigation via `useNavigate` push-states this URL).
- **Add Products to Store flow (`AddProductsToStore.vue`)**: two-step wizard at `/add-products-to-store--h:<store_hashkey>` (allowed for Big3 + `store owner` + `store manager`). Step 1: browse every active global product via `POST /Products/GlobalList` (`ProductController@listGlobalProductsForPicker` — returns all `is_active=true` products regardless of `created_by`, since picking a global product to list in your own store requires visibility into the full catalog). Multi-select card grid + free-text search over name/category/subcategory. Step 2: editable table of selected products with per-row `price` and `available`, seeded from the global defaults, plus a "Bulk apply" panel that sets every row's price or availability at once. Submit iterates `POST /Products/AssignToStore/` per row (existing upsert endpoint — see L266). Entry points: (1) `CreateStore.vue` after `POST /Store/New` success — navigates here with the new store's hashkey instead of `ListStores`; (2) `HomeStoreOwner.vue` Quick Create branch after `POST /Store/AutoCreate`; (3) `ManageStoresAdmin.vue` per-row green `+` "Add Products" action (visible when `canModifyStore(store)`).

## Home Ultimate Dashboard (Revised)
- **Component**: `resources/js/Pages/Fragments/Home/HomeUltimate.vue`
- **Style**: Maintains the "Classic" BukidBounty look with a single **ServiceButtonGrid** for primary services and a **SideTextButtonList** for secondary management actions.
- **Icons**: Standardized to use micons (`/assets/micons/`) for better dark mode visibility and modern aesthetics for key services like Products (`box-seam.svg`), Verification (`patch-check.svg`), Cooperatives (`people.svg`), and Announce (`megaphone.svg`).
- **Organization**:
    - **Primary Grid**: Contains the most visual and frequently used administrative tools (Users, Stores, products, Transactions, Reports, Market, Shipments, etc.).
    - **Management & Tools List**: Text-based list for specific onboarding tasks (New User/Store/Product) and personal/social features (Profile, Referrals, Properties, Credit Transfer).
- **Data Integration**: Connected to live counts for Users, Active Stores, Pending Orders, and System Balance via the updated `/home-data` endpoint.
 
  ## Product Management
- **Manage Product Admin**: `resources/js/Pages/ManageProductAdmin.vue` - Central console for managing a specific product's global and store-specific data.
- **Update Product Modal**: `resources/js/Components/Market/UpdateProductModal.vue` - A unified modal interface for editing product details, including pricing overrides for specific stores.
- **Create Product Flow** (`CreateProductUltimate.vue`): On submit, runs a fuzzy-name dedup check via `POST /Products/Admin/FuzzySearch` (`ProductController@fuzzySearchByName`, name-only LIKE + SOUNDEX + `similar_text` scoring, threshold ≥ 45). If matches exist, a modal lists them with "Import to Store" (calls `/Products/AssignToStore/` with the user's typed price/available). Otherwise — or after "None of these — Create new" — a store-picker modal always opens (per product spec) and the chosen store is sent as `TargetStore` to `/Products/Admin/New/`.
- **`.bb-modal*` styles**: shared modal styles (`.bb-modal-backdrop`, `.bb-modal`, `.bb-modal-header/body/footer/close`) are defined as **scoped** styles inside `CreateProductUltimate.vue` and `BatchAddProducts.vue`. They are NOT global — any new page using `<div class="bb-modal-backdrop">` must duplicate the CSS in its own scoped block or the modal will render invisibly.
- **Batch Add Products** (`BatchAddProducts.vue` → `POST /admin/batch/products` → `BatchController@batchCreateProducts`): Big-3 only. Top-of-page target-store picker (`/Admin/Stores/Selectable`). Each leaf is independent; default mode creates a new global product. "Pick existing" button per leaf opens a fuzzy-search modal (reuses `/Products/Admin/FuzzySearch`) to link a global product instead — if the search returns zero matches, the picker is closed and a `Warning` modal is shown. Payload per leaf: `source: 'new' | 'existing'`. For `existing`, only `product_hash`, `price`, `available`, `description` are sent; backend attaches the global product to the target store via the `prd_str` pivot, **falling back to the global's `price`/`description` when the leaf's value is blank or 0**. For `new`, the global product is created and — when a target store is picked — also attached to that store with the same price/stock/description. Pivot table `prd_str` supports `available`, `price`, `description`, `is_active` etc. (see `Store::products()` `withPivot`).
- **Store-scoped product creation permission**: `UserActions::CreateProductForOwnStore` (granted to STORE_OWNER, STORE_MANAGER, OPERATOR, SUPER_OPERATOR). `ProductController@createNew_Admin` allows the request when the caller has either `CreateProductGlobal` (Big3) or `CreateProductForOwnStore` + a `TargetStore` they own/manage; the existing per-store ownership check at the top of `createNew_Admin` enforces the latter.
- **Selectable Stores Endpoint**: `POST /Admin/Stores/Selectable` → `StoreController@listSelectableStoresForAddingProduct`. Non-Big3 query was widened from descendants-only to include self + descendants + `store_managers` pivot, so a fresh store owner sees their own store(s).
- **Manage Listings Modal (`ManageProductsAdmin.vue` store icon)**: opens a per-product modal listing the user's selectable stores. For each store it shows a "Listed" / "Not listed" badge based on `POST /Products/AssignedStores/` (`ProductController@getAssignedStoresForProduct`, returns store hashkeys the product is attached to). Each row has a List or Unlist action; List runs the existing price/availability prompt → `POST /Products/AssignToStore/`; Unlist confirms then calls `POST /Products/UnassignFromStore/` → `ProductController@RemoveProductFromStore`. `RemoveProductFromStore` was relaxed from the Big3-only `RemoveProductfromAnyStore` permission to ownership-aware checks mirroring `AssignProductToOwnStore` (Big3, owner, legacy manager, store_managers pivot member, or descendant of any of those).
- **Payload Keys**:
    - `product_hashkey`: Used in URL payloads to identify a specific product.
    - `store_hashkey`: Used in URL payloads to identify the store context for a product.
 
  ## Ultimate Console
 - **Component**: `resources/js/Pages/UltimateConsole.vue` - Powerful administrative interface for ULTIMATE accounts.
 - **Roles**: Access restricted via `ultimate` middleware and `UserActions::UltimateConsole`.
 - **Key Features**:
     - Raw SQL Query execution (`UltimateQueryModal.vue`).
     - System-wide maintenance mode toggle (Redis-backed).
     - Global broadcast messaging (Redis-backed).
     - Batch operations for users, transactions, and store management.
     - Database clearing/flushing for specific tables.
     - System statistics and artisan command execution.
 - **Backend**: `app/Http/Controllers/Market/UltimateController.php`
 - **Migrate Endpoint**: `POST /admin/ultimate/migrate` → `UltimateController@runMigrate`. Runs `php artisan migrate --force` (non-interactive, prod-safe). Auth: `auth` + `ultimate` middleware. Returns `{ success, output }`.
- **Flush Endpoint**: `POST /admin/ultimate/flush` → `UltimateController@flushData`. Body `{ target }`. Valid targets: `transactions`, `pos_sessions`, `stores` (truncates `str` + `prd_str` + `store_managers`), `products` (truncates `prd_items` + `prd_str`), `cooperatives` (truncates `cooperative_*` child tables + deletes `organizations` where `type='COOPERATIVE'`), `carts` (truncates `cart_items` + `carts`), `farmer_profiles`, `cache` (Redis flushDB). UI lives in the "Dangerous Zone" tab via `flushOptions` in `UltimateConsole.vue`.
- **Composable**: `resources/js/composables/useUltimate.js` - Contains methods like `getStats` (to retrieve system metrics), `toggleMaintenance`, `sendGlobalMessage`, and `runCommand` (for Artisan calls). Ensure methods are called exactly as defined (e.g., `getStats` instead of `fetchStats`).
 
   ## POS (Point of Sale)
 - **Main Interface**: `resources/js/Pages/PosMain.vue`
 - **Buttons**: In dark mode, quantity adjustment buttons (`btn-light`) and the delete button (`btn-soft-danger`) should use theme-aware glassmorphism or deep charcoal backgrounds to avoid a "stark white" or "quirky" appearance.
 - **Security**: Raw queries are restricted to `SELECT`, `SHOW`, and `DESCRIBE` for data retrieval; others use standard DB statements. Artisan commands are whitelisted.
 - **Dark Mode Overlays**: Global overlays such as the `.loading-overlay` in `application-layout.blade.php` must be dark-mode aware. Ensure `background: rgba(var(--bg-card-rgb), 0.7)` or themed variables are used instead of hardcoded white backgrounds (`rgba(255, 255, 255, 0.7)`).
 - **Hardcoded Backgrounds**: Avoid using `bg-white` or `bg-light` classes directly in Vue templates for components that should persist in dark mode (like modals in `PosMain.vue`). Use themed CSS variables or `:global(.dark-mode)` overrides.
- **listProductsData store resolution**: Must use sequential `if (!$targetStore)` guards, NOT `if/elseif`. A stale `access_key` in localStorage (e.g., a revoked key or session-specific token) must not block the `store_hash`/`session_hash` fallbacks. Priority order: access_key → session_hash → store_hash. Bug pattern: using `elseif` causes all global products to be shown when access_key is present but unrecognized.
- **Session Composable**: `resources/js/composables/Market/usePosSession.js` - Isolates POS initialization, session loading, and transaction completion logic. Use this in `PosMain.vue` and related components to ensure stable terminal identity and prevent logic fragmentation.
- **Session Hashkey Integrity**: The backend `PosController.php` must NOT truncate hashkeys at 36 characters. The `hashkey` field is 300 characters and can contain long uniquely generated identifiers. Incorrect truncation leads to 404 "Session not found" errors.
- **Performance Optimization**: To reduce perceived latency in local and production environments, the POS API uses **Request Consolidation**. The `addItem` and `removeItem` endpoints return the full current session object (with transactions and products) instead of just the single modified record. This eliminates the need for the frontend to make a second `loadSession` call, halving the total network delay for cart actions. Additionally, the backend implements **High-Efficiency SQL Paths**:
    - **Joined Lookups**: Product pricing and store overrides are fetched in a single combined query to reduce database round-trips.
    - **Aggregate Operations**: Session totals are calculated using database-side `SUM()` aggregates rather than memory-heavy PHP collection mapping.
    - **Lean Archiving**: The `PosSessionArchive` logic only captures raw session attributes (`getAttributes()`) rather than nested relationship trees, which significantly reduces JSON serialization overhead and database write bloat.
    - **Column Projection**: Eager loads are restricted to only necessary columns (`select(['id', 'hashkey', ...])`) to minimize the JSON payload size returned in the response.

 
## User Notes
- **Composable**: `resources/js/composables/useUserNotes.js`
- **Controller**: `app/Http/Controllers/Pages/AccountSettingsPageController.php`
- **Mechanics**: Fetches from `/user/note/content`. Also updated in real-time via SSE in `useSessionGuard.js`.
- **Security**: Requires `web` and `auth` middleware to ensure session persistence and prevent 302 redirects to login on AJAX calls.
- **Handling**: Frontend should strictly ignore HTML responses (which indicate redirects) to avoid displaying login page source code in the notes modal.

## Database Backups
- **Table**: `db_backups`
- **Model**: `App\Models\DbBackup`
- **Key Fields**: `hashkey`, `file_content_hashkey`, `filename`, `size_in_bytes`.
- **Logic**: Backups are generated as `.sql` files, compressed to `.7z` Ultra, and then stored as base64 in the `file_content` table. The `db_backups` table tracks these records. Temporary `.sql` and `.7z` files are deleted from the filesystem immediately after being saved to the database to prevent persistence on disk.
- **Exclusion**: The `db_backups` table is excluded from the SQL dump to prevent recursive growth.
- **UI**: Managed in `resources/js/Pages/UltimateConsole.vue` under the "Backups" tab.
- **Controller**: `app/Http/Controllers/Market/UltimateController.php`
 
## POS History
- **Component**: `resources/js/Pages/PosHistory.vue` - Standalone page for viewing a store's POS transaction history.
- **Route**: `/pos-history--h:STORE_HASH` (Mapped in `VueRouteMap.php`).
- **Logic**: Uses `PosHistoryList` component and `posStore` for paginated data retrieval.
- **Navigation**: In `PosMain.vue`, clicking the "Today: X txns" count navigates to this page.
- **Permissions**: Restricted to `ult`, `super operator`, `operator`, `store owner`, and `store manager`.

## Cart Module
- **Table**: `carts`, `cart_items`
- **Models**: `App\Models\Market\Cart`, `App\Models\Market\CartItem`
- **Controller**: `App\Http\Controllers\Market\CartController`
- **Page**: `resources/js/Pages/CartProductMarket.vue`
- **Logic**: Users have a single active cart. Cart items are linked to products from `prd_items`.
- **API Routes**: `/cart/get`, `/cart/add`, `/cart/update`, `/cart/remove`, `/cart/clear`.

## Global System Settings
- **Model**: `App\Models\SystemSetting.php` - Stores key-value configurations with caching.
- **Page**: `resources/js/Pages/SystemSettings.vue` - Admin interface for managing branding and system flags.
- **Helper**: `App\Support\SystemSettingsHelper.php` - Facade-like access for Blade and Controllers.
- **Branding**: Includes `app_name`, `app_logo`, `app_description`, `footer_text`, and `primary_color`. 
- **Dynamic Branding (Frontend)**: 
    - **Pattern**: Use `uiStore.appName` in Vue templates instead of hardcoded strings like "BukidBounty".
    - **Components**: `Home.vue`, `Login.vue`, `AccountSettings.vue`, and `HomePublic.vue` use this pattern.
    - **Tab Title**: Automatically managed via `uiStore.pageTitle`, which defaults to `appName`.
- **Inertia Shared Data**:
    - **Controller**: `App\Http\Controllers\Support\Inertia.php` - Automatically includes `systemSettings` in every `Inertia::render` call.
    - **Synchronization**: `app.js` populates the `uiStore` from `initialPage.props.systemSettings` immediately upon mounting. This eliminates the "flash" of default branding before the API background refresh completes.

## Common Modals & UI Components
- **BaseModal**: `resources/js/Components/Core/BaseModal.vue` - Standardized modal structure with header, body, and footer slots. Supports `v-model` for visibility.
- **ConfirmModal**: `resources/js/Components/Core/ConfirmModal.vue` - Specialized modal for action confirmations (Maintenance toggle, Backups, Flushes). Supports `danger`, `warning`, and `info` variants.
- **UltimateQueryModal**: `resources/js/Components/Ultimate/UltimateQueryModal.vue` - Advanced SQL console for ULTIMATE accounts, refactored to use `BaseModal` and theme-aware styling.
- **FileImage**: `resources/js/Components/Core/FileImage.vue` — emits a single `<img>` with `@error` fallback. The `:src` prop is forwarded as-is, so callers must pass a string URL. `photourl` from product endpoints may be `string | string[] | null`; passing `photourl[0]` when `photourl` is a string yields a 1-char URL that 404s. Use a safe accessor like `const firstPhoto = (v) => Array.isArray(v) ? (v[0] || '') : (v || '');` before binding.
- **FileList::resolvedUrl()**: `app/Models/FileList.php` (table `file_list`) returns `cdn_url` if non-empty, else `/RequestData/File/{hashkey}`. `str.photourl` is a JSON array of `file_list` hashkeys — raw hashkeys are NOT renderable URLs. `StoreController@viewStoreDetails` resolves them into `$store->resolved_photos` (array of usable URLs, cdn_url preferred); `ViewStoreMarket.vue` reads `store.resolved_photos` for its avatar/banner/photo-gallery modal.
- **CardSimple**: `resources/js/Components/Core/CardSimple.vue` — wrapper with `is-premium` defaulting to `true`, which adds a translucent background and a `translateY(-2px)` lift on hover. For non-interactive panels (page headers, search bars, info boxes), pass `:is-premium="false"` to disable the hover lift, otherwise the surrounding card jitters when the cursor moves over it.

## Cooperative Chapter Officer/Member Features
- **User types**: `COOP_OFFICER` ('coop officer'), `COOP_MEMBER` ('coop member') in `app/Enums/UserTypes.php`. Home fragments: `resources/js/Pages/Fragments/Home/HomeCoopOfficer.vue`, `HomeCoopMember.vue` (wired in `Home.vue`).
- **Controller**: `app/Http/Controllers/Support/ChapterController.php` — methods `getOrgChart`, `getOfficerScope`, `memberSearch`, `assignOfficer`, `createChapter`, `publicGetChapter`, `publicRegisterToChapter`.
- **Routes** (`routes/web.php`): authed `POST /Chapters/OrgChart`, `/Chapters/Officer/Scope`, `/Chapters/Members/Search`, `/Chapters/Officer/Assign`, `/Chapters/Create`; public `GET /api/public/chapter/{hkey}`, `POST /api/public/chapter/register`.
- **Composable**: `resources/js/composables/useChapters.js` — `fetchOrgChart`, `fetchOfficerScope`, `searchMembers`, `assignOfficer`, `createChapter`.
- **SPA pages** (VueRouteMap, module 'cooperatives'): `/chapter-org-chart`, `/coop-member-search`, `/create-coop-user`, `/assign-chapter-officer`, `/create-chapter`, `/register-chapter` (public; decodes base64 `payload` prop `{coop_hash,chapter_hash}`).
- **CHILD_LEVELS**: national→region→province→[city|municipal]→barangay. `chapters.level` enum has NO 'municipal' (peers in code only). Level checks use `in_array($level,['city','municipal'])`.
- **assignOfficer** MOVES a member (deactivate parent ChapterMember, create child officer row, upgrade COOP_MEMBER→COOP_OFFICER). **memberSearch** returns ONLY {name, role, chapter_name}. HomeCoopMember shows officer names + member count only (never fellow member names).
- **home-data**: COOP_OFFICER/COOP_MEMBER branches set `$props['props']['chapter_info']` + stats `chapter_member_count`/`child_chapter_count`/`new_members_7d`.
- **Duplicate-check endpoints**: authed `POST /admin/user/number/exists` (`mobile_number`), `POST /admin/user/username/exists` (`username`) → `{exists}`; public `POST /api/public/user/check-mobile`.

## Account Type Definitions (RBAC)
- **ULTIMATE**: full system access, bypasses all hierarchy checks.
- **SUPER_OPERATOR**: management of all entities except ULTIMATE accounts. Includes global store and POS key management.
- **OPERATOR**: management of multiple stores, farmers, and logistics (Shipments/POS Reports). Now includes global store and product management, and POS access keys.
- **COORDINATOR**: focused on logistics, organizations, and farm management.
- **RIDER**: delivery and shipment status updates only; blocked from user management.
- **POS_TERMINAL**: point-of-sale operations, viewing POS reports, and customer lists.
- **AUDIT**: read-only view of all system data (Global Reports, Transactions, Accounting, User Lists).
- **ANY_USER**: Standard system user with no administrative or logistics privileges.

## Page Access Controls
- **Setting Key**: `disabled_pages` (stored as JSON in `system_settings`).
- **Logic**: Enforced at both the backend (`VueRouteMap.php`) and the frontend navigation layer (`useNavigate.js`).
- **Management**: Controlled via the "Page Controls" tab in `UltimateConsole.vue`.
- **Backend API**: `SystemSettingsController@getPublicSettings` exposes the list to the frontend, and `SystemSettingsController@update` handles saving toggled states.
- **Sync Mechanism**:
    - **Initial Load**: `app.js` calls `uiStore.refreshSettings()` on startup.
    - **Background Refresh**: `app.js` runs a background interval calling `uiStore.refreshSettings()` every 1 minute to stay in sync.
    - **Pre-navigation Refresh**: `useNavigate.js` automatically triggers a refresh if settings are "stale" (older than 5 minutes) before evaluating the access guard. **Known Issue**: This threshold may cause a delay when a page is enabled/disabled until a reload or the 5-minute window expires.
    - **Sync Strategy**: Admin tools (e.g., `UltimateConsole.vue`) should manually trigger `uiStore.refreshSettings()` or `syncSettings()` after updating `disabled_pages` to ensure immediate session-wide consistency.
    - **Case-Insensitivity**: All disabled page checks are case-insensitive to ensure reliable blocking regardless of component naming conventions.
- **Affected Files**:
    - `resources/js/composables/Core/useNavigate.js` - Global navigation guard.
    - `resources/js/stores/ui.js` - Reactive store for `disabledPages` and `lastSynced` timestamp.
    - `app/Http/Controllers/Support/VueRouteMap.php` - Backend enforcement for direct URL access; implements `isUserAllowed` logic using `allowedUserTypes` key.
    - `app/Http/Controllers/Helpers/Permissions/UserPermissions.php` - Core RBAC engine mapping roles to `UserActions` enums.
    - `app/Http/Controllers/Admin/SystemSettingsController.php` - API bridge for public setting retrieval.
## System vs Account Settings
- **Account Settings**: `AccountSettings.vue` - User-specific profile and security settings (password, photo, basic info).
- **Management**: Controlled via the "Page Controls" tab in `UltimateConsole.vue`.
- **Global System Settings**: `SystemSettings.vue` - Administrative configuration for the entire platform (branding, maintenance, page controls).
- **Navigation**: In `HomeUltimate.vue` and other navigation menus, "Global System Settings" must point to the `SystemSettings` pagename, while "My Personal Profile" or "Account" points to `AccountSettings`.

## User Additional Details
- **Settings Field**: JSON column in `users` table.
- **Cooperatives**: Stored in `settings.cooperatives` as an array of organization hashkeys.
- **Composable**: `resources/js/composables/useUserAdditionalDetails.js`
- **Controller**: `app/Http/Controllers/UserManagement/UserAdditionalDetailsController.php`
- **Functionality**: Allows users to join/leave cooperatives via settings, and provides quick search by cooperative membership.
- **Sync**: Automatically synced in `CooperativeController::joinCooperative` to maintain consistency between `cooperative_members` table and user settings.

## SSE & Real-time Integration
- **Controller**: `app/Http/Controllers/Support/SSEController.php`
- **Mechanism**: Uses `Hypervel\Coroutine\Parallel` for concurrent fetching of multiple data streams (Stats, Customers, Inventory, Settings) to minimize latency.
- **Pulse Interval**: 5 seconds.
- **Syncing Logic**:
    - **Customers**: Employs a **First-Fetch vs Delta** strategy. Upon initial connection (or first fetch), the top 20 most recent customers are pushed to the client to "preload" search suggestions. Subsequent pulses only push records with `updated_at > lastSync` (deltas).
    - **Products (Marketplace)**: Precaches the full active product list for the global marketplace on the **first fetch** (`isFirstFetch`). Subsequent ticks send detailed product updates (price, stock, descriptions) as `inventory_deltas`.
    - **Inventory**: Product inventory updates (stock/price changes) are pushed as deltas based on the `lastSync` timestamp across all stores owned/managed by the user.
- **Frontend Integration**:
    - **Composable**: `resources/js/composables/Core/useSessionGuard.js` acts as the primary consumer and dispatches data to Pinia stores.
    - **Stores**: `pos.js` (`syncFromSSE`), `product.js` (`syncFromSSE`), and `ui.js` (`syncDisabledPages`) handle the reactive merge of incoming data into the UI state.
    - **Caching**: The `product.js` store maintains a `detailsCache` (Object/Map) of full product details to enable instant page transitions in the Marketplace and Product Detail views.

## Session Management & PWA
- **Multi-tab Logout**: Synchronized via both SSE (`isloggedin: false` payload) and a `localStorage` `storage` event (`logout_event` key). When any tab logs out, it clears `localStorage` and sets `logout_event`, which triggers an immediate redirect to `/login` in all other open tabs via the `useSessionGuard` composable.
- **SSE Connection**: Handled in `resources/js/composables/Core/useSessionGuard.js`. It maintains a persistent `EventSource` connection to `/sse/stream` for real-time updates and session monitoring. The backend `SSEController` explicitly sends an `isloggedin: false` message before closing the stream when a session is lost.
- **Service Worker Registration**: Managed in `resources/js/app.js`. To ensure persistent SSE and background features, the service worker should NOT be unregistered upon landing on the login page; automatic unregistration logic in `Login.vue` was removed to prevent "service worker deleted" issues.
- **Polling Fallback**: If SSE is unavailable, the system automatically falls back to a Web Worker (`session-guard-worker.js`) or main-thread interval polling to ensure session integrity.
- **Observability**: Console logs with the prefix `[SessionGuard]` provide observability into connection status, version changes, and logout events.
    - **Session Locking (SSE)**: Long-running SSE stream loops in PHP can lock the session associated with the request by default. This prevents concurrent requests from the same session (like logout, login, or any other middleware-protected route) from processing until the SSE thread yields. To avoid this "blocking" behavior, call `session()->save()` at the start of the loop in `SSEController` to release the lock immediately.

## User Management
- **Create User**: `resources/js/Pages/CreateUser.vue` - Main interface for creating new users.
- **Controller**: `app/Http/Controllers/UserManagement/CreateUserControllerUltimate.php`
- **Required Fields**: 
    - `mobile_number`: Unique, format `09XXXXXXXXX`.
    - `username`: Unique, required for all users.
    - `name`: Required (Display Name).
    - `password`: Min 6 characters.
    - `type`: User Type (via `UserTypes` enum).
- **Validation**: When the user clicks "Create User Account", a modal appears if any required fields are missing or invalid, listing them clearly with badges and a description of the requirements. This replaces the previous inline badge system.
- **Hierarchy**: Users can be assigned a `parentuid` (parent) to create a multi-level marketing or organizational hierarchy. The `listAllUsersforParentSelectHTML` method in the controller filters the parent list to only show the current user and their descendants, ensuring data isolation.

## Build & Deployment Standards
- **Requirement**: After any changes to the frontend (Vue components, assets) or backend logic, run the build and restart process to ensure the latest changes are active.
- **Build Process**:
    - Primary: `npm run build` (on host, if node/npm are installed).
    - Containerized Fallback: If `npm` is missing on the host, use a specialized Node container to build directly into the host filesystem:
      `docker run --rm -v "$(pwd)":/var/app -w /var/app node:latest /bin/sh -c "npm install && npm run build"`
- **Vite Version**: The project uses **Vite 7**, which requires **Node.js >= 22.12.0** or **>= 20.19.0**.
- **Container Restart**: After building assets, restart the main application container to refresh the Swoole service and pick up the new build:
  `docker restart bukidbountyapp`
- **Volume Mapping**: The application container mounts the current directory to `/var/app`, so build assets generated on the host are immediately visible to the container upon restart.
- **Branch Synchronization**: The `main` branch is periodically updated to match the `experimental` branch to promote stable experimental features to production. This is done via `git checkout main && git reset --hard experimental`.

## RBAC & Session Hardening Best Practices
- **User Type Listing (Dropdown Fix)**: The `CreateUserControllerUltimate@listAllUserTypesforSelectHTML` method must handle `UserTypes` enums directly. Avoid using `UserTypes::from($currentUser->acct_type)` if the `acct_type` attribute is already cast to the enum in the `User` model, as this will trigger a `TypeError`.
- **SPA Route Protection**: All sensitive management pages (e.g., `/create-user`) **MUST** be explicitly defined in `App\Http\Controllers\Support\VueRouteMap::$routes` with an `allowedUserTypes` array. If a route is not mapped, it defaults to allowing any authenticated user via the `handleSpa` catch-all, which creates a security vulnerability.
- **Session State Isolation**: To prevent "Role Leaking" (where a new user sees the previous user's dashboard fragments or cached roles), the `Login.vue` component must execute `sessionStorage.clear()` within its `onMounted` hook. This ensures a clean slate for every new authentication attempt.
- **Dashboard Fragmentation**: Dashboard fragments in `resources/js/Pages/Fragments/Home/` (e.g., `HomeShared.vue`, `HomeOperator.vue`) should implement `computed` filtering for action buttons based on `UserTypes` to ensure that unauthorized actions are not visible in the UI, even if the user has navigated to the dashboard correctly.

## Expanded Member Profile (Cooperative)
- **Table**: `user_infos`
- **Personal Details**: `firstname`, `middlename`, `lastname`, `suffix`, `gender`, `dob`.
- **Dynamic Context**: `priority_sector` (links to `priority_sectors` in system settings).
- **Social Accounts**: `messenger_id`, `viber_number`, `tiktok_username`.
- **Address Components**: `region`, `province`, `city`, `barangay`. Detailed address (House No, Street, Zip, Country) is stored in the `addresses` JSON column.
- **Family & Education**: `civil_status`, `children_count`, `dependent_count`, `education_level`, `course`, `school`, `year_last_attended`.
- **Employment & Livelihood**: `livelihood_source`, `last_company`, `employer_name`, `last_position`, `occupation`, `last_employment_year`.
- **Financial Details**: `monthly_income` (decimal), `bank_account_no` (string).
- **Government Info**: `tin`, `philhealth_id`, `gov_id`, `id_type`, `id_number`, `beneficiary_type`.
- **Emergency Contact**: `emergency_contact_name`, `emergency_contact_address`, `emergency_contact_phone`, `emergency_contact_relation`, `emergency_contact_user_id`.
- **Linking Logic**: The system automatically links emergency contacts by matching their phone number with an existing user's `mobile_number` in `UserInfoController@updateUserInfo`.
- **Virtual Attributes**: `age` (calculated on the fly from `dob`).

## Public Cooperative Registration
- **Route (Frontend)**: `/register-coop--h:HASHKEY` → `RegisterCoop.vue` (`loginRequired: false`).
- **Public API**: `GET /api/public/cooperative/{hkey}` returns coop info (no auth). `POST /api/public/cooperative/register` creates a new USER account and registers them as a MEMBER.
- **Controller Methods**: `CooperativeController@publicGetCooperative` and `CooperativeController@publicRegisterMember`.
- **Parent Assignment**: Uses the cooperative's `created_by` user as parent, falling back to first COORDINATOR, then first user.
- **Share Button**: In `CooperativeDetail.vue` → "Share Register Link" button uses the Web Share API on mobile (native dialog) and falls back to clipboard copy on desktop.

## Cooperative Membership Details
- **Table**: `cooperative_members`
- **Key Fields**: `membership_type`, `membership_level`, `officer_position`, `officer_level`, `concurrent_position`, `concurrent_level`, `cooperative_name_alt`, `cooperative_position`, `year_beginning`.
- **Management**: Membership details can be updated via `/Cooperatives/Member/Update`.
- **Self-Service Registration**: Users can register themselves as members via the `CooperativeMemberRegister.vue` page (route: `/cooperative-member-register--h:COOP_HASH`).
- **Registration Logic**: Handled by `CooperativeController@registerMember`. It automatically links the user to the organization and updates the `settings.cooperatives` array in the `users` table for session/preference synchronization.
- **Access Control**: Controlled by `UserActions::JoinCooperative`. Standard users, operators, and coordinators have this permission by default.
- **UI Integration**: A "Register as Member" button appears on the `CooperativeDetail.vue` page if the user is not yet a member. After registration, the button is hidden and the user appears in the members list.

## RBAC & Hierarchy Concepts
- **Big 3**: Refers to `ULTIMATE`, `SUPER_OPERATOR`, and `OPERATOR` account types. They have global management privileges, bypass standard organizational hierarchy checks, and are the only roles permitted to edit global product details (categories, base prices, etc.) in `ManageProductAdmin.vue`.
- **Hierarchy Management**: Management actions (Listing, Viewing, Editing) for stores and users are typically restricted to direct or indirect parents (ancestors). "Big 3" roles are immune to this restriction when accessing stores.
- **Store Managers**: Users assigned via the `store_managers` table who are granted delegated management access to a specific store.
- **Multi-Manager System**: Replaces the legacy single-manager field (`manager_id`) with a searchable, multi-select interface in `CreateStore.vue` and `EditStoreUltimate.vue`, allowing multiple users to be assigned as managers for a single store.
- **Context-Aware Product Locking**: A UI pattern in `ManageProductAdmin.vue` that hides or disables global product fields for non-"Big 3" users, while still allowing them to manage store-specific overrides if they are an owner or manager.

## POS Access Control (Hardened)
- **Helper**: `UserPermissions::isUserAllowedAccessToStore($user, $store)` - Centralized authorization check for POS/Reports access.
- **Logic**:
    - `ULTIMATE` users have global access.
    - Owners and Managers of the store have access.
    - Any ancestor of the Owner or Manager has access.
    - Children (e.g., `POS_TERMINAL`, `RIDER`) of the Owner or Manager have access.
- **Enforcement**: Applied to `PosController` methods: `startSession`, `getSession`, `getPosSessions`, `getTodayStats`, and `getCustomers`.
- **Ancillary Helper**: `UserPermissions::isAncestorOf($ancestor, $descendant)` - Recursively checks user hierarchy via `parentuid`.

## UI Audit Results (April 2026)
- **Navigation**: "My Personal Profile" now explicitly passes the current user's hashkey in HomeUltimate.vue.
- **Connectivity**: SSE connection refused (ERR_CONNECTION_REFUSED) is a known issue being investigated at the container/proxy level.
- **Functional Checks**: 
    - **UserInfoEdit**: Fixed hanging by ensuring loader always closes and defaults to current user.
    - **Create/Manage Store**: Confirmed functional with correct route mapping.
    - **Ultimate Console**: Operational with full monitoring and setting controls.
## Remote Development & Tunneling
- **Script**: `scripts/tunnel.sh` - Standardized script for creating a Cloudflare Tunnel to `localhost:9522`.
- **Port**: `9522` (Host) maps to `9501` (Container) for the `bukidapp` service.
- **Usage**: 
    - Temporary URL: `./scripts/tunnel.sh` (generates a `*.trycloudflare.com` link).
    - Persistent Tunnel: `./scripts/tunnel.sh <YOUR_TUNNEL_TOKEN>`.
- **Implementation**: Uses Docker `cloudflare/cloudflared` with `--network host` to expose the local development port online for testing and external access.

## Dokploy Deployment
- **Guide**: `dokploy-deployment-guide.md` (repo root) — Full step-by-step deployment guide.
- **Network**: All services (app, MySQL, DragonflyDB) must join `dokploy-network` (external: true) for DNS resolution.
- **Hostname Resolution**:
    - **Swarm services** (Dokploy-managed databases like MySQL): Use the **service name** as hostname (e.g., `prodservers-prodsqlmain-kv3yph`). Find via `docker service ls`.
    - **Compose services** (like DragonflyDB): Use the **full container name** as hostname (e.g., `prodservers-dragonflydb-rnfaje-dragonflydb-1`). Find via `docker ps --format '{{.Names}}'`.
- **Common Error — Redis DNS Lookup Failed**: Caused by `REDIS_HOST` pointing to a container name that is not on the same Docker network. Fix by adding `dokploy-network` to the DragonflyDB compose and using the correct container name.
- **Port Exposure**: Do NOT use host port mapping (e.g., `9522:9501`) in `docker-compose.yml` for Dokploy. Expose only the internal port (`9501`); Traefik handles external routing via auto-injected labels.
- **Variants**: Multiple app instances (prod, beta, test) can share the same MySQL server and DragonflyDB by using different `DB_DATABASE` names and `REDIS_DB` numbers (0–15).

## Landing Page Management
- **Table**: `landing_pages`
- **Model**: `App\Models\LandingPage`
- **Key Fields**: `title`, `html_content`, `description`, `hashkey`, `is_active`.
- **Active Constraint**: Only one landing page can be `is_active=true` at a time, enforced at the application level via `LandingPage::setAsActive()`.
- **Controller**: `App\Http\Controllers\Admin\LandingPageController`
- **Editor Page**: `resources/js/Pages/LandingPageEditor.vue` — Full CRUD interface with HTML editor, live preview, template snippets (hero/features/CTA), and card-based gallery view.
- **Guest Rendering**: `HomePublic.vue` fetches the active landing page via `/api/public/landing-page` and renders the HTML for unauthenticated visitors. Falls back to the default homepage if no active landing page exists.
- **Access Control**: Landing page management is restricted to `ULTIMATE`, `SUPER_OPERATOR`, and `COORDINATOR` roles.
- **RBAC**: `UserActions::ManageLandingPages` permission added to `$RoleswithNoTargetUser`.
- **Route Map**: Registered as `LandingPageEditor` in `VueRouteMap.php`.
- **Public API**: `GET /api/public/landing-page` (no auth) returns the active landing page HTML content.
- **Admin APIs**:
    - `POST /admin/landing-pages/list` — List all landing pages.
    - `POST /admin/landing-pages/show` — Get a single landing page by hashkey.
    - `POST /admin/landing-pages/store` — Create or update (if hashkey provided).
    - `POST /admin/landing-pages/set-active` — Set a page as active (deactivates all others).
    - `POST /admin/landing-pages/deactivate-all` — Deactivate all pages (revert to default homepage).
    - `POST /admin/landing-pages/delete` — Delete a landing page.

## CDN Asset Pipeline (jsDelivr / obj-vault-3a)
- **CDN Repo**: `telemagnadon/obj-vault-3a` on GitHub, served via jsDelivr.
- **Pinned Tag**: Configured in `config/cdn.php` (`base`) and `public/sw.js` (`CDN_SHA`). Current: `v2026.05.14-vendor` (SHA `927de981da85`).
- **Asset Path Convention**: `a/<sha256-12char>.<ext>`. Extension is `.bin` by default to obscure content type. Whitelist that **preserves original extension**: `.css`, `.js`, `.mjs`, `.json`, `.svg`.
- **SVG Critical**: jsDelivr serves all files with `Content-Type: application/octet-stream` + `X-Content-Type-Options: nosniff`. Browsers will render PNG/JPG inside `<img>` from octet-stream (image decoder sniffs bytes anyway), but **SVG requires `image/svg+xml`** — `<img src="*.bin">` containing SVG markup silently fails to render. Therefore SVGs MUST be stored as `a/<hash>.svg` so jsDelivr serves them with the correct MIME.
- **Pipeline Skill**: `cdn-asset-pipeline` (in `~/.claude/skills/`) handles sync. After updating extension whitelist, all SVG `.bin` files must be re-synced to `.svg` and orphaned `.bin` files removed.
- **CSS Relative URLs Break on CDN**: CSS files served from CDN use the flat `a/<hash>.<ext>` path, so any relative `url(...)` inside them (e.g. `@font-face src: url('icomoon.ttf')`) resolves to `a/icomoon.ttf` and 404s. **Fix**: rewrite any internal asset references in CSS to absolute jsDelivr URLs pointing at their published hashed `.bin`/`.svg`. Known offender: `public/assets/vendor/dist/alt-theme/icons-alipay.css` (icomoon @font-face). When breaking this, top-bar back/filter icons and bottom-nav home icon (any `.icon-*` class from icomoon) silently render blank.
- **Icomoon Font Path**: `public/assets/vendor/dist/alt-theme/icomoon.ttf` → CDN `a/c99ad0580805.bin`. Reference absolutely in `icons-alipay.css` so font loads regardless of where the CSS is hosted.
- **Icomoon Font Broken on jsDelivr (May 2026)**: The `.ttf` is published as `a/c99ad0580805.bin` and served as `application/octet-stream` with `X-Content-Type-Options: nosniff`. Chrome/Firefox refuse to use it as a font, silently breaking every `.icon-*` class. Same MIME-sniff problem the SVG migration solved. **Resolution**: don't use `icomoon` `.icon-*` classes in Vue components — use Font Awesome (`fas fa-*`, already loaded). Mappings used: `icon-home → fa-home`, `icon-left → fa-chevron-left`, `icon-right → fa-chevron-right`, `icon-copy2 → fa-copy`, `icon-filter → fa-sliders-h`. If icomoon is ever needed again, either add `.ttf/.woff/.woff2/.eot/.otf` to the CDN pipeline's preserve-extension whitelist and re-publish, or self-host the font under `/public` so Nginx sets the correct MIME.

## Service Worker & Caching
- **Hashed Assets**: Files under `/build/assets/` (generated by Vite) include hashes in their names.
- **Caching Strategy**: These files use a **Cache-First** strategy since their content is immutable for a given filename.
- **Expiration**: Cached for 6 months (`180 * 24 * 60 * 60` seconds) with a maximum of 1000 entries.
- **Implementation**: Configured in `public/sw.js` via Workbox `registerRoute`.


## Infrastructure & Docker
- **Main Service**: `bukidapp` - PHP Swoole/Hypervel application service. 
    - **Container Name**: Usually `bukidbountyapp-bukidapp-1` (or `bukidbountyapp-nginx-1` for the entry point).
- **Port**: Internal `9501`, exposed to the host/nginx.
- **Reverse Proxy**: Nginx acts as the entry point and reverse proxy, configured in `docker/nginx/default.conf`.
- **Static Asset Delivery**: Nginx serves files from `/public` directly (CSS, JS, images) to minimize latency and bypass the PHP/Swoole stack for static requests.
- **Docker Compose**: Managed via `docker-compose-local.yml` (development) and `docker-compose.yml` (production).
- **Service Dependency**: The `nginx` service depends on `bukidapp`.
- **Networking**:
    - Uses `dokploy-network` (external) for Traefik routing and cross-service communication.
    - Uses `app-internal` (bridge) as an **isolated network** for nginx→bukidapp communication to avoid DNS collisions.
    - **DNS Collision Warning**: On `dokploy-network`, multiple compose projects may share the same service name `bukidapp`. Nginx must NOT resolve `bukidapp` directly on this shared network. Instead, use a unique network alias (`swoole-upstream`) on the `app-internal` network.
    - **Upstream Alias**: The `bukidapp` service declares `aliases: [swoole-upstream]` on `app-internal`, and `docker/nginx/default.conf` targets `server swoole-upstream:9501`.
- **Priority Sectors**: Stored as a JSON array in `system_settings` under the key `priority_sectors`. Defines groups eligible for specific assistance and priority (e.g., FISHERMEN, SENIOR, PWD). Managed via the Global System Settings editor.
- **Group Types**: Stored as a JSON array in `system_settings` under the key `group_types`. Defines the categories of organizations (e.g., COOPERATIVE, ASSOCIATION).
- **Address Fields**: Stored as a JSON array in `system_settings` under the key `default_address_fields`. Defines the expected keys in the `user_infos.addresses` JSON (e.g., `house_no`, `street`, `zipcode`).
- **JSON Setting Editor**: A dynamic editor in `SystemSettings.vue` that supports array-based configurations with tag/badge management.

- **Dokploy Traefik Routing**:
    - Dokploy auto-injects Traefik labels on the first service by default.
    - **Domain Target**: In Dokploy UI → Domains tab, the service name MUST be set to `nginx` (not `bukidapp`), so Traefik routes `domain → nginx:80 → bukidapp:9501`.
    - Traefik uses Docker labels (not DNS) to find the target container, so the nginx service MUST be on `dokploy-network` for Traefik to reach it.
- **Local vs Production Volumes**:
    - **Local (`docker-compose-local.yml`)**: Uses bind mount `.:/var/app` for live code reloading during development. Nginx mounts `./public:/var/app/public` directly.
    - **Production (`docker-compose.yml`)**: Does **NOT** use bind mounts on `bukidapp`. The image is self-contained — `composer install` and `npm install` run during `docker build`, and the resulting `vendor/` and `node_modules/` are baked into the image.
    - **Shared Build Volume (Production)**: A named volume `public_build` shares Vite-built assets from bukidapp to nginx. bukidapp copies `/var/app/public/` to `/var/app/public-shared/` (the shared volume) on startup via the command `sh -c "cp -r /var/app/public/. /var/app/public-shared/ && exec php artisan serve"`. Nginx mounts this volume at `/var/app/public`.
    - **Why not bind mount in prod?**: The host's `./public` directory (from the repo clone) does NOT contain Vite build output — those are generated inside the bukidapp container during `docker build`. A bind mount would hide the built assets.
- **Dockerignore**: `.dockerignore` excludes `vendor/`, `node_modules/`, `.git`, and `.env*` to prevent host directories from overwriting dependencies installed during image build via `COPY . .`.


## Module Enable/Disable System
- **Purpose**: Allows enabling or disabling entire application modules (POS, Products, Accounting, etc.) via environment variables without code changes.
- **Config**: `config/modules.php` - Central registry of modules and their associated `MODULE_<NAME>_ENABLED` environment variables.
- **Master Toggle**: `MODULES_SYSTEM_ENABLED` - If set to `false`, all module-specific checks are bypassed (everything is enabled). Defaults to `true`.
- **Helper**: `App\Support\ModuleHelper::isEnabled($moduleKey)` - Used to check module status in code.
- **Middleware**: `module:<key>` (e.g., `module:pos`) - Applied to routes in `web.php` to block API/web access to disabled modules with a 403 response.
- **SPA Routing**: `VueRouteMap.php` - Each SPA route can be mapped to a module using the `'module'` key. The router (`handleSpa` and `registerRoutes`) automatically blocks access and redirects to `/` if the module is disabled.
- **Frontend Sync**: Module states are exposed via `SystemSettingsController@getPublicSettings` under the `module_states` key. This allows the frontend to reactively hide navigation links or UI elements for disabled modules.

## QRPH / EMV Payment QR
- **Standard**: QRPH is the Philippine QR payment standard based on EMVCo Merchant-Presented QR Code Specification (TLV encoding: 2-char tag + 2-char decimal length + value).
- **Decoder**: `app/Http/Controllers/Helpers/QrphDecoder.php` — parses raw QRPH strings into merchant name, network, account, validity (CRC-16/CCITT-FALSE), initiation method, currency.
- **Storage**: QRPH payment code is stored in `system_settings` under key `qrph_payment_code`.
- **Action**: `UserActions::ManageQrphPaymentCode` (`manageqrphpaymentcode`) — ULTIMATE-only via route middleware; listed in `$RoleswithNoTargetUser`.
- **Routes**:
    - `POST /Financial/Qrph/Get` — any authenticated user; returns raw string + decoded info for top-up display.
    - `POST /Financial/Qrph/Set` — `ultimate` middleware; saves QRPH code to system_settings.
    - `POST /Financial/Qrph/Decode` — `ultimate` middleware; decode-only preview (no save).
- **JS Composable**: `resources/js/composables/useQrph.js` — `parseTlv`, `injectAmount` (inserts EMV field 54 + recalculates CRC-16/CCITT-FALSE), `generateQrDataUrl` (renders QR via `qrcode` npm library — no external API).
- **Amount injection**: In `MyWallet.vue` QRPH tab, selecting an amount rebuilds the QRPH string client-side with the amount embedded, then renders a new QR — member's banking app (GoTyme, GCash, Maya, etc.) auto-fills the amount.
- **GoTyme / InstaPay GUIDs**: `QrphDecoder.php` recognises `com.gotyme`, `ph.ppmi`, `ph.bsp.qrph`, `com.p2pqrph` (and all major PH banks). Raw GUID is shown as fallback for unrecognised networks.
- **Top-Up UI**: `MyWallet.vue` top-up modal "Scan to Pay" tab: generates QR client-side with optional amount embedded; falls back to stored static image if no amount set.
- **Admin UI**: `AccountSettings.vue` shows a "Payment QR Code (QRPH)" card only for ULTIMATE accounts; drop-zone decodes QR image locally via `Html5Qrcode.scanFile`, uploads the image file, and shows Static/Dynamic badge.

## Known Bug Patterns & Fixes

### RBAC — Action Permission vs Page Access Mismatch
- VueRouteMap `allowedUserTypes` controls SPA page access; `UserPermissions::roles()` controls individual API action access. These must stay in sync.
- Example: `OPERATOR` listed in `/list-properties` `allowedUserTypes`, but `ViewProperties`/`ViewReferrals` were missing from `UserTypes::OPERATOR->value` in `roles()` → caused 403 on the `POST /admin/properties/list` API.
- Fix: always add the required `UserActions::*` to `roles()` whenever a role is added to `allowedUserTypes` for a page.

### SPA Catch-all — Undefined $moduleKey
- `VueRouteMap::handleSpa()` uses `$moduleKey` on line ~530 but only assigns it inside the `if/else` match blocks. If the path matches no known route, `$moduleKey` is undefined → potential 500.
- Fix: initialize `$moduleKey = null;` before the `if ($routeSettings)` block.
- `/bukidbountyapp` path is now registered in VueRouteMap as an alias of `Home` (no login required) to prevent it hitting the catch-all fallback.

### useUserNotes — Unauthenticated fetch
- `TopHeader.vue` calls `fetchNotes()` in `onMounted` unconditionally, firing `GET /user/note/content` (an auth-protected endpoint) before the user logs in.
- Fix: guard the call with `if (userStore.isLoggedIn)` in TopHeader, and add the same guard inside `useUserNotes::fetchNotes()` itself as a safety net.

### POS Access Key — STORE_OWNER / STORE_MANAGER missing create/delete/toggle permissions
- `/pos-access-keys` VueRouteMap allows `store owner` and `store manager`, but `roles()` only gave them `ViewPosAccessKeys`. Calls to create/delete/toggle keys returned 403.
- Fix: add `CreatePosAccessKey`, `DeletePosAccessKey`, `TogglePosAccessKey` to both `STORE_OWNER` and `STORE_MANAGER` in `UserPermissions::roles()`.
- **Default State**: All modules default to `true` (enabled) if the environment variable is missing.

## Database Table Names (canonical)

**Always reference these exact table names** in raw SQL, `unique:`/`exists:` validation rules, `DB::table(...)`, joins, and migrations. Several tables use abbreviated names — using the human/plural form (e.g. `stores`, `products`) causes `Table not found` SQL errors that Hypervel surfaces as a generic 400 with empty body.

### Market / Commerce
- `str` — **Stores** (model: `App\Models\Market\Store`)
- `prd_items` — **Products** (model: `App\Models\Market\Product`)
- `prd_str` — **Product↔Store pivot** (per-store price, stock, description, is_active)
- `prd_trx` — **Product Transactions** (model: `ProductTransaction`). Fields used by sales aggregation: `product_id`, `store_id`, `quantity`, `created_at`. `ProductController::viewProductDetails` aggregates `sold_today` (global) and `store_sold_today` (per-store, when a store hash is provided) by summing `quantity` filtered with `whereDate('created_at', today())`. Surfaced in `BuyViewProductMarket.vue` POS scan card alongside a `printPosCode()` button (opens a small window with QR + barcode and auto-`window.print()`/close).
- `prd_trx_ses` — **Product Transaction Sessions** (model: `ProductTransactionSession`)
- `prd_trx_ses_arc` — **Product Transaction Sessions Archive** (model: `ProductTransactionSessionArchive`)
- `cst` — **Customers** (model: `App\Models\Market\Customer`)
- `carts` — Carts
- `cart_items` — Cart Items
- `store_managers` — Store ↔ Manager User pivot (multi-manager system)
- `couriers` — Couriers
- `shipments` — Shipments
- `pos_access_keys` — POS Access Keys
- `pos_sessions` — POS Sessions
- `pos_sessions_archive` — Archived POS Sessions
- `pos_transactions` — POS Transactions

### Organizations / Cooperatives
- `organizations` — Organizations (cooperatives, associations, etc.)
- `main_organizations` — Top-level / parent organization records
- `org_str` — **Organization↔Store pivot** (cooperative-store linkage)
- `cooperative_members` — Cooperative Members
- `cooperative_documents` — Cooperative Documents
- `cooperative_resolutions` — Cooperative Resolutions
- `cooperative_votes` — Cooperative Votes
- `chapters` — Chapters
- `chapter_members` — Chapter Members
- `groups` — Groups
- `group_members` — Group Members
- `farmer_profiles` — Farmer Profiles

### Users / Auth / Accounting
- `users` — Users
- `user_infos` — User Info (addresses JSON, profile extras)
- `personal_access_tokens` — API personal access tokens
- `accounts` — Accounting accounts
- `account_transactions` — Account Transactions
- `member_ledgers` — Member Ledgers
- `global_transactions` — Global Transactions (cross-domain ledger)

### Properties / Referrals
- `properties` — Properties
- `referrals` — Referrals
- `referral_keys` — Referral Keys

### Files / System
- `file_list` — File List (uploaded file index)
- `file_content` — File Content (binary/blob storage)
- `landing_pages` — Landing Pages
- `announcements` — Announcements
- `system_settings` — System Settings (key/value, JSON values supported)
- `db_backups` — Database Backup records
- `logs` — Generic Logs
- `table_logs` — Per-table audit logs (model: `App\Models\Generic\TableLog`)

## Performance / Load-Testing API
- **Purpose**: Token-gated REST endpoints for hammering the box from a client machine over curl — exercise creation paths (users/stores/products) and the POS hot path while capturing per-op timing in milliseconds.
- **Controller**: `app/Http/Controllers/Market/PerformanceController.php` (acts as an `ULTIMATE` system user; pick a specific actor via env `PERF_ACTOR_HASH`).
- **Routes** (declared in `routes/api.php`, true API routes — NOT in `web.php`):
  - `GET  /api/perf/ping` — token check / health.
  - `POST /api/perf/seed/users` — body `{count, type?, parent_hash?, prefix?}`.
  - `POST /api/perf/seed/stores` — body `{count, owner_hash?, category?, prefix?}`.
  - `POST /api/perf/seed/products` — body `{count, target_store_hash?, attach_to_store?, prefix?}`.
  - `POST /api/perf/seed/batch` — body `{users?, stores?, products?, type?, category?, prefix?}` runs all three, returns per-phase ms.
  - `POST /api/perf/pos/simulate` — body `{store_hash, items?, cycles?, complete?}` runs N end-to-end POS cycles (open session → bulk insert N line items via raw `pos_transactions` insert → optional complete). Reports `avg/min/max cycle_ms` plus per-cycle `open_ms`/`add_items_ms`/`complete_ms`.
- **Auth**: header `X-Perf-Token: <env PERF_API_TOKEN>` (also accepted as `?token=` query/body). If env unset, every endpoint 403s — feature is off by default.
- **Limits**: each seeder is clamped to 1..1000 per call; POS sim is clamped to ≤200 items per cycle and ≤100 cycles per call.

### Rule of thumb
- Plural English names (`users`, `accounts`, `shipments`, `organizations`, `properties`, `couriers`, `carts`, `groups`, `chapters`, `announcements`, `landing_pages`, `system_settings`, `personal_access_tokens`) → safe to assume the table name matches.
- **Abbreviated tables** (`str`, `cst`, `prd_items`, `prd_str`, `prd_trx`, `prd_trx_ses`, `prd_trx_ses_arc`, `org_str`) → **never guess** — use the canonical name from this list.
- When writing `unique:<table>,<col>` or `exists:<table>,<col>` rules, look up the model's `protected ?string $table` value rather than pluralizing the model class name.