# Laravel Structure — Blazma LIMS

## 1. Directory Reference Map

```
app/
├── Console/
│   └── Commands/                    # Artisan commands (20+)
│       └── UpdateAiDocumentation.php  # Sprint documentation updater
├── Exports/                         # Maatwebsite Excel exports (20+)
│   ├── InvoicesExport.php
│   ├── SalesExport.php
│   └── ...
├── Http/
│   ├── Controllers/
│   │   ├── AiRecommendationController.php
│   │   ├── AlertController.php
│   │   ├── ApiController.php
│   │   ├── AyenatiController.php
│   │   ├── BranchIncomeController.php
│   │   ├── CommandCenterController.php
│   │   ├── Controller.php              # Base controller
│   │   ├── DiabeticDashboardController.php
│   │   ├── ErpController.php
│   │   ├── FitTestController.php
│   │   ├── GeneticsExtractionController.php
│   │   ├── HlController.php
│   │   ├── InsuranceController.php
│   │   ├── InvoiceController.php
│   │   ├── LabController.php           # Core lab operations
│   │   ├── LdmController.php
│   │   ├── LiveHealthController.php
│   │   ├── LoyaltyController.php
│   │   ├── MetadataController.php
│   │   ├── MyHealthController.php
│   │   ├── NewSalesController.php
│   │   ├── NotificationController.php
│   │   ├── Operations/                 # Operations panel controllers
│   │   │   └── OperationsController.php
│   │   ├── OperationsController.php
│   │   ├── PayfortController.php
│   │   ├── PaymentController.php
│   │   ├── QuestionnaireController.php
│   │   ├── SalesController.php
│   │   ├── SalesForecastController.php
│   │   ├── TamaraController.php
│   │   ├── TapController.php
│   │   ├── TerminalController.php
│   │   ├── UserController.php
│   │   ├── V2/                         # API v2 controllers
│   │   ├── WarehouseController.php
│   │   ├── WebController.php           # Main patient-facing controller
│   │   ├── WebhookController.php
│   │   ├── WhitelabelController.php
│   │   └── ZatcaController.php
│   └── Middleware/
│       ├── AccessTokenOptional.php
│       ├── AccessTokenValidation.php
│       ├── Authenticate.php
│       ├── AyenatiTokenAuth.php
│       ├── CorsMiddleware.php
│       ├── ExampleMiddleware.php
│       ├── LdmAuth.php
│       ├── MetaDataAuth.php
│       ├── NormalizeSlashes.php
│       ├── NupcoAuth.php
│       ├── OperationsAuth.php
│       ├── RedirectToPayment.php
│       ├── TerminalAuth.php
│       └── WebAuth.php
├── Imports/                         # Excel imports (10)
├── Jobs/                            # Queue jobs (49) — see business_flows.md
├── Models/
│   ├── Base/                        # Abstract/base model classes
│   │   ├── ENDUSERLABORDERHISTORY.php
│   │   ├── ENDUSERINVITE.php
│   │   └── ...
│   ├── ACCOUNTMANAGER.php
│   ├── ADDRESSTITLE.php
│   ├── ADDRESSTYPE.php
│   ├── ALERT.php
│   ├── ... (431 total models)
│   ├── DiabeticPatientVisit.php    # lowercase table models
│   └── ZATCAINVOICE.php
├── Services/
│   ├── Alert/                       # Alert system services
│   ├── AiRecommendationReportService.php
│   ├── ApiService.php
│   ├── Ayenati/
│   │   └── AyenatiService.php
│   ├── BranchIncomeService.php
│   ├── CommandCenterService.php
│   ├── EmailService.php
│   ├── EndUserService.php           # Patient management
│   ├── ERP/                         # ERP integration services
│   ├── FCMService.php               # Firebase push
│   ├── FileService.php              # S3 file management
│   ├── FlagService.php              # Feature flags
│   ├── HESNPlusService.php          # HESN Plus integration
│   ├── HESNService.php              # HESN legacy
│   ├── HL7Service.php               # HL7 messaging
│   ├── IntegratedReportService.php
│   ├── LabService.php               # Core lab operations
│   ├── LanguageService.php
│   ├── LdmService.php
│   ├── LeanAPIService.php
│   ├── LinkService.php
│   ├── LivehealthService.php
│   ├── LogService.php
│   ├── Master/                      # Core domain services
│   ├── Metadata/                    # Lookup/reference data services
│   ├── MTCService.php
│   ├── MyHealthAiService.php        # OpenAI integration
│   ├── MyHealthService.php
│   ├── NearPayService.php
│   ├── NewSalesService.php
│   ├── NormalReportService.php      # PDF report generation
│   ├── NormalReportServiceV2.php
│   ├── NphiesService.php            # NPHIES insurance
│   ├── Notification/                # Notification services
│   ├── PayfortService.php
│   ├── PaymentService.php
│   ├── QRService.php
│   ├── SalesService.php
│   ├── SmartReportService.php
│   ├── SMSService.php               # SMS (Unifonic/ConnectSaudi)
│   ├── SymbolsService.php
│   ├── TamaraService.php
│   ├── TapService.php
│   ├── TaxService.php
│   ├── TemplateReportService.php
│   ├── TemplateReportV2Service.php
│   ├── TerminalService.php
│   ├── WarehouseService.php
│   ├── WhatsAppService.php
│   └── Zatca/                       # ZATCA e-invoice services
└── helpers.php                      # Global helper functions
```

---

## 2. Routes Structure (`routes/web.php`)

The single `web.php` file contains **1,596 routes** organized into functional groups:

### Route Groups:

#### Public Routes (no auth)
```
GET  /                          → WebController::index / showProfileIndex
GET  /package                   → showPackages
GET  /providers                 → showProviders
GET  /{HospitalID}/lab          → showLab
GET  /signin, /signup           → auth pages
POST /signup, /email/signup     → Signup, SignupEmail
POST /verify_mobile_no          → VerifyMobileNo
GET  /recommended-tests         → showRecommendedTests
GET  /blogs, /blogs/{id}        → Blog pages
GET  /terms, /polices, /faq     → Static pages
```

#### Authenticated Routes (WebAuth middleware)
```
GET  /cart                      → showCart
POST /cart/update               → ManageCartItem
DELETE /cart/{id}               → DeleteCartItem
GET  /confirm                   → ShowConfirm
POST /order                     → Order
POST /cod_order                 → CODOrder
POST /credit_order              → CreditOrder
GET  /orders                    → ShowResults
GET  /orders/{id}               → showOrderDetails
GET  /wallet                    → ShowWallet
GET  /artificial-intelligence   → showArtificialIntelligence
GET  /profile                   → showProfile
GET  /notifications             → showNotifications
```

#### API Routes (AccessToken middleware)
```
Prefix: /api/...
Auth: Bearer token in Authorization header
Returns: JSON
```

#### Lab Operations Routes
```
LabController: sample operations, analyzer results, QC
LdmController: LDM integration endpoints
HL7 Controller: HL7 message handling
```

#### Admin/Operations Routes (OperationsAuth middleware)
```
Operations/OperationsController: internal admin panel
UserController: system user management
```

#### Payment Callbacks
```
GET  /order/check               → CheckPrepaidOrder (PayFort)
GET  /tamara/order/check        → CheckTamaraOrder
POST TapController::TapFeedback
POST PayfortController::PayFortTransactionFeedback
POST TamaraController::TamaraFeedback
```

#### Webhook Routes
```
WebhookController: external system webhooks
```

---

## 3. Service Container Bindings

Services are auto-resolved via Laravel's container. Constructor injection is the standard pattern:

```php
// In controller
public function __construct(
    private LabService $labService,
    private TaxService $taxService
) {}

// In service
public function __construct(
    private FCMService $fcmService,
    private SMSService $smsService
) {}
```

---

## 4. Key Eloquent Model Patterns

### 4.1 PROFILE model (central tenant model)
```php
class PROFILE extends Model
{
    protected $table = 'PROFILE';
    // 150+ fillable columns
    // Feature flags via boolean attributes
    // Per-profile configuration
}
```

### 4.2 END_USER model
```php
class ENDUSER extends Model
{
    protected $table = 'END_USER';
    // Patient data, wallet, insurance, AI data
    // Relationships: orders, cart, notifications, members
}
```

### 4.3 ENDUSERLABORDERPACKAGE (most complex model)
```php
class ENDUSERLABORDERPACKAGE extends Model
{
    protected $table = 'END_USER_LAB_ORDER_PACKAGE';
    // 50+ relationships
    // Tracks entire sample lifecycle
    // References: 15+ staff roles, payment, insurance, QC
}
```

---

## 5. Queue Configuration

```php
// config/queue.php
'default' => env('QUEUE_CONNECTION', 'redis'),

'connections' => [
    'redis' => [
        'driver'  => 'redis',
        'queue'   => env('REDIS_QUEUE', 'default'),
        'retry_after' => 90,
    ],
],
```

### Running Queue Workers:
```bash
# Development (from composer.json dev script)
php artisan queue:listen --tries=1 --timeout=0

# Production (Horizon)
php artisan horizon
```

---

## 6. Console Commands

Located in `app/Console/Commands/`:

| Command | Description |
|---------|-------------|
| `php artisan ai:update-docs` | Regenerate AI documentation after a sprint |
| `php artisan horizon` | Start Laravel Horizon queue monitor |
| `php artisan queue:work` | Process queue jobs |
| `php artisan tinker` | Interactive REPL |
| `php artisan migrate` | Run pending migrations |
| `php artisan cache:clear` | Clear application cache |
| `php artisan config:clear` | Clear config cache |

---

## 7. Exports & Imports

### Excel Exports (`app/Exports/`)
Used via `ExportInvoicesJob` and similar jobs. All exports use `Maatwebsite\Excel`.

### Excel Imports (`app/Imports/`)
Used for bulk data import (price lists, test catalogs, etc.).

---

## 8. PDF Generation Libraries

| Library | Usage | Config |
|---------|-------|--------|
| **DomPDF** (`barryvdh/laravel-dompdf`) | HTML-to-PDF, standard reports | Default |
| **Snappy/wkhtmltopdf** (`barryvdh/laravel-snappy`) | High-quality PDF | `wkhtmltopdf-buster-amd64` binary |
| **TCPDF** (`tecnickcom/tcpdf`) | Advanced PDF generation | Embedded |
| **FPDI/FPDF** (`setasign/fpdi`, `fpdf`) | PDF template overlay | Embedded |

The `wkhtmltopdf-buster-amd64` binary is in the project root.

---

## 9. Helpers (`app/helpers.php`)

Global helper functions autoloaded by Composer. Contains utility functions for:
- Language/locale detection
- Number formatting
- Date helpers
- Profile/hospital detection

---

## 10. Key Config Files

| File | Purpose |
|------|---------|
| `config/app.php` | App name, timezone (UTC), locale (en) |
| `config/database.php` | MySQL connection config |
| `config/queue.php` | Redis queue config |
| `config/filesystems.php` | S3 and local disk config |
| `config/horizon.php` | Laravel Horizon settings |
| `config/mail.php` | Mail settings (log in dev, SES in prod) |
| `config/cache.php` | Cache driver (file) |
| `config/session.php` | Session (file, 120 min) |

---

## 11. Bootstrap & Providers

| Provider | Purpose |
|----------|---------|
| `AppServiceProvider` | Service bindings, global config |
| `RouteServiceProvider` | Route registration |
| `AuthServiceProvider` | Auth guards definition |
| `EventServiceProvider` | Event-listener registration |
| `HorizonServiceProvider` | Queue monitoring |
| `TelescopeServiceProvider` | Debug monitoring (dev only) |