Applicant Tracking Module (ATM)
===============================

Overview
--------

The **Applicant Tracking Module (ATM)** is Tafkar's built-in applicant tracking
system. It allows projects to manage vacancies and applications directly inside
the CMS, without requiring an external ATS integration.

ATM is useful when a project does not use a third-party ATS (such as Carerix,
Bullhorn or Greenhouse) and wants to handle the full recruitment workflow —
vacancy creation, application intake, status tracking and confirmation e-mails —
within Tafkar itself.

Enabling the Module
-------------------

ATM is controlled by a feature flag in project settings:

.. code-block:: json

   {
     "atm-module-enabled": true
   }

Backend reference: ``src/FloHam/Cms/Settings/FeatureFlags.hs`` — the
``atmModuleEnabled`` lens (defaults to ``False``).

ATS Type
--------

Every vacancy carries an ``Ats`` type that indicates where it is managed.
When ATM is active and a vacancy is created through the CMS, its ATS type is
set to ``HamiltonCMS``:

.. code-block:: haskell

   & ats .~ Ats.HamiltonCMS

The ``HamiltonCMS`` variant is defined in ``src/FloHam/Cms/Types/Ats.hs``
alongside the external ATS variants (Carerix, Bullhorn, Greenhouse, etc.).

A vacancy with ``ats == HamiltonCMS`` is considered *internally managed* — it
was created in the CMS and its applications are handled by ATM rather than
forwarded to an external system.

Key Features
------------

- **Vacancy creation in CMS** — CMS users can create and edit vacancies without
  an external ATS. New vacancies are automatically tagged with
  ``ats = HamiltonCMS``.

- **Application management** — Incoming applications are stored locally. CMS
  users can view, filter and update application statuses.

- **Activity tracking** — Every status change, comment and assignment is logged
  as an activity event, visible on the vacancy Activity tab.

- **Confirmation e-mails** — The system can send confirmation and invite mails
  to applicants and assignees (see ``sendInviteMail``, ``sendNewApplicationMail``
  and ``sendNewAssigneeMail`` in ``CmsApplication``).

- **User / group permissions** — Access to applications is governed by the
  ``CmsApplicationAdmin`` permission. The ATM menu items and permission options
  are only shown when ``atmModuleEnabled`` is ``True``.

CMS User Interface
------------------

When ``atmModuleEnabled`` is enabled and a vacancy has ``ats == HamiltonCMS``,
the CMS vacancy page (``cms/src/Page/Vacancy.elm``) shows additional tabs:

- **Activity** — Displays a chronological log of events (status changes,
  comments, assignment changes) with filtering support.

- **Applications** — Lists all applications for the vacancy with status
  management, search and bulk operations.

The vacancy overview page (``cms/src/Page/VacancyOverview.elm``) also adapts its
UI based on ATM status.

The CMS sidebar menu (``cms/src/Component/Menu.elm``) conditionally shows ATM-
related menu items and adjusts user/group management routes depending on the
``atmModuleEnabled`` flag.

ATM Migration
-------------

The ``Migration.Atm`` module (``src/Migration/Atm.hs``) provides helpers to
enable ATM for an existing project:

- ``enable`` — Activates the feature flag for a project.
- ``migrate`` — Performs data migration (e.g. setting existing vacancies to
  ``HamiltonCMS``, updating master-data origins).

Architecture Overview
---------------------

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Area
     - Source file
   * - ATS type definition
     - ``src/FloHam/Cms/Types/Ats.hs`` (``HamiltonCMS`` variant)
   * - Feature flag
     - ``src/FloHam/Cms/Settings/FeatureFlags.hs`` (``atmModuleEnabled``)
   * - Application handling
     - ``src/FloHam/Cms/Model/Extra/CmsApplication.hs``
   * - Vacancy creation
     - ``src/Handler/Api/VacancyCollection.hs``
   * - Vacancy management
     - ``src/Handler/Api/Vacancy.hs``, ``src/Handler/Api/VacancyStatus.hs``
   * - ATM migrations
     - ``src/Migration/Atm.hs``
   * - CMS vacancy page
     - ``cms/src/Page/Vacancy.elm`` (Activity + Applications tabs)
   * - CMS vacancy overview
     - ``cms/src/Page/VacancyOverview.elm``
   * - CMS menu
     - ``cms/src/Component/Menu.elm``