# ranjithreddybandi/jobsearch architecture

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

- Interactive diagram: https://gitdiagram.com/ranjithreddybandi/jobsearch
- Repository: https://github.com/ranjithreddybandi/jobsearch

## Overview

JobSearch is a web-based job-opportunity search product backed by a Python agent pipeline. A user submits role and preference criteria in the web UI; the backend invokes the pipeline, which normalizes the query, selects sources, scrapes jobs, classifies and ranks results, summarizes them, and exports files. The UI presents results and search controls. The README is minimal, so the workflow is supported mainly by sampled source and the source index; unsampled stage ordering is shown as unverified.

Main entry points: [`JobSearch_Agent/wrappers.py`](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/wrappers.py) (Step wrappers), [`JobSearch_Agent/RoleQueryNormalizer_Agent.py`](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/RoleQueryNormalizer_Agent.py) (Query normalizer), [`JobSearch_Agent/JobSourceDiscovery_Agent.py`](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobSourceDiscovery_Agent.py) (Source discovery), [`JobSearch_Agent/JobScraper_Agent.py`](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobScraper_Agent.py) (Job scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_ui["Search UI<br/>[App.tsx]"]
  node_api["Web API<br/>[main.py]"]
end

subgraph group_pipeline["Search pipeline"]
  node_orchestrator["Step wrappers<br/>[wrappers.py]"]
  node_normalizer["Query normalizer"]
  node_discovery["Source discovery"]
  node_scraper["Job scraper"]
  node_classification["Job classification"]
  node_ranker["Relevance ranker<br/>[ranker_Agent.py]"]
  node_summarizer["Job summarizer"]
  node_exporter["Result exporter<br/>[Export_Agent.py]"]
end

subgraph group_integrations["External services"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
  node_job_sources["Job boards and APIs"]
  node_llm_providers["LLM providers"]
end

subgraph group_data["Configuration and state"]
  node_state["Pipeline state<br/>[state.py]"]
  node_config["Runtime defaults<br/>[config.py]"]
  node_source_registry["Source registry<br/>[sources.yaml]"]
end

node_user(("Job seeker"))

node_user -->|"submits search"| node_ui
node_ui -->|"starts run"| node_api
node_api -->|"invokes pipeline"| node_orchestrator
node_orchestrator -->|"calls"| node_normalizer
node_orchestrator -->|"calls"| node_discovery
node_orchestrator -->|"calls"| node_scraper
node_orchestrator -->|"calls"| node_classification
node_orchestrator -->|"calls"| node_ranker
node_orchestrator -->|"calls"| node_summarizer
node_orchestrator -->|"calls"| node_exporter
node_normalizer -.->|"requests expansion"| node_llm_client
node_summarizer -->|"requests summaries"| node_llm_client
node_llm_client -->|"sends completion"| node_llm_providers
node_discovery -.->|"loads sources"| node_source_registry
node_scraper -.->|"fetches listings"| node_job_sources
node_normalizer -.->|"reads defaults"| node_config
node_orchestrator -.->|"maps state"| node_state
node_orchestrator -.->|"returns results"| node_ui
node_normalizer -.->|"prepares search"| node_discovery
node_discovery -.->|"selects sources"| node_scraper
node_scraper -.->|"provides jobs"| node_classification
node_classification -.->|"provides classified jobs"| node_ranker
node_ranker -.->|"provides ranked jobs"| node_summarizer
node_summarizer -.->|"provides summaries"| node_exporter

click node_ui "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Web/frontend/src/App.tsx"
click node_api "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Web/backend/main.py"
click node_orchestrator "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/wrappers.py"
click node_normalizer "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/RoleQueryNormalizer_Agent.py"
click node_discovery "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobSourceDiscovery_Agent.py"
click node_scraper "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobScraper_Agent.py"
click node_classification "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobClassification_Agent.py"
click node_ranker "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/ranker_Agent.py"
click node_summarizer "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/summarizer_Agent.py"
click node_exporter "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/Export_Agent.py"
click node_state "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/state.py"
click node_config "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/config.py"
click node_source_registry "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/data/sources.yaml"
click node_llm_client "https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/llm_client.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_ui,node_api toneBlue
class node_orchestrator,node_normalizer,node_discovery,node_scraper,node_classification,node_ranker,node_summarizer,node_exporter toneAmber
class node_llm_client,node_job_sources,node_llm_providers toneMint
class node_state,node_config,node_source_registry toneRose
class node_user toneIndigo
```

## Components

### Web application

- [Search UI](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Web/frontend/src/App.tsx): `JobSearch_Web/frontend/src/App.tsx`
- [Web API](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Web/backend/main.py): `JobSearch_Web/backend/main.py`

### Search pipeline

- [Step wrappers](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/wrappers.py): `JobSearch_Agent/wrappers.py`
- [Query normalizer](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/RoleQueryNormalizer_Agent.py): `JobSearch_Agent/RoleQueryNormalizer_Agent.py`
- [Source discovery](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobSourceDiscovery_Agent.py): `JobSearch_Agent/JobSourceDiscovery_Agent.py`
- [Job scraper](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobScraper_Agent.py): `JobSearch_Agent/JobScraper_Agent.py`
- [Job classification](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/JobClassification_Agent.py): `JobSearch_Agent/JobClassification_Agent.py`
- [Relevance ranker](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/ranker_Agent.py): `JobSearch_Agent/ranker_Agent.py`
- [Job summarizer](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/summarizer_Agent.py): `JobSearch_Agent/summarizer_Agent.py`
- [Result exporter](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/Export_Agent.py): `JobSearch_Agent/Export_Agent.py`

### External services

- [LLM client](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/llm_client.py): `JobSearch_Agent/llm_client.py`
- **Job boards and APIs**
- **LLM providers**

### Configuration and state

- [Pipeline state](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/state.py): `JobSearch_Agent/state.py`
- [Runtime defaults](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/config.py): `JobSearch_Agent/config.py`
- [Source registry](https://github.com/ranjithreddybandi/jobsearch/blob/main/JobSearch_Agent/data/sources.yaml): `JobSearch_Agent/data/sources.yaml`

### Other components

- **Job seeker**

## Connections

- Job seeker → Search UI: submits search (evidence: `JobSearch_Web/frontend/src/App.tsx`)
- Search UI → Web API: starts run (evidence: `JobSearch_Web/frontend/src/App.tsx`)
- Web API → Step wrappers: invokes pipeline (evidence: `JobSearch_Web/backend/main.py`)
- Step wrappers → Query normalizer: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Source discovery: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Job scraper: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Job classification: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Relevance ranker: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Job summarizer: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Step wrappers → Result exporter: calls (evidence: `JobSearch_Agent/wrappers.py`)
- Query normalizer → LLM client: requests expansion (evidence: `JobSearch_Agent/RoleQueryNormalizer_Agent.py`)
- Job summarizer → LLM client: requests summaries (evidence: `JobSearch_Agent/summarizer_Agent.py`)
- LLM client → LLM providers: sends completion (evidence: `JobSearch_Agent/llm_client.py`)
- Source discovery → Source registry: loads sources
- Job scraper → Job boards and APIs: fetches listings
- Query normalizer → Runtime defaults: reads defaults
- Step wrappers → Pipeline state: maps state
- Step wrappers → Search UI: returns results
- Query normalizer → Source discovery: prepares search
- Source discovery → Job scraper: selects sources (evidence: `JobSearch_Agent/JobScraper_Agent.py`)
- Job scraper → Job classification: provides jobs
- Job classification → Relevance ranker: provides classified jobs
- Relevance ranker → Job summarizer: provides ranked jobs
- Job summarizer → Result exporter: provides summaries