# Architecture Overview

This document provides a comprehensive overview of the BuyerKiosk application architecture, including the namespace hierarchy, directory structure, and key architectural patterns.

## Quick Stats

| Category | Count |
|----------|-------|
| **Model Classes** | ~200 PHP files |
| **Controller Classes** | 63 PHP files |
| **Namespaces (Models)** | 20+ organized namespaces |
| **Namespaces (Controllers)** | 22 organized namespaces |
| **Feature Domains** | 24 distinct domains |

## Technology Stack

- **Backend**: PHP 8.x
- **Framework**: Slim 2.6.2 (extended by UserFrosting)
- **Templating**: Twig 1.44.8
- **Database**: MySQL (multi-store architecture)
- **Caching**: Redis
- **Realtime**: Ably
- **SMS**: Twilio/Vonage

## Entry Points

```
public_html/index.php → userfrosting/initialize.php
```

## Directory Structure

```
userfrosting/
├── controllers/          # MVC controllers (63 files, 24 domains)
├── models/
│   ├── BaseModel.php     # Core utilities and class loader
│   ├── Class/            # Domain models (~200 files)
│   ├── mysql/            # MySQL implementation layer
│   └── Interface/        # Interface definitions
├── services/             # Business logic services
├── routes/               # Route definitions
│   ├── api.php           # API routes
│   └── groups/           # Grouped route definitions
├── templates/themes/default/  # Twig templates
└── patches/              # PHP 8.x compatibility fixes
```

## Multi-Store Architecture

BuyerKiosk operates as a multi-tenant system where each store has:

1. **TypeNum Identifier**: Pattern `[a-z][a-z]\d+` (e.g., `ou00`, `pa00`)
2. **Dedicated Database**: Named by typeNum (e.g., `kiosk_ou00`)
3. **Central Auth Database**: `kiosk_users` for authentication

### Store Access Pattern

```php
// Standard store initialization
$storeController = new \BuyerKiosk\StoreController($typeNum);
$store = $storeController->getStore();
$db = dbConnectByName($store->getDbName());

// Permission check
if (!$app->user->checkAccess('uri_store_settings')) $app->notAuthorized();
if (!$app->user->checkStoreGroup($typeNum)) $app->notAuthorized();
```

## Route Patterns

| Pattern | Purpose |
|---------|---------|
| `/:typeNum/` | Store operations (queue, workbook) |
| `/:typeNum/workbook/` | Workbook/daybook system |
| `/:typeNum/backstock/` | Backstock inventory |
| `/admin/:typeNum/` | Admin pages |
| `/api/` | API endpoints |
| `/api/mobile/` | Mobile app API |
| `/account/` | Authentication (login, register) |

## Architectural Tiers

```
┌─────────────────────────────────────┐
│         Presentation Layer          │
│   (Twig templates, JavaScript)      │
└──────────────────┬──────────────────┘
                   │
┌──────────────────▼──────────────────┐
│        Controller Layer             │
│  (Slim routes, Controllers)         │
└──────────────────┬──────────────────┘
                   │
┌──────────────────▼──────────────────┐
│         Service Layer               │
│  (Business logic, Workers)          │
└──────────────────┬──────────────────┘
                   │
┌──────────────────▼──────────────────┐
│          Model Layer                │
│  (Entities, Managers, Repos)        │
└──────────────────┬──────────────────┘
                   │
┌──────────────────▼──────────────────┐
│       Data Access Layer             │
│  (MySQL*, dbConnectByName)          │
└──────────────────┬──────────────────┘
                   │
┌──────────────────▼──────────────────┐
│           Database                  │
│  (Multi-store MySQL + Redis)        │
└─────────────────────────────────────┘
```

## Related Documentation

- [Namespace Structure](./namespace-structure.md)
- [Controller Patterns](./controller-patterns.md)
- [Model Patterns](./model-patterns.md)
- [Framework Migration Analysis](./framework-migration-analysis.md) - Slim/Twig upgrade assessment
- [Authentication Flow](../systems/authentication-flow.md)
- [Redis Worker System](../systems/redis-worker-system.md)