initial: bootstrap from BukidBountyApp base

ai-docs/modules/accountSettings.md

@@ -0,0 +1,23 @@
+# Account Settings Module
+
+## Purpose
+Manages user account settings including password changes, notes, and script execution.
+
+## Key Files
+- `app/Http/Controllers/Pages/AccountSettingsPageController.php` - Controller
+- `resources/js/Pages/AccountSettings.vue` - Vue component
+
+## Public APIs
+- `listDetails()` - List account details
+- `changepassword()` - Change user password
+- `logoutnow()` - Logout current user
+- `getUserNotes()` / `clearUserNotes()` - Note management
+
+## Dependencies
+- `App\Models\User`
+- `Hypervel\Support\Facades\Auth`
+
+## Important Behavior
+- Passwords are encrypted using bcrypt
+- Notes stored in user's notes field
+- Scripts can be executed via exec_command field

ai-docs/modules/auth.md

@@ -0,0 +1,24 @@
+# Auth Module
+
+## Purpose
+Handles user authentication, login, session management, and logout functionality. This module provides the foundation for all authenticated routes in the application.
+
+## Key Files
+- `resources/js/Pages/Auth/Login.vue` - Vue login component
+- `app/Http/Controllers/LoginController.php` - Authentication controller
+- `app/Models/User.php` - User model with authentication
+
+## Public APIs
+- `authenticate()` - Authenticate user via JWT
+- `extendcurrentSession()` - Extend current session lifetime
+- `setSessiontoKeepAlive()` - Keep session alive
+
+## Dependencies
+- `Hypervel\Support\Facades\Auth`
+- `App\Http\Controllers\Pages\Core\ApplicationController`
+
+## Important Behavior
+- Uses JWT-based authentication
+- Validates user credentials against database
+- Creates session upon successful login
+- Redirects to home page or returns JSON response based on request type

ai-docs/modules/cooperative_module.md

@@ -0,0 +1,71 @@
+# Module Planning: Cooperative Module
+
+## Overview
+The Cooperative Module manages associations of users (members) who work together, typically in agriculture. It integrates deeply with `user_infos` to provide a complete picture of each member.
+
+## Data Models
+
+### `Organization` (existing)
+Used to store the cooperative's main details.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `name` (String)
+- `type` (Enum: `COOPERATIVE`, `ASSOCIATION`, `COMPANY`)
+- `address` (Text)
+- `is_active` (Boolean)
+
+### `CooperativeMember` [NEW]
+Links users to cooperatives.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `organization_id` (Foreign Key to `organizations`)
+- `user_id` (Foreign Key to `users`)
+- `role` (String: `MEMBER`, `OFFICER`, `ADMIN`)
+- `joined_at` (DateTime)
+- `is_active` (Boolean)
+- `created_by` (Foreign Key to `users`)
+- `updated_by` (Foreign Key to `users`)
+
+### `UserInfo` [NEW]
+Detailed personal information for users, expanding the core `users` table.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `user_id` (Foreign Key to `users`)
+- `firstname` (String)
+- `middlename` (String)
+- `lastname` (String)
+- `fullname` (String) - Generated or stored
+- `landline` (String)
+- `mobile` (String)
+- `email` (String)
+- `alt_email` (String)
+- `alt_landline` (String)
+- `alt_mobile` (String)
+- `facebook_url` (String)
+- `bank_details` (JSON)
+- `addresses` (JSON) - Array of address objects
+- `other_details` (JSON)
+- `is_active` (Boolean)
+- `created_by` (Foreign Key to `users`)
+- `updated_by` (Foreign Key to `users`)
+
+## Core Workflows
+
+1. **Cooperative Management**: Creating and updating cooperative profiles (using `organizations` table).
+2. **Member Enrollment**: Adding users to a cooperative and assigning roles.
+3. **User Profile Completion**: Linking users to their detailed `userinfo` record.
+
+## API Endpoints (Proposed)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/cooperatives` | GET | List all cooperatives |
+| `/api/cooperatives/{hashkey}/members` | GET | List members of a cooperative |
+| `/api/cooperatives/{hashkey}/join` | POST | Request to join or add a member |
+| `/api/user-info/{user_hashkey}` | GET | Get detailed user info |
+| `/api/user-info/{user_hashkey}` | POST/PUT | Update detailed user info |
+
+## UI Components (Vue)
+- **CooperativeList.vue**: Standard list of cooperatives.
+- **CooperativeDetail.vue**: detailed view with member list.
+- **UserInfoEdit.vue**: Comprehensive form for editing personal details.

ai-docs/modules/farmer_management_module.md

@@ -0,0 +1,48 @@
+# Module Planning: Supplier/Farmer Management
+
+## Overview
+This module expands the basic member information into a full profile for producers (farmers/suppliers). It allows the system to track where products come from, verify farmer credentials, and manage relationships with cooperatives.
+
+## Data Models
+
+### `FarmerProfile`
+Extended details for a producer.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `user_id` (Foreign Key to `users`)
+- `organization_id` (Foreign Key to `organizations/cooperatives`, nullable)
+- `farm_name` (String)
+- `farm_location` (Point/Coordinates or Text)
+- `main_crops` (JSON/Array of strings)
+- `verification_status` (Enum: `UNVERIFIED`, `PENDING`, `VERIFIED`, `REJECTED`)
+- `certification_details` (JSON)
+- `created_by` (Foreign Key to `users`)
+- `updated_by` (Foreign Key to `users`)
+- `is_active` (Boolean)
+
+### `FarmerProductMapping`
+Links farmers to the specific products they supply to stores.
+- `farmer_id` (Foreign Key to `farmer_profiles`)
+- `product_id` (Foreign Key to `products`)
+- `supply_capacity` (Decimal/Unit)
+- `harvest_season` (String)
+
+## Core Workflows
+
+1. **Farmer Registration**: Capturing the detailed "Member Information" as seen in the README.
+2. **Profile Verification**: Admin review of submitted documents and farm location.
+3. **Product Sourcing**: Linking products in the store to their original farmer sources for traceability.
+
+## API Endpoints (Proposed)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/farmers` | GET | List all farmers (filtered by org/admin) |
+| `/api/farmers` | POST | Register a new farmer profile |
+| `/api/farmers/{hashkey}` | GET | Get farmer details |
+| `/api/farmers/{hashkey}/verify` | PATCH | Update verification status |
+
+## UI Components (Vue)
+- **FarmerProfileEdit.vue**: Comprehensive form for farmer details.
+- **FarmerDirectory.vue**: Searchable list of registered farmers.
+- **VerificationDashboard.vue**: Admin interface for approving farmer applications.

ai-docs/modules/files.md

@@ -0,0 +1,23 @@
+# Files Module
+
+## Purpose
+Handles file uploads and management operations including photos, documents, and binary files.
+
+## Key Files
+- `app/Http/Controllers/FilesMainController.php` - File upload controller
+- `app/Models/FileContent.php` - File content model
+- `app/Models/FileList.php` - File list metadata model
+
+## Public APIs
+- `uploadFilefromRequest()` - Upload file from request
+- `viewFilebyFileListHash()` - View file by hash key
+
+## Dependencies
+- `App\Models\FileContent`
+- `Hypervel\Support\Facades\Storage`
+
+## Important Behavior
+- Stores files in binary format via FileContent model
+- Tracks metadata in FileList model
+- Supports various file categories
+- Returns file content with proper headers for download/viewing

ai-docs/modules/home.md

@@ -0,0 +1,23 @@
+# Home Module
+
+## Purpose
+Provides the main application shell and home page functionality. Includes layout fragments, top header, and bottom navigation.
+
+## Key Files
+- `resources/js/Pages/Home.vue` - Main home component
+- `resources/js/Pages/Fragments/Home/HomePublic.vue` - Public home fragment
+- `resources/js/Pages/Fragments/Home/HomeUltimate.vue` - Ultimate user home fragment
+- `app/Http/Controllers/Pages/Core/HomeController.php`
+
+## Public APIs
+- `render()` - Renders the main application shell
+
+## Dependencies
+- `TopHeader` - Header component
+- `BottomNav` - Bottom navigation component
+- `BaseModal` - Modal component
+
+## Important Behavior
+- Uses Pinia stores for state management (user, UI, network)
+- Async component loading based on current page
+- Global navigate helper available via `$navigate`

ai-docs/modules/market.md

@@ -0,0 +1,28 @@
+# Market Module
+
+## Purpose
+Manages product and store operations for the multi-vendor marketplace. Handles product CRUD, store management, and transaction tracking.
+
+## Key Files
+- `app/Http/Controllers/Market/ProductController.php` - Product controller
+- `app/Http/Controllers/Market/StoreController.php` - Store controller
+- `app/Models/Market/Product.php` - Product model
+- `app/Models/Market/Store.php` - Store model
+
+## Public APIs
+- `createNew_Admin()` - Create product for admin
+- `editProductAdmin()` - Edit product
+- `AddProducttoStore()` / `RemoveProductFromStore()`
+- `store()` - Create new store
+- `update()` - Update store
+
+## Dependencies
+- `App\Models\Market\Product`
+- `App\Models\Market\Store`
+- `App\Models\User`
+
+## Important Behavior
+- Products can belong to multiple stores (belongsToMany)
+- Supports categories and subcategories via enums
+- Tracks transaction sessions per store
+- Store-product relationship with pivot data (available, price, is_active)

ai-docs/modules/pages.md

@@ -0,0 +1,25 @@
+# Pages Module
+
+## Purpose
+Handles page rendering and server-side Vue component delivery. Provides unified approach for both SPA (client-side) and traditional server-rendered pages.
+
+## Key Files
+- `app/Http/Controllers/viewHelperController.php` - Main page controller
+- `resources/js/Pages/Fragments/Home/*.vue` - Home page fragments
+- `app/Http/Controllers/PageMemoryController.php`
+
+## Public APIs
+- `servePageFragment()` - Render page without template
+- `servePageFragmentWithTemplate()` - Render page with layout template
+- `getDefaultDataVariables()` - Get default view variables
+- `getAllViews()` - Get all available views
+
+## Dependencies
+- `App\Enums\UserTypes` - Role enum
+- `App\Http\Controllers\Pages\Core\ApplicationController`
+
+## Important Behavior
+- Routes pages via `/p/{page}/s/` pattern
+- Uses viewMap config for page-to-view mapping
+- Supports public and authenticated routes
+- Returns base64-encoded HTML for SPA navigation

ai-docs/modules/shipment_module.md

@@ -0,0 +1,56 @@
+# Module Planning: Shipment & Logistics
+
+## Overview
+The Shipment Module handles the movement of products from stores to customers. It tracks the status of deliveries, manages courier information, and provides updates to both sellers and buyers.
+
+## Data Models
+
+### `Shipment`
+Tracks an individual delivery process.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `transaction_id` (Foreign Key to `global_transactions` or `pos_transactions`)
+- `store_id` (Foreign Key to `stores`)
+- `customer_id` (Foreign Key to `cst`)
+- `courier_id` (Foreign Key to `couriers`, nullable)
+- `tracking_number` (String, Unique)
+- `status` (Enum: `PENDING`, `PICKED_UP`, `IN_TRANSIT`, `DELIVERED`, `FAILED`, `RETURNED`)
+- `origin_address` (Text)
+- `destination_address` (Text)
+- `estimated_delivery_date` (DateTime)
+- `actual_delivery_date` (DateTime)
+- `shipping_fee` (Decimal)
+- `created_by` (Foreign Key to `users`)
+- `updated_by` (Foreign Key to `users`)
+- `is_active` (Boolean)
+
+### `Courier`
+External or internal delivery services.
+- `id` (Primary Key)
+- `hashkey` (String, Unique)
+- `name` (String, e.g., "J&T Express", "Lalamove", "Local Rider")
+- `contact_number` (String)
+- `type` (Enum: `EXTERNAL`, `INTERNAL`)
+- `is_active` (Boolean)
+
+## Core Workflows
+
+1. **Shipment Creation**: Triggered when an order is confirmed or a "Create Shipment" action is performed in the POS.
+2. **Courier Assignment**: Assigning a courier to a pending shipment.
+3. **Status Updates**: Manual or API-based updates as the package moves.
+4. **Delivery Confirmation**: Final status update and timestamp recording.
+
+## API Endpoints (Proposed)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/shipments` | GET | List all shipments (filtered by store/user) |
+| `/api/shipments` | POST | Create a new shipment |
+| `/api/shipments/{hashkey}` | GET | Get shipment details |
+| `/api/shipments/{hashkey}/status` | PATCH | Update shipment status |
+| `/api/couriers` | GET | List active couriers |
+
+## UI Components (Vue)
+- **ShipmentList.vue**: Dashboard for tracking multiple deliveries.
+- **ShipmentDetail.vue**: detailed view of a single shipment with timeline.
+- **CreateShipmentModal.vue**: Form to initialize a shipment for an order.

ai-docs/modules/transferCredits.md

@@ -0,0 +1,20 @@
+# Transfer Credits Module
+
+## Purpose
+Handles credit transfers between users within the marketplace system.
+
+## Key Files
+- `app/Http/Controllers/Pages/TransferMyCreditPageController.php` - Controller
+- `resources/js/Pages/TransferMyCredit.vue` - Vue component
+
+## Public APIs
+- `Response_TransferMyCredit()` - Transfer credits to another user
+
+## Dependencies
+- `App\Models\User`
+- `Hypervel\Support\Facades\Auth`
+
+## Important Behavior
+- Transfers credit balance between users
+- Validates user existence before transfer
+- Updates total_credit fields for both parties

ai-docs/modules/userManagement.md

@@ -0,0 +1,28 @@
+# User Management Module
+
+## Purpose
+Manages user lifecycle including creation, modification, role assignment, and permission control. Provides hierarchical user role system with 13 distinct roles.
+
+## Key Files
+- `app/Http/Controllers/UserManagement/CreateUserControllerUltimate.php` - User creation controller
+- `app/Http/Controllers/Pages/UserModifyAdminPageController.php` - Admin user management controller
+- `app/Http/Controllers/Pages/UserListPageController.php` - User list controller
+- `app/Enums/UserTypes.php` - User role enumeration
+
+## Public APIs
+- `CreateUser()` - Create new user with validation
+- `Response_ListChildrenofCurrentUser()` - Get user's children
+- `Response_UserDetails()` - Get user details by ID
+- `Response_DisableUser()` / `EnableUser()` / `DeleteUser()`
+- `listAllUserTypesforSelectHTML()` - Get all user types for dropdown
+
+## Dependencies
+- `App\Enums\UserActions` - Permission actions
+- `App\Http\Controllers\Helpers\Permissions\UserPermissions` - Role permissions
+
+## Important Behavior
+- Validates mobile number and username uniqueness
+- Creates users with encrypted password
+- Supports hierarchical user structure (parent/children)
+- Role assignment via `Response_ChangeUserRoles()`
+- Permissions checked via `canDo()` method on User model