hamkadr/PLAN.md

# JobsMedical — Medical Shift Marketplace (Iran)

> A niche platform connecting **GP doctors** with **hospitals & clinics** that have open shifts.
> Replaces the chaotic hunt across Bale / Telegram channels / Divar with one structured,
> filterable view organized by **hospital, location, and weekly shift calendar**.

Date: 2026-06-02 · Market: Iran (Persian/Farsi, RTL) · Revenue: TBD

---

## 1. The problem & the bet

**Today:** A GP doctor wanting locum/extra shifts scrolls dozens of Telegram/Bale channels and
Divar posts. Listings are unstructured text, no filters, no calendar, no trust signals, expire
silently. Hospitals broadcast to the same noisy channels and get random DMs.

**Our bet:** The value isn't *more* listings — it's **structure + filtering + trust**.
"Show me open GP shifts, in Tehran, this week, paid X" should be one screen, not 40 channels.

**Why a marketplace is hard (and our answer):**
- *Cold-start problem* — empty marketplace helps no one. We solve supply first via the **mixed
  strategy**: (1) admin posts manually + (2) auto-aggregate from channels → so the site looks
  full from day one, then (3) convert hospitals to self-serve posting over time.

---

## 2. The two sides

| | Doctors (supply of labor) | Hospitals / Clinics (demand) |
|---|---|---|
| Who | GPs (پزشک عمومی) seeking shifts | Hospitals, clinics, درمانگاه‌ها |
| Want | Find shifts fast: by city, date, pay | Fill open shifts with vetted doctors |
| Onboard via | Phone OTP signup, build profile | Phase 2 self-serve; phase 1 we post for them |
| Trust signal | نظام پزشکی (medical license) number | Verified facility badge |

---

## 3. MVP scope (Phase 1 — "the structured board")

Goal: a doctor can **find and express interest in a relevant shift in under 60 seconds**.

**Must have:**
1. **Shift browse + filter** — by city, hospital, date range, specialty, shift type (day/night), pay.
2. **Weekly calendar view** per hospital — the signature feature. Jalali (Shamsi) week grid showing
   open shifts per day.
3. **Shift detail page** — hospital, location (map pin), date, hours, pay, requirements, how to apply.
4. **Doctor signup/login** — phone OTP (standard in Iran), basic profile (name, license, city, specialty).
5. **Express interest / apply** — doctor taps "interested" → handoff to facility contact (call/Bale/
   in-app message). Track applications.
6. **Admin panel** — we add/edit shifts manually, and review/normalize aggregated listings before
   they go live.
7. **Aggregation ingest (basic)** — pull text from selected Telegram/Bale channels into a "raw
   listings" queue for admin to normalize. (Start semi-manual; full automation later.)

**Explicitly NOT in MVP** (Phase 2+):
- Hospital self-serve posting & dashboards
- Payments / monetization
- Ratings & reviews
- Automated matching/recommendations, push alerts
- Full unattended scraping pipeline

---

## 4. Data model (core entities)

```
User            id, phone, full_name, role(doctor|facility_admin|admin), created_at
DoctorProfile   user_id, license_no(نظام پزشکی), specialty, city, years_exp, bio, verified
Facility        id, name, type(hospital|clinic|درمانگاه), city, address, lat,lng,
                phone, bale_id, verified, owner_user_id(nullable, phase 2)
Shift           id, facility_id, date(jalali stored as ISO), start_time, end_time,
                specialty_required, shift_type(day|night|on_call), pay_amount, pay_type,
                description, status(open|filled|expired|cancelled),
                source(direct|admin|aggregated), source_url, created_at
Application     id, shift_id, doctor_id, status(interested|accepted|rejected|withdrawn),
                message, created_at
RawListing      id, source_channel, raw_text, parsed_json, status(new|normalized|discarded),
                linked_shift_id, fetched_at      ← aggregation staging area
City            id, name, province              ← canonical city list for filters
```

Key decisions:
- **Dates stored as ISO (UTC) in DB, displayed as Jalali** in the UI. Never store Jalali strings.
- A `Shift` can originate from a `RawListing` (aggregation) or be created directly (admin/facility).
- Phone is the unique identity; OTP login, no passwords.

---

## 5. Tech architecture

Constraints that drive choices: **Iran hosting** (many global SaaS block Iranian IPs/payments →
prefer self-hostable, open-source), **SEO matters** (doctors will find shifts via Google → need
server-rendered pages), **RTL + Jalali**, **phone OTP** via Iranian SMS providers.

**Recommended stack:**
- **Frontend + backend:** Next.js (App Router) + TypeScript — SSR for SEO, one codebase, great RTL support.
- **UI:** Tailwind CSS (RTL mode) + a Persian font (Vazirmatn). Jalali via `dayjs-jalali` or `jalaali-js`.
- **DB:** PostgreSQL + Prisma ORM.
- **Auth:** Phone OTP. SMS via **Kavenegar** or **SMS.ir** (Iranian providers). Sessions via JWT/cookies.
- **Maps:** Neshan or Balad map tiles (Iranian, work without VPN) instead of Google Maps.
- **Aggregation:** A small worker (Node) using Telegram Bot API / Telethon-style reader for Bale,
  writing into `RawListing`. Runs as a separate scheduled job.
- **Hosting / CI:** Self-hosted on an Iranian VPS, deployed via your **Gitea + Nexus** pipeline
  (soroush ci/cd method). Docker Compose: web + postgres + worker.

> If you'd rather build in **.NET** (you have the Nexus/.NET pipeline set up), the equivalent is
> ASP.NET Core + Blazor/Razor + EF Core + Postgres. Same architecture, different language. ← confirm.

**Why not Google Maps / Vercel / Firebase / Stripe:** all routinely blocked or unusable from Iran.
Everything above is self-hostable or has an Iranian equivalent.

---

## 6. Key screens

1. **Home** — hero + search (city, specialty, date) + "shifts this week" + featured hospitals. SEO landing.
2. **Shift listing** — filter sidebar + result cards + map toggle.
3. **Weekly calendar** (per hospital or per city) — Shamsi week grid, open shifts as chips.
4. **Shift detail** — all info + map + "I'm interested" CTA.
5. **Doctor onboarding** — phone OTP → profile form.
6. **Doctor dashboard** — my applications, saved shifts.
7. **Admin** — shift CRUD, raw-listing normalization queue, facility management.

---

## 7. Phased roadmap

- **Phase 0 — Foundation:** repo, Docker, Postgres+Prisma schema, RTL+Jalali shell, OTP auth. 
- **Phase 1 — MVP board:** browse/filter, calendar, shift detail, doctor signup, apply, admin CRUD,
  basic raw-listing ingest. → *launch to a few hospitals + a doctor Telegram group.*
- **Phase 2 — Self-serve + trust:** hospital posting dashboards, facility/doctor verification,
  in-app messaging, saved searches + alerts (via Bale bot).
- **Phase 3 — Monetization:** pick model (likely **hospitals pay to post** or **commission per
  filled shift** — decide after we see what converts), Iranian payment gateway (Zarinpal/IDPay).
- **Phase 4 — Scale:** full automated aggregation, recommendations, expand beyond GPs to specialists.

---

## 8. Open questions to revisit

- Monetization model (deferred — validate demand first).
- Which specific Telegram/Bale channels to aggregate first?
- Start single-city (Tehran?) to concentrate liquidity, or national from day one?
- Build language: **TypeScript/Next.js** (recommended) vs **.NET** (your existing pipeline)?
```