# luxinyue0910/job-search-agent architecture

> Architecture diagram of the GitHub repository luxinyue0910/job-search-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luxinyue0910/job-search-agent
- Repository: https://github.com/luxinyue0910/job-search-agent

## Overview

Job Search Agent is a local, human-in-the-loop assistant that discovers jobs, evaluates fit, prepares tailored application materials, and fills supported ATS forms without submitting them. The primary workflow runs through the CLI: configured sources feed discovery and filtering, results are scored and tracked, then selected applications proceed to material preparation and browser-assisted review. The README also documents multi-track search, local-company coverage, and source-health reporting. Several subsystems are described in the README but their implementation was not sampled; their links reflect documented behavior, not inspected call sites.

Main entry points: [`job-search/scripts/job_search.py`](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py) (Search CLI), [`job-search/agents/discovery_agent.py`](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/discovery_agent.py) (Daily discovery agent), [`job-search/scripts`](https://github.com/luxinyue0910/job-search-agent/tree/master/job-search/scripts) (Source adapters), [`job-search/scripts/fill_form.js`](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/fill_form.js) (ATS form filler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Job Discovery"]
  node_cli["Search CLI<br/>[job_search.py]"]
  node_source_config["Source registry"]
  node_watchlist["Company coverage"]
  node_discovery_adapters["Source adapters"]
  node_aggregator["Aggregator lead collector"]
end

subgraph group_evaluation["Evaluation And Tracking"]
  node_freshness_filter["Freshness and role filters<br/>[job_search.py]"]
  node_track_routing["Track routing<br/>[job_search.py]"]
  node_fit_scoring["Fit and ATS scoring<br/>[job_search.py]"]
  node_fit_review["Fit review rules"]
  node_tracker[("Application tracker<br/>[job_search.py]")]
  node_seen_store[("Seen-job history<br/>[job_search.py]")]
end

subgraph group_application["Application Preparation"]
  node_materials["Material preparation<br/>[job_search.py]"]
  node_templates["Application templates"]
  node_application_qa["Material QA review"]
  node_form_filler["ATS form filler<br/>[fill_form.js]"]
end

subgraph group_agent["Agent Support"]
  node_runner["Agent workflow runner<br/>[runner.py]"]
  node_discovery_agent["Daily discovery agent<br/>[discovery_agent.py]"]
  node_tools["CLI tool wrapper<br/>[tools.py]"]
  node_source_health[("Source health records<br/>[tools.py]")]
  node_run_trace["Auditable run artifacts<br/>[trace.py]"]
end

node_applicant(("Human applicant"))
node_private_data[("Private candidate data")]
node_career_sources[("Career sites and ATS APIs")]
node_browser_review(("Manual browser review"))

node_applicant -->|"starts search"| node_cli
node_private_data -->|"provides configuration"| node_cli
node_cli -->|"reads sources"| node_source_config
node_cli -->|"reads coverage"| node_watchlist
node_cli -->|"dispatches discovery"| node_discovery_adapters
node_discovery_adapters -->|"fetches listings"| node_career_sources
node_career_sources -->|"returns postings"| node_discovery_adapters
node_discovery_adapters -->|"returns jobs"| node_freshness_filter
node_aggregator -.->|"searches leads"| node_career_sources
node_cli -->|"filters postings"| node_freshness_filter
node_freshness_filter -->|"checks duplicates"| node_seen_store
node_freshness_filter -->|"routes candidates"| node_track_routing
node_track_routing -->|"selects track"| node_fit_scoring
node_fit_scoring -->|"records scores"| node_tracker
node_fit_review -.->|"reviews fit"| node_fit_scoring
node_cli -->|"updates applications"| node_tracker
node_cli -->|"records seen jobs"| node_seen_store
node_applicant -->|"requests preparation"| node_cli
node_cli -->|"prepares application"| node_materials
node_private_data -->|"provides profile"| node_materials
node_templates -->|"guides drafting"| node_materials
node_materials -->|"saves material paths"| node_tracker
node_materials -.->|"submits drafts"| node_application_qa
node_tracker -->|"provides application"| node_form_filler
node_private_data -->|"provides profile and files"| node_form_filler
node_form_filler -->|"fills for review"| node_browser_review
node_browser_review -->|"awaits decision"| node_applicant
node_applicant -->|"starts daily run"| node_runner
node_runner -->|"dispatches run"| node_discovery_agent
node_discovery_agent -->|"requests discovery"| node_tools
node_tools -->|"invokes command"| node_cli
node_discovery_agent -->|"updates health"| node_source_health
node_discovery_agent -->|"records run"| node_run_trace

click node_cli "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_source_config "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/examples/sources.example.json"
click node_watchlist "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/examples/company_watchlist.example.json"
click node_discovery_adapters "https://github.com/luxinyue0910/job-search-agent/tree/master/job-search/scripts"
click node_aggregator "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/collect_aggregator_leads.js"
click node_freshness_filter "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_track_routing "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_fit_scoring "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_fit_review "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/fit_review_agent.py"
click node_tracker "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_seen_store "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_materials "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py"
click node_templates "https://github.com/luxinyue0910/job-search-agent/tree/master/job-search/templates"
click node_application_qa "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/application_qa_agent.py"
click node_form_filler "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/fill_form.js"
click node_runner "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/runner.py"
click node_discovery_agent "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/discovery_agent.py"
click node_tools "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/tools.py"
click node_source_health "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/tools.py"
click node_run_trace "https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/trace.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_source_config,node_watchlist,node_discovery_adapters,node_aggregator,node_browser_review toneBlue
class node_freshness_filter,node_track_routing,node_fit_scoring,node_fit_review,node_tracker,node_seen_store,node_private_data,node_career_sources toneAmber
class node_materials,node_templates,node_application_qa,node_form_filler toneMint
class node_runner,node_discovery_agent,node_tools,node_source_health,node_run_trace toneRose
class node_applicant toneIndigo
```

## Components

### Job Discovery

- [Search CLI](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Source registry](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/examples/sources.example.json): `job-search/examples/sources.example.json`
- [Company coverage](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/examples/company_watchlist.example.json): `job-search/examples/company_watchlist.example.json`
- [Source adapters](https://github.com/luxinyue0910/job-search-agent/tree/master/job-search/scripts): `job-search/scripts`
- [Aggregator lead collector](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/collect_aggregator_leads.js): `job-search/scripts/collect_aggregator_leads.js`

### Evaluation And Tracking

- [Freshness and role filters](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Track routing](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Fit and ATS scoring](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Fit review rules](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/fit_review_agent.py): `job-search/agents/fit_review_agent.py`
- [Application tracker](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Seen-job history](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`

### Application Preparation

- [Material preparation](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/job_search.py): `job-search/scripts/job_search.py`
- [Application templates](https://github.com/luxinyue0910/job-search-agent/tree/master/job-search/templates): `job-search/templates`
- [Material QA review](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/application_qa_agent.py): `job-search/agents/application_qa_agent.py`
- [ATS form filler](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/scripts/fill_form.js): `job-search/scripts/fill_form.js`

### Agent Support

- [Agent workflow runner](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/runner.py): `job-search/agents/runner.py`
- [Daily discovery agent](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/discovery_agent.py): `job-search/agents/discovery_agent.py`
- [CLI tool wrapper](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/tools.py): `job-search/agents/tools.py`
- [Source health records](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/tools.py): `job-search/agents/tools.py`
- [Auditable run artifacts](https://github.com/luxinyue0910/job-search-agent/blob/master/job-search/agents/trace.py): `job-search/agents/trace.py`

### Other components

- **Human applicant**
- **Private candidate data**
- **Career sites and ATS APIs**
- **Manual browser review**

## Connections

- Human applicant → Search CLI: starts search
- Private candidate data → Search CLI: provides configuration
- Search CLI → Source registry: reads sources
- Search CLI → Company coverage: reads coverage
- Search CLI → Source adapters: dispatches discovery
- Source adapters → Career sites and ATS APIs: fetches listings
- Career sites and ATS APIs → Source adapters: returns postings
- Source adapters → Freshness and role filters: returns jobs
- Aggregator lead collector → Career sites and ATS APIs: searches leads
- Search CLI → Freshness and role filters: filters postings
- Freshness and role filters → Seen-job history: checks duplicates
- Freshness and role filters → Track routing: routes candidates
- Track routing → Fit and ATS scoring: selects track
- Fit and ATS scoring → Application tracker: records scores
- Fit review rules → Fit and ATS scoring: reviews fit
- Search CLI → Application tracker: updates applications
- Search CLI → Seen-job history: records seen jobs
- Human applicant → Search CLI: requests preparation
- Search CLI → Material preparation: prepares application
- Private candidate data → Material preparation: provides profile
- Application templates → Material preparation: guides drafting
- Material preparation → Application tracker: saves material paths
- Material preparation → Material QA review: submits drafts
- Application tracker → ATS form filler: provides application
- Private candidate data → ATS form filler: provides profile and files
- ATS form filler → Manual browser review: fills for review
- Manual browser review → Human applicant: awaits decision
- Human applicant → Agent workflow runner: starts daily run
- Agent workflow runner → Daily discovery agent: dispatches run
- Daily discovery agent → CLI tool wrapper: requests discovery
- CLI tool wrapper → Search CLI: invokes command
- Daily discovery agent → Source health records: updates health
- Daily discovery agent → Auditable run artifacts: records run