# imnazirul/job-hunter-django architecture

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

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

## Overview

JobHunter is a Django API that turns a reviewed candidate profile into personalized job-search results. The main workflow is CV upload and parsing, profile review, asynchronous searches across available boards, job normalization and deduplication, then rule-based scoring with optional LLM refinement. Users can poll search progress and browse scored jobs. The README also documents registration and authentication. The graph follows documented endpoints and the sampled task, parsing, source, and scoring relationships; some wiring is supported by the SOURCE INDEX rather than full-file inspection.

Main entry points: [`jobs/views.py`](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/views.py) (Search and jobs API), [`jobs/tasks.py`](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/tasks.py) (Search orchestration), [`profiles/tasks.py`](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/tasks.py) (CV processing), [`profiles/views.py`](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/views.py) (Profile and CV API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Accounts and profiles"]
  node_auth_api["Auth API<br/>[views.py]"]
  node_account_data[("Account data<br/>[models.py]")]
  node_profile_api["Profile and CV API<br/>[views.py]"]
  node_profile_data[("Profile and CV records<br/>[models.py]")]
  node_cv_task["CV processing<br/>[tasks.py]"]
  node_cv_extract["CV text extraction<br/>[cv_text.py]"]
  node_profile_parse["Profile parsing<br/>[parsing.py]"]
  node_skill_vocab["Skill vocabulary"]
end

subgraph group_search["Job discovery"]
  node_search_api["Search and jobs API<br/>[views.py]"]
  node_search_tasks["Search orchestration<br/>[tasks.py]"]
  node_source_registry["Source registry<br/>[registry.py]"]
  node_remotive["Remotive source<br/>[remotive.py]"]
  node_source_contract["Source contract and HTTP<br/>[base.py]"]
  node_job_normalize["Job normalization<br/>[normalize.py]"]
  node_dedup["Duplicate detection<br/>[dedup.py]"]
  node_job_data[("Search and job records<br/>[models.py]")]
end

subgraph group_ranking["Scoring and language models"]
  node_score_service["Scoring service<br/>[service.py]"]
  node_rule_score["Rule scoring<br/>[rules.py]"]
  node_llm_score["LLM re-scoring<br/>[llm_scorer.py]"]
  node_llm_client["LLM client<br/>[client.py]"]
  node_llm_coerce["LLM output coercion<br/>[coerce.py]"]
end

subgraph group_platform["Runtime and data"]
  node_celery["Celery worker<br/>[celery.py]"]
  node_file_storage[("Uploaded CV storage<br/>[storage.py]")]
end

node_candidate(("Candidate"))
node_openrouter{{"OpenRouter"}}
node_remotive_service{{"Remotive API"}}

node_candidate -->|"registers or signs in"| node_auth_api
node_auth_api -->|"uses accounts"| node_account_data
node_candidate -->|"uploads CV; reviews profile"| node_profile_api
node_profile_api -->|"reads and updates"| node_profile_data
node_profile_api -->|"queues parsing"| node_cv_task
node_cv_task -->|"updates CV and profile"| node_profile_data
node_cv_task -->|"extracts text"| node_cv_extract
node_cv_task -->|"parses extracted text"| node_profile_parse
node_profile_parse -->|"uses vocabulary"| node_skill_vocab
node_profile_parse -->|"requests structured output"| node_llm_client
node_profile_parse -->|"validates output"| node_llm_coerce
node_candidate -->|"starts search; polls results"| node_search_api
node_search_api -->|"checks candidate profile"| node_profile_data
node_search_api -->|"reads and creates search records"| node_job_data
node_search_api -->|"lists available sources"| node_source_registry
node_search_api -->|"dispatches search"| node_search_tasks
node_search_api -->|"queues asynchronous work"| node_celery
node_search_tasks -->|"updates runs and jobs"| node_job_data
node_search_tasks -->|"selects source"| node_source_registry
node_source_registry -->|"registers source"| node_remotive
node_search_tasks -->|"normalizes fetched jobs"| node_job_normalize
node_remotive -->|"uses source HTTP helpers"| node_source_contract
node_remotive -->|"fetches listings"| node_remotive_service
node_remotive -->|"normalizes source content"| node_job_normalize
node_search_tasks -->|"marks duplicates"| node_dedup
node_dedup -->|"uses normalized keys"| node_job_normalize
node_search_tasks -->|"scores completed run"| node_score_service
node_score_service -->|"loads and updates scores"| node_job_data
node_score_service -->|"scores every job"| node_rule_score
node_rule_score -->|"matches canonical skills"| node_skill_vocab
node_score_service -->|"refines shortlist"| node_llm_score
node_llm_score -->|"requests validated scores"| node_llm_client
node_llm_score -->|"coerces response fields"| node_llm_coerce
node_llm_client -->|"sends model requests"| node_openrouter
node_profile_api -.->|"stores uploaded CVs"| node_file_storage
node_cv_task -->|"runs as background task"| node_celery

click node_auth_api "https://github.com/imnazirul/job-hunter-django/blob/main/accounts/views.py"
click node_account_data "https://github.com/imnazirul/job-hunter-django/blob/main/accounts/models.py"
click node_profile_api "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/views.py"
click node_profile_data "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/models.py"
click node_cv_task "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/tasks.py"
click node_cv_extract "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/cv_text.py"
click node_profile_parse "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/parsing.py"
click node_skill_vocab "https://github.com/imnazirul/job-hunter-django/blob/main/profiles/skill_vocabulary.py"
click node_search_api "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/views.py"
click node_search_tasks "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/tasks.py"
click node_source_registry "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/registry.py"
click node_remotive "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/remotive.py"
click node_source_contract "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/base.py"
click node_job_normalize "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/normalize.py"
click node_dedup "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/dedup.py"
click node_job_data "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/models.py"
click node_score_service "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/service.py"
click node_rule_score "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/rules.py"
click node_llm_score "https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/llm_scorer.py"
click node_llm_client "https://github.com/imnazirul/job-hunter-django/blob/main/llm/client.py"
click node_llm_coerce "https://github.com/imnazirul/job-hunter-django/blob/main/llm/coerce.py"
click node_celery "https://github.com/imnazirul/job-hunter-django/blob/main/jobhunter/celery.py"
click node_file_storage "https://github.com/imnazirul/job-hunter-django/blob/main/jobhunter/storage.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_auth_api,node_account_data,node_profile_api,node_profile_data,node_cv_task,node_cv_extract,node_profile_parse,node_skill_vocab toneBlue
class node_search_api,node_search_tasks,node_source_registry,node_remotive,node_source_contract,node_job_normalize,node_dedup,node_job_data toneAmber
class node_score_service,node_rule_score,node_llm_score,node_llm_client,node_llm_coerce,node_openrouter,node_remotive_service toneMint
class node_celery,node_file_storage toneRose
class node_candidate toneIndigo
```

## Components

### Accounts and profiles

- [Auth API](https://github.com/imnazirul/job-hunter-django/blob/main/accounts/views.py): `accounts/views.py`
- [Account data](https://github.com/imnazirul/job-hunter-django/blob/main/accounts/models.py): `accounts/models.py`
- [Profile and CV API](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/views.py): `profiles/views.py`
- [Profile and CV records](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/models.py): `profiles/models.py`
- [CV processing](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/tasks.py): `profiles/tasks.py`
- [CV text extraction](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/cv_text.py): `profiles/cv_text.py`
- [Profile parsing](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/parsing.py): `profiles/parsing.py`
- [Skill vocabulary](https://github.com/imnazirul/job-hunter-django/blob/main/profiles/skill_vocabulary.py): `profiles/skill_vocabulary.py`

### Job discovery

- [Search and jobs API](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/views.py): `jobs/views.py`
- [Search orchestration](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/tasks.py): `jobs/tasks.py`
- [Source registry](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/registry.py): `jobs/sources/registry.py`
- [Remotive source](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/remotive.py): `jobs/sources/remotive.py`
- [Source contract and HTTP](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/sources/base.py): `jobs/sources/base.py`
- [Job normalization](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/normalize.py): `jobs/normalize.py`
- [Duplicate detection](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/dedup.py): `jobs/dedup.py`
- [Search and job records](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/models.py): `jobs/models.py`

### Scoring and language models

- [Scoring service](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/service.py): `jobs/scoring/service.py`
- [Rule scoring](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/rules.py): `jobs/scoring/rules.py`
- [LLM re-scoring](https://github.com/imnazirul/job-hunter-django/blob/main/jobs/scoring/llm_scorer.py): `jobs/scoring/llm_scorer.py`
- [LLM client](https://github.com/imnazirul/job-hunter-django/blob/main/llm/client.py): `llm/client.py`
- [LLM output coercion](https://github.com/imnazirul/job-hunter-django/blob/main/llm/coerce.py): `llm/coerce.py`

### Runtime and data

- [Celery worker](https://github.com/imnazirul/job-hunter-django/blob/main/jobhunter/celery.py): `jobhunter/celery.py`
- [Uploaded CV storage](https://github.com/imnazirul/job-hunter-django/blob/main/jobhunter/storage.py): `jobhunter/storage.py`

### Other components

- **Candidate**
- **OpenRouter**
- **Remotive API**

## Connections

- Candidate → Auth API: registers or signs in (evidence: `README.md`)
- Auth API → Account data: uses accounts (evidence: `accounts/views.py`)
- Candidate → Profile and CV API: uploads CV; reviews profile (evidence: `README.md`)
- Profile and CV API → Profile and CV records: reads and updates (evidence: `profiles/views.py`)
- Profile and CV API → CV processing: queues parsing (evidence: `profiles/views.py`)
- CV processing → Profile and CV records: updates CV and profile (evidence: `profiles/tasks.py`)
- CV processing → CV text extraction: extracts text (evidence: `profiles/tasks.py`)
- CV processing → Profile parsing: parses extracted text (evidence: `profiles/tasks.py`)
- Profile parsing → Skill vocabulary: uses vocabulary (evidence: `profiles/parsing.py`)
- Profile parsing → LLM client: requests structured output (evidence: `profiles/parsing.py`)
- Profile parsing → LLM output coercion: validates output (evidence: `profiles/parsing.py`)
- Candidate → Search and jobs API: starts search; polls results (evidence: `README.md`)
- Search and jobs API → Profile and CV records: checks candidate profile (evidence: `jobs/views.py`)
- Search and jobs API → Search and job records: reads and creates search records (evidence: `jobs/views.py`)
- Search and jobs API → Source registry: lists available sources (evidence: `jobs/views.py`)
- Search and jobs API → Search orchestration: dispatches search (evidence: `jobs/views.py`)
- Search and jobs API → Celery worker: queues asynchronous work (evidence: `README.md`)
- Search orchestration → Search and job records: updates runs and jobs (evidence: `jobs/tasks.py`)
- Search orchestration → Source registry: selects source (evidence: `jobs/tasks.py`)
- Source registry → Remotive source: registers source (evidence: `jobs/sources/registry.py`)
- Search orchestration → Job normalization: normalizes fetched jobs (evidence: `jobs/tasks.py`)
- Remotive source → Source contract and HTTP: uses source HTTP helpers (evidence: `jobs/sources/remotive.py`)
- Remotive source → Remotive API: fetches listings (evidence: `jobs/sources/remotive.py`)
- Remotive source → Job normalization: normalizes source content (evidence: `jobs/sources/remotive.py`)
- Search orchestration → Duplicate detection: marks duplicates (evidence: `jobs/tasks.py`)
- Duplicate detection → Job normalization: uses normalized keys (evidence: `jobs/dedup.py`)
- Search orchestration → Scoring service: scores completed run (evidence: `jobs/tasks.py`)
- Scoring service → Search and job records: loads and updates scores (evidence: `jobs/scoring/service.py`)
- Scoring service → Rule scoring: scores every job (evidence: `jobs/scoring/service.py`)
- Rule scoring → Skill vocabulary: matches canonical skills (evidence: `jobs/scoring/rules.py`)
- Scoring service → LLM re-scoring: refines shortlist (evidence: `jobs/scoring/service.py`)
- LLM re-scoring → LLM client: requests validated scores (evidence: `jobs/scoring/llm_scorer.py`)
- LLM re-scoring → LLM output coercion: coerces response fields (evidence: `jobs/scoring/llm_scorer.py`)
- LLM client → OpenRouter: sends model requests (evidence: `llm/client.py`)
- Profile and CV API → Uploaded CV storage: stores uploaded CVs (evidence: `README.md`)
- CV processing → Celery worker: runs as background task (evidence: `profiles/tasks.py`)
