hamkadr/FEATURES.md

Feature Catalog & Recommendation Engine

Scope note: the platform now serves all healthcare staff — پزشک عمومی/متخصص، پرستار، ماما، تکنسین (اتاق عمل، بیهوشی، رادیولوژی، آزمایشگاه)، و سایر کادر درمان — not just GPs. The unit of value is the shift/job, matched to a person's interests.

---

Part A — The interest & recommendation engine

Goal: learn what each person wants and proactively surface the right shifts ("به‌جای اینکه کاربر دنبال شیفت بگردد، شیفت مناسب سراغ او بیاید").

What we track (signals)

Explicit (the person tells us):

• Role(s) + specialty/skills (پزشک، پرستار، ماما، …)
• Preferred cities / areas / max commute distance
• Preferred shift types (صبح/عصر/شب/آنکال) and days/times available
• Minimum pay expectation, pay type
• Saved searches + favorited facilities

Implicit (behavior — the gold for ML later):

• InterestEvent log: view, click, dwell-time, save, apply, dismiss, hide-facility
• Which shifts they applied to vs ignored
• Outcomes: accepted / rejected / completed (and did they come back)

Three-stage build (ship value early, add intelligence over time)

Stage 1 — Pattern engine (rule-based scoring). Explainable, cold-start-safe, no ML infra.

score(shift, person) =
    w1 · role/specialty match        (hard filter or heavy weight)
  + w2 · city/area match
  + w3 · shift-type preference
  + w4 · pay vs expectation
  + w5 · availability/day-time fit
  + w6 · affinity (favorited / previously applied to this facility)
  + w7 · freshness
  − penalties (dismissed similar, hidden facility)

Produces a ranked personalized feed + a reason chip: «چون به شیفت‌های شب بیمارستان میلاد علاقه نشان دادی». Tunable weights, fully deterministic.

Stage 2 — Behavioral / collaborative. From the InterestEvent matrix:

• «کاربرانی شبیه تو این شیفت‌ها را برداشتند» (item-item / user-user collaborative filtering)
• Implicit-feedback preference vectors; auto-learn weights instead of hand-tuning.

Stage 3 — AI / ML.

• Embeddings: encode each shift (free-text + structured) and each profile into vectors; rank by similarity. Enables fuzzy/semantic matching and natural-language search («شیفت شب آخر هفته نزدیک خونه با حقوق خوب»).
• LLM for listing-parsing: turn messy Telegram/Bale/Divar posts into structured shifts automatically (huge for the aggregation pipeline + cold-start).
• Learning-to-rank trained on apply→accept outcomes.
• Demand forecasting: flag shifts likely to go unfilled; suggest pay to facilities.

Iran constraint: OpenAI/Anthropic APIs are blocked. Plan to self-host a multilingual embedding model + a small Persian-capable LLM on the VPS, or use an Iranian AI provider. Stage 1 needs zero AI infra, so we get personalization live immediately.

How suggestions reach the person

Personalized home feed · "پیشنهادهای ویژه شما" section · daily/instant alerts via Bale bot + SMS (Kavenegar) + email · and the reverse: suggest candidates to facilities.

New data entities this needs

UserPreferences, InterestEvent, SavedSearch, Favorite, AlertSubscription, plus Skill/Role taxonomy.

---

Part B — Full functionality catalog

1. For job seekers (پزشک/پرستار/ماما/…)

• Multi-role profile + skills, with medical-council (نظام پزشکی/نظام پرستاری) verification
• Document wallet (license, certificates) — verified badge
• Personalized recommendation feed (Part A)
• Availability calendar — mark when you're free; get matched
• Saved searches + instant alerts (Bale/SMS/email/push)
• One-tap «اعلام تمایل» / apply; application tracking board
• Favorites / bookmarks; hide facilities
• In-app chat with facility (or contact handoff)
• Ratings & reviews of facilities; earnings tracker
• Shift-swap marketplace — trade shifts with other staff
• Reliability/reputation score (shows up first to facilities)

2. For facilities (بیمارستان/کلینیک/درمانگاه)

• Self-serve posting + recurring shift templates (e.g. "every night this month")
• Applicant management — shortlist, accept, reject, message
• Reverse recommendations — «این پزشکان مناسب شیفت شما هستند»
• Urgent shift broadcast (push to all matching nearby staff instantly)
• Verified-facility badge; rate doctors
• Analytics: fill rate, time-to-fill, no-show rate
• Bulk import; multi-branch/department management

3. Marketplace / platform

• Aggregation pipeline from Telegram/Bale/Divar + AI parsing (Part A Stage 3)
• Admin moderation/normalization queue
• Trust & safety: identity & license verification, spam/fraud detection
• Notifications hub (Bale bot, SMS, email, web push)
• Dispute resolution / no-show handling
• Payments later: subscriptions, pay-per-post, or commission/escrow (Iranian gateway: Zarinpal/IDPay)

4. AI / intelligence layer

• Recommendation engine · natural-language search · listing auto-parsing
• Demand forecasting + dynamic pay suggestions for facilities
• Profile/resume parsing · duplicate & fraud detection on listings
• Chatbot assistant (Bale) to search and apply by chat

5. Growth & engagement

• Bale/Telegram bot (search, alerts, apply — meets users where they already are)
• SEO content pages per hospital / city / role (organic doctor traffic)
• Referral program · reliability gamification · SMS/email campaigns

---

Part C — Naming (decide with the user)

Working name is شیفت‌یاب. Since scope is now all roles, a shift-centric, brandable name fits Iranian startup naming (Snapp/Tapsi/Divar/Bama style). Shortlist:

• شیفتو (Shifto) — short, playful, very on-trend; strong .ir brand potential
• شیفت‌یار (ShiftYar) — "shift companion/helper"; professional, clear meaning
• هم‌شیفت (Hamshift) — "co-shift"; community feel
• کادریاب (Kadryab) — "staff-finder"; emphasizes whole کادر درمان, not just doctors