# raghu1134/ai-job-agent architecture

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

- Interactive diagram: https://gitdiagram.com/raghu1134/ai-job-agent
- Repository: https://github.com/raghu1134/ai-job-agent

## Overview

AI Job Agent is a self-hosted job-discovery and matching service. Its main workflow runs on a schedule or on demand: search job boards, filter and deduplicate adverts, score candidates against the user’s profile with Ollama, record seen jobs, save matches to NocoDB, and send a Telegram summary. The repository implements much of this workflow in one file, so several stage nodes share its path. The setup-check and chat-ID tools support configuration. Relationship evidence is limited to the excerpts and README; unsampled implementation details are not inferred.

Main entry points: [`jobagent/app/finder.py`](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py) (Job Finder), [`jobagent/tools/check_setup.py`](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/check_setup.py) (Connection check), [`jobagent/tools/get_chat_id.py`](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/get_chat_id.py) (Chat ID lookup), [`jobagent/app/config.json`](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/config.json) (Run schedule)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Job discovery"]
  node_finder["Job Finder<br/>[finder.py]"]
  node_schedule["Run schedule<br/>[config.json]"]
  node_search["Board search<br/>[finder.py]"]
  node_reed["Reed API"]
  node_adzuna["Adzuna API"]
  node_filter["Filter and dedupe<br/>[finder.py]"]
end

subgraph group_matching["Matching and state"]
  node_profile["User profile<br/>[master.md]"]
  node_scoring["AI scoring<br/>[finder.py]"]
  node_ollama["Ollama model"]
  node_seen[("Seen-job state<br/>[finder.py]")]
end

subgraph group_delivery["Results delivery"]
  node_tracker[("NocoDB tracker")]
  node_telegram["Telegram bot"]
end

subgraph group_setup["Setup tools"]
  node_setupcheck["Connection check<br/>[check_setup.py]"]
  node_chatid["Chat ID lookup<br/>[get_chat_id.py]"]
end

node_user(("Job seeker"))

node_user -->|"runs"| node_finder
node_schedule -->|"sets run times"| node_finder
node_finder -->|"starts search"| node_search
node_search -->|"queries"| node_reed
node_search -->|"queries"| node_adzuna
node_finder -->|"filters candidates"| node_filter
node_finder -->|"reads and saves"| node_seen
node_finder -->|"loads"| node_profile
node_finder -->|"scores candidates"| node_scoring
node_scoring -->|"requests scores"| node_ollama
node_finder -->|"saves matches"| node_tracker
node_finder -->|"sends summary"| node_telegram
node_user -->|"checks setup"| node_setupcheck
node_setupcheck -->|"tests connection"| node_reed
node_setupcheck -->|"tests connection"| node_adzuna
node_setupcheck -->|"checks model"| node_ollama
node_setupcheck -->|"tests connection"| node_tracker
node_setupcheck -->|"tests connection"| node_telegram
node_user -->|"looks up chat"| node_chatid
node_chatid -->|"reads updates"| node_telegram

click node_finder "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py"
click node_schedule "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/config.json"
click node_search "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py"
click node_filter "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py"
click node_profile "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/cv/master.md"
click node_scoring "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py"
click node_seen "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py"
click node_setupcheck "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/check_setup.py"
click node_chatid "https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/get_chat_id.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_finder,node_schedule,node_search,node_reed,node_adzuna,node_filter toneBlue
class node_profile,node_scoring,node_ollama,node_seen toneAmber
class node_tracker,node_telegram toneMint
class node_setupcheck,node_chatid toneRose
class node_user toneIndigo
```

## Components

### Job discovery

- [Job Finder](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py): `jobagent/app/finder.py`
- [Run schedule](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/config.json): `jobagent/app/config.json`
- [Board search](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py): `jobagent/app/finder.py`
- **Reed API**
- **Adzuna API**
- [Filter and dedupe](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py): `jobagent/app/finder.py`

### Matching and state

- [User profile](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/cv/master.md): `jobagent/cv/master.md`
- [AI scoring](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py): `jobagent/app/finder.py`
- **Ollama model**
- [Seen-job state](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/app/finder.py): `jobagent/app/finder.py`

### Results delivery

- **NocoDB tracker**
- **Telegram bot**

### Setup tools

- [Connection check](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/check_setup.py): `jobagent/tools/check_setup.py`
- [Chat ID lookup](https://github.com/raghu1134/ai-job-agent/blob/main/jobagent/tools/get_chat_id.py): `jobagent/tools/get_chat_id.py`

### Other components

- **Job seeker**

## Connections

- Job seeker → Job Finder: runs (evidence: `README.md`)
- Run schedule → Job Finder: sets run times (evidence: `jobagent/app/finder.py`)
- Job Finder → Board search: starts search (evidence: `jobagent/app/finder.py`)
- Board search → Reed API: queries (evidence: `jobagent/app/finder.py`)
- Board search → Adzuna API: queries (evidence: `jobagent/app/finder.py`)
- Job Finder → Filter and dedupe: filters candidates (evidence: `jobagent/app/finder.py`)
- Job Finder → Seen-job state: reads and saves (evidence: `jobagent/app/finder.py`)
- Job Finder → User profile: loads (evidence: `jobagent/app/finder.py`)
- Job Finder → AI scoring: scores candidates (evidence: `README.md`)
- AI scoring → Ollama model: requests scores (evidence: `jobagent/app/finder.py`)
- Job Finder → NocoDB tracker: saves matches (evidence: `README.md`)
- Job Finder → Telegram bot: sends summary (evidence: `README.md`)
- Job seeker → Connection check: checks setup (evidence: `README.md`)
- Connection check → Reed API: tests connection (evidence: `jobagent/tools/check_setup.py`)
- Connection check → Adzuna API: tests connection (evidence: `jobagent/tools/check_setup.py`)
- Connection check → Ollama model: checks model (evidence: `jobagent/tools/check_setup.py`)
- Connection check → NocoDB tracker: tests connection (evidence: `jobagent/tools/check_setup.py`)
- Connection check → Telegram bot: tests connection (evidence: `jobagent/tools/check_setup.py`)
- Job seeker → Chat ID lookup: looks up chat (evidence: `README.md`)
- Chat ID lookup → Telegram bot: reads updates (evidence: `jobagent/tools/get_chat_id.py`)
