# Recruitment Module

This document outlines the candidate intake and recruitment features available in TAF. It covers job postings, applicant management, interview scheduling and supporting tools.

When working on a module, run the tests for that module. Full or integration suites are only required when specifically requested. As modules are refactored, update or extend their tests accordingly.

## Candidate Application and Intake

This submodule captures candidate data from intuitive online forms. Applicants can upload resumes in PDF, DOCX or TXT formats. The system parses these files to extract personal details, education, skills and prior experience. Basic screening filters enable HR staff to quickly shortlist applicants by skills, qualifications, experience or location.

### Key Features

- Responsive web and mobile application forms.
- Resume upload with automatic parsing.
- Configurable search and filter options for initial screening.

### API Endpoints
```
GET  /api/applications
POST /api/applications
GET  /api/application_documents?application_id={id}
POST /api/applications/shortlist
```

### Custom Application Fields

Arbitrary fields submitted with an application are saved to the
`application_custom_fields` table. Each record stores the application ID,
field name and value along with tenant and branch identifiers.

Additional CRUD endpoints are exposed via `/api/application-custom-fields`.
These allow HR staff to view or edit custom values attached to an
application.

## Job Posting Management

HR personnel can create and manage vacancies centrally. Posts can be distributed to external boards such as LinkedIn or Indeed. Automation options allow scheduling of posts and setting expiry dates.

### Key Features

- Templates for creating job postings.
- Administrators can define job opening templates to prefill job details. These
  templates store custom form configuration in JSON and can be selected when
  creating a new open position.
- Integration hooks for external job boards and social media.
- Automated scheduling and expiry handling.

### API Endpoints
```
GET  /api/open-positions
POST /api/open-positions
```

## Interview Scheduling

Interviews are coordinated with built in calendar integration. Participants avoid double bookings and receive automatic notifications. Virtual meeting links can be generated for remote interviews.

### Key Features

- Google Calendar or Outlook integration.
- Automatic notifications and reminders.
- Zoom, Teams or Google Meet links for virtual interviews.

### API Endpoints
```
GET  /api/interviews
POST /api/interviews
POST /api/interviews/{id}/schedule
POST /api/interviews/{id}/addParticipant
```

## Document Management

All candidate documents – resumes, offer letters and contracts – are stored centrally. The module supports digital signatures for online acceptance and provides fine grained access control.

### Key Features

- Secure document repository with permissions.
- Built in e-signature workflow.
- Secure sharing with audit trail.

## Communication Tools

Integrated email templates and an internal messaging system streamline collaboration. HR staff can send messages directly from the system while maintaining a record of correspondence.

### Key Features

- Email integration for applicant communications.
- Customisable template library.
- Internal team messaging with real-time updates.

## Running Recruitment Tests

Run the helper script to prepare the environment and then execute the tests yourself. Set `DB_DRIVER` for the desired backend:

```bash
DB_DRIVER=pgsql ./test_setup.sh
phpunit -c api/phpunit.xml
jest
```

Only run the recruitment tests when this module is modified unless a full suite is requested.