# api — Public-Facing Proxy API

Internal port 8080. The only service exposed to the internet.

## Responsibilities

- Validates reCAPTCHA on CV upload and match requests
- Proxies CV operations to `cv-matcher-api` via Refit (`ICvMatcherApi`, `IJobSearchApi`)
- Sends match result emails via SMTP (`SmtpEmailSender`)
- Includes a job search link in match emails when a `CvDocumentId` is present
- Serves the job-search-start page (`GET /api/cv-matcher/job-search/start?t=<token>`)
- Enforces rate limiting (`cvMatcher` policy: 10 req / 10 min)
- Enforces CORS (allow list from `Cors__AllowedOrigins__*` env vars)
- Caches uploaded CV PDFs locally to `FileStorage:Path` for email attachment

## Key routes

| Method | Route | Description |
|--------|-------|-------------|
| POST | `/api/cv-matcher/upload` | Upload CV PDF, forward to cv-matcher-api |
| POST | `/api/cv-matcher/match` | Match CV+job, send email with job search link |
| GET  | `/api/cv-matcher/job-search/start?t=<token>` | One-click job search start; returns plain HTML |
| GET  | `/api/health` | Health check |

## Job search link flow

1. After a successful match with an email, `CvMatcherController.MatchJob` calls `IJobSearchApi.CreateTokenAsync`
2. Builds link: `{JobSearch:BaseUrl}/api/cv-matcher/job-search/start?t={tokenId}`
3. Passes link to `SmtpEmailSender.BuildMatchEmailBody(result, jobSearchLink)`
4. When user clicks link → `GET /api/cv-matcher/job-search/start?t=` → proxies to `cv-matcher-api POST /api/cv/job-search/token/{tokenId}/start`
5. Returns styled HTML page (Started / AlreadyUsed / Expired / NotFound)

## Settings

| Section | Key env var | Notes |
|---------|-------------|-------|
| `CvMatcherApi` | `CvMatcherApi__BaseUrl`, `CvMatcherApi__InternalApiKey` | Shared by both Refit clients |
| `JobSearch` | `JobSearch__BaseUrl` | Base URL for link generation only (maps to `JobSearchLinkSettings.BaseUrl`) |
| `FileStorage` | `FileStorage__Path` | Directory for cached CV PDFs; shared volume with cv-search-job |
| `Smtp` | `Smtp__Host`, `Smtp__Username`, etc. | Used by SmtpEmailSender |
| `Captcha` | `Captcha__SecretKey` | reCAPTCHA v3 secret |

## HTML page generation

`CvMatcherController.HtmlPage(title, message)` uses `$$"""` raw string literal so CSS `{` / `}` are literal. Do not change to `$"""` — causes CS9006.