# jeffersonislima/job-hunter architecture

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

- Interactive diagram: https://gitdiagram.com/jeffersonislima/job-hunter
- Repository: https://github.com/jeffersonislima/job-hunter

## Overview

Job Hunter automates finding, evaluating, storing, and alerting on job listings. A run prepares its context, gathers listings from web search and JobSpy sources, curates and validates them, then notifies through Telegram; SQLite tracks processed and pending jobs. Scheduling and environment-based assembly support unattended execution. The graph follows the pipeline and wiring visible in the indexed sources; external-service links are marked optional where the excerpts do not establish their runtime calls.

Main entry points: [`src/application/jobHunter.ts`](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/jobHunter.ts) (Job hunter), [`src/bootstrap/createJobHunter.ts`](https://github.com/jeffersonislima/job-hunter/blob/main/src/bootstrap/createJobHunter.ts) (Dependency assembly), [`src/application/pipeline/gatherAndCurateStep.ts`](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/gatherAndCurateStep.ts) (Gather and curate), [`src/application/pipeline/curateStep.ts`](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/curateStep.ts) (Curation service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Run orchestration"]
  node_main["Application entry<br/>[main.ts]"]
  node_bootstrap["Dependency assembly<br/>[createJobHunter.ts]"]
  node_scheduler["Hunt scheduler<br/>[huntScheduler.ts]"]
  node_hunter["Job hunter<br/>[jobHunter.ts]"]
end

subgraph group_pipeline["Hunt pipeline"]
  node_context["Pipeline context<br/>[context.ts]"]
  node_pipeline["Pipeline runner<br/>[hunterPipeline.ts]"]
  node_prepare["Prepare step<br/>[prepareStep.ts]"]
  node_gather["Gather and curate"]
  node_curate["Curation service<br/>[curateStep.ts]"]
  node_notify["Notification step<br/>[notifyStep.ts]"]
end

subgraph group_adapters["External adapters"]
  node_websearch["Web search source<br/>[webSearchSource.ts]"]
  node_jobspy["JobSpy sources<br/>[jobSpySource.ts]"]
  node_scraper["Job scraper<br/>[scraper.ts]"]
  node_validator["Listing validation<br/>[jobValidation.ts]"]
  node_evaluator["LLM curator<br/>[curator.ts]"]
  node_telegram["Telegram notifier<br/>[telegram.ts]"]
end

subgraph group_state["Domain and storage"]
  node_domain["Job and port contracts"]
  node_repository["Job repository<br/>[jobRepository.ts]"]
  node_database[("SQLite database<br/>[database.ts]")]
end

node_operator(("Operator"))
node_telegram_api["Telegram service"]
node_llm_api["LLM service"]

node_operator -->|"starts"| node_main
node_main -->|"creates hunter"| node_bootstrap
node_main -->|"starts scheduling"| node_scheduler
node_bootstrap -->|"assembles"| node_hunter
node_bootstrap -->|"creates"| node_repository
node_bootstrap -->|"creates"| node_database
node_bootstrap -->|"creates"| node_scraper
node_bootstrap -->|"creates"| node_evaluator
node_bootstrap -->|"creates"| node_telegram
node_hunter -->|"initializes"| node_context
node_hunter -->|"runs"| node_pipeline
node_hunter -->|"constructs"| node_prepare
node_hunter -->|"constructs"| node_gather
node_hunter -->|"constructs"| node_notify
node_hunter -->|"constructs"| node_websearch
node_hunter -->|"constructs"| node_jobspy
node_pipeline -->|"passes state"| node_context
node_gather -->|"searches"| node_websearch
node_gather -->|"searches"| node_jobspy
node_gather -->|"evaluates listings"| node_curate
node_websearch -->|"requests listings"| node_scraper
node_jobspy -->|"requests listings"| node_scraper
node_curate -->|"scores listings"| node_evaluator
node_curate -->|"validates listings"| node_validator
node_curate -.->|"checks and saves"| node_repository
node_notify -->|"sends alerts"| node_telegram
node_notify -->|"checks listings"| node_validator
node_telegram -.->|"sends messages"| node_telegram_api
node_evaluator -.->|"requests evaluation"| node_llm_api
node_repository -->|"reads and writes"| node_database
node_repository -->|"canonicalizes links"| node_validator
node_database -->|"canonicalizes links"| node_validator

click node_main "https://github.com/jeffersonislima/job-hunter/blob/main/src/main.ts"
click node_bootstrap "https://github.com/jeffersonislima/job-hunter/blob/main/src/bootstrap/createJobHunter.ts"
click node_scheduler "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scheduling/huntScheduler.ts"
click node_hunter "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/jobHunter.ts"
click node_context "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/context.ts"
click node_pipeline "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/hunterPipeline.ts"
click node_prepare "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/prepareStep.ts"
click node_gather "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/gatherAndCurateStep.ts"
click node_curate "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/curateStep.ts"
click node_notify "https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/notifyStep.ts"
click node_websearch "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/sources/webSearchSource.ts"
click node_jobspy "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/sources/jobSpySource.ts"
click node_scraper "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scraping/scraper.ts"
click node_validator "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scraping/jobValidation.ts"
click node_evaluator "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/llm/curator.ts"
click node_telegram "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/messaging/telegram.ts"
click node_domain "https://github.com/jeffersonislima/job-hunter/tree/main/src/domain"
click node_repository "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/persistence/jobRepository.ts"
click node_database "https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/persistence/database.ts"

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_main,node_bootstrap,node_scheduler,node_hunter toneBlue
class node_context,node_pipeline,node_prepare,node_gather,node_curate,node_notify toneAmber
class node_websearch,node_jobspy,node_scraper,node_validator,node_evaluator,node_telegram toneMint
class node_domain,node_repository,node_database toneRose
class node_operator,node_telegram_api,node_llm_api toneIndigo
```

## Components

### Run orchestration

- [Application entry](https://github.com/jeffersonislima/job-hunter/blob/main/src/main.ts): `src/main.ts`
- [Dependency assembly](https://github.com/jeffersonislima/job-hunter/blob/main/src/bootstrap/createJobHunter.ts): `src/bootstrap/createJobHunter.ts`
- [Hunt scheduler](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scheduling/huntScheduler.ts): `src/infrastructure/scheduling/huntScheduler.ts`
- [Job hunter](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/jobHunter.ts): `src/application/jobHunter.ts`

### Hunt pipeline

- [Pipeline context](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/context.ts): `src/application/pipeline/context.ts`
- [Pipeline runner](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/hunterPipeline.ts): `src/application/pipeline/hunterPipeline.ts`
- [Prepare step](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/prepareStep.ts): `src/application/pipeline/prepareStep.ts`
- [Gather and curate](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/gatherAndCurateStep.ts): `src/application/pipeline/gatherAndCurateStep.ts`
- [Curation service](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/curateStep.ts): `src/application/pipeline/curateStep.ts`
- [Notification step](https://github.com/jeffersonislima/job-hunter/blob/main/src/application/pipeline/notifyStep.ts): `src/application/pipeline/notifyStep.ts`

### External adapters

- [Web search source](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/sources/webSearchSource.ts): `src/infrastructure/sources/webSearchSource.ts`
- [JobSpy sources](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/sources/jobSpySource.ts): `src/infrastructure/sources/jobSpySource.ts`
- [Job scraper](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scraping/scraper.ts): `src/infrastructure/scraping/scraper.ts`
- [Listing validation](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/scraping/jobValidation.ts): `src/infrastructure/scraping/jobValidation.ts`
- [LLM curator](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/llm/curator.ts): `src/infrastructure/llm/curator.ts`
- [Telegram notifier](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/messaging/telegram.ts): `src/infrastructure/messaging/telegram.ts`

### Domain and storage

- [Job and port contracts](https://github.com/jeffersonislima/job-hunter/tree/main/src/domain): `src/domain`
- [Job repository](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/persistence/jobRepository.ts): `src/infrastructure/persistence/jobRepository.ts`
- [SQLite database](https://github.com/jeffersonislima/job-hunter/blob/main/src/infrastructure/persistence/database.ts): `src/infrastructure/persistence/database.ts`

### Other components

- **Operator**
- **Telegram service**
- **LLM service**

## Connections

- Operator → Application entry: starts
- Application entry → Dependency assembly: creates hunter (evidence: `src/main.ts`)
- Application entry → Hunt scheduler: starts scheduling (evidence: `src/main.ts`)
- Dependency assembly → Job hunter: assembles (evidence: `src/bootstrap/createJobHunter.ts`)
- Dependency assembly → Job repository: creates (evidence: `src/bootstrap/createJobHunter.ts`)
- Dependency assembly → SQLite database: creates (evidence: `src/bootstrap/createJobHunter.ts`)
- Dependency assembly → Job scraper: creates (evidence: `src/bootstrap/createJobHunter.ts`)
- Dependency assembly → LLM curator: creates (evidence: `src/bootstrap/createJobHunter.ts`)
- Dependency assembly → Telegram notifier: creates (evidence: `src/bootstrap/createJobHunter.ts`)
- Job hunter → Pipeline context: initializes (evidence: `src/application/jobHunter.ts`)
- Job hunter → Pipeline runner: runs (evidence: `src/application/jobHunter.ts`)
- Job hunter → Prepare step: constructs (evidence: `src/application/jobHunter.ts`)
- Job hunter → Gather and curate: constructs (evidence: `src/application/jobHunter.ts`)
- Job hunter → Notification step: constructs (evidence: `src/application/jobHunter.ts`)
- Job hunter → Web search source: constructs (evidence: `src/application/jobHunter.ts`)
- Job hunter → JobSpy sources: constructs (evidence: `src/application/jobHunter.ts`)
- Pipeline runner → Pipeline context: passes state (evidence: `src/application/pipeline/hunterPipeline.ts`)
- Gather and curate → Web search source: searches (evidence: `src/application/pipeline/gatherAndCurateStep.ts`)
- Gather and curate → JobSpy sources: searches (evidence: `src/application/pipeline/gatherAndCurateStep.ts`)
- Gather and curate → Curation service: evaluates listings (evidence: `src/application/pipeline/gatherAndCurateStep.ts`)
- Web search source → Job scraper: requests listings (evidence: `src/infrastructure/sources/webSearchSource.ts`)
- JobSpy sources → Job scraper: requests listings (evidence: `src/infrastructure/sources/jobSpySource.ts`)
- Curation service → LLM curator: scores listings (evidence: `src/application/pipeline/curateStep.ts`)
- Curation service → Listing validation: validates listings (evidence: `src/application/pipeline/curateStep.ts`)
- Curation service → Job repository: checks and saves
- Notification step → Telegram notifier: sends alerts (evidence: `src/application/pipeline/notifyStep.ts`)
- Notification step → Listing validation: checks listings (evidence: `src/application/pipeline/notifyStep.ts`)
- Telegram notifier → Telegram service: sends messages
- LLM curator → LLM service: requests evaluation
- Job repository → SQLite database: reads and writes (evidence: `src/infrastructure/persistence/jobRepository.ts`)
- Job repository → Listing validation: canonicalizes links (evidence: `src/infrastructure/persistence/jobRepository.ts`)
- SQLite database → Listing validation: canonicalizes links (evidence: `src/infrastructure/persistence/database.ts`)
