# vnk8071/goodjobs architecture

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

- Interactive diagram: https://gitdiagram.com/vnk8071/goodjobs
- Repository: https://github.com/vnk8071/goodjobs

## Overview

Good Jobs aggregates job-board listings into a searchable feed: a user submits a keyword or CV and location, the backend normalizes intent and location, checks cache, then streams cached or freshly scraped results to the browser. Scrape work is concurrency-limited; vector search supplements cache misses, and background warmup maintains cached searches. The product also includes chat, submissions, and a separate worker-based jobs-news experience. Some backend route bodies and worker routing details were not excerpted, so uncertain internal links are omitted.

Main entry points: [`backend/main.py`](https://github.com/vnk8071/goodjobs/blob/main/backend/main.py) (Search API), [`backend/src/cache.py`](https://github.com/vnk8071/goodjobs/blob/main/backend/src/cache.py) (Redis job cache), [`backend/src/warmup.py`](https://github.com/vnk8071/goodjobs/blob/main/backend/src/warmup.py) (Cache warmup), [`backend/src/chat.py`](https://github.com/vnk8071/goodjobs/blob/main/backend/src/chat.py) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Search experience"]
  node_browser["Search UI<br/>[main.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_chat_ui["Chat UI<br/>[chat.ts]"]
end

subgraph group_search["Search backend"]
  node_search_orchestrator["Search API<br/>[main.py]"]
  node_intent["Intent and city<br/>[intent.py]"]
  node_matching["Job matching<br/>[matching.py]"]
  node_scrape_dispatch["Scraper dispatch<br/>[__init__.py]"]
  node_site_scrapers["Job-board scrapers"]
  node_concurrency["Scrape queue<br/>[concurrency.py]"]
  node_chat_service["Chat service<br/>[chat.py]"]
end

subgraph group_data["Cache and enrichment"]
  node_cache[("Redis job cache<br/>[cache.py]")]
  node_vector_search["Vector search<br/>[vector.py]"]
  node_warmup["Cache warmup<br/>[warmup.py]"]
  node_summaries["Job summaries"]
  node_submissions["Job submissions<br/>[submissions.py]"]
end

subgraph group_news["Jobs news"]
  node_news_worker["News worker<br/>[index.js]"]
  node_news_pipeline["News generation<br/>[generate.js]"]
  node_news_sources["News sources<br/>[sources.js]"]
  node_news_render["News rendering<br/>[render.js]"]
end

subgraph group_integrations["External integrations"]
  node_mcp_tools["MCP tools<br/>[goodjobs_mcp.py]"]
  node_redis[("Redis")]
  node_board_sites["Job boards"]
  node_cloudflare_ai["Cloudflare AI"]
  node_news_inputs["News inputs"]
end

node_jobseeker(("Job seeker"))

node_jobseeker -->|"searches"| node_browser
node_browser -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_search_orchestrator
node_browser -->|"opens chat"| node_chat_ui
node_api_client -->|"streams results"| node_search_orchestrator
node_search_orchestrator -->|"classifies input"| node_intent
node_search_orchestrator -->|"checks cache"| node_cache
node_search_orchestrator -->|"supplements results"| node_vector_search
node_search_orchestrator -->|"queues scrapes"| node_concurrency
node_search_orchestrator -->|"dispatches scrapers"| node_scrape_dispatch
node_scrape_dispatch -->|"selects boards"| node_site_scrapers
node_site_scrapers -->|"scrapes listings"| node_board_sites
node_search_orchestrator -->|"matches jobs"| node_matching
node_search_orchestrator -->|"stores results"| node_cache
node_cache -->|"reads and writes"| node_redis
node_vector_search -.->|"uses cached jobs"| node_redis
node_warmup -->|"refreshes cache"| node_cache
node_warmup -->|"runs scrapers"| node_scrape_dispatch
node_warmup -->|"shares queue"| node_concurrency
node_warmup -->|"schedules summaries"| node_summaries
node_submissions -->|"reads cache"| node_cache
node_chat_service -->|"uses intent"| node_intent
node_chat_service -->|"searches cached jobs"| node_cache
node_chat_service -->|"uses semantic search"| node_vector_search
node_intent -->|"classifies with"| node_cloudflare_ai
node_news_worker -->|"routes news work"| node_news_pipeline
node_news_pipeline -->|"collects sources"| node_news_sources
node_news_worker -.->|"renders pages"| node_news_render
node_news_sources -.->|"fetches content"| node_news_inputs
node_jobseeker -.->|"uses MCP client"| node_mcp_tools
node_mcp_tools -.->|"exposes search tools"| node_search_orchestrator

click node_browser "https://github.com/vnk8071/goodjobs/blob/main/frontend/src/main.ts"
click node_api_client "https://github.com/vnk8071/goodjobs/blob/main/frontend/src/api.ts"
click node_chat_ui "https://github.com/vnk8071/goodjobs/blob/main/frontend/src/chat.ts"
click node_search_orchestrator "https://github.com/vnk8071/goodjobs/blob/main/backend/main.py"
click node_intent "https://github.com/vnk8071/goodjobs/blob/main/backend/src/intent.py"
click node_matching "https://github.com/vnk8071/goodjobs/blob/main/backend/src/matching.py"
click node_scrape_dispatch "https://github.com/vnk8071/goodjobs/blob/main/backend/src/scrapers/__init__.py"
click node_site_scrapers "https://github.com/vnk8071/goodjobs/tree/main/backend/src/scrapers"
click node_concurrency "https://github.com/vnk8071/goodjobs/blob/main/backend/src/concurrency.py"
click node_cache "https://github.com/vnk8071/goodjobs/blob/main/backend/src/cache.py"
click node_vector_search "https://github.com/vnk8071/goodjobs/blob/main/backend/src/vector.py"
click node_warmup "https://github.com/vnk8071/goodjobs/blob/main/backend/src/warmup.py"
click node_summaries "https://github.com/vnk8071/goodjobs/blob/main/backend/src/background_summarizer.py"
click node_submissions "https://github.com/vnk8071/goodjobs/blob/main/backend/src/submissions.py"
click node_chat_service "https://github.com/vnk8071/goodjobs/blob/main/backend/src/chat.py"
click node_news_worker "https://github.com/vnk8071/goodjobs/blob/main/worker/src/index.js"
click node_news_pipeline "https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/generate.js"
click node_news_sources "https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/sources.js"
click node_news_render "https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/render.js"
click node_mcp_tools "https://github.com/vnk8071/goodjobs/blob/main/mcp/goodjobs_mcp.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_browser,node_api_client,node_chat_ui toneBlue
class node_search_orchestrator,node_intent,node_matching,node_scrape_dispatch,node_site_scrapers,node_concurrency,node_chat_service toneAmber
class node_cache,node_vector_search,node_warmup,node_summaries,node_submissions toneMint
class node_news_worker,node_news_pipeline,node_news_sources,node_news_render toneRose
class node_mcp_tools,node_redis,node_board_sites,node_cloudflare_ai,node_news_inputs,node_jobseeker toneIndigo
```

## Components

### Search experience

- [Search UI](https://github.com/vnk8071/goodjobs/blob/main/frontend/src/main.ts): `frontend/src/main.ts`
- [API client](https://github.com/vnk8071/goodjobs/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Chat UI](https://github.com/vnk8071/goodjobs/blob/main/frontend/src/chat.ts): `frontend/src/chat.ts`

### Search backend

- [Search API](https://github.com/vnk8071/goodjobs/blob/main/backend/main.py): `backend/main.py`
- [Intent and city](https://github.com/vnk8071/goodjobs/blob/main/backend/src/intent.py): `backend/src/intent.py`
- [Job matching](https://github.com/vnk8071/goodjobs/blob/main/backend/src/matching.py): `backend/src/matching.py`
- [Scraper dispatch](https://github.com/vnk8071/goodjobs/blob/main/backend/src/scrapers/__init__.py): `backend/src/scrapers/__init__.py`
- [Job-board scrapers](https://github.com/vnk8071/goodjobs/tree/main/backend/src/scrapers): `backend/src/scrapers`
- [Scrape queue](https://github.com/vnk8071/goodjobs/blob/main/backend/src/concurrency.py): `backend/src/concurrency.py`
- [Chat service](https://github.com/vnk8071/goodjobs/blob/main/backend/src/chat.py): `backend/src/chat.py`

### Cache and enrichment

- [Redis job cache](https://github.com/vnk8071/goodjobs/blob/main/backend/src/cache.py): `backend/src/cache.py`
- [Vector search](https://github.com/vnk8071/goodjobs/blob/main/backend/src/vector.py): `backend/src/vector.py`
- [Cache warmup](https://github.com/vnk8071/goodjobs/blob/main/backend/src/warmup.py): `backend/src/warmup.py`
- [Job summaries](https://github.com/vnk8071/goodjobs/blob/main/backend/src/background_summarizer.py): `backend/src/background_summarizer.py`
- [Job submissions](https://github.com/vnk8071/goodjobs/blob/main/backend/src/submissions.py): `backend/src/submissions.py`

### Jobs news

- [News worker](https://github.com/vnk8071/goodjobs/blob/main/worker/src/index.js): `worker/src/index.js`
- [News generation](https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/generate.js): `worker/src/news/generate.js`
- [News sources](https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/sources.js): `worker/src/news/sources.js`
- [News rendering](https://github.com/vnk8071/goodjobs/blob/main/worker/src/news/render.js): `worker/src/news/render.js`

### External integrations

- [MCP tools](https://github.com/vnk8071/goodjobs/blob/main/mcp/goodjobs_mcp.py): `mcp/goodjobs_mcp.py`
- **Redis**
- **Job boards**
- **Cloudflare AI**
- **News inputs**

### Other components

- **Job seeker**

## Connections

- Job seeker → Search UI: searches
- Search UI → API client: requests (evidence: `frontend/src/main.ts`)
- API client → Search API: calls API
- Search UI → Chat UI: opens chat (evidence: `frontend/src/main.ts`)
- API client → Search API: streams results
- Search API → Intent and city: classifies input (evidence: `backend/main.py`)
- Search API → Redis job cache: checks cache (evidence: `backend/main.py`)
- Search API → Vector search: supplements results (evidence: `backend/main.py`)
- Search API → Scrape queue: queues scrapes (evidence: `backend/main.py`)
- Search API → Scraper dispatch: dispatches scrapers (evidence: `backend/main.py`)
- Scraper dispatch → Job-board scrapers: selects boards (evidence: `backend/src/scrapers/__init__.py`)
- Job-board scrapers → Job boards: scrapes listings
- Search API → Job matching: matches jobs (evidence: `backend/main.py`)
- Search API → Redis job cache: stores results (evidence: `backend/main.py`)
- Redis job cache → Redis: reads and writes (evidence: `backend/src/cache.py`)
- Vector search → Redis: uses cached jobs
- Cache warmup → Redis job cache: refreshes cache (evidence: `backend/src/warmup.py`)
- Cache warmup → Scraper dispatch: runs scrapers (evidence: `backend/src/warmup.py`)
- Cache warmup → Scrape queue: shares queue (evidence: `backend/src/warmup.py`)
- Cache warmup → Job summaries: schedules summaries (evidence: `backend/src/warmup.py`)
- Job submissions → Redis job cache: reads cache (evidence: `backend/src/submissions.py`)
- Chat service → Intent and city: uses intent (evidence: `backend/src/chat.py`)
- Chat service → Redis job cache: searches cached jobs (evidence: `backend/src/chat.py`)
- Chat service → Vector search: uses semantic search (evidence: `backend/src/chat.py`)
- Intent and city → Cloudflare AI: classifies with (evidence: `backend/src/intent.py`)
- News worker → News generation: routes news work (evidence: `worker/src/index.js`)
- News generation → News sources: collects sources (evidence: `worker/src/news/generate.js`)
- News worker → News rendering: renders pages
- News sources → News inputs: fetches content
- Job seeker → MCP tools: uses MCP client
- MCP tools → Search API: exposes search tools
