# Job matching (option 3)

`POST /api/v1/job-matching/recommend`

## Architecture: DB → Platform → `job_catalog`

| Layer | Responsibility |
|-------|----------------|
| **Platform job DB** | Source of truth for open / available roles |
| **Platform API** | Query jobs, build `job_catalog`, call Gateway |
| **TJ AI Gateway** | Rank supplied catalog vs candidate (ResumeService); never invent jobs |

Gateway `ai_jobs` (Create Job draft/publish) is **not** the recommendation catalog.

## Why not direct Gateway DB matching?

Creates SoR coupling in the AI service and would miss Platform marketplace filters
(tenant, status, visibility). Platform already owns CRM and job listings.

## Request contract

```json
{
  "candidate_id": "cand-jane-001",
  "skills": ["Python", "FastAPI"],
  "job_catalog": [
    {
      "job_id": "job-be-001",
      "title": "Backend Engineer",
      "description": "Python APIs",
      "skills": ["Python", "SQL"],
      "location": "Remote"
    }
  ],
  "limit": 10
}
```

- `job_catalog` is **required** (min 1). Empty → HTTP `422`.
- Each item needs a Platform `job_id` (alias `id` accepted).
- Skills: `skills` and/or `required_skills` (merged).
- Candidate resume may come from text, structured JSON, or stored profile via `candidate_id`.

## Response

Ordered `recommendations` with `job_id`, `title`, `match_score`, `reasons`,
`skill_overlap`, `gaps`. `catalog_size` echoes how many Platform jobs were received.
Only `job_id`s from the request catalog are returned (no placeholders).

## Integration checklist (Platform)

1. Query open jobs for the candidate’s context (company / market / prefs).
2. Map rows → `job_catalog` (`job_id`, title, skills, optional JD fields).
3. POST `/api/v1/job-matching/recommend` with candidate + catalog.
4. Present ranked results; Gateway does not persist the catalog.
