# Contracts ERP System Information

## Summary
A comprehensive Laravel-based Enterprise Resource Planning (ERP) and business management system with multi-module architecture. The application supports accounting, inventory management, manufacturing, human resources, restaurant operations, dental lab services, treasury operations, ZATCA e-invoicing integration, and government integrations. Built with Laravel 9, PHP 8.0.2+, MySQL database, and modern frontend technologies (Vite, Tailwind CSS, React/Alpine.js).

## Structure

**Root Directories:**
- **app/** - Application logic (Models, Controllers, Services, Helpers, Jobs, Observers)
- **database/** - Migrations, seeders, and factories
- **resources/** - Frontend assets (CSS, JavaScript, Views, Language files)
- **routes/** - API and web route definitions (23+ route files per module)
- **public/** - Web-accessible assets, static files, entry point (index.php)
- **config/** - Configuration files (app, auth, database, ZATCA, cache, mail, etc.)
- **storage/** - Application cache, logs, framework files
- **tests/** - Feature and Unit tests
- **vendor/** - Composer dependencies
- **node_modules/** - NPM dependencies

**Main Components:**
- **Accounting Module**: Chart of accounts, journal entries, cost centers, account balances, fiscal years
- **Banking Module**: Bank accounts, deposits, withdrawals, reconciliation, checks
- **Inventory Module**: Items, warehouses, movements, counts, finished goods, raw materials
- **Manufacturing**: Production orders, BOMs, production schedules, quality control
- **HR Module**: Employees, attendance, payroll, leaves, contracts, salary structures
- **Restaurant Module**: POS terminals, menu management, orders, invoices, kitchen display
- **Dental Lab**: Clinics, dentists, lab orders, services, technicians, tooth colors
- **Treasury**: Payments, deposits, transfers, reconciliation
- **ZATCA Integration**: E-invoice binding, government regulations, tracking

## Language & Runtime

**Language**: PHP  
**Version**: 8.0.2+ (specified as `^8.0.2`)  
**Framework**: Laravel 9.19+  
**Build System**: Vite 4.0+  
**Package Manager**: Composer (PHP), NPM (Node.js)  
**Database**: MySQL 5.7+

## Dependencies

**Main PHP Dependencies**:
- `laravel/framework` (^9.19) - Core framework
- `laravel/sanctum` (^3.0) - API authentication
- `barryvdh/laravel-dompdf` (^3.1) - PDF generation
- `maatwebsite/excel` (^3.1) - Excel import/export
- `simplesoftwareio/simple-qrcode` (^4.2) - QR code generation
- `spatie/laravel-activitylog` (4.7) - Activity logging
- `doctrine/dbal` (^3.5) - Database abstraction
- `guzzlehttp/guzzle` (^7.2) - HTTP client

**Development Dependencies**:
- `phpunit/phpunit` (^9.5.10) - Testing framework
- `laravel/sail` (^1.0.1) - Docker development environment
- `laravel/pint` (^1.0) - Code style formatter
- `mockery/mockery` (^1.4.4) - Mocking library
- `spatie/laravel-ignition` (^1.0) - Error debugging
- `fakerphp/faker` (^1.9.1) - Fake data generation

**Frontend Dependencies**:
- `vite` (^4.0.0) - Frontend build tool
- `tailwindcss` (^3.1.0) - Utility-first CSS framework
- `axios` (^1.1.2) - HTTP client
- `chart.js` (^4.5.1) - Charting library
- `react` & `react-dom` (latest) - UI library
- `alpinejs` (^3.4.2) - Lightweight JavaScript framework
- `laravel-vite-plugin` (^0.7.2) - Laravel integration for Vite

## Build & Installation

**Installation**:
```bash
composer install
npm install
```

**Generate Application Key**:
```bash
php artisan key:generate
```

**Database Setup**:
```bash
php artisan migrate
php artisan db:seed
```

**Build Frontend Assets**:
```bash
npm run build
```

**Development Server**:
```bash
php artisan serve
npm run dev
```

## Testing

**Framework**: PHPUnit 9.5.10  
**Test Location**: `tests/` directory  
**Test Suites**:
- **Unit**: `tests/Unit/` (unit tests)
- **Feature**: `tests/Feature/` (feature/integration tests)

**Test File Naming Convention**: Files ending with `Test.php`  
**Configuration File**: `phpunit.xml`  
**Test Environment**: SQLite in-memory or MySQL test database (configurable in phpunit.xml)

**Run Tests**:
```bash
php artisan test
vendor/bin/phpunit
```

## Main Entry Points

**Application Entry**: `public/index.php`  
**Console Entry**: `artisan` (Laravel CLI)  
**Configuration Bootstrap**: `bootstrap/app.php`  
**Service Providers**: `app/Providers/` - Register services and boot application

**Main Route Files** (in `routes/`):
- `web.php` - Web application routes
- `api.php` - RESTful API routes
- `accounting.php` - Accounting module
- `inventory.php` - Inventory management
- `restaurant.php` - Restaurant operations
- `manufacturing.php` - Manufacturing operations
- `banking.php` - Banking operations
- `hr.php` - Human resources
- `contracts.php` - Contract management
- `zatca.php` - Government integrations
- Multiple other module-specific routes

**Key Controllers** (50+ total):
- `Accounting/ChartOfAccountController.php`
- `Inventory/InventoryDocumentController.php`
- `Restaurant/POSController.php`
- `Manufacturing/ProductionOrderController.php`
- `Banking/BankDepositController.php`
- `HR/PayrollController.php`
- `Zatca/SimpleBindingController.php`

## Configuration

**Key Config Files** (in `config/`):
- `app.php` - Application configuration
- `database.php` - Database connections
- `auth.php` - Authentication settings
- `cache.php` - Caching configuration
- `mail.php` - Email configuration
- `zatca.php` - ZATCA government integration settings
- `accounting.php` - Accounting module configuration
- `government-integrations.php` - Government API integrations

**Environment Configuration**:
- `.env.example` - Example environment file
- `.env` - Local environment (not committed)
- `.env.production` - Production environment settings

## Models

**90+ Eloquent Models** organized in:
- **Root Models**: ChartOfAccount, User, Company, Journal, etc.
- **Module-Specific Models**:
  - **Accounting**: JournalEntry, AccountBalance, CostCenter, FiscalYear
  - **Inventory**: Item, InventoryDocument, Warehouse, InventoryCount
  - **Manufacturing**: ProductionOrder, BOM, ProductionSchedule
  - **HR**: Employee, Payroll, Attendance, Leave
  - **Restaurant**: RestaurantOrder, MenuItem, RestaurantPOSTerminal
  - **DentalLab**: LabOrder, Dentist, Clinic, LabTechnician
  - **Banking**: BankAccount, Check, BankDeposit, BankReconciliation
  - **Treasury**: TreasuryPayment, TreasuryDeposit, TreasuryTransfer

## Localization

**Supported Languages**:
- Arabic (`lang/ar/`)
- English (`lang/en/`)

**Translation System**: Laravel's translation system with keys in language-specific files

## Assets & Frontend

**CSS**: Tailwind CSS with PostCSS and nested plugins  
**JavaScript**: Vite-bundled with React components and Alpine.js directives  
**Build Output**: `public/build/` (auto-generated by Vite)  
**Static Resources**: `public/images/`, `public/css/`, `public/js/`

## Key Helpers

Auto-loaded helpers in `app/Helpers/`:
- `ProjectHelpers.php` - Project-related utilities
- `PaymentCertificateHelpers.php` - Payment certificate utilities
- `TestHelper.php` - Testing utilities
- `TranslationHelper.php` - Translation utilities

## Database

**Connection**: MySQL (primary)  
**Port**: 3306  
**Migrations**: Located in `database/migrations/`  
**Seeders**: Located in `database/seeders/` for test data  
**Factories**: Located in `database/factories/` for model factories

## Permissions & Policies

**Authorization**: Laravel Sanctum + custom permission system  
**Policies**: `app/Policies/` - Resource-based authorization  
**Permissions Table**: Tracks user roles and permissions  
**Roles**: Admin, Manager, User, module-specific roles

## Logging & Monitoring

**Log Channel**: Stack  
**Log Location**: `storage/logs/laravel.log`  
**Activity Logging**: Spatie Laravel Activity Log (tracks model changes)  
**Debug Mode**: Configurable via `APP_DEBUG` environment variable

## External Integrations

**ZATCA e-Invoicing**: Government tax compliance for Saudi Arabia  
**Government APIs**: Banking, tax, and regulatory integrations  
**Email**: SMTP configuration with Mailpit support for local development  
**File Storage**: Local disk storage with extensible filesystem configuration