BarangaySystem/ai-docs/architecture.md

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