# Project Overview

## Introduction

The **Building Management System** is an enterprise-grade platform designed to manage construction projects, maintenance operations, procurement, accounting, and human resources. Built with Laravel 12 and following Domain-Driven Design (DDD) principles, it provides a comprehensive RESTful API for frontend applications.

## Technology Stack

### Backend
| Technology | Version | Purpose |
|------------|---------|---------|
| PHP | 8.2+ | Runtime |
| Laravel | 12.0 | Framework |
| MySQL | 8.0+ | Primary Database |
| Redis | 6.0+ | Caching & Queues |
| Laravel Sanctum | - | API Authentication |

### Key Libraries
| Library | Purpose |
|---------|---------|
| spatie/laravel-permission | Role-Based Access Control |
| spatie/laravel-medialibrary | Media & File Management |
| spatie/laravel-activitylog | Audit Logging |
| barryvdh/laravel-dompdf | PDF Generation |
| phpoffice/phpspreadsheet | Excel Import/Export |
| pusher/pusher-php-server | Real-time Broadcasting |

### Frontend Integration
| Technology | Purpose |
|------------|---------|
| Vite 5.0 | Asset Bundling |
| Axios | HTTP Client |
| Pusher | WebSocket Communication |

## Business Domains

The system is organized into the following core domains:

### 1. Construction Domain
- Project management and tracking
- Cost estimation and budgeting
- Material requisitions
- Progress monitoring

### 2. Accounting Domain
- Invoice management
- Financial reporting
- Inventory valuation
- Tax compliance (ZATCA integration)

### 3. Maintenance Domain
- Asset management
- Scheduled maintenance visits
- Checklist management
- Service reporting

### 4. Management Domain
- Human Resources
- Payroll processing
- Recruitment management
- Leave and attendance tracking

### 5. Procurement Domain
- Supplier management
- Purchase orders
- Quotation handling
- Delivery tracking

### 6. Catalog Domain
- Product management
- Service catalog
- Inventory tracking
- Unit management

### 7. Supply Domain
- Supply chain operations
- Driver management
- Delivery scheduling

### 8. CRM Domain
- Customer relationship management
- Event tracking
- Communication logs

## Key Features

- **Multi-tenant Support**: Branch-based data isolation
- **Role-Based Access Control**: Granular permissions system
- **Real-time Updates**: WebSocket-powered live notifications
- **Audit Logging**: Complete activity tracking
- **Document Generation**: PDF reports, invoices, and receipts
- **QR Code Integration**: Asset and document tagging
- **Mobile-Ready API**: RESTful endpoints for mobile apps

## API Versioning

All API endpoints follow the versioning pattern:
```
/api/v1/{domain}/{resource}
```

Current version: **v1**

## System Requirements

- PHP 8.2 or higher
- Composer 2.x
- MySQL 8.0+ or MariaDB 10.6+
- Redis 6.0+
- Node.js 18+ (for asset compilation)
- Imagick PHP Extension