initial: bootstrap from BukidBountyApp base

ai-docs/architecture.md

@@ -0,0 +1,90 @@
+# Architecture
+
+## Major Modules
+
+### User Management Module
+- **Purpose**: Handles user authentication, roles, and permissions
+- **Key Components**:
+  - `User` model with hierarchical relationships (parent/children)
+  - 13 user types via enum (Ultimate through Public)
+  - Permission system via `UserActions` enum
+- **Location**: `app/Models/User.php`, `app/Enums/UserTypes.php`
+
+### Market Module
+- **Purpose**: Product and store management
+- **Key Components**:
+  - `Product` model - Products with categories, stores relationship
+  - `Store` model - Stores with products via belongsToMany
+  - `ProductTransaction` models - Transaction tracking
+- **Location**: `app/Models/Market/`
+
+### File Management Module
+- **Purpose**: File upload and management system
+- **Key Components**:
+  - `FileContent` model - Binary file storage
+  - `FileList` model - File metadata
+- **Location**: `app/Models/FileContent.php`, `app/Models/FileList.php`
+
+## Module Interactions
+
+```
+User (Auth) → Middleware → Controllers → Models
+                             ↓
+                        Market Models
+                             ↓
+                        File Management
+```
+
+### Authentication Flow
+1. User attempts to access protected route
+2. `Authenticate` middleware checks session/JWT
+3. User object loaded with roles and permissions
+4. Route middleware (`auth`, `ultimate`, etc.) validates access
+
+## Data Flows
+
+### Login Flow
+```
+POST /post/loginnow → LoginController@authenticate
+  ↓
+Auth::attempt() (JWT-based)
+  ↓
+Session created via Hypervel\Session
+  ↓
+Redirect to home or return JSON response
+```
+
+### User Creation Flow
+```
+POST /admin/user/create → CreateUserControllerUltimate@CreateUser
+  ↓
+Validate data (mobile number, username uniqueness)
+  ↓
+Create user record with encrypted password
+  ↓
+Return success/error response
+```
+
+### Product View Flow
+```
+POST /View/Product/Details/data → ProductController@viewProductDetails
+  ↓
+Fetch product by ID
+  ↓
+Fetch associated stores
+  ↓
+Return product data with store info
+```
+
+## External Services
+
+- **Redis**: Caching layer (configurable via CACHE_DRIVER)
+- **Session Storage**: Database-backed sessions
+- **File Storage**: Local filesystem (via Flysystem)
+
+## Architectural Patterns
+
+- **MVC Pattern**: Models-Views-Controllers separation
+- **SPA Architecture**: Single Page Application with Vue Router
+- **Middleware Chain**: Request filtering via Hypervel middleware
+- **Enum-based Roles**: Type-safe user role system