JobFit AI is searches real-time active LinkedIn jobs without limits, computes deep ATS match percentages (0β100%) and selection probabilities, and broadcasts top matches directly to a Telegram bot.
100% Free & Local β No paid LLM subscriptions, no OpenAI tokens, and no LinkedIn API keys required. Features built-in SQLite persistence and a 24/7 background watcher daemon.
- Key Features
- How It Works (Matching Engine)
- System Architecture
- Tech Stack
- Quick Start Guide
- 1-Minute Telegram Bot Setup
- Running the Application
- Docker Deployment
- API Reference
- Step-by-Step: Push to GitHub
- Project Directory Structure
-
Unlimited LinkedIn Guest Job Harvester:
- Searches active, real-time LinkedIn job postings across multiple pages with no artificial limits (fetches all available jobs).
- Supports up to 3 target locations (e.g., Remote, United States, India) β location is completely optional (defaults to worldwide if omitted).
- Experience Level Filter: Target Entry Level, Associate / Mid, Mid-Senior, Senior, Director / Lead, or Internship.
- Recency Prioritization: Queries LinkedIn with
sortBy=DDand sorts postings so the newest job is the top priority.
-
Multi-Format Resume Parser & Smart Title Inference:
- Upload resumes in PDF, DOCX, or TXT format (or paste raw text).
- Boundary-safe regex extractor identifies 60+ technical skills and estimates professional experience.
- Tailored Job Title Suggestions: Automatically suggests 3 to 4 recommended target roles matching the resume stack.
-
Hybrid ATS Matching Engine (Zero Cost):
- Skill Overlap Score: Compares required vs. candidate skills using set theory.
- Contextual TF-IDF Similarity: Computes semantic N-gram cosine similarity using Scikit-Learn.
- Experience Calibration: Penalizes seniority mismatches (prevents showing Lead/Principal roles to freshers).
- Selection Probability: Categorizes matches into
Very High,High,Moderate, orLowlikelihood of resume selection.
-
Instant Telegram Alerts:
- Dispatches formatted HTML alert cards directly to your Telegram chat or channel.
- Includes Match Badge, Company, Location, Date Posted, Experience Level, Matching Skills, Missing Skills, and a direct LinkedIn application link.
-
Zero-Repetition SQLite Persistence:
- Auto-saves user profile, parsed resume, search preferences, and Telegram credentials to an embedded SQLite database (
data/jobfit.db). - Automatically pre-fills the dashboard on page reload β no repeated uploads.
- Auto-saves user profile, parsed resume, search preferences, and Telegram credentials to an embedded SQLite database (
-
24/7 Background Watcher Daemon:
- Autonomous server-side background task runs periodically (e.g., every 5β10 minutes) even when the browser is closed.
- Compares findings against
data/sent_jobs.jsonto deliver alerts only for brand-new postings with zero duplicate spam.
JobFit AI does not require heavy, costly cloud LLMs. It uses high-speed, deterministic Machine Learning & Information Retrieval algorithms:
-
Skill Overlap Ratio:
$S = \frac{|\text{Candidate Skills} \cap \text{Job Skills}|}{|\text{Job Skills}|}$ -
Semantic Vector Distance: High-dimensional cosine angle computed via
TfidfVectorizer(ngram_range=(1, 2)) - Execution Speed: Sub-second evaluation across hundreds of jobs with zero API token consumption.
flowchart TD
A[Candidate Resume / Profile] -->|PDF / DOCX / Text| B[Resume Parser Service]
B -->|Skills & Title| C[Candidate Profile Model]
D[LinkedIn Public Guest API] -->|Keywords, Locations, Experience Level| E[LinkedIn Scraper Service]
E -->|Newest Postings First| F[Job Postings Collection]
C --> G[Hybrid Matching Engine]
F --> G
G -->|TF-IDF + Cosine Similarity| H[Match Percentage 0-100%]
G -->|Skill Overlap & Seniority| I[Selection Probability High/Med/Low]
H --> J[Rank by Recency & Match]
I --> J
J --> K[FastAPI Interactive Dashboard]
J -->|Telegram Bot API Free| L[User's Telegram Chat]
M[(SQLite DB: data/jobfit.db)] <-->|Auto-Save & Auto-Fill| K
N[24/7 Watcher Daemon] -->|Continuous Scan & Deduplication| L
- Backend Framework: FastAPI + Uvicorn
- Data & Matching: Scikit-Learn (TF-IDF, Cosine Similarity), NumPy
- Document Processing: PyPDF, python-docx, BeautifulSoup4, LXML
- Database: SQLite3 (Built-in standard library, zero setup)
- HTTP Client: HTTPX (Async requests)
- Frontend: HTML5, Tailwind CSS, FontAwesome, Modern Vanilla JavaScript
- Specification: IEEE Std 830-1998 compliant (SRS.md)
- Python 3.10+ installed on your system.
- A Telegram account (free).
git clone https://github.com/<your-username>/jobfit_ai.git
cd jobfit_aiWindows (PowerShell):
python -m venv .venv
.venv\Scripts\activateLinux / macOS:
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txt- Open Telegram and search for @BotFather.
- Send
/newbot, choose a name and username (e.g.MyJobAlertBot). - Copy the HTTP API token provided (
123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ). - Search for @userinfobot on Telegram and send
/startto retrieve your numeric Chat ID (e.g.987XXXXX6). - Open your bot in Telegram and click START so it has permission to message you.
- Enter your token and Chat ID into the web dashboard and click Save Credentials (or add them to
.env).
Start the application with the runner script:
python run.pyOr directly using Uvicorn:
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload- π Web Dashboard: http://127.0.0.1:8000
- π Interactive Swagger Docs: http://127.0.0.1:8000/docs
- π©Ί Health Check Endpoint: http://127.0.0.1:8000/health
You can build and run JobFit AI using Docker:
# Build the Docker image
docker build -t jobfit-ai .
# Run container mounting persistent data volume
docker run -d -p 8000:8000 -v $(pwd)/data:/app/data --name jobfit-ai jobfit-aiOr using Docker Compose:
docker compose up -d| Method | Endpoint | Description |
|---|---|---|
POST |
/api/pipeline/run |
Master Pipeline: Parses resume, scrapes LinkedIn, calculates match %, and auto-sends to Telegram. |
GET |
/api/profile/saved |
Retrieves saved user profile, resume details, and credentials from SQLite. |
POST |
/api/profile/save |
Upserts profile and search preferences to SQLite. |
POST |
/api/resume/upload |
Parses .pdf, .docx, or .txt resume and auto-persists to SQLite. |
POST |
/api/resume/parse-text |
Parses raw text or structured skills into a UserProfile. |
POST |
/api/telegram/test |
Sends a verification ping message to test credentials. |
POST |
/api/telegram/save |
Explicitly saves Telegram credentials to SQLite and .env. |
POST |
/api/telegram/send |
Dispatches matched jobs directly to Telegram. |
GET |
/api/watcher/status |
Real-time status and telemetry for the 24/7 background watcher. |
POST |
/api/watcher/start |
Starts the autonomous background watcher loop. |
POST |
/api/watcher/stop |
Stops the background watcher loop. |
GET |
/health |
System health check and service status. |
Follow these steps to initialize and push this project to your GitHub repository:
cd c:\Users\acer\OneDrive\Desktop\jobfit_ai
git initgit add .(Note: .gitignore will automatically exclude .venv, .env, temporary files, and local databases).
git commit -m "feat: Initial commit of JobFit AI platform"Create a new empty repository on GitHub (e.g. jobfit_ai), then run:
git branch -M main
git remote add origin https://github.com/<your-username>/jobfit_ai.gitgit push -u origin mainjobfit_ai/
βββ app/
β βββ routers/
β β βββ pipeline.py # Master End-to-End Pipeline
β β βββ profile.py # SQLite Persistence API
β β βββ resume.py # Multi-format Resume Ingestion API
β β βββ telegram.py # Telegram Ping & Send API
β β βββ watcher.py # 24/7 Background Daemon Controls
β βββ schemas/ # Pydantic v2 validation models
β βββ services/
β β βββ db_service.py # SQLite persistence service
β β βββ linkedin_service.py # Guest scraper with recency priority
β β βββ matching_service.py # TF-IDF + Skill Overlap matching engine
β β βββ resume_service.py # Document parsing & title suggestion engine
β β βββ telegram_service.py # Rich HTML Telegram alert formatter
β β βββ watcher_service.py # 24/7 autonomous loop with deduplication
β βββ static/ # Client-side JavaScript & CSS
β βββ templates/ # Tailwind CSS responsive dashboard
β βββ config.py # Application settings & environment loader
β βββ main.py # FastAPI application entrypoint
βββ data/ # Persistent storage (SQLite DB & tracker)
βββ .env.example # Template configuration
βββ .gitignore # Safe Git ignore configuration
βββ docker-compose.yml # Docker Compose configuration
βββ Dockerfile # Production container specification
βββ requirements.txt # Production dependencies
βββ run.py # Server startup script
βββ SRS.md # IEEE 830 Software Requirements Specification
βββ README.md # Complete project documentation