# The Foxit TalentFlow ATS Sample Application

## Introduction
The Foxit ATS Sample Application is a Foxit sample app for HR and hiring workflows with auditable AI features.

It follows a simple event-driven pattern:

> **Actions happen in the UI, API routes execute deterministic calls, and events are recorded as an audit trail.**

The app includes seeded positions/applicants, stage movement through a hiring pipeline, AI screening against versioned policies, manager reporting via Foxit Document Generation, and offer-letter eSign workflows via Foxit eSign.

---

## What this sample demonstrates

1. **ATS pipeline with seeded demo data**
   * Positions and applicants are seeded and stored in browser LocalStorage
   * Applicants move across stages: `new_applied` -> `resume_review_screening` -> `offer_letter_sent` -> `hired_or_closed`

2. **AI screening against versioned policies**
   * Policies are loaded from `inputs/evaluation_policy_v*`
   * Screening runs through `/api/screening/run-evaluation` using `AI_PROVIDER_KEY`
   * Recruiters can re-run screening and create policy versions from the applicant screen

3. **Foxit Document Generation for manager reporting**
   * Generates a Candidate Pipeline Summary PDF by leveraging the template in `inputs/templates/Candidate_Pipeline_Report_Template.docx`
   * Uses `/api/manager-actions/generate-candidate-pipeline-report`

4. **Foxit eSign offer-letter workflow**
   * Creates an embedded sending session for an offer letter template
   * Polls and normalizes status updates (`DRAFT`, `SHARED`, `PARTIALLY SIGNED`, `EXECUTED`, etc.)
   * Uses `/api/offer-letter/run-esign-offer-letter` and `/api/offer-letter/get-esign-status`

5. **Auditable event timeline**
   * User actions append structured events (stage moves, screening, offer actions, disposition decisions)
   * Global, position-level, and applicant-level audit logs can be downloaded from the UI

---

## Installation

### Prerequisites
* Node.js (LTS recommended) + npm
* Foxit API credentials:
  * Document Generation credentials (`FOXIT_DOCGEN_CLIENT_ID`, `FOXIT_DOCGEN_CLIENT_SECRET`)
  * eSign API access token (`FOXIT_ESIGN_API_ACCESS_TOKEN`)
* AI provider key (`AI_PROVIDER_KEY`) for screening

### Installation steps (manual)
1. Clone this repository:
   ```bash
   git clone <REPO_URL>
   cd foxit-sample-ats-auditable-ai
   ```

2. Create your environment file:
   ```bash
   cp .env.example .env
   ```

3. Update `.env` with your values:
   ```bash
   FOXIT_DOCGEN_CLIENT_ID=...
   FOXIT_DOCGEN_CLIENT_SECRET=...
   FOXIT_ESIGN_API_ACCESS_TOKEN=...
   AI_PROVIDER_KEY=...
   ```

   > **Note:** Keep credentials server-side only and never commit secrets.

4. Install dependencies:
   ```bash
   npm install
   ```

---

## Running the TalentFlow Sample App

### Manual
1. Start the development server:
   ```bash
   npm run dev
   ```

2. Open:
   ```
   http://localhost:3000
   ```

3. Typical flow:
   - Open a position and upload a new applicant
   - Run AI screening (and optionally re-run with a policy update)
   - Send offer letter for eSignature
   - Generate the candidate pipeline report
   - Download audit logs

---

## License information
This repository uses the MIT License. See the [LICENSE](./LICENSE) file for more information.
