# Suggested File Name: HCMS-FO-HUMANABLE-Final-v1.3-Selfcontained-2026.md

# HUMANABLE — HCMS Sovereign Recruitment Platform
## Functional Outline (FO) — v1.3 LOCKED · Self-Contained · Engineering Handoff Pending User Confirmation

---

## Document Control

| Field | Value |
| :---- | :---- |
| **Document Type** | Functional Outline (FO) — Final, Self-Contained |
| **Version** | **1.3 LOCKED — All Pre-Handoff Decisions Resolved** |
| **Date** | May 23, 2026 |
| **Owner** | HCMS N.V. (subsidiary of K&K Heritage Group N.V.) |
| **Author** | Sovereign HCMS Architect (AI Head of Business Unit) |
| **Approvers** | Chairman (Strategic) · CEO (Operational) · IQT Lead (Technical) |
| **Service Lines** | HCMS-PRO-001 (Recruitment) · HCMS-PRO-005 (AI Talent Solutions) · Bridges to PRO-002/003/004/006 |
| **HCMS App Suite Position** | Pillar I of IV (Recruitment) |
| **Companion FOs** | `HCMS-FO-ATLAS-Final-v1.3-Selfcontained-2026.md` (Pillar II) · `HCMS-FO-ComplianceShield-v1.0-2026.md` (Shared 3rd FO) |
| **Self-Contained Note** | This document supersedes v1.0 / v1.1 / v1.2 entirely. No external references required for the HUMANABLE specification. The Compliance Shield specification lives in its own 3rd FO and is consumed via internal HTTP API. |

---

## Executive Summary

HUMANABLE is HCMS N.V.'s purpose-built recruitment operations platform, replacing Zoho Recruit and serving as the operational system of record for the HCMS-PRO-001 Recruitment & Selection service line and HCMS-PRO-005 AI Talent Solutions. It is **Pillar I of the four-pillar HCMS App Suite** (HUMANABLE · ATLAS · HCMS Academy · HCMS Digi Coaches).

HUMANABLE is engineered around **five architectural pillars**: (1) Agentic AI Workflow Layer with eight named autonomous agents, (2) Voice & Multi-Modal Communication, (3) Compliance Shield as a shared microservice (separate 3rd FO), (4) Service Line Specialization Bridges, (5) Quality of Hire (QoH) Engine.

**v1.3 represents the final pre-handoff state** with all infrastructure, service-provider, AI-strategy, mobile-framework, and scope decisions locked. The platform deploys on a **shared LiquidNet US VPS** (16 GB RAM minimum, co-hosted with ATLAS and the Compliance Shield) running Laravel 13+, PHP 8.3+, PostgreSQL 16 + pgvector. No Docker, no Redis, no Meilisearch. AI strategy: Claude API primary + Google Gemini API fallback + Anthropic embedding service. Mobile (v1.2 phase): React Expo + EAS Build. Communication: WhatsApp Business Cloud API + Gmail SMTP + Twilio (critical SMS only). Backup: Google Drive. Monitoring: self-hosted Sentry. Languages: **English only in v1** (NL/FR/PT in v1.x, Spanish in v2).

---

## 1. Platform Identity

| Element | Definition |
| :---- | :---- |
| **Internal/Operator Name** | **HUMANABLE** |
| **Public-Facing Brand (to candidates)** | HCMS Careers |
| **Public-Facing Brand (to employers)** | HCMS Recruitment Solutions |
| **Tagline (Internal)** | *"Recruitment, sovereign. In the agentic age."* |
| **Owner** | HCMS N.V. (subsidiary of K&K Heritage Group N.V.) |
| **Domains** | `hcmsnv.com/jobs` (public careers) · `humanable.hcmsnv.com` (internal back-office) · `employer.hcmsnv.com` (employer portal) |
| **Replaces** | Zoho Recruit (full ATS + pipeline + contracts) |
| **Public Brand Note** | "De Oplossing" dormant; HCMS branding used |
| **Model** | Single-tenant, HCMS-operated managed recruitment platform |
| **Primary Communication Channel** | WhatsApp Business Cloud API (with Gmail SMTP as universal fallback) |
| **Languages (v1)** | **English only** · v1.x adds Dutch, French, Portuguese · v2 adds Spanish |
| **Geographic Scope (v1)** | Suriname |
| **Geographic Scope (v2+)** | Guyana, Caribbean, regional K&K Heritage Group expansion |
| **Recruitment License Status** | ✅ HCMS already holds required recruitment license(s) in Suriname |
| **Deployment Target** | **Shared LiquidNet US VPS** (co-hosted with ATLAS + Compliance Shield · 16 GB RAM minimum · US region) |
| **Mobile (v1.2 phase)** | React Expo + EAS Build · Apple Developer + Google Play under Chivaro Gajadien personal account (interim; org account transition planned by v1.1) |

---

## 2. The HCMS App Suite

HUMANABLE is one of four purpose-built apps in the HCMS Sovereign App Suite. Each is a standalone operational platform; together they form a unified human-capital operating system.

### 2.1 The Four Pillars

| Pillar | App | Service Line | Primary User | Lifecycle |
| :---- | :---- | :---- | :---- | :---- |
| **I — Recruitment** | **HUMANABLE** | HCMS-PRO-001, HCMS-PRO-005 | Candidates, recruiters, employers | Days to weeks |
| **II — Expat Concierge** | **ATLAS** | HCMS-PRO-003 | Expats, families, sponsors | 24+ months |
| **III — Learning & Training** | **HCMS Academy** | HCMS-PRO-006 | Employees, trainers, employers | Recurring/ongoing |
| **IV — AI Executive Coaching** | **HCMS Digi Coaches** | Cross-cutting | Executives, managers | Always-on |

### 2.2 Suite Design Principles

1. Each app is sovereign — fully functional in isolation
2. Each app integrates — shared identity, shared data fabric, shared compliance
3. Each app exports value — events from one feed enriched workflows in others
4. One brand, four products — all under HCMS N.V., backed by K&K Heritage Group

### 2.3 Shared Infrastructure

Consumed by all four apps (deployed on shared LiquidNet US VPS):
- Shared Identity Layer (SSO via Laravel Sanctum + JWT)
- K&K Master User Directory
- Shared Vendor Database
- Shared Employer/Client Database
- **Compliance Shield Microservice** — separate 3rd FO (`HCMS-FO-ComplianceShield-v1.0-2026.md`)
- Unified Analytics Data Warehouse
- ISR Engine (K&K Central Support Units routing)
- Asana Bidirectional Sync (CG POWER Method™ mandate)

### 2.4 HUMANABLE App-to-App Bridges

- **HUMANABLE → ATLAS** — Offer accepted with `expat_flag = true` creates ATLAS expat profile + family records
- **HUMANABLE → HCMS Academy** — Hire confirmed enrolls new hire in onboarding learning path
- **HUMANABLE → HCMS Digi Coaches** — Hire confirmed assigns BRIAN coach (AXIS for executives)

---

## 3. User Roles

| Role | Definition | Authentication |
| :---- | :---- | :---- |
| **Public Visitor** | Anyone browsing partial job listings on hcmsnv.com/jobs | None — anonymous |
| **Job Seeker (Candidate)** | Registered candidate with profile, CV, application history | **WhatsApp number + Email** (dual primary identifiers, no third-party SSO) |
| **Employer (Client Contact)** | Company contact with access to their own pipeline | Email + Password + MFA |
| **HCMS Recruiter** | Operational staff running day-to-day pipeline | Email + Password + MFA |
| **HCMS Admin** | Full back-office, contracts, billing, reporting | Email + Password + MFA |
| **HCMS Operations Manager** | Oversight, escalations, KPI ownership | Email + Password + MFA |
| **Interviewer** | Limited access to fill scorecards | Email + Password (MFA optional) |
| **External Vendor** | Background check vendors, external search firms | Email + Password + MFA |
| **Read-Only Auditor** | For client audits or compliance reviews | Email + Password + MFA |

### 3.1 Special Permission Rules

- Interviewers see only assigned candidates
- Employer users see only their own vacancies and candidates
- External Vendors see only their assigned tickets
- Candidates never see HCMS-internal notes
- **Salary/compensation hidden from employer until shortlist stage** (recruiter sees throughout)
- **Bulk operations restricted to Operations Manager + Admin only** (recruiters request escalation)
- Audit logs capture every privilege escalation, document access, offer signature

---

## 4. The Recruitment Lifecycle — Five Phases

### Phase 0 — Pre-Approval
Trigger phrase: `"Initiate HCMS Recruitment Project"`

| Step | Activity |
| :---- | :---- |
| 0.1 | Initial Inquiry Intake (from employer or self-serve) |
| 0.2 | Discovery & Needs Analysis → HCMS-F-025 (general) or HCMS-F-025-AI (AI Talent) |
| 0.3 | Formal Recruitment Proposal Generation |
| 0.4 | Agreement Finalization → Contractbeheer handoff via ISR |

### Phase 1 — Attract & Source
Trigger phrase: `"Activate Recruitment for [Client Name]"`

- Branded careers page on `hcmsnv.com/jobs` — **partial browse model**: titles + summaries public; details + apply behind login
- Employer self-serve vacancy intake (subject to HCMS approval)
- AI-generated job descriptions in **English** (multilingual returns in v1.x)
- Auto-post to Facebook Jobs + LinkedIn
- Programmatic job advertising (Appcast/Talroo) — v1.1
- WhatsApp broadcast to opted-in candidate segments
- Passive sourcing via HCMS talent graph
- **Public CV optimizer tool** with **implicit consent** model
- Employer Brand Pages at `hcmsnv.com/employers/[client]`
- **Confidential Search Mode** for executive/leadership searches
- Sector-specific JD templates (Oil & Gas, Mining, Construction, Finance, Healthcare, Government)
- Sourcing Agent runs continuously

### Phase 2 — Screen & Triage

- CV parser (PDF/DOCX → structured profile)
- Photo CV capture and OCR via Claude vision
- LinkedIn URL import
- Voice note as CV intro (WhatsApp voice → transcribed + embedded)
- Standardized digital candidate profile
- pgvector embeddings (via Anthropic embedding service)
- AI match score (semantic + structured filters)
- Skills-Based Matching Engine with O*NET/ESCO taxonomy
- AI screening summary (3-line: fit / concerns / recommendation)
- **Blind Screening Mode** — per-vacancy toggle (recruiter decides per role)
- Configurable auto-rejection rules with human review queue
- **Two-tier Duplicate Detection**:
  - Tier 1 (Auto-merge): Strict email + phone exact match
  - Tier 2 (Surface for review): AI embedding similarity → recruiter confirms merge
- Triage Agent auto-processes inbound applications
- Resurfacing Agent auto-matches new vacancies against historical pool
- Counter-Offer Risk Scoring at shortlist stage
- Predicted Time-to-Fill at vacancy creation
- **Identity verification trigger at shortlist** — before client presentation

### Phase 3 — Evaluate & Interview
Trigger phrase: `"Prepare Candidate Slate for [Client Name]"`

- Kanban pipeline per vacancy with configurable stages
- Master pipeline view across all vacancies (HCMS admin)
- SLA tracking + bottleneck alerts
- Self-scheduling via WhatsApp link + Google/Outlook calendar sync
- Scheduling Agent handles interview logistics autonomously
- Standardized scorecards per role type
- @-mentions and internal notes on candidate profiles
- Candidate rating (1–5 stars), placement history
- **Candidate Summary Profile (CSA) Generator** — auto-generated for client presentation
- WhatsApp Voice Screening — AI-conducted 3–5 minute voice interview
- Reference Check Agent — structured WhatsApp reference questionnaires
- Real-Time Interview Co-Pilot — AI present during live interviews
- Live Interview Transcription
- **Ideal Candidate Profile (ICP) Module** — formal artifact per vacancy
- Client-Facing Progress Tracker — automated weekly export to employer
- **Good Behaviour Document (Verklaring van goed gedrag)** — required upload before final selection (waiver path via Ops Head approval)

### Phase 4 — Offer & Onboard
Trigger phrase: `"Generate Offer for [Candidate Name]"`

- Template-based offer letter generator with AI language polish
- Salary Negotiation Simulator
- Internal approval routing (HCMS admin + employer sign-off)
- Lightweight in-house e-signature
- **Personalized rejection workflow** for unsuccessful candidates (Claude-drafted, references the role, suggests other open roles)
- Offer Agent drafts letter, routes for approval, sends to candidate, triggers ISR to K&K Finance
- Pre-Boarding Engagement — automated WhatsApp engagement
- 30/60/90-day check-in automation
- Post-Placement Agent
- Replacement Guarantee Tracker (90-day local / 180-day expat/AI Talent)
- Hired-candidate export (PDF + structured data) for HRIS handoff
- **Bridge to ATLAS** for expat-flagged hires
- **Bridge to HCMS-PRO-002 EOR** — auto-handoff to QuickBooks/Celery
- **Bridge to HCMS Academy** — enroll new hire in onboarding learning path
- **Bridge to HCMS Digi Coaches** — assign AI coach
- Follow-Up Agent ensures 48-hour response SLA

---

## 5. Architectural Pillars

### 5.1 Pillar A — Agentic AI Workflow Layer

Eight named autonomous agents with **Claude → Gemini → graceful-degrade** failure chain. When primary Claude API fails, Gemini API fallback engages. If Gemini also fails, the workflow step becomes a manual task for the assigned recruiter. All attempts logged in `agent_runs` + Compliance Shield Module 5 (EU AI Act).

| Agent | Function | Trigger |
| :---- | :---- | :---- |
| **Sourcing Agent** | Continuously scans LinkedIn, job boards, talent graph | Vacancy created/updated |
| **Triage Agent** | Auto-processes inbound applications (CV parse, match score, route) | New application |
| **Scheduling Agent** | Coordinates interview logistics via WhatsApp + calendars | Move to interview stage |
| **Reference Check Agent** | Sends WhatsApp reference questionnaires | Offer stage reached |
| **Follow-Up Agent** | Ensures candidate response within 48 hours | Stale candidate detected |
| **Offer Agent** | Drafts offer, routes approval, sends, triggers ISR | "Generate Offer" trigger |
| **Post-Placement Agent** | 30/60/90-day check-ins with placed candidates + employers | Hire confirmed + N days |
| **Resurfacing Agent** | Matches new vacancies against historical pool | Vacancy created |

**Implementation:** Laravel job-based via database queue (no Redis). Director-Worker pattern. Each agent has own context window, prompt template, retry logic (3 retries with exponential backoff), 5-min timeout, audit trail.

### 5.2 Pillar B — Voice & Multi-Modal Communication

| Capability | Engine |
| :---- | :---- |
| WhatsApp Voice Screening | Claude voice |
| Voice Note CV Intro | Claude or Gemini |
| Photo CV Capture | Claude vision |
| LinkedIn URL Import | Public web scraping |
| Live Interview Transcription | Claude voice |

### 5.3 Pillar C — Compliance Shield (Shared Microservice)

**The Compliance Shield is documented in its own dedicated FO:** `HCMS-FO-ComplianceShield-v1.0-2026.md`. HUMANABLE consumes its 8 modules via internal HTTP API at `compliance-shield.internal:8003`:

1. **38% Expat Income Tax Pre-Flight** — at offer drafting for expat-flagged hires
2. **Article 1639 Seniority Liability Flag** — at vacancy creation for crew take-over scenarios
3. **Work Permit Pre-Screening** — at expat candidate shortlisting
4. **Local Content Auto-Reporter** — quarterly for Tier-1 Operator clients
5. **EU AI Act Compliance Layer** — every AI agent decision logged here
6. **Bias Detection** — JDs and scorecards scanned before publish
7. **GDPR Subject Request Portal** — candidate data subject requests
8. **Right-to-Work Verification** — pre-offer for expat candidates

### 5.4 Pillar D — Service Line Specialization Bridges

| Specialization | Distinct Workflow |
| :---- | :---- |
| HCMS-PRO-001 General Recruitment | Standard 4-phase + Phase 0 · 90-day guarantee · 12–15% fee |
| HCMS-PRO-005 AI Talent Solutions | AI Talent flag → HCMS-F-025-AI + HCMS-F-026 + Tech Fit Score >85% + GitHub/HuggingFace/arXiv/Kaggle sourcing · 18–20% · 180-day guarantee |
| HCMS-PRO-003 Expat Recruitment | Expat flag → Compliance Shield modules 1+3+8 + 180-day guarantee + ATLAS handoff at offer · 22–25% |
| HCMS-PRO-002 EOR Bridge | EOR-managed hire → auto-handoff to QuickBooks/Celery |
| HCMS-PRO-004 Outplacement Bridge | Offboarded candidates → outplacement pipeline |
| HCMS-PRO-006 Academy Bridge | Hired → onboarding path · Academy graduates → pre-verified talent pool |

### 5.5 Pillar E — Quality of Hire (QoH) Engine

QoH is the **apex KPI**. Composite Score:

| Input | Weight |
| :---- | :---- |
| 30/60/90-day retention | 25% |
| Employer-rated performance at 90 days | 25% |
| Internal mobility/promotion within 12 months | 15% |
| Counter-offer rate (inverse) | 15% |
| Candidate NPS post-placement | 10% |
| Time-to-Fill (inverse) | 10% |

QoH data feeds back into the matching model continuously.

---

## 6. Service Line Specialization

### 6.1 HCMS-PRO-001 General Recruitment (Default)

- 4-phase + Phase 0 lifecycle
- Pricing: 12–15% of annual gross salary
- Replacement guarantee: 90 days
- Standard sourcing: LinkedIn, Facebook, talent graph, programmatic ads
- Fee tranches: 65% at offer acceptance, 35% at guarantee close

### 6.2 HCMS-PRO-005 AI Talent Solutions

Activated by **AI Talent flag** at vacancy creation.

| Element | General | AI Talent |
| :---- | :---- | :---- |
| Needs Analysis Form | HCMS-F-025 | **HCMS-F-025-AI** |
| Vetting Questionnaire | Standard scorecard | **HCMS-F-026** |
| Gating Criteria | General fit | **Technical Fit Score >85%** |
| Sourcing Channels | LinkedIn, FB, boards | **+ GitHub, HuggingFace, arXiv, Kaggle** |
| Service Agreement | Standard MSA | **AI Talent Service Agreement** |
| Pricing | 12–15% | **18–20%** |
| Replacement Guarantee | 90 days | **180 days** |

### 6.3 HCMS-PRO-003 Expat Recruitment (Bridge to ATLAS)

Activated by **Expat flag** at vacancy creation:
- 38% Expat Income Tax Pre-Flight via Compliance Shield Module 1
- Work Permit Pre-Screening via Compliance Shield Module 3
- 180-day replacement guarantee
- Pricing: 22–25% of annual gross
- At offer acceptance → automated handoff to ATLAS

---

## 7. Trigger Phrase Workflows (HCMS-CYL-002)

| Trigger Phrase | Executes |
| :---- | :---- |
| `"Initiate HCMS Recruitment Project"` | Phase 0: Inquiry intake → Needs Analysis → Proposal Generator → Submission Email |
| `"Activate Recruitment for [Client]"` | Phase 1: Project Plan + ICP + Client-Facing Progress Tracker |
| `"Prepare Candidate Slate for [Client]"` | Phase 3: CSA Generator + Submission Email |
| `"Generate Offer for [Candidate]"` | Phase 4: Offer Letter + Submission Email + Personalized Rejection Emails for non-selected candidates |

Trigger phrases work in HUMANABLE chat/AI interface, Asana task creation, and email subject lines.

---

## 8. AI Capabilities

### 8.1 Provider Strategy (Locked v1.3)

| Tier | Provider | Use Cases |
| :---- | :---- | :---- |
| **Primary** | **Claude API (Anthropic)** | All generative tasks: JDs, CV parsing, screening summaries, offer letters, personalized rejections, AI Concierge, vision (photo CV), reference questionnaires |
| **Fallback** | **Google Gemini API** | Triggered when Claude API fails or rate-limits. Same task scope. ✅ §29 approved exception |
| **Embeddings** | **Anthropic embedding service** | Candidate-vacancy matching, semantic search, duplicate detection (Tier 2), resurfacing agent |
| **Open-source LLM** | **REMOVED from plan** (was in v1.2) — replaced by Gemini fallback |

### 8.2 Generative Tasks (Claude API)

Job Description Generator · CV Parsing & Extraction · Match Score + 3-Line Summary · Outreach Message Drafter · Interview Question Generator · Salary Band Suggestions · Public CV Optimizer · Offer Letter Polish · **Personalized Rejection Generator** · Weekly Recruiter Digest · Candidate Resurfacing Notifications · AI Concierge Chatbot · Cultural Coach

### 8.3 Cost Posture

- Claude API: budgeted monthly with cost monitoring
- Gemini API: minimal spend (fallback only)
- Anthropic embedding service: estimated <$10/month at HUMANABLE's <100/month volume
- **No self-hosted infrastructure** — simpler ops at acceptable cost

### 8.4 AI Agent Orchestration

See §5.1 — 8 named agents with Claude → Gemini → graceful-degrade chain. Runs on Laravel database queue (no Redis).

### 8.5 AI Governance (EU AI Act via Compliance Shield)

All AI decisions logged via Compliance Shield Module 5. Candidates have right to request explanation. No high-stakes decision is fully automated — always human-in-the-loop. Bias detection on JDs and scorecards via Compliance Shield Module 6.

---

## 9. Candidate Experience

### 9.1 Public Visitor Journey (Anonymous Browse)

**Partial browse model** at `hcmsnv.com/jobs`:

| Element | No Login | Logged In |
| :---- | :---- | :---- |
| Job titles | ✅ Visible | ✅ Visible |
| Job summary (2–3 lines) | ✅ Visible | ✅ Visible |
| Full job description | ❌ Login required | ✅ Visible |
| Salary band | ❌ Login required | ✅ Visible |
| Apply button | ❌ Login required | ✅ Available |
| Company name | Per-employer setting (Confidential Search Mode → hidden) | Per setting |

### 9.2 Account Creation Flow

**Authentication: WhatsApp number + Email** (dual primary identifiers). No third-party SSO in v1.

Account creation occurs **during application** (no pre-registration required):

1. Candidate clicks "Apply"
2. System prompts for WhatsApp number + email
3. Inline account creation
4. Application form follows
5. Confirmation via WhatsApp + email

### 9.3 Public CV Optimizer (Lead-Gen Surface)

Free public tool — talent graph capture via **implicit consent**:

- Clear notice before tool use: *"By using the CV Optimizer, you agree to enter the HCMS Talent Graph. We may match you to future opportunities. You can request data deletion at any time."*
- Use of tool = consent
- GDPR-compliant clear language + explicit deletion path (via Compliance Shield Module 7)

### 9.4 Application Status Visibility (Milestone-Only)

| State | Meaning |
| :---- | :---- |
| **Applied** | Application received |
| **Under Review** | Active screening / interview / decision in progress |
| **Decision Made** | Final outcome — accepted or politely rejected |

Internal stages NOT exposed to candidates.

### 9.5 Mobile-First Experience

- True mobile-first web design (Suriname is a mobile-first market)
- WhatsApp as primary notification + interaction channel
- Photo CV upload via mobile camera (Claude vision)
- LinkedIn URL paste-import
- Voice note CV intro (60 sec)
- Native mobile recruiter app (v1.2 phase via React Expo)

### 9.6 Rejection UX (Personalized)

Unsuccessful candidates receive a **personalized, Claude-drafted rejection** that:
1. References the specific role they applied for
2. Communicates with warmth and professionalism
3. Suggests other open roles where they might fit
4. Provides talent graph opt-in for future opportunities

### 9.7 Additional Capabilities

- Job Seeker Dashboard (profile, CV versions, application status, communications)
- WhatsApp-First Communication
- Email Fallback (Gmail SMTP) for candidates without WhatsApp
- Self-Service Interview Scheduling
- GDPR Self-Service (partial — access + export self-service; deletion via support ticket via Compliance Shield Module 7)
- **English in v1** (multilingual returns in v1.x)
- AI Concierge 24/7 (Claude with Gemini fallback)
- Auto-Resurfacing Notifications

---

## 10. Employer Experience

### 10.1 Employer Portal Capabilities

- Read + comment access to their own pipeline
- Self-serve vacancy submission (HCMS approval required before publish)
- Candidate profile review with AI summary, match score, scorecards
- Interview scheduling participation
- Offer approval workflow
- Communication thread with assigned HCMS recruiter
- Employer Brand Page at `hcmsnv.com/employers/[client]`
- Quarterly Business Review (QBR) Auto-Generator
- Client AI Copilot (Claude with Gemini fallback)
- Replacement Guarantee Tracker
- Cost & Invoice Visibility
- Internal Mobility Module (v1.1)
- HRIS API Integration (v2 for Workday, SuccessFactors, SAP)
- Local Content Compliance Reports for Tier-1 Operators (via Compliance Shield Module 4)

### 10.2 Salary Visibility Rule (CRITICAL)

**Salary/compensation hidden from employer until shortlist stage.**

- During application + screening: recruiter sees expected/current salary; employer does NOT
- At shortlist: salary visible to employer alongside CSA
- Rationale: reduces anchoring bias, protects candidate negotiation, lets HCMS recruiter triage on fit before salary noise

### 10.3 Per-Employer Configurable Settings

| Setting | Options |
| :---- | :---- |
| **Default invoice currency** | USD / SRD / other |
| **Tax handling** | Configurable per-employer profile (OB applicability, withholding rules) |
| **Blind screening default** | On / Off (overridable per-vacancy) |
| **Good behaviour document** | Required (default) / Waived (motivated + Ops Head approval) |
| **Document retention override** | Standard 5 years / Extended (per agreement) |
| **Approval thresholds** | Per-cost-category |
| **Notification cadence** | Real-time / Daily digest / Weekly digest |
| **Bulk operations access** | Read-only / Comment / Approve |

---

## 11. HCMS Back-Office (Filament 3 Admin)

### 11.1 Core Modules

- Master Pipeline Manager (Kanban across all active vacancies)
- Candidates Module (full DB, search/filter, AI match)
- Vacancies Module (lifecycle, AI Talent flag, Expat flag)
- Employers Module (per-employer config — §10.3)
- Scorecards Module
- Communications Log
- Offer Letters Module
- Reports Module (funnel analytics, time-to-hire, source attribution, **QoH dashboard**)
- Users & Permissions
- Settings
- Agent Orchestrator Dashboard (8 agents status, retry queue, Claude/Gemini health)
- Compliance Dashboard (consumes Compliance Shield API)
- Recruiter Performance Layer
- Recruiter AI Copilot ("OSCAR-R")
- Asana Bidirectional Sync
- ISR Engine
- MSA/SOW Generator
- Replacement Guarantee Tracker
- Vendor/Partner Management

### 11.2 Document Verification UI

Recruiters use a dedicated verification interface for:
- Identity documents (passport, national ID)
- Good behaviour document (Verklaring van goed gedrag)
- Diploma/education credentials (technical/professional roles)
- Other supporting documents

States: `pending` / `verified` / `flagged` / `rejected` / `waived`. Waived requires justification + Ops Head approval.

### 11.3 Blind Screening Toggle

**Per-vacancy toggle** controlled by assigned recruiter. When active: candidate name + photo + age + gender + ethnicity + nationality hidden during initial review. Recruiter "reveals" identity at decision stage (audit logged). Per-employer override available.

### 11.4 Bulk Operations Governance

**Restricted to Operations Manager + Admin only.**

| Bulk Action | Allowed Role |
| :---- | :---- |
| Bulk reject from closed vacancy | Ops Manager + Admin |
| Bulk reassign between recruiters | Ops Manager + Admin |
| Bulk status update | Ops Manager + Admin |
| Bulk export | Admin + Auditor (read-only) |
| Bulk delete | Admin only |

Recruiters request bulk operations from Ops Manager via in-platform escalation.

### 11.5 Duplicate Detection Workflow

**Two-tier model:**

**Tier 1 — Auto-Merge (Strict):** New record with email + phone exact match → automatic merge; older record retained; new application appended; both IDs logged.

**Tier 2 — Surface for Review (AI-Driven):** New record with embedding similarity > threshold (no exact match) → surface to assigned recruiter in "potential duplicate" queue; recruiter confirms merge OR rejects as distinct.

### 11.6 Recruiter Ownership (First-Come-First-Served)

When a recruiter attaches a candidate to a vacancy, that recruiter "owns" the candidate-vacancy pairing. Visible: "Owned by: [Recruiter] · since [date]". Ownership release requires original owner OR Ops Manager arbitration.

---

## 12. Vendor & Partner Experience

- Vendor Portal (per-vendor login showing only assigned tickets)
- Ticket Workflow (receive, update status, submit documents, request clarification)
- Document Upload (encrypted, audit-logged to VPS local storage)
- Invoice Submission (auto-routes to HCMS Admin via ISR)
- Performance Ratings (per-ticket; affects future assignment priority)
- SLA Acceptance (vendor must accept within agreed SLA or auto-reassign)
- Communication Thread (logged)
- Confidentiality Agreement e-signed before access

---

## 13. Collaboration & Evaluation Tools

- Standardized Customizable Scorecards
- @-Mentions on candidate profiles
- Internal Recruiter Notes (separate from employer-visible)
- Shared Candidate Profile Views
- Interview Scheduling (Google + Outlook OAuth)
- Real-Time Interview Co-Pilot
- Approval Workflows
- Salary Negotiation Simulator
- Recruiter Coaching Prompts

---

## 14. Analytics & Reporting

### 14.1 Apex KPI

**Quality of Hire (QoH)** per §5.5.

### 14.2 Standard KPIs

| KPI | Target |
| :---- | :---- |
| Time-to-Fill (avg) | <45 days |
| Time-to-Fill (AI Talent) | <60 days |
| Time-to-Fill (Expat) | <75 days |
| Placement Success Rate | >95% |
| Client Satisfaction (CSAT) | >90% |
| SLA Breach Rate | <5% |
| First-Response Time (Candidate) | <48 hours |

### 14.3 Performance & Infrastructure Targets (v1.3)

| Metric | Year 1 |
| :---- | :---- |
| Concurrent active users | 50–200 |
| Application volume / month | <100/month (premium specialized focus) |
| Response time SLA | Best-effort — optimize as we grow |
| VPS resource utilization | 30–60% steady state (shared with ATLAS + Compliance Shield) |

**Performance Note:** Due to VPS-native architecture (no Redis, no Meilisearch), queue throughput and search latency are reduced vs Redis/Meilisearch. At HUMANABLE's volume this is acceptable. If load grows substantially in Year 2+, Redis can be reintroduced as a §29 exception via change request.

### 14.4 Compliance Reporting

- Local Content reports via Compliance Shield Module 4
- GDPR fulfillment metrics via Module 7
- EU AI Act decision audit trail via Module 5
- Diversity reporting where permissible

---

## 15. Integrations (Locked v1.3)

| Integration | Purpose | Status |
| :---- | :---- | :---- |
| **Claude API (Anthropic)** | Primary AI engine | ✅ §29 approved exception |
| **Google Gemini API** | Claude fallback | ✅ §29 approved exception |
| **Anthropic Embedding Service** | Semantic matching, search | ✅ §29 approved exception |
| **WhatsApp Business Cloud API (Meta)** | Primary comms + auth | ✅ §29 approved exception |
| **Gmail / Google Workspace SMTP** | Universal email + auth | ✅ §29 approved (standard) |
| **Twilio SMS** | Critical-notification escalation only | ✅ §29 approved exception |
| **Self-hosted Sentry** | Error monitoring (shared with ATLAS + Compliance Shield) | ✅ Approved |
| **EAS Build (Expo Application Services)** | Mobile CI/CD for v1.2 phase | ✅ §29 approved exception |
| **Google Drive API** | Offsite backup destination | ✅ §29 approved exception |
| **Google Calendar + Outlook OAuth** | Interview scheduling | ✅ Approved (standard) |
| **Facebook Jobs API** | Auto-post vacancies | ✅ Approved (standard) |
| **LinkedIn API** | Auto-post + URL profile import | ✅ Approved (standard) |
| **Asana API** | Bidirectional sync (CG POWER mandate) | ✅ Approved (standard) |
| **GitHub Actions** | CI/CD (backend) | ✅ Approved (standard) |
| **Compliance Shield Microservice** | Internal HTTP API (separate FO) | Internal — VPS-local |
| **Identity Layer (SSO)** | Shared with App Suite | Internal |
| **K&K Vendor Database** | Shared vendor directory | Internal |
| **K&K Employer Database** | Shared client directory | Internal |
| **ISR Engine** | K&K Central Support routing | Internal |
| **ATLAS Bridge** | Expat handoff at offer | Internal |
| **HCMS Academy Bridge** | Onboarding enrollment | Internal — v1.1 |
| **HCMS Digi Coaches Bridge** | New-hire AI coach | Internal — v1.1 |
| **EOR Payroll Bridge (QuickBooks/Celery)** | EOR onboarding | v1.1 |
| **HRIS Exports per Employer** | Tier-1 Operator integrations | v1.1 |
| **GitHub / HuggingFace / arXiv / Kaggle** | AI Talent sourcing | v1.1 |
| **Programmatic Job Ads (Appcast/Talroo)** | 50+ board distribution | v1.1 |
| **Currency Exchange API (free public source)** | Multi-currency per-employer | v1 |

### 15.1 Explicitly Removed (from prior plans)

| Removed | Reason | Replacement |
| :---- | :---- | :---- |
| Docker / docker-compose | No container support on VPS | Direct Laravel deployment |
| AWS ECS Fargate + RDS + S3 | No managed cloud services | LiquidNet VPS + local disk + Google Drive backup |
| Redis (cache + queue + session + broadcast) | Not approved per guidelines | Laravel database drivers |
| Meilisearch | External service not approved | PostgreSQL FTS + pgvector |
| Laravel Horizon | Redis-dependent | Laravel Pulse |
| Open-source LLM (Llama/Mistral) | Replaced by Gemini | Claude + Gemini dual-provider |
| Self-hosted embedding model (sentence-transformers) | Operational complexity | Anthropic embedding service |
| Datadog | Not justified at scale | Self-hosted Sentry |
| LinkedIn SSO / Google SSO for candidates | Per gap-closure decision | WhatsApp + Email dual auth only |
| Voyage / OpenAI embeddings APIs | Consolidated to Anthropic ecosystem | Anthropic embedding service |

---

## 16. HCMS App Suite Integration Architecture

### 16.1 Direct App-to-App Bridges (HUMANABLE-Centric)

**HUMANABLE → ATLAS:**
- Trigger: Offer accepted + `expat_flag = true`
- Action: Auto-create ATLAS expat profile + family member records
- Payload: Candidate data, employer data, offer terms, anticipated start date
- Authentication: Shared service token

**HUMANABLE → HCMS Academy:**
- Trigger: Hire confirmed (post-90-day guarantee close)
- Action: Auto-enroll new hire in role-specific onboarding learning path

**HUMANABLE → HCMS Digi Coaches:**
- Trigger: Hire confirmed
- Action: Assign BRIAN coach for first 90 days; AXIS for executive hires

### 16.2 Shared Infrastructure Consumed

- Shared Identity Layer (Laravel Sanctum + JWT)
- Compliance Shield Microservice (separate 3rd FO)
- K&K Master User Directory
- Shared Vendor + Employer Databases
- Unified Analytics Data Warehouse
- ISR Engine

---

## 17. Compliance & Security

### 17.1 Regulatory Alignment

- **GDPR** (via Compliance Shield Module 7)
- **Suriname Data Protection Act**
- **Suriname Labour Law** — 5-year document retention
- **EU AI Act** (via Compliance Shield Module 5)
- **Suriname Recruitment Licensing** — ✅ HCMS already holds

### 17.2 Security Baseline

| Element | Specification |
| :---- | :---- |
| Document Encryption | At-rest (VPS filesystem encryption) + in-transit (TLS 1.3) |
| RBAC | Granular; spatie/laravel-permission |
| MFA | Mandatory for HCMS-internal + employer users; optional for candidates |
| SSO | Shared identity layer across App Suite |
| Audit Logs | All sensitive actions logged |
| PII Tokenization | Passport numbers, financial data tokenized |
| Data Residency | LiquidNet US VPS (US region) — explicit data residency in §1 |
| SOC 2 Type II Readiness | Post-launch certification roadmap |
| Penetration Testing | Quarterly external pen-test post-launch |
| Incident Response | Documented playbook + 4-hour escalation SLA |
| Backup & DR | Daily VPS backups to Google Drive · 24-hour RTO · 1-hour RPO |
| Bias Detection | Compliance Shield Module 6 |

### 17.3 Document Retention Policy

**5-year retention** (Suriname Labour Law alignment). Auto-purge workflow with 30/14/7-day pre-purge notifications. Documents in active engagements are retention-extended. Candidate deletion via GDPR portal subject to active engagement review (Compliance Shield Module 7).

### 17.4 Right-to-Work & Identity Verification

See §23 below.

### 17.5 Internationalization (i18n) Strategy

**v1: English only.** Laravel native i18n framework built but only `en_US` locale populated. v1.x adds NL/FR/PT; v2 adds Spanish.

| Content Type | v1 Approach |
| :---- | :---- |
| UI strings | Single locale (`en_US`) |
| Dynamic content (JDs, AI summaries) | Claude/Gemini generating English |
| Email/WhatsApp templates | English templates |

### 17.6 GDPR Subject Request Portal

Consumed via Compliance Shield Module 7. Partial self-service model:
- Right to Access: ✅ Self-service
- Right to Portability (Export): ✅ Self-service
- Right to Rectification: ✅ Self-service for own fields
- Right to Erasure (Deletion): ⚠️ Support ticket required, 30-day SLA
- Right to Object / Restrict: Support ticket workflow

### 17.7 Backup Strategy (v1.3)

| Backup Type | Frequency | Destination |
| :---- | :---- | :---- |
| PostgreSQL database dump | Daily (2 AM local) | **Google Drive** (HCMS Workspace) + local 7-day retention |
| File storage sync | Daily (2:30 AM local) | **Google Drive** (incremental) |
| Configuration + `.env` (encrypted) | Weekly + on-change | **Google Drive** (encrypted bundles) |
| Application code | Continuous | GitHub |

Retention: 30 days daily · 12 weeks weekly · 5 years for compliance-relevant data.

### 17.8 Consent Capture

- Public CV Optimizer: implicit consent with clear notice
- Job Applications: explicit consent at submission
- Talent graph re-engagement: opt-out via dashboard or support ticket
- All consent events stored in `consent_records` table

---

## 18. Technical Architecture (v1.3 LOCKED)

### 18.1 Locked Stack

| Layer | Choice |
| :---- | :---- |
| **OS** | Ubuntu LTS 22.04 (LiquidNet default) |
| **Web Server** | Nginx |
| **Backend Framework** | **Laravel 13+** |
| **PHP** | **PHP 8.3+** |
| **Frontend (Web)** | **React 18 + Inertia.js + TailwindCSS + Vite** |
| **Mobile (v1.2 phase)** | **React Expo** + EAS Build |
| **Mobile Distribution** | Chivaro Gajadien personal Apple Developer + Google Play (interim) |
| **Admin Back-Office** | **Filament 3** |
| **Database (Production)** | **PostgreSQL 16 + pgvector** (shared DB server, schema `humanable`) |
| **Database (Local Dev)** | **SQLite** |
| **Cache Driver** | Laravel `database` driver |
| **Queue Driver** | Laravel `database` driver |
| **Session Driver** | Laravel `database` driver |
| **Broadcasting** | Laravel `log` driver |
| **Search** | PostgreSQL Full-Text Search + pgvector |
| **Background Jobs** | Laravel queue worker (systemd-managed) |
| **Queue Monitoring** | Laravel Pulse |
| **AI (Primary)** | Claude API |
| **AI (Fallback)** | Google Gemini API |
| **Embeddings** | Anthropic embedding service |
| **File Storage** | Local disk on shared VPS + Google Drive offsite backup |
| **WhatsApp** | Meta WhatsApp Business Cloud API |
| **Email** | Gmail / Google Workspace SMTP |
| **SMS** | Twilio (critical-only) |
| **Auth + SSO** | Laravel Sanctum + JWT |
| **Error Monitoring** | Self-hosted Sentry on shared VPS |
| **Application Monitoring** | Laravel Pulse + Laravel Telescope (dev only) |
| **CI/CD (Backend)** | GitHub Actions |
| **CI/CD (Mobile v1.2)** | GitHub Actions + EAS Build + Fastlane |
| **Hosting** | Shared LiquidNet US VPS |
| **VPS Region** | US |
| **VPS Specs (shared min)** | 16 GB RAM · 6 vCPU · 400 GB SSD |
| **Environment Topology** | Dev (SQLite local) → Staging → Production |
| **Process Management** | systemd |
| **TLS** | Let's Encrypt via Certbot |

### 18.2 Deployment Workflow

```bash
1. git pull origin main
2. composer install --no-dev --optimize-autoloader
3. npm install
4. npm run build
5. php artisan migrate --force
6. php artisan config:cache
7. php artisan route:cache
8. php artisan view:cache
9. php artisan queue:restart
10. systemctl reload nginx
```

**No Docker. No Kubernetes. No managed cloud services beyond approved exceptions.**

### 18.3 Shared VPS Topology

```
┌────────────────────────────────────────────────────────┐
│ LiquidNet US VPS · Ubuntu 22.04 · 16 GB RAM · 400 GB  │
│                                                        │
│  Nginx (reverse proxy + SSL termination)              │
│  ├── humanable.hcmsnv.com    → HUMANABLE  (8001)      │
│  ├── atlas.hcmsnv.com         → ATLAS      (8002)     │
│  └── compliance-shield.internal → CS       (8003)     │
│                                                        │
│  PostgreSQL 16 + pgvector (shared instance)           │
│  ├── humanable schema                                  │
│  ├── atlas schema                                      │
│  └── compliance_shield schema                          │
│                                                        │
│  Self-hosted Sentry (shared monitoring)               │
│  systemd services (queue workers, scheduler)          │
│  Local file storage + Google Drive backup sync        │
└────────────────────────────────────────────────────────┘
```

### 18.4 Single-VPS Resource Topology (HUMANABLE Share)

| Process | Resource Profile | Management |
| :---- | :---- | :---- |
| Nginx (web server) | ~150 MB RAM (shared with ATLAS + CS) | systemd |
| PHP-FPM (HUMANABLE) | ~300–500 MB RAM (multiple workers) | systemd |
| PostgreSQL 16 + pgvector | ~1.5 GB RAM (shared with all apps) | systemd |
| Laravel queue worker (HUMANABLE, 2 daemons) | ~150–200 MB RAM | systemd |
| Laravel scheduler (HUMANABLE cron) | ~50 MB RAM | crontab |
| File storage (HUMANABLE) | Disk-bound | Filesystem |

### 18.5 Backup & DR

Daily PostgreSQL dump + filesystem sync to Google Drive. Retention: 30 days daily · 12 weeks weekly · 5 yearly · 5-year compliance retention. RTO 24 hours · RPO 1 hour.

### 18.6 Agent Orchestration Implementation

- Each agent = Laravel Job class implementing `ShouldQueue`
- Dispatched via database queue (`database` driver)
- Queue worker (systemd service) processes jobs
- Configurable retries (default 3), exponential backoff, 5-min timeout
- **Failure chain**: Claude → Gemini → graceful degrade (manual task for recruiter)
- All runs logged in `agent_runs` table + Compliance Shield Module 5
- Monitoring via Laravel Pulse dashboard

### 18.7 PostgreSQL Full-Text Search (Replaces Meilisearch)

- Each searchable table (candidates, vacancies) gets a generated `tsvector` column
- GIN index for fast lookup
- Multi-language search via PostgreSQL text search configurations (en in v1; nl/fr/pt added v1.x)
- Semantic search via pgvector (cosine similarity on Anthropic embeddings)
- Combined: FTS for keyword + pgvector for semantic, blended in application layer
- Expected performance: 50–200ms for typical candidate search

### 18.8 Anthropic Embedding Integration

```php
// Lightweight wrapper service in HUMANABLE
$response = Http::withToken(config('services.anthropic.embedding_key'))
    ->post('https://api.anthropic.com/v1/embeddings', [
        'model' => 'voyage-3', // or current Anthropic-ecosystem model
        'input' => $textToEmbed,
    ]);

$embedding = $response->json()['data'][0]['embedding'];
// Stored as vector(N) in pgvector column
```

Cost: <$0.0001 per embedding (negligible at HUMANABLE's <100/month volume).

---

## 19. Data Model (Core Tables)

### 19.1 HUMANABLE Business Tables

| Table | Purpose |
| :---- | :---- |
| `users` | All account types (shared identity layer) |
| `candidates` | Job seeker profiles |
| `cv_versions` | Uploaded + AI-revised versions |
| `employers` | Client companies + per-employer config |
| `inquiries` | Phase 0 — initial employer inquiries |
| `needs_analyses` | Phase 0 — HCMS-F-025 / HCMS-F-025-AI |
| `proposals` | Phase 0 — formal recruitment proposals |
| `agreements` | Phase 0 — signed MSA/SOW + Contractbeheer linkage |
| `vacancies` | Job postings (with flags: AI Talent, Expat, blind screening toggle, sector tag) |
| `ideal_candidate_profiles` | Formal ICP per vacancy |
| `pipeline_stages` | Configurable per vacancy or role type |
| `applications` | Candidate ↔ vacancy |
| `interviews` | Scheduled sessions |
| `scorecards` | Templates + completed instances |
| `offers` | Generated offer letters + signature status |
| `placements` | Confirmed hires |
| `replacement_guarantees` | 90/180-day SLA tracking |
| `communications` | WhatsApp/email/SMS thread log |
| `embeddings` | pgvector storage for candidates + vacancies |
| `audit_logs` | Compliance trail (HUMANABLE-internal) |
| `bias_scans_local` | Local cache of Compliance Shield bias scan results |
| `agent_runs` | Agent orchestrator logs |
| `qoh_scores` | Quality of Hire composite scores |
| `references` | Reference check responses |
| `csa_records` | Generated Candidate Summary Profiles |
| `progress_trackers` | Client-Facing Progress Tracker exports |
| `qbr_packs` | Quarterly Business Review packs |
| `consent_records` | GDPR consent capture |
| `vendors` | External partners |
| `vendor_assignments` | Vendor ↔ ticket linkage |
| `invoice_requests` | ISR-routed invoice requests to K&K Finance |
| `bridge_events` | App-to-app integration events |
| `webhook_subscriptions` | External system event subscriptions (v1.2) |
| `recruiter_metrics` | Per-recruiter performance |
| `candidate_documents` | Document store with verification status |
| `document_waivers` | Good behaviour waiver requests + Ops Head approval |
| `recruiter_ownership_claims` | First-come-first-served ownership audit trail |
| `duplicate_detection_queue` | Tier 2 AI-surfaced potential duplicates |
| `notifications` | Multi-channel notification log |
| `notification_preferences` | Per-user channel preferences + quiet hours |
| `zoho_migration_records` | Migration audit table |

### 19.2 Compliance Shield References (External Tables)

The following are tracked in Compliance Shield's own schema (see `HCMS-FO-ComplianceShield-v1.0-2026.md` §5); HUMANABLE keeps local pointers/references for fast lookup:
- `ai_decision_audit` (Compliance Shield Module 5)
- `gdpr_requests_central` (Module 7)
- `tax_calculations` (Module 1)
- `work_permit_screenings` (Module 3)
- `local_content_reports` (Module 4)

### 19.3 Laravel Framework Tables (Required by Database Drivers)

| Table | Purpose |
| :---- | :---- |
| `sessions` | Laravel database session driver |
| `jobs` | Laravel database queue driver — active jobs |
| `failed_jobs` | Failed queue jobs for retry |
| `job_batches` | Laravel job batching |
| `cache` | Laravel database cache driver |
| `cache_locks` | Laravel cache atomic locks |
| `pulse_*` | Laravel Pulse monitoring metrics |
| `personal_access_tokens` | Laravel Sanctum |

---

## 20. Build Phasing & Roadmap

### 20.1 Environment Topology

| Environment | Database | Storage | URL |
| :---- | :---- | :---- | :---- |
| **Dev** | SQLite (local) | Local filesystem | `localhost` |
| **Staging** | PostgreSQL 16 + pgvector on staging VPS | VPS local disk | `humanable-staging.hcmsnv.com` |
| **Production** | PostgreSQL 16 + pgvector on shared LiquidNet US VPS | VPS local disk + Google Drive backup | `humanable.hcmsnv.com` · `hcmsnv.com/jobs` · `employer.hcmsnv.com` |

**Important:** pgvector is PostgreSQL-only. AI matching features must be tested against staging PostgreSQL (SQLite has no pgvector equivalent). CLAUDE.md flags this.

### 20.2 Phased Roadmap (52 weeks)

| Phase | Window | Scope |
| :---- | :---- | :---- |
| **Phase 0 — Bootstrap** | Weeks 1–2 | Repo setup · LiquidNet VPS provisioning · Dev environment (SQLite + Laravel 13+ + Vite + Tailwind) · GitHub Actions CI/CD · CLAUDE.md · base scaffold |
| **Phase 1 — Auth & Identity** | Weeks 3–4 | Laravel Sanctum · Shared SSO · MFA · WhatsApp + Email auth · RBAC · database session driver |
| **Phase 2 — Core Data Model + Zoho Migration Foundation** | Weeks 5–7 | All tables (§19) · Migrations · Framework tables · Zoho migration scripts (§22) |
| **Phase 3 — Filament Admin Back-Office** | Weeks 8–10 | Master Pipeline · Candidates · Vacancies · Employers · Compliance Dashboard |
| **Phase 4 — Public Careers Page + Candidate Portal** | Weeks 11–14 | `hcmsnv.com/jobs` · Application flow · Candidate dashboard · CV Optimizer · **English-only content** |
| **Phase 5 — Phase 0 Pre-Approval Workflow** | Weeks 15–17 | Inquiry · Needs Analysis · Proposal Generator · Agreement Finalization |
| **Phase 6 — Phases 1–4 Lifecycle + Notification Service** | Weeks 18–24 | Attract · Source · Screen · Triage · Evaluate · Interview · Offer · Onboard · Multi-channel notification service (Twilio + Gmail SMTP integration) |
| **Phase 7 — AI Agent Orchestration (Pillar A)** | Weeks 25–28 | 8 agents · Claude + Gemini fallback orchestration · Database-queue execution · Graceful degrade |
| **Phase 8 — Voice & Multi-Modal (Pillar B)** | Weeks 29–31 | WhatsApp voice · Photo CV · LinkedIn URL · Live transcription |
| **Phase 9 — Compliance Shield Integration (Pillar C)** | Weeks 32–34 | Consumes Compliance Shield microservice via HTTP API (CS must be operational by Week 30) |
| **Phase 10 — Service Line Specialization (Pillar D)** | Weeks 35–37 | AI Talent · Expat bridge · EOR/Academy/Digi Coaches bridges |
| **Phase 11 — QoH Engine (Pillar E)** | Weeks 38–40 | QoH data pipeline + dashboard |
| **Phase 12 — Employer Portal** | Weeks 41–43 | `employer.hcmsnv.com` |
| **Phase 13 — Integrations & Search** | Weeks 44–46 | WhatsApp · Asana · Programmatic ads · HRIS exports · Webhooks · PostgreSQL FTS implementation |
| **Phase 14 — Hardening, Zoho Cutover & Launch** | Weeks 47–52 | Pen testing · Performance tuning · LiquidNet production cutover · Google Drive backup activation · Zoho cutover · Soft launch · Full launch |

---

## 21. Glossary

| Term | Definition |
| :---- | :---- |
| **HUMANABLE** | The HCMS Sovereign Recruitment Platform (this FO) |
| **ATLAS** | The HCMS Expat Concierge Portal (Pillar II) |
| **HCMS Academy** | Learning & training platform (Pillar III) |
| **HCMS Digi Coaches** | AI executive coaching platform (Pillar IV) |
| **HCMS App Suite** | Four-pillar product family |
| **Compliance Shield** | Shared microservice (separate 3rd FO) — 8 modules consumed by HUMANABLE + ATLAS |
| **The Vault** | K&K Heritage Group Google Drive Shared Drives |
| **ISR** | Internal Service Request — formalized routing to K&K Central Support |
| **K&K Central Support Units** | Marketing, Finance, Procurement, HR Central, Academy |
| **Sovereign Engine** | HCMS's autonomous operational doctrine |
| **CG POWER Method™** | K&K's scaling methodology — mandates Asana as primary OS |
| **QoH** | Quality of Hire — apex KPI |
| **CSA** | Candidate Summary Profile — generated for client presentation |
| **ICP** | Ideal Candidate Profile — formal per-vacancy artifact |
| **Tier-1 Operators** | TotalEnergies, Chevron, Staatsolie, Newmont |
| **38% Expat Income Tax** | Suriname statutory expat income tax rate |
| **Article 1639** | Suriname civil code seniority liability — Clean Break Protocol |
| **Trigger Phrase** | Canonical phrases per HCMS-CYL-002 |
| **AI Talent Flag** | Vacancy-level flag activating HCMS-PRO-005 |
| **Expat Flag** | Vacancy-level flag activating HCMS-PRO-003 + ATLAS handoff |
| **Verklaring van goed gedrag** | Suriname Certificate of Good Conduct (required pre-final-selection) |
| **Blind Screening Mode** | Per-vacancy toggle hiding names/photos/age during initial review |
| **OB (Omzetbelasting)** | Suriname turnover tax (VAT-equivalent) |
| **Talent Graph** | HCMS's repository of all candidate profiles |
| **Confidential Search Mode** | Anonymized vacancy postings + NDA workflows for executive searches |
| **LiquidNet US LLC** | Locked VPS provider for all HCMS App Suite apps |
| **Gemini API** | Google's LLM API — approved fallback when Claude API fails |
| **EAS Build** | Expo Application Services Build — cloud mobile build service for React Expo apps |
| **Anthropic Embedding Service** | Claude-ecosystem embedding API used for semantic matching |
| **Shared VPS** | Single LiquidNet US VPS co-hosting HUMANABLE + ATLAS + Compliance Shield |
| **VPS** | Virtual Private Server — HCMS-approved deployment platform |
| **PostgreSQL FTS** | Full-Text Search using PostgreSQL's native features |
| **pgvector** | PostgreSQL extension for vector similarity search |
| **Database Driver** | Laravel's option to use the application database for cache/queue/session instead of Redis |
| **Approved External Exception** | Explicitly approved SaaS dependency listed in §29.7 |
| **systemd** | Linux service manager |

---

## 22. Zoho Recruit Migration Strategy

### 22.1 Migration Decisions (Locked)

| Item | Value |
| :---- | :---- |
| **Migration Depth** | Full migration (no date cut-off, all rows within selected categories) |
| **Data Types IN** | Candidate profiles + CVs · Active in-flight vacancies · Employer/client records |
| **Data Types OUT** | Historical placements · Email communications · Scorecards/notes |
| **Cutover Approach** | Decided during Phase 2 (Core Data Model) based on HUMANABLE schema readiness |
| **Rollback Plan** | Defined in Phase 2 as part of cutover specification |

### 22.2 Migration Workstreams

**Workstream A — Data Extraction (Weeks 5–6):** Export from Zoho Recruit · Data quality assessment · Data classification

**Workstream B — Schema Mapping (Weeks 6–7):** Zoho field → HUMANABLE table mapping document · Zoho-specific custom fields · Define `zoho_migration_records` audit table

**Workstream C — Import & Validation (Weeks 7–8):** Batch import scripts (idempotent, resumable) · Validation queries · 1% sample hand-verification

**Workstream D — Cutover Planning (Weeks 45–47):** Decision on cutover approach · Runbook · Communication plan · Zoho license sunset timing

### 22.3 What Does NOT Migrate

Historical placements, email threads, scorecards/notes — clean break. If needed post-cutover (audit), they remain in Zoho as read-only archive for the remainder of the existing contract.

### 22.4 Success Criteria

- 100% of in-scope candidate records imported with original Zoho ID preserved in `zoho_migration_records`
- 100% of active vacancies migrated and verified
- 100% of employer/client records migrated with config defaults set per §10.3
- Zero data corruption
- HCMS recruiter user-acceptance sign-off

---

## 23. Identity & Credential Verification Workflow

### 23.1 Verification Modes (Dual-Mode)

| Mode | Default Use |
| :---- | :---- |
| **In-Person Verification** | Common path — Suriname-pragmatic, default for local candidates |
| **Self-Upload Digital Verification** | Growing demand path — remote candidates, expats, AI Talent specialists |

Recruiter selects mode per candidate. Self-upload requires authenticated session on verified device.

### 23.2 Verification Timing

**Identity verification occurs at the shortlist stage** — before candidate is presented to employer client.

### 23.3 Background Check — Good Behaviour Document Workflow

**Standard Requirement:** All placements require Verklaring van goed gedrag uploaded before final selection. Recruiter verifies via Document Verification UI. States: `pending` / `verified` / `flagged`.

**Waiver Workflow:**
- Recruiter or employer requests waiver with written justification
- **Operations Manager approval required**
- Approved waivers logged in `document_waivers` with full audit trail
- Two levels: candidate-level (specific candidate) OR vacancy-level (specific role)

### 23.4 Diploma / Education Verification

- Required for technical/professional roles only
- Recruiter flags requirement at vacancy creation (`requires_diploma_verification` field)
- Candidate uploads during application or shortlist
- Recruiter verifies (visual review)
- Tier-1 Operator placements: optional third-party verification

### 23.5 Document Storage & Retention

- All uploaded documents stored encrypted on local disk (`storage/app/`) on shared VPS
- **Retention: 5 years** (Suriname Labour Law)
- Auto-purge with 30/14/7-day pre-purge notifications
- Active engagements: retention auto-extended
- Candidate deletion via Compliance Shield Module 7

### 23.6 Verification UI

Located in Filament 3 back-office. Per-candidate dashboard showing required documents (per vacancy + employer config), uploaded documents, verification status, waiver requests with approval state, audit history.

---

## 24. Notification Architecture

### 24.1 Unified Notification Service

Single dispatcher routes all platform notifications through channel routing layer. **No per-channel notification logic in business code.**

### 24.2 Channel Strategy (Hybrid)

| Role | Default Primary | Default Secondary |
| :---- | :---- | :---- |
| Job Seeker (Candidate) | WhatsApp | Gmail SMTP |
| HCMS Recruiter | Email + In-app | WhatsApp |
| Employer (Client Contact) | Email | In-app |
| HCMS Admin/Ops Manager | Email + In-app | WhatsApp |
| External Vendor | Email | In-app |

Users override channel preferences in profile settings. Stored in `notification_preferences`.

### 24.3 Multi-Stage Failure Escalation

**Standard notifications:**
1. Primary channel (e.g., WhatsApp)
2. On failure → Gmail SMTP fallback
3. Log all attempts in `notifications`
4. If both fail → surface to recruiter dashboard as undelivered

**Critical notifications** (offer sent · replacement guarantee breach · compliance alert):
1. Primary (WhatsApp)
2. Gmail SMTP fallback
3. **Twilio SMS** (critical-only escalation)
4. All attempts logged
5. If all three fail → escalate to Operations Manager

### 24.4 Quiet Hours (Per-User Opt-In)

- Default: quiet hours OFF
- User opt-in toggle in profile settings
- When opted in: 22:00–07:00 local time quiet window
- Non-urgent queued; urgent overrides (default: allow override)

### 24.5 Notification Categories

| Category | Example | Default Urgency |
| :---- | :---- | :---- |
| System | Password reset, MFA setup | Routine |
| Workflow | Application status, interview scheduled | Routine |
| Action Required | Document upload requested, approval needed | Important |
| Critical | Offer signed, compliance alert, security event | Critical (overrides quiet hours; uses SMS fallback) |

### 24.6 Template Management

Centralized templates with localization (English in v1; NL/FR/PT in v1.x). Managed in Filament 3 (admin role). AI-assisted personalization layer (Claude with Gemini fallback). Version-controlled with audit trail.

### 24.7 Audit & Compliance

Every notification attempt logged in `notifications` (timestamp, channel, status, retry count, consent status). Retained 5 years per §17.3. GDPR-compliant — candidates can request notification history via Compliance Shield Module 7.

---

## 25. Decision Log

### 25.1 Pre-Handoff Gap Closure Decisions (Tier 1 + Tier 2)

| # | Decision Area | Resolution |
| :---- | :---- | :---- |
| 1 | Zoho Migration — Depth | Full migration |
| 2 | Zoho Migration — Data IN | Candidate profiles + CVs · Active vacancies · Employer records |
| 3 | Zoho Migration — Data OUT | Historical placements · Email · Scorecards/notes |
| 4 | Zoho Migration — Cutover | Deferred to Phase 2 |
| 5 | Public Visitor — Browse Model | Partial (titles + summary public; details + apply behind login) |
| 6 | Public Visitor — Application Flow | Apply without registration |
| 7 | CV Optimizer — Consent Model | Implicit consent with clear notice |
| 8 | Rejection UX | Personalized Claude-drafted with role reference + alternative suggestions |
| 9 | Application Status Visibility | Milestone-only |
| 10 | Candidate Authentication | WhatsApp + Email dual identifiers |
| 11 | Identity Verification — Mode | Dual-mode (in-person + self-upload) |
| 12 | Identity Verification — Timing | At shortlist |
| 13 | Background Check Approach | HCMS-internal + Good behaviour document required |
| 14 | Good Behaviour Document Scope | All placements; waivable with Ops Head approval |
| 15 | Diploma Verification | Technical/professional roles only |
| 16 | Document Retention | 5 years (Suriname Labour Law) |
| 17 | Notification Channel Strategy | Hybrid (role defaults + user override) |
| 18 | Notification Failure Escalation | Multi-stage (WhatsApp → email → SMS for critical) |
| 19 | Notification Quiet Hours | Per-user opt-in |
| 20 | Concurrent Users Year 1 | Medium (50–200) |
| 21 | Response Time SLA | Best-effort |
| 22 | Application Volume / Month | <100/month |
| 23 | i18n Implementation | Hybrid Laravel + AI-assisted dynamic (v1 single locale) |
| 24 | Environment Topology | Standard 3-environment |
| 25 | Default Invoice Currency | Per-employer setting |
| 26 | Tax Handling (OB) | Configurable per-employer profile |
| 27 | Bulk Operations Access | Ops Manager + Admin only |
| 28 | Duplicate Detection (Auto-Merge) | Strict email + phone exact match |
| 29 | Duplicate Detection (Surface for Review) | AI embedding similarity → recruiter confirms |
| 30 | Recruiter Conflict Resolution | First-come-first-served |
| 31 | AI Agent Failure Mode | Graceful degrade (after Claude + Gemini fallback exhausted) |
| 32 | Suriname Recruitment Licensing | ✅ HCMS already holds |
| 33 | Blind Screening Mode | Per-vacancy toggle |
| 34 | Salary Visibility | Hidden from employer until shortlist |
| 35 | GDPR Subject Portal Scope | Partial self-service (access + export self-service; deletion via support ticket) |

### 25.2 Environment Alignment Decisions

| # | Decision Area | Resolution |
| :---- | :---- | :---- |
| 36 | Deployment Model | Single VPS — no Docker, no Kubernetes |
| 37 | Backend Stack | Laravel 13+ · PHP 8.3+ |
| 38 | Frontend Stack | React 18 + Vite + Inertia.js + TailwindCSS |
| 39 | Local Dev Database | SQLite |
| 40 | Production Database | PostgreSQL 16 + pgvector |
| 41 | Cache/Queue/Session Drivers | Laravel database drivers |
| 42 | Search Engine | PostgreSQL FTS + pgvector |
| 43 | Queue Monitoring | Laravel Pulse (Horizon removed) |
| 44 | File Storage | Local disk + scheduled offsite backup |
| 45 | Error Monitoring | Self-hosted Sentry |
| 46 | Web Server | Nginx |
| 47 | Process Management | systemd |
| 48 | CI/CD (Backend) | GitHub Actions |

### 25.3 Final Pre-Handoff Decisions (v1.3)

| # | Decision Area | Resolution |
| :---- | :---- | :---- |
| 49 | VPS provider | **LiquidNet US LLC** |
| 50 | VPS region | **US** |
| 51 | VPS topology | **Shared single VPS** (HUMANABLE + ATLAS + Compliance Shield · 16 GB RAM minimum) |
| 52 | Offsite backup cloud | **Google Drive** (via Google Drive API) |
| 53 | SMTP provider | **Gmail / Google Workspace** |
| 54 | SMS gateway | **Twilio** |
| 55 | Sentry deployment | **Self-hosted on shared VPS** |
| 56 | Mobile framework | **React Expo** (supersedes bare React Native plan) |
| 57 | Mobile CI/CD | **EAS Build (Expo Application Services)** — approved §29 exception |
| 58 | App store developer account | Chivaro Gajadien personal account (interim — org account transition planned by v1.1) |
| 59 | AI primary provider | Claude API |
| 60 | AI fallback provider | **Google Gemini API** (supersedes open-source LLM plan) |
| 61 | Embedding service | **Anthropic embedding service** (supersedes self-hosted plan) |
| 62 | Compliance Shield documentation | **Promoted to dedicated 3rd FO** |
| 63 | Language scope (v1) | **English only** (NL/FR/PT in v1.x; Spanish in v2) |
| 64 | Engineering Handoff Authorization | **"Ask first always"** governance |
| 65 | Subdomain naming | `humanable.hcmsnv.com` confirmed |

### 25.4 Architectural Rationale Summary

1. **Premium specialized recruitment** — not mass-throughput · low volume · governance over speed · per-employer flexibility
2. **VPS-native pragmatism** — single shared LiquidNet server · standard Laravel deployment · no Docker · no Redis · no Meilisearch
3. **Google ecosystem concentration** — Gmail SMTP · Google Drive backup · Gemini API fallback (consolidates billing + account management)
4. **Approved external services only where architecturally non-negotiable** — Claude · Gemini · WhatsApp · SMTP · Twilio · EAS Build · Sentry · Google Drive
5. **Suriname-native operational reality** — WhatsApp + Email auth · in-person verification · Verklaring van goed gedrag · 5-year retention
6. **English-only v1** — accelerates launch; multilingual returns post-launch as content load (i18n framework already built)
7. **Compliance Shield as 3rd FO** — separate microservice owned by Compliance team; strategic moat codified

---

## 26. Remaining Open Questions for Final Sign-Off

| # | Question | Recommended Default | Status |
| :---- | :---- | :---- | :---- |
| 1 | Confirm 16 GB RAM minimum LiquidNet VPS spec acceptable | Confirm | Awaiting IT |
| 2 | Confirm Google Drive Workspace plan covers backup volume | Confirm | Awaiting IT |
| 3 | Confirm Twilio account setup + Suriname SMS routing tested | Confirm | Awaiting IT |
| 4 | Confirm Chivaro Gajadien personal Apple Developer + Google Play account (interim) AND begin organizational account provisioning in parallel | Approve interim + start org account process | Awaiting CEO |
| 5 | Confirm Gemini API access (Google Cloud account setup) | Confirm | Awaiting IT |
| 6 | Confirm decision: transition mobile distribution to organizational account by v1.1 | Confirm | Awaiting CEO |
| 7 | **Issue Engineering Handoff Authorization** | **Pending explicit user confirmation per "ask first always" governance** | **PRIMARY** |

---

## 27. Implementation Note for Engineering Team

1. **Read this FO in full** plus `HCMS-FO-ComplianceShield-v1.0-2026.md` for the Compliance Shield specification HUMANABLE consumes.
2. **§29 Development Stack & Delivery Guidelines is a hard constraint** — no Docker, no Redis, no Meilisearch, no managed cloud services beyond approved exceptions.
3. **Mirror ATLAS architecture patterns** — same stack, shared infrastructure, shared Compliance Shield.
4. **Treat the five Architectural Pillars (§5) as first-class components** — not features.
5. **Compliance Shield microservice deployed in parallel** — must be operational by Week 30 (HUMANABLE Phase 9 depends on it).
6. **HCMS App Suite integration bridges (§16) are CRITICAL** — they unlock the App Suite's strategic value.
7. **Trigger phrase workflows (§7)** are architectural anchors.
8. **Data model (§19) is descriptive, not prescriptive** — refine as needed, but listed entities must exist.
9. **Phase the build per §20** — do not one-shot.
10. **Pillar A (Agentic AI) is the single biggest differentiator** — invest engineering quality here.
11. **Notification Service (§24) is foundational** — build before Phase 6 lifecycle features.
12. **Zoho Migration scripts (§22) are Phase 2 deliverables** — not Phase 14.
13. **SQLite local dev limitation:** pgvector is PostgreSQL-only. Test AI matching against staging PostgreSQL. Flag in CLAUDE.md.
14. **Claude → Gemini → graceful degrade chain is mandatory** for every AI agent. No "Claude-only" implementations.
15. **EAS Build for mobile** (v1.2 phase): not built in v1. CLAUDE.md should flag so engineering doesn't add native mobile dependencies in v1.
16. **Decision Log §25 records the WHY** — refer when implementation questions arise.
17. **When in doubt, ask the FO. When the FO doesn't answer, escalate to HCMS Operations Manager. Never assume engineering handoff authorization — confirm explicitly per Decision #64.**

---

## 28. Companion Documents

| Document | Purpose |
| :---- | :---- |
| `HCMS-FO-ATLAS-Final-v1.3-Selfcontained-2026.md` | Sister app (Pillar II) — same v1.3 baseline |
| `HCMS-FO-ComplianceShield-v1.0-2026.md` | **3rd FO — Compliance Shield microservice (consumed by HUMANABLE)** |
| `HCMS-ARCH-HCMSAppSuite-2026.md` | Cross-app architecture (to be produced) |
| `HCMS-ARCH-ComplianceShieldShared-2026.md` | Shared compliance microservice architecture (to be produced) |
| `HCMS-SPEC-HUMANABLEATLASBridge-2026.md` | HUMANABLE → ATLAS handoff (to be produced) |
| `HCMS-CLAUDECODE-HUMANABLE-BootstrapPrompt-v1.3-2026.md` | Engineering bootstrap (to be produced on request) |

---

## 29. Development Stack & Delivery Guidelines (Authoritative)

This section is the authoritative engineering constraint document for HUMANABLE.

### 29.1 Purpose

This section defines the required development stack and project rules for building HUMANABLE on HCMS's actual VPS environment. The AI coding tool (Claude Code) and engineering team must follow this stack strictly and must not introduce unsupported technologies without explicit IQT Lead + CEO approval.

### 29.2 Server & Hosting Restrictions

HCMS's VPS environment does not support Docker:
- ❌ No Docker containers · No Dockerfile · No docker-compose.yml
- ❌ Do not assume container-based deployment
- ❌ Do not use services requiring containers

The application runs directly on a **shared LiquidNet US VPS** (web server + DB + queue worker + file storage on one box). Recommended minimum: 16 GB RAM · 6 vCPU · 400 GB SSD (shared with ATLAS + Compliance Shield).

### 29.3 Required Backend Stack

| Component | Choice |
| :---- | :---- |
| Framework | **Laravel 13+** |
| Language | **PHP 8.3+** |
| Local Dev Database | **SQLite** |
| Production Database | **PostgreSQL 16 + pgvector** |
| Dependency Manager | **Composer** |
| Backend Pattern | Laravel Blade + Inertia.js |
| Admin Panel | **Filament 3** |
| Cache Driver | Laravel `database` driver |
| Queue Driver | Laravel `database` driver |
| Session Driver | Laravel `database` driver |
| Queue Monitoring | **Laravel Pulse** |

### 29.4 Required Frontend Stack

| Component | Choice |
| :---- | :---- |
| Framework | **React 18** |
| Bundler | **Vite** |
| Styling | **TailwindCSS** |
| API Client | Axios or Fetch API |
| Routing/Glue | **Inertia.js** |

(For mobile v1.2 phase: React Expo + EAS Build.)

### 29.5 Database Rules

**Use:** ✅ SQLite local · ✅ PostgreSQL 16 + pgvector production
**Don't use without approval:** ❌ MySQL · ❌ MongoDB · ❌ SQLite in production · ❌ Supabase · ❌ Firebase · ❌ Redis · ❌ External database services

All schema changes via Laravel migrations.

### 29.6 File Storage Rules

**Use:** ✅ Local disk (Laravel filesystem driver) on shared VPS · ✅ Daily scheduled offsite backup to **Google Drive**

**Don't use without approval:** ❌ AWS S3 / S3-compatible as primary storage · ❌ Direct user uploads to external cloud

### 29.7 Approved External Service Exceptions

| Service | Justification | Status |
| :---- | :---- | :---- |
| **Claude API (Anthropic)** | Core AI engine — agents, generation, vision, embeddings | ✅ APPROVED |
| **Google Gemini API** | Claude fallback in dual-provider AI strategy | ✅ APPROVED v1.3 |
| **Anthropic Embedding Service** | Semantic matching, search, duplicate detection | ✅ APPROVED v1.3 |
| **WhatsApp Business Cloud API (Meta)** | Primary communication channel | ✅ APPROVED |
| **Gmail / Google Workspace SMTP** | Universal email | ✅ APPROVED v1.3 |
| **Twilio SMS** | Critical-notification escalation only | ✅ APPROVED v1.3 |
| **Google Drive API** | Offsite backup destination | ✅ APPROVED v1.3 |
| **EAS Build (Expo Application Services)** | Mobile CI/CD for v1.2 phase | ✅ APPROVED v1.3 |
| **Self-hosted Sentry** | Error monitoring | ✅ APPROVED |
| **GitHub Actions** | CI/CD (backend) | ✅ APPROVED standard |
| **Google Calendar / Outlook OAuth** | Interview scheduling | ✅ APPROVED standard |
| **Apple Developer Program + Google Play Console** | Mobile distribution (v1.2 phase) | ✅ APPROVED standard |

**Any other external service proposed by engineering requires explicit IQT Lead + CEO approval.**

### 29.8 Deployment Requirements

```bash
1. composer install --no-dev --optimize-autoloader
2. npm install
3. npm run build
4. php artisan migrate --force
5. php artisan config:cache
6. php artisan route:cache
7. php artisan view:cache
8. php artisan queue:restart
9. systemctl reload nginx
```

The project must NOT depend on Docker · Kubernetes · managed PostgreSQL · managed Redis · serverless platforms · any orchestration unavailable on the HCMS VPS.

### 29.9 AI Development Rules for Claude Code

When using Claude Code for HUMANABLE:

- ❌ Do not use Docker · Do not introduce Redis · Do not introduce Meilisearch
- ✅ Use Laravel 13+, PHP 8.3+, SQLite local, PostgreSQL production
- ✅ Use Laravel database drivers for cache/queue/session
- ✅ Use PostgreSQL FTS + pgvector for search
- ✅ Use local disk for file storage with Google Drive backup
- ✅ For AI: Claude API primary, Gemini API fallback
- ✅ For embeddings: Anthropic embedding service (not self-hosted)
- ✅ For mobile: React Expo + EAS Build (v1.2 phase only)
- ✅ Keep code clean, documented, easy for another developer to continue
- ✅ Do not introduce external services beyond §29.7

### 29.10 Project Structure

```
app/
bootstrap/
config/
database/
public/
resources/
routes/
storage/
tests/
.env.example
composer.json
package.json
vite.config.js
CLAUDE.md
```

### 29.11 Environment File Rules

`.env.example` must include:

```
APP_NAME=HUMANABLE
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

# Local Dev (SQLite)
DB_CONNECTION=sqlite
# Production (PostgreSQL) — uncomment for staging/prod
# DB_CONNECTION=pgsql
# DB_HOST=
# DB_PORT=5432
# DB_DATABASE=
# DB_USERNAME=
# DB_PASSWORD=

# Database-driven (no Redis)
CACHE_STORE=database
QUEUE_CONNECTION=database
SESSION_DRIVER=database
BROADCAST_CONNECTION=log

# Email (Gmail SMTP)
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=HUMANABLE

# File Storage (local)
FILESYSTEM_DISK=local

# Approved External Services
ANTHROPIC_API_KEY=
ANTHROPIC_EMBEDDING_KEY=
GEMINI_API_KEY=
WHATSAPP_BUSINESS_API_TOKEN=
WHATSAPP_BUSINESS_PHONE_ID=
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_FROM=
GOOGLE_DRIVE_CLIENT_ID=
GOOGLE_DRIVE_CLIENT_SECRET=
SENTRY_LARAVEL_DSN=

# Compliance Shield (internal)
COMPLIANCE_SHIELD_URL=http://compliance-shield.internal:8003
COMPLIANCE_SHIELD_TOKEN=
```

**Never hardcode credentials.**

### 29.12 Packages & Dependencies

**Mandatory:**
- ✅ `laravel/framework: ^13.0`
- ✅ `laravel/sanctum`
- ✅ `inertiajs/inertia-laravel`
- ✅ `filament/filament: ^3.0`
- ✅ `pgvector/pgvector`
- ✅ `spatie/laravel-permission`
- ✅ `spatie/laravel-activitylog`
- ✅ `laravel/pulse`
- ✅ Claude API client (anthropic/claude-php-sdk or community equivalent)
- ✅ Gemini API client (google/generative-ai-php or community equivalent)

**Do not add:**
- ❌ Docker-related packages
- ❌ Redis-related packages
- ❌ Laravel Horizon
- ❌ Meilisearch packages
- ❌ AWS SDK (except for unavoidable approved use)
- ❌ External SaaS dependencies beyond §29.7
- ❌ Unmaintained packages

### 29.13 Final Delivery Checklist (Per Phase)

- [ ] Project runs locally on SQLite without Docker
- [ ] Project runs on staging VPS with PostgreSQL + pgvector
- [ ] Laravel migrations work in both SQLite and PostgreSQL
- [ ] `.env.example` complete and matches §29.11
- [ ] No credentials committed
- [ ] `npm run build` works
- [ ] Admin login works
- [ ] Main user flows tested
- [ ] Database seeders included where needed
- [ ] Deployment instructions documented (§29.8)
- [ ] No unnecessary AI-generated files
- [ ] No Docker artifacts
- [ ] No Redis or Meilisearch configuration
- [ ] Code committed properly to GitHub
- [ ] CLAUDE.md up-to-date

### 29.14 Required Handover Notes (Per Phase)

```
Project Name: HUMANABLE
Phase: [N]
Framework: Laravel 13+
PHP Version: 8.3+
Node Version: [Specify]
Database (Dev): SQLite
Database (Prod): PostgreSQL 16 + pgvector
Web Server: Nginx
Queue Driver: database
Cache Driver: database
Session Driver: database
Hosting: Shared LiquidNet US VPS
Admin Login: [URL + test credentials]
Main Features Built: [List]
Pending Features: [List]
Known Issues: [List]
Deployment Steps: [Reference §29.8]
External Services Used: [Confirm only from §29.7]
```

### 29.15 The Main Rule

**Claude Code may assist with development, but it must not make architectural decisions that conflict with §29 or with the broader FO. The project must be built for HCMS's actual server environment (shared LiquidNet US VPS), not for an idealized container-orchestrated environment.**

Any deviation from §29 requires explicit written approval from IQT Lead + CEO, documented in `HCMS-DECISION-DevStackException-[Topic]-2026.md`.

---

*HCMS N.V. — A K&K Heritage Group N.V. Company · Paramaribo, Suriname*
*FO v1.3 LOCKED · Self-Contained · All 65 Decisions Resolved · Engineering Handoff Pending User Confirmation*
*Authored by: Sovereign HCMS Architect (AI Head of Business Unit) · May 23, 2026*