# Namespace Structure

This document details the namespace organization for both models and controllers in the BuyerKiosk application.

## Root Namespaces

| Namespace | Purpose |
|-----------|---------|
| `UserFrosting` | Framework core (auth, users, groups, base controllers) |
| `BuyerKiosk` | Business domain (all feature namespaces) |
| `ResalePerks` | External integration (loyalty/community) |
| `Slim\Extras\Middleware` | Slim framework extensions |

## BuyerKiosk Namespace Hierarchy

```
BuyerKiosk
├── Backstock             # Inventory management
├── Billing               # Billing/invoicing
├── Cash                  # Cash handling
├── ConstantContact       # Email marketing integration
├── CustomerSurvey        # Survey system
├── DailyReport           # Reporting
├── DigitalSign           # Digital signage
├── Employee              # Employee management (with providers)
├── FiveStars             # Loyalty integration
├── MobileApi             # Mobile app API
├── QuickBooks            # Accounting integration
├── Sales                 # Sales domain
├── Security              # Encryption/security
├── SellerMarketing       # SMS automation (Redis workers)
├── ServiceQueue          # Service queue
├── Shopify               # eCommerce integration
├── SimpleQueue           # Simple queue
├── SMS                   # Twilio/Vonage adapters
├── Stats                 # Statistics service
├── Support               # Help center
├── UserEmployee          # User-Employee linking
├── WhenIWork             # Scheduling integration
└── Workbook              # Workspace/daybook (tasks, notes, KPIs)
```

## Namespace by Feature Domain

### Core Business (`BuyerKiosk\*`)

| Namespace | Key Classes | Purpose |
|-----------|-------------|---------|
| `BuyerKiosk` (root) | `StoreController` | Store caching and initialization |
| `BuyerKiosk\Cash` | `CashActivity*`, `SafeConfiguration*` | Cash handling |
| `BuyerKiosk\Sales` | `SalesItem`, `BrandImporter` | Sales tracking |
| `BuyerKiosk\Stats` | `StatsCalculator` | Statistics generation |
| `BuyerKiosk\Billing` | `Invoice`, `Bill` | Billing entities |

### Workbook System (`BuyerKiosk\Workbook`)

| Class | Purpose |
|-------|---------|
| `TaskListManager` | Task management |
| `TaskCompletion`, `TaskAssignment` | Task tracking |
| `Note`, `NoteManager` | Notes system |
| `NoteReaction`, `NoteComment` | Note engagement |
| `WhiteboardManager` | Whiteboard features |
| `ScheduleManager` | Schedule management |
| `HomebaseSchedule`, `WhenIWorkSchedule` | External scheduling |
| `WorkbookAbly` | Realtime (Ably) |
| `KPIConfig`, `KPIService` | KPI tracking |

### Employee System (`BuyerKiosk\Employee`)

| Class | Purpose |
|-------|---------|
| `Employee` | Employee entity |
| `EmployeeManager` | CRUD operations |
| `EmployeeProviderInterface` | Provider contract |
| `HomegrownProvider` | Internal employee data |
| `HomebaseProvider` | Homebase integration |
| `WhenIWorkProvider` | WhenIWork integration |
| `SyncResult` | Sync operation results |

### User-Employee Linking (`BuyerKiosk\UserEmployee`)

| Class | Purpose |
|-------|---------|
| `UserEmployeeLink` | Link entity |
| `UserEmployeeLinkManager` | Link management |
| `EmployeeInvitation` | Invitation entity |
| `EmployeeInvitationManager` | Invitation workflow |
| `UserEmployeePromotion` | Role promotions |

### Backstock System (`BuyerKiosk\Backstock`)

| Class | Purpose |
|-------|---------|
| `Backstock` | Core backstock entity |
| `Bin`, `BinNamingService` | Bin management |
| `Category`, `Location` | Organization |
| `Event*`, `EventService` | Event-based tracking |
| `Action` | Inventory actions |
| `BackstockFactory` | Factory pattern |
| `ReportService` | Reporting |

### Marketing/SMS (`BuyerKiosk\SellerMarketing`)

| Class | Purpose |
|-------|---------|
| `SellerMarketingQueue` | SMS queue |
| `SellerMarketingBlast` | Blast campaigns |
| `SellerMarketingTrigger` | Trigger management |
| `SellerMarketingQueueProcessor` | Queue processing |
| `SellerMarketingTriggerProcessor` | Trigger processing |
| `RedisQueueManager` | Redis management |
| `SmsWorker*`, `SmsWorkerManager` | Worker processes |
| `OpenAIService` | AI integration |

### Support Portal (`BuyerKiosk\Support`)

| Class | Purpose |
|-------|---------|
| `Category`, `Article` | Help center content |
| `ArticleManager` | Article CRUD |
| `SearchManager` | Search functionality |
| `Reaction`, `Comment` | Engagement |
| `EditSuggestion` | Suggestion system |

### Integrations

| Namespace | Key Classes | Integration |
|-----------|-------------|-------------|
| `BuyerKiosk\QuickBooks` | `QuickBooks`, `AccountMapper`, `JournalEntryService` | QuickBooks accounting |
| `BuyerKiosk\FiveStars` | `API`, `Points`, `Reward`, `Sale` | FiveStars loyalty |
| `BuyerKiosk\Shopify` | `Sale` | Shopify eCommerce |
| `BuyerKiosk\WhenIWork` | `Employee` | WhenIWork scheduling |
| `BuyerKiosk\ConstantContact` | `ConstantContactController`, `ConstantContactService` | Email marketing |
| `BuyerKiosk\SMS` | `Twilio`, `Vonage` | SMS gateways |
| `ResalePerks` | `Contact`, `Feed`, `RemoteCheckIn` | Community integration |

## UserFrosting Framework Namespace

| Class | Purpose |
|-------|---------|
| `UserFrosting` | Main Slim extension |
| `BaseController` | Controller foundation |
| `AccountController` | Authentication |
| `AdminController` | Site administration |
| `UserController` | User management |
| `GroupController` | Permission groups |
| `InstallController` | System installation |

## Legacy (No Namespace)

Root-level classes in `models/Class/` without namespaces (legacy code):

- `Store`, `Buy`, `BuyQueue`, `BuyReport`
- `Customer`, `CustomerAlerts`
- `Loyalty*` (10+ classes)
- `MassSMSRobot`, `TriggerRobot`
- `ContactNumber`, `TextLog`
- And many others...

These are loaded via `BaseModel.php` include statements.

## Namespace Organization Patterns

### 1. Feature-Based Grouping
Each major feature has its own namespace (Workbook, Backstock, SellerMarketing).

### 2. Provider Pattern
Integration adapters follow the Provider interface pattern (Employee providers).

### 3. Manager Pattern
Complex domains use Manager classes for operations (EmployeeManager, ArticleManager).

### 4. Service Pattern
Business logic encapsulated in Service classes (KPIService, EventService).

## Related Documentation

- [Architecture Overview](./architecture-overview.md)
- [Controller Patterns](./controller-patterns.md)
- [Model Patterns](./model-patterns.md)