Telegram Job & Candidate Match Bot

Simple, fast, and clear hiring in Telegram: job seekers find jobs, employers find candidates.

---

📚 Table of Contents

• What the Bot Does
• What Makes It Different
• User Flows
• Commands
• Admin & Moderation
• Analytics
• Security & Privacy
• Architecture & Tech
• Testing & Quality
• Limits & Behavior
• Roadmap
• Author

🎯 What the Bot Does

• Clear flows without noise. • Candidate: sign up (profile) → browse vacancies → "Apply/Skip" → next card. • Employer: create vacancy → receive and conveniently review applications.
• Full‑featured profile & vacancy editor (not a demo‑level form).
• City‑first recommendations on day one, so the feed is relevant immediately.
• De‑spam applications. If a vacancy gets multiple applications, the bot merges them into a queue and lets HR review them one by one.
• Gentle reminders for users (come back later) and admin alerts on reported profiles.
• Anti‑spam: if a candidate reacts too fast to cards, a short 5‑minute cooldown is applied.
• Content limits: per user — 1 vacancy; per vacancy — 1 photo and up to 1024 characters in the description.
• Paid access for employers (posting vacancies) via Tribute. The bot checks daily whether the employer still belongs to the required group/channel: if yes — access stays on; if not — access is revoked and the vacancy is hidden.
• Privacy: candidate contacts are revealed only on a match and only to the employer. Data is not shared with third parties and is stored on our server. No global export on demand.
• Data normalization: clickable links are stripped from descriptions.

---

✨ What Makes It Different

• Production‑grade editors for profiles and vacancies — not restricted demo forms.
• Anti‑spam & quiet applications: merging into a queue reduces noise and saves HR time.
• Relevance out of the box: city‑based recommendations for a useful initial feed.
• Controlled monetization: Tribute‑based access without tying into Telegram Payments; daily membership validation in a channel/group.
• Retention without annoyance: short motivational snippets between cards — light “breaks” that improve engagement.
• Privacy by default: contacts show up only on match and only to the employer.
• Production readiness: the project has been handed over and is ready for real‑world use; this repository showcases the architecture.

🧭 User Flows

Candidate

1. Creates a profile.
2. Swipes through vacancy cards.
3. Presses "Apply" or "Skip" — receives the next card.

Employer

1. Creates a vacancy.
2. Receives and reviews merged applications.

---

💬 Commands

• /start — full session reset and FSM reset.
• /admin — enter the admin panel (whitelist‑only access).

---

🔧 Admin & Moderation

• Create stub vacancies for launch (so new users see enough cards and don’t churn).
• Moderation: remove a profile or block a user.
• Search by user ID with a quick profile view.
• Generate tracking links (UTM‑like) to attribute traffic sources.
• Motivational content for candidates: shown between cards (short “breaks” in a TikTok‑like spirit to reduce fatigue and motivate further browsing).

---

📊 Analytics

Deep analytics wasn’t required. Implemented basic tracking: counting visits from the special links generated by the bot.

---

🛡️ Security & Privacy

• No data is shared with third parties.
• Candidate contacts are visible to the employer only after a match.
• Data is stored on our server. Centralized user‑data export is not provided.

---

🧱 Architecture & Tech

• Language/Framework: Python 3.12.4, aiogram 3.3.0.
• Database: PostgreSQL (administered via pgAdmin 4 if needed).
• ORM/DB access: SQLAlchemy.
• Logging: separate files for regular events and errors — convenient for incident analysis and regression tracking.
• Interface: standard Telegram messages and inline buttons; Telegram Web App is not used.
• Monetization/Access: Tribute integration with a daily membership check in the target group/channel.

---

🧪 Testing & Quality

• Manual testing throughout development: author, friends, and the employer.
• Checklist of key flows: onboarding and FSM reset; creating/editing profiles and vacancies; browsing cards; matching and contact reveal; limits (1 photo, 1024 chars); 5‑minute anti‑spam cooldown; moderation/blocks; Tribute subscription check; reports and admin notifications.
• Edge cases and negative scenarios: double button presses, stale callback_data, length limits for text/media, missing photos, empty required fields.
• Reliability: careful FSM reset on /start and predictable state under network timeouts.
• Debugging via logs: separate event/error files; anomaly detection by correlating records.

Automated tests were not in scope for this project.

---

🚧 Limits & Behavior

• 1 photo and up to 1024 characters in a vacancy description.
• 1 active vacancy per user; no other hard limits.
• Under peak load the bot processes events sequentially; critical errors are logged.

---

🗺️ Roadmap

• Multi‑language (RU/UA/EN, etc.).
• Extended analytics (funnels, apply/match conversion, button CTR).
• Smarter matching (skill weights, distance/relocation, work‑format preferences).
• Admin reports and exports (vacancies/applications/users).

---

👤 Author

Vlad Khoroshylov — Instagram: @vlad.khoro.

The project has been handed over to the employer and runs on their side; this repository is for portfolio purposes and to showcase the architecture.