# hunainadhi/jobhunter architecture

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

- Interactive diagram: https://gitdiagram.com/hunainadhi/jobhunter
- Repository: https://github.com/hunainadhi/jobhunter
- Video tour (about a minute): https://gitdiagram.com/hunainadhi/jobhunter/video

## Overview

JobHunter discovers and ingests job postings, filters them for Canadian locations, scores eligible jobs with an LLM, then serves searchable listings and scored matches. A separate dashboard supports company blacklisting, pipeline health, and application-policy decisions recorded in an application ledger. The graph preserves the documented discovery, enrichment, cleanup, and self-chaining capabilities; sampled source confirms selected internal calls, while other runtime links rely on README documentation.

Main entry points: [`lambdas/ingestion/handler.py`](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/handler.py) (ATS ingestion workers), [`lambdas/scoring/handler.py`](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/scoring/handler.py) (AI job scoring), [`app/lib/actions.ts`](https://github.com/hunainadhi/jobhunter/blob/master/app/lib/actions.ts) (Dashboard actions), [`board/app/jobs/page.tsx`](https://github.com/hunainadhi/jobhunter/blob/master/board/app/jobs/page.tsx) (Job board pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Company discovery"]
  node_discovery_lambda["Company discovery<br/>[handler.py]"]
end

subgraph group_pipeline["Ingestion and scoring"]
  node_orchestrator["Ingestion orchestrator<br/>[orchestrator.py]"]
  node_ingestion["ATS ingestion workers<br/>[handler.py]"]
  node_location_resolution["Canadian location resolution"]
  node_location_filter["Location filtering<br/>[location_filter.py]"]
  node_scoring["AI job scoring<br/>[handler.py]"]
end

subgraph group_data["Shared data"]
  node_supabase[("Supabase database")]
  node_cleanup["Expired-job cleanup"]
end

subgraph group_board["Public job board"]
  node_board_filters["Search filters<br/>[search-filters.tsx]"]
  node_location_combo["Location suggestions"]
  node_board_queries["Job search queries<br/>[queries.ts]"]
  node_board_pages["Job board pages<br/>[page.tsx]"]
  node_board_table["Job results table"]
end

subgraph group_dashboard["Candidate dashboard"]
  node_dashboard_home["Scored jobs dashboard<br/>[page.tsx]"]
  node_job_table["Scored jobs table<br/>[job-table.tsx]"]
  node_health["Pipeline health<br/>[health-banner.tsx]"]
  node_blacklist["Company blacklist<br/>[page.tsx]"]
  node_actions["Dashboard actions<br/>[actions.ts]"]
  node_application_policy["Application policy"]
  node_applications["Application ledger views<br/>[page.tsx]"]
  node_stats["Pipeline statistics<br/>[page.tsx]"]
end

node_eventbridge(("Scheduled trigger"))
node_commoncrawl["Common Crawl"]
node_openrouter["OpenRouter"]

node_eventbridge -->|"triggers"| node_orchestrator
node_commoncrawl -->|"company discovery"| node_discovery_lambda
node_orchestrator -->|"launches workers"| node_ingestion
node_ingestion -->|"resolves locations"| node_location_resolution
node_ingestion -->|"filters locations"| node_location_filter
node_ingestion -->|"upserts jobs"| node_supabase
node_scoring -->|"claims and saves scores"| node_supabase
node_scoring -->|"requests scores"| node_openrouter
node_scoring -->|"self-chains"| node_scoring
node_cleanup -->|"purges expired data"| node_supabase
node_board_filters -->|"renders"| node_location_combo
node_board_pages -->|"loads listings"| node_board_queries
node_board_queries -->|"searches jobs"| node_supabase
node_board_pages -.->|"displays results"| node_board_table
node_dashboard_home -->|"queries matches"| node_supabase
node_dashboard_home -->|"renders jobs"| node_job_table
node_health -->|"shows scrape health"| node_supabase
node_blacklist -.->|"manages companies"| node_actions
node_actions -->|"evaluates applications"| node_application_policy
node_actions -->|"writes ledger and events"| node_supabase
node_applications -.->|"reads ledger"| node_supabase
node_stats -.->|"queries pipeline stats"| node_supabase

click node_discovery_lambda "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/discovery/handler.py"
click node_orchestrator "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/orchestrator.py"
click node_ingestion "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/handler.py"
click node_location_resolution "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/location_resolver.py"
click node_location_filter "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/location_filter.py"
click node_scoring "https://github.com/hunainadhi/jobhunter/blob/master/lambdas/scoring/handler.py"
click node_board_filters "https://github.com/hunainadhi/jobhunter/blob/master/board/components/search-filters.tsx"
click node_location_combo "https://github.com/hunainadhi/jobhunter/blob/master/board/components/location-combobox.tsx"
click node_board_queries "https://github.com/hunainadhi/jobhunter/blob/master/board/lib/queries.ts"
click node_board_pages "https://github.com/hunainadhi/jobhunter/blob/master/board/app/jobs/page.tsx"
click node_board_table "https://github.com/hunainadhi/jobhunter/blob/master/board/components/job-board-table.tsx"
click node_dashboard_home "https://github.com/hunainadhi/jobhunter/blob/master/app/app/page.tsx"
click node_job_table "https://github.com/hunainadhi/jobhunter/blob/master/app/components/job-table.tsx"
click node_health "https://github.com/hunainadhi/jobhunter/blob/master/app/components/health-banner.tsx"
click node_blacklist "https://github.com/hunainadhi/jobhunter/blob/master/app/app/blacklist/page.tsx"
click node_actions "https://github.com/hunainadhi/jobhunter/blob/master/app/lib/actions.ts"
click node_application_policy "https://github.com/hunainadhi/jobhunter/blob/master/app/lib/application-policy.mjs"
click node_applications "https://github.com/hunainadhi/jobhunter/blob/master/app/app/applications/page.tsx"
click node_stats "https://github.com/hunainadhi/jobhunter/blob/master/app/app/stats/page.tsx"

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_discovery_lambda toneBlue
class node_orchestrator,node_ingestion,node_location_resolution,node_location_filter,node_scoring toneAmber
class node_supabase,node_cleanup,node_openrouter toneMint
class node_board_filters,node_location_combo,node_board_queries,node_board_pages,node_board_table toneRose
class node_dashboard_home,node_job_table,node_health,node_blacklist,node_actions,node_application_policy,node_applications,node_stats,node_eventbridge,node_commoncrawl toneIndigo
```

## Components

### Company discovery

- [Company discovery](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/discovery/handler.py): `lambdas/discovery/handler.py`

### Ingestion and scoring

- [Ingestion orchestrator](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/orchestrator.py): `lambdas/ingestion/orchestrator.py`
- [ATS ingestion workers](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/handler.py): `lambdas/ingestion/handler.py`
- [Canadian location resolution](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/location_resolver.py): `lambdas/ingestion/location_resolver.py`
- [Location filtering](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/ingestion/location_filter.py): `lambdas/ingestion/location_filter.py`
- [AI job scoring](https://github.com/hunainadhi/jobhunter/blob/master/lambdas/scoring/handler.py): `lambdas/scoring/handler.py`

### Shared data

- **Supabase database**
- **Expired-job cleanup**

### Public job board

- [Search filters](https://github.com/hunainadhi/jobhunter/blob/master/board/components/search-filters.tsx): `board/components/search-filters.tsx`
- [Location suggestions](https://github.com/hunainadhi/jobhunter/blob/master/board/components/location-combobox.tsx): `board/components/location-combobox.tsx`
- [Job search queries](https://github.com/hunainadhi/jobhunter/blob/master/board/lib/queries.ts): `board/lib/queries.ts`
- [Job board pages](https://github.com/hunainadhi/jobhunter/blob/master/board/app/jobs/page.tsx): `board/app/jobs/page.tsx`
- [Job results table](https://github.com/hunainadhi/jobhunter/blob/master/board/components/job-board-table.tsx): `board/components/job-board-table.tsx`

### Candidate dashboard

- [Scored jobs dashboard](https://github.com/hunainadhi/jobhunter/blob/master/app/app/page.tsx): `app/app/page.tsx`
- [Scored jobs table](https://github.com/hunainadhi/jobhunter/blob/master/app/components/job-table.tsx): `app/components/job-table.tsx`
- [Pipeline health](https://github.com/hunainadhi/jobhunter/blob/master/app/components/health-banner.tsx): `app/components/health-banner.tsx`
- [Company blacklist](https://github.com/hunainadhi/jobhunter/blob/master/app/app/blacklist/page.tsx): `app/app/blacklist/page.tsx`
- [Dashboard actions](https://github.com/hunainadhi/jobhunter/blob/master/app/lib/actions.ts): `app/lib/actions.ts`
- [Application policy](https://github.com/hunainadhi/jobhunter/blob/master/app/lib/application-policy.mjs): `app/lib/application-policy.mjs`
- [Application ledger views](https://github.com/hunainadhi/jobhunter/blob/master/app/app/applications/page.tsx): `app/app/applications/page.tsx`
- [Pipeline statistics](https://github.com/hunainadhi/jobhunter/blob/master/app/app/stats/page.tsx): `app/app/stats/page.tsx`

### Other components

- **Scheduled trigger**
- **Common Crawl**
- **OpenRouter**

## Connections

- Scheduled trigger → Ingestion orchestrator: triggers
- Common Crawl → Company discovery: company discovery
- Ingestion orchestrator → ATS ingestion workers: launches workers
- ATS ingestion workers → Canadian location resolution: resolves locations (evidence: `lambdas/ingestion/handler.py`)
- ATS ingestion workers → Location filtering: filters locations
- ATS ingestion workers → Supabase database: upserts jobs
- AI job scoring → Supabase database: claims and saves scores
- AI job scoring → OpenRouter: requests scores
- AI job scoring → AI job scoring: self-chains (evidence: `lambdas/scoring/handler.py`)
- Expired-job cleanup → Supabase database: purges expired data
- Search filters → Location suggestions: renders (evidence: `board/components/search-filters.tsx`)
- Job board pages → Job search queries: loads listings
- Job search queries → Supabase database: searches jobs (evidence: `board/lib/queries.ts`)
- Job board pages → Job results table: displays results
- Scored jobs dashboard → Supabase database: queries matches
- Scored jobs dashboard → Scored jobs table: renders jobs (evidence: `app/components/job-table.tsx`)
- Pipeline health → Supabase database: shows scrape health
- Company blacklist → Dashboard actions: manages companies
- Dashboard actions → Application policy: evaluates applications (evidence: `app/lib/actions.ts`)
- Dashboard actions → Supabase database: writes ledger and events (evidence: `app/lib/actions.ts`)
- Application ledger views → Supabase database: reads ledger
- Pipeline statistics → Supabase database: queries pipeline stats
