# mohamedalsayed12/job-application-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedalsayed12/job-application-agent
- Repository: https://github.com/mohamedalsayed12/job-application-agent

## Overview

This is a job-application platform: applicants manage profiles and view job matches, while a background worker collects listings, cleans and evaluates them, and refreshes matches. The graph covers account/profile entry, board collection, normalization, skills, quality, matching, summaries, and shared storage. Worker stage ordering and several API routes are documented in the README; arrows are limited to relationships supported by the excerpts, source index, or README, so unsampled implementation links are omitted.

Main entry points: [`app/worker.py`](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/worker.py) (Collection worker), [`app/main.py`](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/main.py) (FastAPI application), [`app/ai/anthropic.py`](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/ai/anthropic.py) (Anthropic client), [`app/api/profile.py`](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/profile.py) (Profile management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Applicant experience"]
  node_api["FastAPI application<br/>[main.py]"]
  node_accounts["Accounts<br/>[accounts.py]"]
  node_profile["Profile management<br/>[profile.py]"]
  node_cv["CV suggestions<br/>[cv_read.py]"]
  node_listings["Matched listings<br/>[listings.py]"]
  node_job_summary["Job summaries<br/>[generate.py]"]
end

subgraph group_collection["Job collection"]
  node_worker["Collection worker<br/>[worker.py]"]
  node_linkedin["LinkedIn discovery<br/>[linkedin.py]"]
  node_gateway["Outbound gateway<br/>[gateway.py]"]
  node_cleaning["Posting cleanup<br/>[clean.py]"]
  node_linking["Duplicate linking<br/>[linking.py]"]
end

subgraph group_enrichment["Job enrichment"]
  node_skills["Skill taxonomy<br/>[taxonomy.py]"]
  node_quality["Quality checks<br/>[checks.py]"]
  node_matching["Rule matching<br/>[match.py]"]
  node_judge["AI fit judging<br/>[judge.py]"]
  node_match_report["Fit reports<br/>[report.py]"]
end

subgraph group_platform["Shared platform"]
  node_anthropic["Anthropic client<br/>[anthropic.py]"]
  node_budget["Spend gate<br/>[gate.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
end

node_applicant(("Applicant"))
node_admin(("Admin"))

node_applicant -->|"uses"| node_api
node_admin -->|"administers"| node_api
node_api -->|"routes to"| node_accounts
node_api -->|"routes to"| node_profile
node_api -->|"routes to"| node_listings
node_profile -->|"requests suggestions"| node_cv
node_profile -->|"matches on save"| node_matching
node_listings -->|"reads matches"| node_matching
node_listings -->|"shows summary"| node_job_summary
node_worker -->|"runs discovery"| node_linkedin
node_linkedin -->|"fetches through"| node_gateway
node_worker -->|"cleans fetches"| node_cleaning
node_cleaning -->|"links duplicates"| node_linking
node_worker -->|"maps skills"| node_skills
node_worker -->|"checks jobs"| node_quality
node_worker -->|"refreshes matches"| node_matching
node_worker -->|"processes fits"| node_judge
node_worker -->|"processes reports"| node_match_report
node_cv -->|"requests extraction"| node_anthropic
node_job_summary -->|"requests summary"| node_anthropic
node_judge -->|"requests judgment"| node_anthropic
node_match_report -->|"requests report"| node_anthropic
node_anthropic -->|"sends request"| node_gateway
node_job_summary -->|"reserves spend"| node_budget
node_cv -->|"reserves spend"| node_budget
node_worker -.->|"updates domain data"| node_models
node_api -.->|"persists records"| node_database
node_models -->|"maps tables"| node_database

click node_api "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/main.py"
click node_accounts "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/accounts.py"
click node_profile "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/profile.py"
click node_cv "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/applicants/cv_read.py"
click node_listings "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/listings.py"
click node_job_summary "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/summaries/generate.py"
click node_worker "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/worker.py"
click node_linkedin "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/linkedin.py"
click node_gateway "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/fetch/gateway.py"
click node_cleaning "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/cleaning/clean.py"
click node_linking "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/cleaning/linking.py"
click node_skills "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/skills/taxonomy.py"
click node_quality "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/quality/checks.py"
click node_matching "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/match.py"
click node_judge "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/judge.py"
click node_match_report "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/report.py"
click node_anthropic "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/ai/anthropic.py"
click node_budget "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/budget/gate.py"
click node_models "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/models.py"
click node_database "https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/core/db.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_api,node_accounts,node_profile,node_cv,node_listings,node_job_summary toneBlue
class node_worker,node_linkedin,node_gateway,node_cleaning,node_linking toneAmber
class node_skills,node_quality,node_matching,node_judge,node_match_report toneMint
class node_anthropic,node_budget,node_models,node_database toneRose
class node_applicant,node_admin toneIndigo
```

## Components

### Applicant experience

- [FastAPI application](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/main.py): `app/main.py`
- [Accounts](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/accounts.py): `app/api/accounts.py`
- [Profile management](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/profile.py): `app/api/profile.py`
- [CV suggestions](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/applicants/cv_read.py): `app/applicants/cv_read.py`
- [Matched listings](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/api/listings.py): `app/api/listings.py`
- [Job summaries](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/summaries/generate.py): `app/summaries/generate.py`

### Job collection

- [Collection worker](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/worker.py): `app/worker.py`
- [LinkedIn discovery](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/linkedin.py): `app/linkedin.py`
- [Outbound gateway](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/fetch/gateway.py): `app/fetch/gateway.py`
- [Posting cleanup](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/cleaning/clean.py): `app/cleaning/clean.py`
- [Duplicate linking](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/cleaning/linking.py): `app/cleaning/linking.py`

### Job enrichment

- [Skill taxonomy](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/skills/taxonomy.py): `app/skills/taxonomy.py`
- [Quality checks](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/quality/checks.py): `app/quality/checks.py`
- [Rule matching](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/match.py): `app/matching/match.py`
- [AI fit judging](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/judge.py): `app/matching/judge.py`
- [Fit reports](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/matching/report.py): `app/matching/report.py`

### Shared platform

- [Anthropic client](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/ai/anthropic.py): `app/ai/anthropic.py`
- [Spend gate](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/budget/gate.py): `app/budget/gate.py`
- [Domain records](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/models.py): `app/models.py`
- [PostgreSQL](https://github.com/mohamedalsayed12/job-application-agent/blob/master/app/core/db.py): `app/core/db.py`

### Other components

- **Applicant**
- **Admin**

## Connections

- Applicant → FastAPI application: uses (evidence: `README.md`)
- Admin → FastAPI application: administers (evidence: `README.md`)
- FastAPI application → Accounts: routes to (evidence: `app/main.py`)
- FastAPI application → Profile management: routes to (evidence: `app/main.py`)
- FastAPI application → Matched listings: routes to (evidence: `app/main.py`)
- Profile management → CV suggestions: requests suggestions (evidence: `app/api/profile.py`)
- Profile management → Rule matching: matches on save (evidence: `README.md`)
- Matched listings → Rule matching: reads matches (evidence: `app/api/listings.py`)
- Matched listings → Job summaries: shows summary (evidence: `README.md`)
- Collection worker → LinkedIn discovery: runs discovery (evidence: `app/worker.py`)
- LinkedIn discovery → Outbound gateway: fetches through (evidence: `app/linkedin.py`)
- Collection worker → Posting cleanup: cleans fetches (evidence: `README.md`)
- Posting cleanup → Duplicate linking: links duplicates (evidence: `app/cleaning/clean.py`)
- Collection worker → Skill taxonomy: maps skills (evidence: `README.md`)
- Collection worker → Quality checks: checks jobs (evidence: `README.md`)
- Collection worker → Rule matching: refreshes matches (evidence: `README.md`)
- Collection worker → AI fit judging: processes fits (evidence: `app/worker.py`)
- Collection worker → Fit reports: processes reports (evidence: `app/worker.py`)
- CV suggestions → Anthropic client: requests extraction (evidence: `app/applicants/cv_read.py`)
- Job summaries → Anthropic client: requests summary (evidence: `app/summaries/generate.py`)
- AI fit judging → Anthropic client: requests judgment (evidence: `app/matching/judge.py`)
- Fit reports → Anthropic client: requests report (evidence: `app/matching/report.py`)
- Anthropic client → Outbound gateway: sends request (evidence: `app/ai/anthropic.py`)
- Job summaries → Spend gate: reserves spend (evidence: `app/summaries/generate.py`)
- CV suggestions → Spend gate: reserves spend (evidence: `app/applicants/cv_read.py`)
- Collection worker → Domain records: updates domain data (evidence: `app/worker.py`)
- FastAPI application → PostgreSQL: persists records
- Domain records → PostgreSQL: maps tables (evidence: `app/models.py`)