## DAMAC Towers Jordan – Rental Housing Management Platform

### Overview
DAMAC Towers Jordan is a full‑stack Laravel application for managing residential properties, units, tenancies, invoices, and payments for the DAMAC community in Amman, Jordan. It serves both administrators (property managers/association staff) and residents (owners/tenants) with web and mobile integrations.

### Key Capabilities
- Admin portal for end‑to‑end property operations
  - Properties, Towers, and Units cataloging
  - Applications and Lease lifecycle (apply → approve → manage)
  - Invoices: create, bulk generate, email, export PDF
  - Payments: record, receipt PDF, receipt email, list/filter
  - Maintenance and Workorders management
  - Vendors and News management
  - User and Role/Permission administration
  - Push Notifications to the mobile app
  - Secure internal messaging (Messenger)

- Resident (frontend) portal
  - View dashboards and invoices
  - Online payment initiation and success flow
  - Submit maintenance requests
  - Manage profile and units

- Mobile API (v1)
  - Invoices list/search for authenticated users
  - Payments listing per invoice
  - Receipt/Invoice PDF endpoints used by web; receipts emailed on demand


## Architecture at a Glance
- Framework: Laravel (PHP)
- Datatables: Yajra DataTables for server‑backed tables in the admin UI
- PDFs: mPDF for generating invoice PDFs and payment receipts
- Mail: Laravel mailer for invoice/receipt emails
- AuthZ: Gates/Policies and Roles/Permissions
- Notifications: `PushNotificationService` used to fan‑out device token notifications

Primary domains and controllers (non‑exhaustive):
- Admin domain (`App\Http\Controllers\Admin`)
  - `InvoiceController` – CRUD, DataTables, mass generate, email, PDF, add payment, receipts
  - `PaymentController` – Payments list with filters and receipt links
  - `PropertiesController`, `UnitController`, `LeaseController`, `ApplicationsController`, `MaintenanceController`, `WorkorderController`, `VendorController`, `NewsController`, `UsersController`, `PermissionsController`, `RolesController`, `PushNotificationController`

- Frontend domain (`App\Http\Controllers\Frontend`)
  - `HomeController` – dashboard, payments success
  - `InvoiceController` – user‑scoped invoices

- Mobile API v1 (`App\Http\Controllers\Api\V1\Mobile`)
  - `InvoicesController` – user invoices endpoint with search
  - `PaymentsController` – payments for a specific invoice

- Models
  - `Invoice`, `Payment`, `Unit`, `Application`, `User`, and related Eloquent relationships


## Getting Started

### Prerequisites
- PHP 8.x
- Composer
- MySQL/MariaDB (or compatible)
- Node.js and npm (optional, if you need to rebuild any frontend assets)

### Quick Setup
```bash
git clone <repo-url> damac-rental
cd damac-rental

composer install --prefer-dist --no-interaction --no-progress

cp .env.example .env
php artisan key:generate

# Configure database in .env (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD)

php artisan migrate --force

# Optional: link storage for media if used
php artisan storage:link

# Optional: build assets if you modify them
npm install
npm run build

# Run locally
php artisan serve
# App typically runs at http://127.0.0.1:8000
```

### Environment Variables
Set the following in `.env` as applicable:
- App: `APP_NAME`, `APP_ENV`, `APP_URL`
- DB: `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
- Mail (for invoice/receipt emails): `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_ENCRYPTION`, `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME`
- Queue/Cache (optional): `QUEUE_CONNECTION`, `CACHE_DRIVER`
- Push notifications (if applicable to your provider) – see `PushNotificationService`


## Feature Deep‑Dive

### Invoices (Admin)
- DataTable with sorting, searching, and server‑side JSON feed: `GET admin/invoices`
- Columns include User, Tower, Unit, Billing For, Amount, Remainder, Due, Last Payment, Status
- Actions include View/Edit/Delete and Generate PDF button
- Add Payment modal with type, date, and notes
- Mass Generate invoices: rate per SQM × unit deed area, with optional push notifications
- Email invoice PDF directly from the table row
- Date range filter by creation date (From/To) in the UI

Controller highlights: `App\Http\Controllers\Admin\InvoiceController`
- `index()` builds the DataTable JSON (joins user/unit/property, computes status/remaining)
- `massGenerate()` bulk creates invoices and sends notifications
- `generatePdf()` creates an invoice PDF via mPDF
- `sendInvoiceEmail()` emails PDF to the user
- `addPayment()` records partial/complete payments and updates invoice status
- `generateReceiptPdf()` / `generatePaymentReceiptPdf()` produce PDF receipts

### Payments (Admin)
- DataTable view mirroring invoices style: `GET admin/payments`
- Columns include User, Tower, Unit, Invoice ID, Amount, Type, Date, Actions (Receipt)
- Date range filter by `payment_date` (From/To) in the UI

Controller: `App\Http\Controllers\Admin\PaymentController`
- `index()` returns JSON for DataTables and supports start/end date filters

### Maintenance, Workorders, Vendors, News
- Standard resource controllers for CRUD + listing, dedicated admin pages

### Applications and Leases
- Manage incoming applications, associate users to units, create/manage leases

### Roles & Permissions
- Built‑in administration for permissions, roles, users

### Push Notifications
- `PushNotificationService` invoked on invoice creation/payment to notify device tokens

### Messenger
- Internal messaging system with inbox/outbox and unread count


## Frontend (Residents)
- Dashboard at `frontend/home`
- Invoices pages and payment initiation with success callback
- Maintenance requests
- Profile and Units management

Frontend controllers and views are under `resources/views/frontend` and `App\Http\Controllers\Frontend`.


## API (Mobile v1)
Base namespace: `App\Http\Controllers\Api\V1\Mobile`

Example endpoints (authenticated):
- Invoices
  - `GET /api/v1/mobile/invoices?search=` – returns user’s invoices, supports simple search
- Payments
  - `GET /api/v1/mobile/invoices/{invoiceId}/payments` – payments for a given invoice

Responses return `success` and `data`/`payments` payloads, with standard HTTP codes. See controllers for details.


## Operations

### Email
Ensure mail credentials are set; invoice and receipt emails are sent with PDF attachments generated via mPDF.

### PDFs
Arabic font support is configured through mPDF defaults (`NotoNaskhArabic` in most PDF methods). Adjust as needed if you change templates or languages.

### DataTables
Admin tables use Yajra DataTables. JSON is served from controller `index()` methods. Filters (e.g., date range) are passed via AJAX `data` and applied server‑side.


## Development Tips
- Use role/permission gates to secure new admin features consistently
- Reuse DataTables patterns (actions column via `partials/datatablesActions`)
- When extending invoices or payments, ensure totals and status states are consistent across UI and server
- For PDFs, keep shared styles in their Blade templates and validate RTL font support when required