# volodymyr-holovan/ats-resume-xray architecture

> Architecture diagram of the GitHub repository volodymyr-holovan/ats-resume-xray, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/volodymyr-holovan/ats-resume-xray
- Repository: https://github.com/volodymyr-holovan/ats-resume-xray

## Overview

ATS Resume X-Ray is a resume-analysis product with a Streamlit web app and CLI. The main workflow accepts a PDF or DOCX, compares naive and layout-aware extraction, evaluates parsing and convention risks, recognizes fields, and produces findings and a readiness score; optional rendering boxes finding locations. A separate job-match branch parses an advert into weighted requirements, compares them with CV content, and feeds unmet requirements into a prioritized action plan. The graph follows documented and indexed dependencies; some detector internals and UI wiring are unsampled, so those links are omitted.

Main entry points: [`src/ats_xray/pipeline.py`](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/pipeline.py) (Analysis pipeline), [`app.py`](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/app.py) (Web app), [`src/ats_xray/vacancy.py`](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/vacancy.py) (Advert parsing), [`src/ats_xray/engine.py`](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/engine.py) (Risk rule engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Resume analysis"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_pdf_extract["PDF extraction<br/>[extract.py]"]
  node_docx_extract["DOCX extraction<br/>[docx_extract.py]"]
  node_pdf_document["Shared PDF reader<br/>[pdf_document.py]"]
end

subgraph group_detect["Detection and reporting"]
  node_engine["Risk rule engine<br/>[engine.py]"]
  node_structure["Structure detectors<br/>[structure.py]"]
  node_field_report["Field recognition<br/>[field_report.py]"]
  node_score["Readiness score<br/>[score.py]"]
  node_overlay["Finding overlays<br/>[overlay.py]"]
  node_regions["Page regions<br/>[regions.py]"]
  node_conventions["Locale conventions<br/>[conventions.py]"]
  node_src_sections["Resume sections<br/>[sections.py]"]
end

subgraph group_match["Job matching"]
  node_vacancy["Advert parsing<br/>[vacancy.py]"]
  node_terms["Unknown term mining<br/>[terms.py]"]
  node_lexicon["Skills lexicon<br/>[skills_lexicon.py]"]
  node_match_cv["CV matching<br/>[match.py]"]
  node_plan["Action plan<br/>[action_plan.py]"]
end

subgraph group_presentation["User interfaces"]
  node_web["Web app<br/>[app.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

node_user(("Resume owner"))
node_job_ad["Job advert"]

node_user -->|"uploads resume"| node_web
node_user -->|"submits resume"| node_cli
node_web -->|"analyzes file"| node_pipeline
node_cli -->|"analyzes file"| node_pipeline
node_pipeline -->|"dispatches PDF"| node_pdf_extract
node_pipeline -->|"dispatches DOCX"| node_docx_extract
node_pipeline -->|"shares document"| node_pdf_document
node_pdf_extract -->|"reads PDF"| node_pdf_document
node_pipeline -->|"runs rules"| node_engine
node_pipeline -->|"builds report"| node_field_report
node_pipeline -->|"scores resume"| node_score
node_engine -->|"checks structure"| node_structure
node_engine -->|"checks conventions"| node_conventions
node_pipeline -->|"renders findings"| node_overlay
node_overlay -->|"draws regions"| node_regions
node_job_ad -->|"provides requirements"| node_vacancy
node_vacancy -->|"guesses unknowns"| node_terms
node_vacancy -->|"recognizes skills"| node_lexicon
node_match_cv -->|"uses requirements"| node_vacancy
node_match_cv -->|"matches skills"| node_lexicon
node_web -->|"matches CV"| node_match_cv
node_web -->|"reads advert"| node_vacancy
node_web -->|"builds action plan"| node_plan
node_field_report -->|"recognizes sections"| node_src_sections

click node_web "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/app.py"
click node_cli "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/cli.py"
click node_pipeline "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/pipeline.py"
click node_pdf_extract "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/extract.py"
click node_docx_extract "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/docx_extract.py"
click node_pdf_document "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/pdf_document.py"
click node_engine "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/engine.py"
click node_structure "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/structure.py"
click node_field_report "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/field_report.py"
click node_score "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/score.py"
click node_overlay "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/overlay.py"
click node_regions "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/regions.py"
click node_conventions "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/conventions.py"
click node_vacancy "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/vacancy.py"
click node_terms "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/terms.py"
click node_lexicon "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/skills_lexicon.py"
click node_match_cv "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/match.py"
click node_plan "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/action_plan.py"
click node_src_sections "https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/sections.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_pipeline,node_pdf_extract,node_docx_extract,node_pdf_document toneBlue
class node_engine,node_structure,node_field_report,node_score,node_overlay,node_regions,node_conventions,node_src_sections toneAmber
class node_vacancy,node_terms,node_lexicon,node_match_cv,node_plan toneMint
class node_web,node_cli toneRose
class node_user,node_job_ad toneIndigo
```

## Components

### Resume analysis

- [Analysis pipeline](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/pipeline.py): `src/ats_xray/pipeline.py`
- [PDF extraction](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/extract.py): `src/ats_xray/extract.py`
- [DOCX extraction](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/docx_extract.py): `src/ats_xray/docx_extract.py`
- [Shared PDF reader](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/pdf_document.py): `src/ats_xray/pdf_document.py`

### Detection and reporting

- [Risk rule engine](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/engine.py): `src/ats_xray/engine.py`
- [Structure detectors](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/structure.py): `src/ats_xray/structure.py`
- [Field recognition](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/field_report.py): `src/ats_xray/field_report.py`
- [Readiness score](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/score.py): `src/ats_xray/score.py`
- [Finding overlays](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/overlay.py): `src/ats_xray/overlay.py`
- [Page regions](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/regions.py): `src/ats_xray/regions.py`
- [Locale conventions](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/conventions.py): `src/ats_xray/conventions.py`
- [Resume sections](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/sections.py): `src/ats_xray/sections.py`

### Job matching

- [Advert parsing](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/vacancy.py): `src/ats_xray/vacancy.py`
- [Unknown term mining](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/terms.py): `src/ats_xray/terms.py`
- [Skills lexicon](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/skills_lexicon.py): `src/ats_xray/skills_lexicon.py`
- [CV matching](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/match.py): `src/ats_xray/match.py`
- [Action plan](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/action_plan.py): `src/ats_xray/action_plan.py`

### User interfaces

- [Web app](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/app.py): `app.py`
- [Command line](https://github.com/volodymyr-holovan/ats-resume-xray/blob/master/src/ats_xray/cli.py): `src/ats_xray/cli.py`

### Other components

- **Resume owner**
- **Job advert**

## Connections

- Resume owner → Web app: uploads resume (evidence: `README.md`)
- Resume owner → Command line: submits resume (evidence: `README.md`)
- Web app → Analysis pipeline: analyzes file (evidence: `app.py`)
- Command line → Analysis pipeline: analyzes file (evidence: `src/ats_xray/cli.py`)
- Analysis pipeline → PDF extraction: dispatches PDF (evidence: `src/ats_xray/pipeline.py`)
- Analysis pipeline → DOCX extraction: dispatches DOCX (evidence: `src/ats_xray/pipeline.py`)
- Analysis pipeline → Shared PDF reader: shares document (evidence: `src/ats_xray/pipeline.py`)
- PDF extraction → Shared PDF reader: reads PDF (evidence: `src/ats_xray/extract.py`)
- Analysis pipeline → Risk rule engine: runs rules (evidence: `src/ats_xray/pipeline.py`)
- Analysis pipeline → Field recognition: builds report (evidence: `src/ats_xray/pipeline.py`)
- Analysis pipeline → Readiness score: scores resume (evidence: `src/ats_xray/pipeline.py`)
- Risk rule engine → Structure detectors: checks structure (evidence: `src/ats_xray/engine.py`)
- Risk rule engine → Locale conventions: checks conventions (evidence: `src/ats_xray/engine.py`)
- Analysis pipeline → Finding overlays: renders findings (evidence: `src/ats_xray/pipeline.py`)
- Finding overlays → Page regions: draws regions (evidence: `src/ats_xray/overlay.py`)
- Job advert → Advert parsing: provides requirements (evidence: `README.md`)
- Advert parsing → Unknown term mining: guesses unknowns (evidence: `src/ats_xray/vacancy.py`)
- Advert parsing → Skills lexicon: recognizes skills (evidence: `src/ats_xray/vacancy.py`)
- CV matching → Advert parsing: uses requirements (evidence: `src/ats_xray/match.py`)
- CV matching → Skills lexicon: matches skills (evidence: `src/ats_xray/match.py`)
- Web app → CV matching: matches CV (evidence: `app.py`)
- Web app → Advert parsing: reads advert (evidence: `app.py`)
- Web app → Action plan: builds action plan (evidence: `app.py`)
- Field recognition → Resume sections: recognizes sections (evidence: `src/ats_xray/field_report.py`)
