# Permits Module

The Permits module tracks applications for various permits and ties into the Finance and HR modules. Applicants submit a request, pay any associated fee, an inspection is performed and finally the permit is approved.

## Database Schema

### permit_types
- `id` INT PRIMARY KEY
- `name` VARCHAR NOT NULL
- `description` TEXT nullable
- `updatedSince` TIMESTAMP

### permit_applications
- `id` INT PRIMARY KEY
- `permit_type_id` INT FOREIGN KEY
- `applicant_id` INT (customer)
- `status` VARCHAR DEFAULT `Requested`
- `start_date` DATE nullable
- `end_date` DATE nullable
- `fee_amount` DECIMAL DEFAULT 0.00
- `description` TEXT nullable
- `work_location` VARCHAR nullable
- `equipment` VARCHAR nullable
- `hazard_assessment` TEXT nullable
- `control_measures` TEXT nullable
- `ppe_required` TEXT nullable
- `loto_instructions` TEXT nullable
- `emergency_response` TEXT nullable
- `issuer_id` INT nullable
- `supervisor_id` INT nullable
- `signed_off_at` DATETIME nullable
- `expires_at` DATE nullable
- `created_at` DATETIME
- `updated_at` DATETIME
- `updatedSince` TIMESTAMP

### permit_documents
- `id` INT PRIMARY KEY
- `permit_application_id` INT FOREIGN KEY
- `file_name` VARCHAR
- `file_type` VARCHAR
- `file_path` TEXT
- `uploaded_at` DATETIME
- `uploaded_by` INT
- `updatedSince` TIMESTAMP

### permit_inspections
- `id` INT PRIMARY KEY
- `permit_application_id` INT FOREIGN KEY
- `inspector_id` INT (employee)
- `scheduled_for` DATETIME
- `result` VARCHAR nullable
- `notes` TEXT nullable
- `hours_logged` DECIMAL nullable
- `created_at` DATETIME
- `updated_at` DATETIME
- `updatedSince` TIMESTAMP

## API Endpoints
Most resources expose CRUD actions under `/api/{resource}`.

### Permit Applications
```
GET    /api/permit_applications
POST   /api/permit_applications
GET    /api/permit_applications/{id}
PUT    /api/permit_applications/{id}
DELETE /api/permit_applications/{id}

POST   /api/permit_applications/approve/{id}
POST   /api/permit_applications/scheduleInspection/{id}
POST   /api/permit_applications/uploadDocument/{id}
```

### Permit Types
```
GET  /api/permit_types
POST /api/permit_types
```

### Permit Documents
```
GET  /api/permit_documents
POST /api/permit_documents
```

### Permit Inspections
```
GET  /api/permit_inspections
POST /api/permit_inspections
```

## Example Workflows

### 1. Application Submission
Applicants submit a new record specifying the permit type and applicant. An invoice is generated via `PermitService::generateInvoice()`.
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"permit_type_id":1,"applicant_id":2,"fee_amount":100}' \
  http://localhost/api/permit_applications
```

### 2. Fee Payment
The Finance module records the payment against the AR invoice created in step one using its standard payment APIs.

### 3. Inspection Scheduling
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"inspector_id":5,"scheduled_for":"2024-05-01 10:00:00"}' \
  http://localhost/api/permit_applications/scheduleInspection/1
```
This updates the application status to `Inspection Scheduled`.

### 4. Approval
```bash
curl -X POST -b cookie.txt \
  http://localhost/api/permit_applications/approve/1
```
The application status becomes `Approved` and another invoice can be generated if required.

## Offline Behaviour
The Permits module is defined as a UI modal stored in the `ui_modals` table. `ModuleLoader` and `ModalBuilder` render this modal and use `LocalSyncManager` to cache `permit_applications`, `permit_types`, `permit_documents` and `permit_inspections` in IndexedDB. Records created while offline are marked with `pendingSync` and pushed to the API when connectivity returns.

## Integration Points
- **Finance** – invoices created by `PermitService::generateInvoice()` post journal entries and AR transactions, connecting the permit fee to accounting.
- **HR** – inspectors come from the `employees` table and hours logged on inspections may feed into payroll or time tracking.