# Architecture Notes

AI Job Radar is described as a local-first workflow with public-safe demo fixtures. The architecture can be implemented with scripts, notebook-style analysis, a CLI, or a lightweight web UI.

## Core Modules

| Module | Responsibility | Public Demo Artifact |
| --- | --- | --- |
| Source intake | Accept manual alert text or public source records | `demo-job-alert.txt` |
| Source health | Classify availability, blockers, and manual imports | `source_health` field |
| Job card normalizer | Convert raw signals into structured `job_card` objects | `job-cards.sample.json` |
| Relevance scorer | Score AI PM / AI design / workflow PM fit | `role_relevance_score` |
| Location scorer | Score remote, Shanghai, APAC, hybrid, and onsite fit | `location_fit_score` |
| Gap extractor | Identify portfolio proof and capability gaps | `capability_gaps` |
| Report builder | Produce shortlist, blockers, and manual next actions | `match-report.sample.md` |
| Eval checker | Review role, location, blocker, and human-gate quality | `eval-report.sample.md` |

## Source Health States

```text
public_source
manual_import
login_required
http_451_blocked
rate_limited
unavailable
unknown
```

These states protect interpretation. `login_required` and `http_451_blocked` are source-health outcomes, not evidence that there are no relevant jobs.

## Human Review Gate

All external actions must stay manual:

- applying to a job
- sending a message
- following a person or company
- editing a public profile
- uploading a resume
- storing account-specific data

The workflow can prepare a checklist or draft reasoning, but the human decides whether to act.

## Suggested Future Implementation

```text
src/
  intake/
  source_health/
  normalization/
  scoring/
  reporting/
  eval/
examples/
  demo-job-alert.txt
  job-cards.sample.json
docs/
  case-study.md
  demo-runbook.md
  security-and-privacy.md
```

## Public-Safe Deployment Options

- Documentation-only portfolio repository
- Static GitHub Pages case study
- CLI demo with synthetic fixtures
- Local web demo that loads only sample data

Avoid public deployment modes that require account login, private browser profiles, or real application data.