# 🏛️ System Architecture & Engineering Principles

## 1. Executive Summary

The **Al-Hilal Medical Visits System** is an enterprise-grade field force automation and medical CRM tailored for the Syrian pharmaceutical market. The application bridges field operations (Medical Representatives visiting healthcare practitioners and pharmacies) with executive management (Supervisors and Company Directors tracking territory coverage, sample distribution, and marketing ROI).

---

## 2. Technology Stack

```mermaid
graph TD
    Client["Client Browser / Mobile PWA\n(Vue 3 + Tailwind CSS v4 + Lucide)"]
    Inertia["Inertia.js v2 Wire\n(Hydration, Partial Reloads, Form State)"]
    Routing["Laravel 13 Routing & Middleware\n(Web, Fortify Auth, Spatie RBAC)"]
    Controllers["HTTP Controllers & Form Requests\n(Validation & Request Transformation)"]
    Services["Domain Service Layer\n(VisitService, ReportService, ArchivingService, DataImportService)"]
    Eloquent["Eloquent ORM & Scopes\n(HasUlids, SoftDeletes, Prunable)"]
    Database[("Database Engine\nSQLite / MySQL 8.0+")]

    Client <--> Inertia
    Inertia <--> Routing
    Routing --> Controllers
    Controllers --> Services
    Services --> Eloquent
    Eloquent <--> Database
```

### Core Technologies
- **Backend Framework**: **Laravel 13 (v13.32.0 on PHP 8.3+)**
- **SPA Bridge**: Inertia.js v2 (Server-driven client routing without REST boilerplate)
- **Frontend Framework**: Vue 3 with `<script setup lang="ts">` and Composition API
- **Styling & Design System**: Tailwind CSS v4 utilizing CSS-native configuration and RTL-first directionality
- **Access Control & RBAC**: Spatie Laravel Permission v8
- **Authentication & Security**: Laravel Fortify with multi-factor support, PIN verification, and re-confirmation
- **Excel Ingestion & Export**: PhpSpreadsheet & Maatwebsite Excel v4
- **PDF Generation**: `barryvdh/laravel-dompdf` for formal printable stock and visit audit sheets

---

## 3. Layered Architectural Design Pattern

The application enforces a strict separation of concerns across clean horizontal layers:

```
app/
├── Http/
│   ├── Controllers/          <-- Thin HTTP endpoints: orchestrate responses
│   │   ├── Admin/            <-- Area, User, Role, DataImport & SystemArchive controllers
│   │   ├── Doctors/          <-- Doctors & Doctor Workplaces CRUD
│   │   ├── Pharmacies/       <-- Pharmacies directory & hospital units
│   │   ├── Visits/           <-- Visit execution, check-ins, samples
│   │   └── Reports/          <-- Analytics, performance summaries, exports
├── Services/                 <-- Reusable business domain logic
│   ├── ArchivingService.php  <-- Multi-year data archiving, sealed snapshots, vacuuming
│   ├── DataImportService.php <-- Universal Excel/CSV import, template generator, preview matcher
│   ├── VisitService.php      <-- Complex visit logging, samples & inventory audits
│   ├── ReportService.php     <-- Vectorized single-query KPI aggregations & statistics
│   └── ActivityLogger.php    <-- System audit trail recorder
├── Models/                   <-- Eloquent models with ULIDs, relationships, and scopes
└── Policies/                 <-- Fine-grained authorization logic
```

---

## 4. Key Architectural Subsystems

### 4.1 Universal Data Import Engine (`DataImportService`)
- **Template Generation**: Dynamically creates `.xlsx` workbooks with native Excel data validation dropdowns (`DataValidation::TYPE_LIST`) for classifications, hospital types, and dosage forms, paired with reference sheets.
- **Smart Entity Matching**: Case-insensitive matching across Arabic and English nomenclature for specialties, governorates, and areas with fuzzy spelling allowances.
- **Pre-Flight Preview**: Parses spreadsheets entirely in memory, returns validated sample rows with status badges (`valid`, `duplicate`, `invalid`) before committing any changes.
- **Atomic Batch Processing**: Executes imports inside database transactions (`DB::transaction`) with selectable duplicate handling (`skip` vs. `update`).

### 4.2 Multi-Year Archiving Engine (`ArchivingService`)
- **Database Partitioning by Year**: Historical visits and associated child relations (`doctorProducts`, `pharmacyInventories`) are moved from active tables (`visits`) to archived mirrors (`archived_visits`) within atomic transactions.
- **Sealed Integrity Snapshots**: Generates a self-contained, styled Excel snapshot of all archived records and computes a SHA-256 integrity hash stored in `archive_batches`.
- **Read-Only Vault**: Accessible via `/admin/system/archives` and integrated into `/visits?vault=archived` with amber historical warnings.
- **Database Optimization**: Automatically executes driver-specific reclamation (`PRAGMA incremental_vacuum` for SQLite / `OPTIMIZE TABLE` for MySQL).
- **Automated Pruning**: `ActivityLog` leverages Laravel 13 `Prunable` with a lifecycle hook to archive logs older than 6 months into `archived_activity_logs`.

---

## 5. Security & Data Integrity Patterns

1. **ULID Primary Keys (`HasUlids`)**:
   All entities use Universally Unique Lexicographically Sortable Identifiers (ULIDs) instead of auto-incrementing integers.
2. **Soft Deletion (`SoftDeletes`)**:
   Critical master records (Doctors, Pharmacies, Products, Areas) utilize soft deletion to preserve historical visit trails and reporting integrity.
3. **Syrian Phone Normalization**:
   All phone numbers are validated and stored in standardized local mobile format (`09xxxxxxxx`), eliminating formatting errors and dial-prefix fragmentation.
4. **CSRF & Session Protection**:
   Strict SameSite cookies, session rotation on privilege change, and automatic CSRF tokens injected into all Inertia requests.