# LinkProx Project Structure

```text
<app-root>/
├── app/                          # Backend Application Logic
│   └── modules/
│       ├── Admin/
│       │   ├── AdminCompanyController.php    # Company approvals, suspend, verify
│       │   ├── AdminSettingsController.php   # Platform-wide settings
│       │   └── CategoryMappingController.php # Global catalog categories
│       ├── Auth/
│       │   └── AuthController.php            # Login, OTP, password reset, logout
│       ├── Company/
│       │   ├── CatalogController.php         # Products CRUD (company catalog)
│       │   ├── DashboardController.php     # Dashboard stats, activity, widgets
│       │   ├── NotificationController.php    # Notifications list + mark read
│       │   ├── ProfileController.php         # Company profile, legal info, documents
│       │   ├── ServiceController.php         # Services CRUD with multi-media
│       │   ├── SettingsController.php        # Settings + deactivation requests
│       │   └── TeamController.php            # Staff, agents, site engineers
│       ├── Contracts/
│       │   └── ContractController.php        # Contracts + milestones + termination settlement APIs
│       ├── Customer/
│       │   ├── BrowseController.php          # Browse companies/services/products
│       │   ├── CustomerContractController.php# Customer-side contract actions
│       │   ├── CustomerController.php        # Profile, addresses, agents
│       │   ├── CustomerDashboardController.php
│       │   ├── CustomerNotificationController.php
│       │   ├── CustomerQuotationController.php # Quotation review + respond
│       │   └── CustomerRequestController.php # Create/manage requests
│       ├── Execution/
│       │   └── ExecutionController.php       # Stages, progress evidence, extensions
│       ├── Messaging/
│       │   └── MessagingController.php       # Customer conversation endpoints
│       ├── Notifications/
│       │   └── NotificationController.php    # Shared notification logic
│       ├── Payments/
│       │   ├── PaymentController.php         # Customer payment submission
│       │   └── CompanyMilestoneController.php# Milestone management for companies
│       ├── Quotations/
│       │   └── QuotationController.php       # Quotation creation + upload
│       └── Requests/
│           ├── ChatController.php            # Chat history + send message
│           └── RequestController.php         # Company-side request list/details
│
├── assets/                       # Static assets (logo, images)
├── config/
│   ├── constants.php             # Global constants (JWT_SECRET, BASE_URL, etc.)
│   ├── env.php                   # Loads `.env` (KEY=value) for PHP
│   └── database.php              # PDO MySQL connection (`DB_*` from env)
├── helpers/
│   ├── AppUrls.php               # ⭐ Mount path + /views, /public, /api/v1 URLs
│   ├── JwtHandler.php            # JWT encode/decode
│   ├── Lang.php                  # Lang::get('key') — PHP translation helper
│   ├── Response.php              # Response::json(...) — standardized JSON output
│   ├── Uploader.php              # File upload utility
│   └── ViewUrls.php              # Back-compat: viewsBase() → AppUrls::viewsBase()
├── language/
│   ├── en.php                    # English strings (array)
│   └── ar.php                    # Arabic strings (array, must mirror en.php)
├── middlewares/
│   └── AuthMiddleware.php        # protect() + requireRole()
├── migrations/                   # DB patch scripts
├── public/
│   ├── index.php                 # ⭐ API ROUTER — all endpoints registered here
│   ├── .htaccess                 # Rewrites /api/* → public/index.php
│   └── uploads/                  # Uploaded files (logos, quotation attachments, etc.)
├── resources/
│   ├── css/style.css             # Global stylesheet (Navy+Teal brand)
│   └── js/
│       ├── api.js                # ⭐ JS API client wrapper (all API methods)
│       └── main.js               # Shared JS utilities
├── views/
│   ├── admin/
│   │   ├── dashboard.php
│   │   ├── companies.php         # Company list + approval
│   │   ├── company_details.php
│   │   ├── categories.php
│   │   ├── manage_categories.php
│   │   ├── category_mappings.php
│   │   ├── category_companies.php
│   │   ├── company_category_items.php
│   │   ├── settings.php
│   │   └── security.php
│   ├── auth/
│   │   └── login.php
│   ├── company/
│   │   ├── dashboard.php         # KPIs + widgets via DashboardController APIs
│   │   ├── activity.php          # Company activity list
│   │   ├── requests.php          # Request list
│   │   ├── request_details.php   # Request detail + chat/messaging
│   │   ├── quotations.php
│   │   ├── create_quotation.php
│   │   ├── contracts.php         # Contract list
│   │   ├── contract_details.php  # ⭐ Dynamic timeline + chat + actions
│   │   ├── execution_control.php # ⭐ Project execution/stages management
│   │   ├── contract_review.php   # Final legal document preview + send
│   │   ├── contract_roles.php    # Assign rep + engineer
│   │   ├── generate_contract.php # Contract editor (line items, milestones, clauses)
│   │   ├── revision_review.php   # Side-by-side revision comparison
│   │   ├── revision_sent.php     # Revision sent confirmation page
│   │   ├── contract_termination_settlement.php  # Termination settlement wizard
│   │   ├── contract_settlement_reconciliation.php
│   │   ├── contract_settlement_recalculate.php
│   │   ├── catalog.php
│   │   ├── catalog_products.php / catalog_services.php (+ add/edit variants)
│   │   ├── profile.php
│   │   ├── legal_information.php
│   │   ├── settings.php
│   │   ├── security.php
│   │   ├── notifications.php
│   │   └── notification_settings.php
│   └── layouts/
│       ├── header.php            # Top nav, LINKPROX_* globals, api.js, Bootstrap
│       ├── sidebar.php           # Nav links; dashboard href from LINKPROX_VIEWS_BASE
│       └── footer.php
│
├── .env.example                  # Template for `.env` (DB + LINKPROX_BASE_PATH); copy to `.env`
├── API_COLLECTION.json           # Postman collection (keep synced)
├── README.md                     # Project overview + setup
├── PROJECT_STRUCTURE.md          # This file
├── DATABASE_OVERVIEW.md          # Table-level DB schema reference
├── API_STRUCTURE.md              # API conventions + all routes
├── COMPANY_MODULES.md            # Company portal feature docs
├── ADMIN_MODULES.md              # Admin panel feature docs
├── IMPLEMENTATION_PLAN.md        # ⭐ Current progress + next steps for AI agents
├── PERMISSIONS_MATRIX.md         # Role/permission reference
└── UI_GUIDELINES.md              # Brand colors, fonts, design rules
```

## Backend Architecture Rules
1. Every API endpoint is an `if` block in `public/index.php`. No magic routing.
2. Controller methods call `AuthMiddleware::protect()` first, then `requireRole()`.
3. All responses use `Response::json('success'|'error', 'message', $data, $errors, $httpCode)`.
4. DB access is PDO only. No ORM.

## Frontend Architecture Rules
1. Every page is a `.php` file that `include`s `header.php` (top) and `footer.php` (bottom).
2. All API calls go through the `window.API` object defined in `api.js`.
3. Data is fetched via JS on `DOMContentLoaded` and injected into the DOM — no PHP echoing API data directly.
4. SweetAlert2 (`Swal`) is used for confirmations and loading states.

## Adding a New Feature (Checklist)
- [ ] Add the API endpoint `if` block to `public/index.php`
- [ ] Write the controller method in the relevant `app/modules/*/Controller.php`
- [ ] Add the JS API method to `resources/js/api.js`
- [ ] Add any new translation strings to `language/en.php` AND `language/ar.php`
- [ ] Add the UI view to `views/company/*.php` (include header/footer)
- [ ] Update `API_COLLECTION.json` (Postman collection)
- [ ] Update the relevant `.md` files