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