🚀 ATS Career Engine (Phase 1–5 Complete)

Autonomous Multi-Platform Job Discovery, Zero-Hallucination Resume Optimization, Human-in-the-Loop Command Center, Undetectable CDP Application Agent, and Post-Application Radar.

---

🎯 The Problem

Modern recruitment is gated by Applicant Tracking Systems (ATS) such as Workday, Greenhouse, Lever, Taleo, and iCIMS:

• 75%+ of Qualified CVs are Auto-Rejected: Complex multi-column templates, tables, non-standard fonts, and missing exact keywords prevent parser indexing.
• The Junior vs. Senior Dilemma: Juniors waste time applying to roles requiring 5+ years of experience; seniors miss opportunities because their resumes aren't tailored to specific architectural paradigms.
• Bot Detection & CAPTCHA Walls: Naive headless scrapers are immediately blocked by Cloudflare and LinkedIn anti-bot heuristics.
• The Post-Application "Black Hole": Candidates have zero visibility into whether their resume was actually viewed, ingested by the ATS, or discarded.

ATS Career Engine solves this end-to-end for candidates of any seniority (from Entry-Level to Lead/Manager) across any industry.

---

🏗️ Architecture Diagram

flowchart TD
    subgraph P2["Phase 2: Discovery & Pre-Filter"]
        A["Target Roles & Location"] --> B["Multi-Platform Scraper (LinkedIn & Indeed)"]
        B --> C["SHA-256 Deduplication (SQLite jobs.db)"]
        C --> D{"Deterministic Pre-Filter"}
        D -- "Seniority Mismatch / Excluded KW" --> D1["DISCARDED_PREFILTER (0 Tokens)"]
        D -- "Passes Criteria" --> E["Viable Job Posting"]
    end

    subgraph P1["Phase 1: ATS Tailoring & Typst Compiler"]
        E --> F["Gemini 2.5 Flash (Structured Outputs)"]
        F --> G["Zero-Hallucination STAR / XYZ Optimization"]
        G --> H["Single-Column Typst Compiler"]
        H --> I["pypdf Keyword Retention Auditor"]
        I -- "Retention >= 80%" --> J["VIABLE_PENDING_APPROVAL"]
    end

    subgraph P3["Phase 3: Interactive Command Center"]
        J --> K["Telegram Bot Notification Card"]
        K --> L{"User Decision Callback"}
        L -- "apply_ats" --> M1["APPROVED_WITH_ATS_CV (+ Typst PDF attached)"]
        L -- "apply_base" --> M2["APPROVED_WITH_BASE_CV"]
        L -- "reject" --> M3["USER_REJECTED"]
    end

    subgraph P4["Phase 4: Undetectable Playwright CDP Applier"]
        M1 & M2 --> N["BrowserManager (Chrome CDP Port 9222)"]
        N --> O{"Platform Router"}
        O -- "LinkedIn" --> P["LinkedInApplier (Easy Apply + Jitter + Stop-at-Review)"]
        O -- "Greenhouse / Lever" --> Q["GreenhouseApplier (Auto-Fill & PDF Upload)"]
        P & Q --> R["SQLite Status: APPLIED / APPLICATION_FAILED"]
    end

    subgraph P5["Phase 5: Post-Application Radar"]
        R --> S["IMAP Mailbox Scanner (Workday, Greenhouse, LinkedIn)"]
        S --> T["Intelligent Classification Engine"]
        T --> U{"Event Classification"}
        U -- "ACK_RECEIVED" --> V1["Status: ACK_RECEIVED"]
        U -- "CV_VIEWED" --> V2["Status: CV_VIEWED_BY_HR (Human Read Rate)"]
        U -- "INTERVIEW_INVITE" --> V3["Status: IN_PROCESS_INTERVIEW (🏆 Conversion)"]
        V1 & V2 & V3 --> W["Telegram Alert & Candidate Lifecycle Dashboard"]
    end

Loading

---

📦 Project Structure

ats-career-engine/
├── .env.example                     # Environment template (Gemini, Telegram, IMAP)
├── .gitignore                       # Ignores .venv, PDFs, DBs, screenshots, profiles
├── main.py                          # Unified CLI orchestrator (--discover, --notify, etc.)
├── main_test.py                     # Phase 1 standalone test (Gemini + Typst + pypdf)
├── phase2_pipeline_test.py          # Phase 2 standalone test (Discovery + Deduplication)
├── phase3_notification_test.py      # Phase 3 standalone test (Telegram Bot + Callbacks)
├── phase4_apply_test.py             # Phase 4 standalone test (Playwright CDP + Fillers)
├── phase5_lifecycle_test.py         # Phase 5 standalone test (IMAP Radar + Dashboard)
├── data/
│   ├── jobs.db                      # SQLite database (job_offers & application_events)
│   └── generated_cvs/               # Typst compiled single-column ATS PDFs
└── src/
    ├── core/
    │   ├── schemas.py               # Pydantic v2 data models & lifecycle enums
    │   ├── tailor_engine.py         # Gemini 2.5 Flash zero-hallucination tailor engine
    │   └── ats_compiler.py          # Typst single-column compiler & pypdf auditor
    ├── database/
    │   ├── models.py                # SQLAlchemy models (JobOffer, ApplicationEvent)
    │   └── repository.py            # SQLite queries, SHA-256 hashing, event logging
    ├── scraper/
    │   ├── discovery.py             # JobSpy LinkedIn/Indeed scraper with mock fallback
    │   └── pre_filter.py            # Zero-token deterministic seniority/keyword filter
    ├── notifications/
    │   ├── telegram_bot.py          # aiogram interactive cards & callback handlers
    │   └── inbox_monitor.py         # IMAP email reader & ATS survival classifier
    └── applier/
        ├── browser_manager.py       # Playwright CDP port 9222 connection & local fallback
        ├── base_applier.py          # Abstract applier with human jitter & file upload
        ├── linkedin_applier.py      # LinkedIn Easy Apply multi-step modal automation
        └── greenhouse_applier.py    # Greenhouse / Lever clean career portal auto-filler

---

⚡ Quick Start

1. Clone & Environment Setup

# Clone the repository
git clone https://github.com/your-username/ats-career-engine.git
cd ats-career-engine

# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install pydantic google-genai typst pypdf python-dotenv python-jobspy sqlalchemy pandas aiogram playwright
playwright install chromium

2. Configure Environment Variables

Copy .env.example to .env:

Copy-Item .env.example .env

Fill in your configuration:

# Gemini AI
GEMINI_API_KEY=your_gemini_api_key

# Telegram Interactive Command Center
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id

# Post-Application Email Radar (IMAP)
IMAP_SERVER=imap.gmail.com
EMAIL_USER=your_email@gmail.com
EMAIL_APP_PASSWORD=your_app_password

3. Configure Your Candidate Profile

Copy data/profile.example.json to data/my_profile.json and customize your verified background and job targets:

Copy-Item data/profile.example.json data/my_profile.json

(Note: data/my_profile.json is automatically ignored by Git to keep your personal contact details strictly private).

---

🛡️ Undetectable Chrome CDP Mode (Port 9222)

To automate applications on platforms like LinkedIn without bot flags or CAPTCHA blocks, launch your real Chrome browser with the Chrome DevTools Protocol port enabled:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="chrome-automation-profile"

1. Log into your LinkedIn account in this Chrome window once.
2. The BrowserManager connects to http://localhost:9222, inheriting your active session cookies, hardware fingerprints, and authentic user state.

---

🕹️ CLI Orchestrator Usage (main.py)

Run individual stages or the entire pipeline:

# 1. Discover and deduplicate jobs across platforms, adapting viable ATS resumes:
python main.py --discover

# 2. Dispatch interactive Telegram cards with inline decision buttons:
python main.py --notify

# 3. Execute Playwright / CDP browser automation for user-approved positions:
python main.py --apply

# 4. Scan your mailbox via IMAP for acknowledgments, CV views, and interviews:
python main.py --monitor-inbox

# 5. Show full pipeline status dashboard & post-application event audit trail:
python main.py --status-dashboard

# 6. Execute full end-to-end lifecycle pipeline:
python main.py --all

---

🧪 Verification & Standalone Test Suites

Each phase includes an independent standalone test suite:

Phase	Test Command	Focus
Phase 1	python main_test.py	Gemini 2.5 Flash tailoring, Typst PDF compilation, and 100% keyword retention audit.
Phase 2	python phase2_pipeline_test.py	Live LinkedIn/Indeed scraping, SHA-256 deduplication, and zero-token pre-filter.
Phase 3	python phase3_notification_test.py	Interactive Telegram cards and state machine transitions.
Phase 4	python phase4_apply_test.py	Playwright CDP connection, LinkedIn Easy Apply safety, and Greenhouse form fill.
Phase 5	python phase5_lifecycle_test.py	Post-application IMAP radar, event audit trail, and ATS survival metrics.

---

📊 Lifecycle Status Machine

               [NEW]
                 │
     ┌───────────┴───────────┐
     ▼                       ▼
[DISCARDED_PREFILTER]  [VIABLE_PENDING_APPROVAL]
(Zero Token Reject)          │
                 ┌───────────┼───────────┐
                 ▼           ▼           ▼
        [APPROVED_ATS] [APPROVED_BASE] [USER_REJECTED]
                 │           │
                 └─────┬─────┘
                       ▼
                   [APPLIED]
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
[ACK_RECEIVED]   [CV_VIEWED_BY_HR]  [IN_PROCESS_INTERVIEW] 🏆

---

📄 License

MIT License. Designed and built with enterprise standards for autonomous career engineering.