# Model Patterns This document details the model architecture, patterns, and conventions used in the BuyerKiosk application. ## Directory Structure ``` userfrosting/models/ ├── BaseModel.php # Include hub for all model classes ├── DatabaseCheck.php # Slim middleware for DB checks ├── DatabaseInterface.php # Interface definitions ├── DatabaseTable.php # DatabaseTable interface implementation ├── PageSchema.php # CSS/JS page asset registry ├── UFDatabase.php # Abstract database registry │ ├── Class/ # ~184 PHP files - Domain models │ ├── [Legacy Classes] # No namespace (loaded via BaseModel) │ ├── Backstock/ # BuyerKiosk\Backstock │ ├── Billing/ # BuyerKiosk\Billing │ ├── Cash/ # BuyerKiosk\Cash │ ├── Customer/ # Customer subdomain │ ├── CustomerSurvey/ # BuyerKiosk\CustomerSurvey │ ├── DailyReport/ # BuyerKiosk\DailyReport │ ├── DigitalSign/ # BuyerKiosk\DigitalSign │ ├── Employee/ # BuyerKiosk\Employee │ ├── FiveStars/ # BuyerKiosk\FiveStars │ ├── QuickBooks/ # BuyerKiosk\QuickBooks │ ├── ResalePerks/ # ResalePerks namespace │ ├── Sales/ # BuyerKiosk\Sales │ ├── Security/ # BuyerKiosk\Security │ ├── SellerMarketing/ # BuyerKiosk\SellerMarketing │ ├── ServiceQueue/ # BuyerKiosk\ServiceQueue │ ├── ShiftNotes/ # Shift note tracking │ ├── Shopify/ # BuyerKiosk\Shopify │ ├── SimpleQueue/ # BuyerKiosk\SimpleQueue │ ├── SMS/ # BuyerKiosk\SMS │ ├── Stats/ # BuyerKiosk\Stats │ ├── Support/ # BuyerKiosk\Support │ ├── SyncApp/ # Sync app management │ ├── UserEmployee/ # BuyerKiosk\UserEmployee │ ├── WhenIWork/ # BuyerKiosk\WhenIWork │ └── Workbook/ # BuyerKiosk\Workbook │ ├── mysql/ # MySQL implementation layer │ ├── MySqlDatabase.php # Connection & execution │ ├── MySqlDatabaseObject.php # Object persistence │ ├── MySqlObjectLoader.php # Data loading │ ├── MySqlAuthLoader.php # Auth data loading │ ├── MySqlUser.php # User entity │ ├── MySqlUserLoader.php # User loader │ ├── MySqlGroup.php # Group entity │ ├── MySqlGroupLoader.php # Group loader │ └── MySqlSiteSettings.php # Site settings │ └── Interface/ # Interface definitions └── SellerMarketing/ └── TriggerInterface.php # Trigger provider interface ``` ## Inheritance Hierarchies ### Store-Scoped Entities (extends Store) ``` Store (Base class for store-scoped entities) ├── Buy │ ├── DeletedBuy │ └── CompletedBuys ├── BuyQueue ├── BuyReport ├── Customer │ └── CustomerAlerts ├── ContactNumber ├── Employee ├── EmployeeDaily ├── EstimatedWaitTime ├── InstallKey ├── MobileAPIKey ├── ReceiptCoupon ├── RemoteCheckIn ├── StoreStat ├── TaskGroup ├── TaskList ├── TextInvoice ├── TextLog └── [Billing] Invoice, Bill ``` ### Loyalty System ``` LoyaltyCustomer (Loyalty base) ├── LoyaltyData └── LoyaltyResponse LoyaltyGroup (Loyalty container) ├── LoyaltyCoupon ├── LoyaltyMassSMS ├── LoyaltySMSMessage ├── LoyaltyTrigger └── LoyaltyUsageReport ``` ### Automation/SMS ``` Robot (Automation base) ├── MassSMSRobot ├── MassSMSFinder └── TriggerRobot ``` ### Backstock System ``` Backstock (Inventory base) ├── Action ├── Bin ├── BinNamingService ├── Category ├── Event ├── EventAlert ├── EventCategory ├── EventProgress ├── EventService ├── Location ├── Note └── ReportService ``` ### Daily Reports ``` BaseReport (DailyReport base) ├── EmailReport └── SalesReport ``` ### External Integrations ``` ResalePerks\Base ├── Contact │ ├── Feed │ └── RemoteCheckIn └── StoreFeed ``` ## Design Patterns ### 1. Manager Pattern Complex domains use Manager classes for CRUD and business operations. **Examples**: - `EmployeeManager` - Employee CRUD operations - `ArticleManager` - Support article management - `TaskListManager` - Task management - `NoteManager` - Notes system - `WhiteboardManager` - Whiteboard features - `ScheduleManager` - Schedule management - `UserEmployeeLinkManager` - User-employee linking **Usage**: ```php $manager = new \BuyerKiosk\Workbook\TaskListManager($db, $store); $tasks = $manager->getTodayTasks(); $manager->createTask($taskData); ``` ### 2. Repository Pattern Data access through dedicated Repository classes. **Examples**: - `CashActivityRepository` - Cash activity data access **Usage**: ```php $repo = new \BuyerKiosk\Cash\CashActivityRepository($db); $activities = $repo->findByDateRange($start, $end); ``` ### 3. Factory Pattern Complex object creation via factory classes. **Examples**: - `BackstockFactory` - Backstock instance creation - `CustomerSurveyFactory` - Survey creation **Usage**: ```php $factory = new \BuyerKiosk\Backstock\BackstockFactory($db, $store); $backstock = $factory->create($eventId); ``` ### 4. Provider Pattern Integration adapters following a common interface. **Examples**: ``` EmployeeProviderInterface ├── HomegrownProvider # Internal employee data ├── HomebaseProvider # Homebase integration └── WhenIWorkProvider # WhenIWork integration ``` **Usage**: ```php $provider = new \BuyerKiosk\Employee\WhenIWorkProvider($store); $employees = $provider->getEmployees(); $syncResult = $provider->sync(); ``` ### 5. Service Pattern Business logic encapsulated in Service classes. **Examples**: - `KPIService` - KPI calculations - `EventService` - Backstock event handling - `ReportService` - Report generation - `JournalEntryService` - QuickBooks journal entries - `QuickBooksService` - QuickBooks integration - `OpenAIService` - AI operations - `SearchManager` - Support search **Usage**: ```php $service = new \BuyerKiosk\Workbook\KPIService($db, $store); $kpis = $service->calculateTodayKPIs(); ``` ## Interface Implementations ``` DatabaseTableInterface ← DatabaseTable DatabaseInterface ← MySqlDatabase ObjectLoaderInterface ← MySqlObjectLoader, MySqlAuthLoader, MySqlGroupLoader, MySqlUserLoader DatabaseObjectInterface ← MySqlDatabaseObject, MySqlUser, MySqlGroup UserObjectInterface ← MySqlUser GroupObjectInterface ← MySqlGroup GroupLoaderInterface ← MySqlGroupLoader UserLoaderInterface ← MySqlUserLoader GroupUserLoaderInterface ← (implemented classes) SiteSettingsInterface ← MySqlSiteSettings EmployeeProviderInterface ← HomegrownProvider, HomebaseProvider, WhenIWorkProvider TriggerInterface ← DaysSinceSoldTrigger ``` ## Data Access Patterns ### 1. Direct Database Connection ```php $db = dbConnectByName($store->getDbName()); $result = $db->query("SELECT * FROM buys WHERE ..."); ``` ### 2. Store-Scoped Entity ```php class Buy extends Store { public function __construct($typeNum) { parent::__construct($typeNum); $this->loadBuyData(); } } ``` ### 3. MySQL Layer ```php $loader = new MySqlObjectLoader($db); $user = $loader->load('users', $userId); ``` ## Key Model Classes ### Core Business | Class | File | Purpose | |-------|------|---------| | `Store` | `Class/Store.php` | Store entity, config, integrations | | `Buy` | `Class/Buy.php` | Buy transaction | | `BuyQueue` | `Class/BuyQueue.php` | Queue management | | `Customer` | `Class/Customer.php` | Customer entity | | `Employee` | `Class/Employee.php` | Legacy employee | ### Workbook System | Class | File | Purpose | |-------|------|---------| | `TaskListManager` | `Class/Workbook/TaskListManager.php` | Task management | | `TaskCompletion` | `Class/Workbook/TaskCompletion.php` | Task tracking | | `Note` | `Class/Workbook/Note.php` | Notes entity | | `NoteManager` | `Class/Workbook/NoteManager.php` | Note operations | | `KPIService` | `Class/Workbook/KPIService.php` | KPI calculations | | `WorkbookAbly` | `Class/Workbook/WorkbookAbly.php` | Realtime | ### Employee System | Class | File | Purpose | |-------|------|---------| | `Employee` | `Class/Employee/Employee.php` | Employee entity (namespaced) | | `EmployeeManager` | `Class/Employee/EmployeeManager.php` | Employee operations | | `EmployeeProviderInterface` | `Class/Employee/EmployeeProviderInterface.php` | Provider contract | | `HomegrownProvider` | `Class/Employee/HomegrownProvider.php` | Internal provider | | `HomebaseProvider` | `Class/Employee/HomebaseProvider.php` | Homebase integration | | `WhenIWorkProvider` | `Class/Employee/WhenIWorkProvider.php` | WhenIWork integration | ### SMS/Marketing | Class | File | Purpose | |-------|------|---------| | `SellerMarketingQueue` | `Class/SellerMarketing/SellerMarketingQueue.php` | SMS queue | | `SmsWorkerManager` | `Class/SellerMarketing/SmsWorkerManager.php` | Worker management | | `RedisQueueManager` | `Class/SellerMarketing/RedisQueueManager.php` | Redis operations | | `Twilio` | `Class/SMS/Twilio.php` | Twilio adapter | | `Vonage` | `Class/SMS/Vonage.php` | Vonage adapter | ## BaseModel.php Loading `BaseModel.php` serves as the central include hub, loading ~200 classes in dependency order: 1. Core infrastructure (Store, Database) 2. Domain entities (Buy, Queue, Customer) 3. Feature subsystems (Workbook, SellerMarketing, Backstock) 4. Integration adapters (FiveStars, QuickBooks, Shopify, WhenIWork) ## Multi-Store Pattern Every store-scoped class follows this pattern: ```php class MyEntity extends Store { public function __construct($typeNum) { parent::__construct($typeNum); $this->db = dbConnectByName($this->getDbName()); } } ``` Or for non-Store classes: ```php class MyService { private $db; private $store; public function __construct($db, $store) { $this->db = $db; $this->store = $store; } } ``` ## Feature Development Phases | Phase | Feature | Key Classes | |-------|---------|-------------| | 2 | SellerMarketing | `SellerMarketing*`, `SmsWorker*` | | 3 | Workbook Tasks | `TaskListManager`, `TaskCompletion` | | 4 | Workbook Notes | `Note`, `NoteManager`, `NoteReaction` | | 5 | Workbook Whiteboard | `WhiteboardManager` | | 7 | Workbook Ably | `WorkbookAbly` | | 12 | User-Employee Linking | `UserEmployee*`, `EmployeeInvitation*` | ## Related Documentation - [Architecture Overview](./architecture-overview.md) - [Namespace Structure](./namespace-structure.md) - [Controller Patterns](./controller-patterns.md)