LinkedIn for Doctors — Verified identities, doctor-only jobs, clinical networking & locum marketplace.
- Project Overview
- Module 1 & 2 — Doctor Professional Network
- Module 3 — Doctor Career Marketplace
- Module 4 — Doctor Availability Exchange
- Module 5 — Platform Operations (Admin CRM)
- Module 6 — Doctor Mobile App
- Backend, Database & API Specification (Spec 02)
- API Global Contract
- System Architecture
- Technology Stack
- Database Design
- API Architecture (FastAPI)
- Project Structure
- Development Setup
- Deployment
- API Documentation
- Security
- Testing
- Troubleshooting
- Roadmap
- Gap Audit Final Report
- Contributing
DocConnect is a verified professional network exclusively for doctors. It provides a LinkedIn-style platform purpose-built for MBBS/MD/MS professionals with features including:
- Verified Identity - NMC + State Medical Council registration checked at sign-up
- Doctor-only Jobs - Hospitals & clinics post full-time, locum & consultant roles
- Clinical Networking - Case discussions, referrals, second opinions among peers
- CME & Compliance - Track continuing-education credits required for license renewal
- Availability Exchange - Structured locum and part-time marketplace
| Module | Description | Section |
|---|---|---|
| Module 1 — Identity, Onboarding & Verification | Doctor registration/verification, hospital onboarding, branches, staff roles | Section 2 |
| Module 2 — Professional Network & Community | LinkedIn-style verified profiles, connections, feed, specialty communities, messaging | Section 2 |
| Module 3 — Career Marketplace & Recruitment | Hospital job posting, one-tap apply, recruitment CRM, AI matching | Section 3 |
| Module 4 — Availability Exchange & Workforce | Doctor availability, urgent shift requirements, doctor matching, shift lifecycle | Section 4 |
| Module 5 — Platform Operations | Admin CRM, moderation, reports, support, audit, analytics, billing | Section 5 |
| Module 6 — Doctor Mobile App | Navigation, onboarding, profile, networking rules, feed safety, jobs, availability, edge cases | Section 6 |
| Actor | Core Responsibility | Access Domain |
|---|---|---|
| Doctor | Professional identity, network, jobs, applications, availability, shifts, messaging | Own data + permitted public/network/career data |
| Hospital Admin | Organization, branches, users, jobs, candidates, applications, urgent workforce | Own hospital/branch data + permitted doctor data |
| HR / Recruiter | Recruitment workflow and candidate operations | Assigned hospital scope |
| Branch User | Branch-scoped recruitment/workforce operations | Assigned branch scope |
| Platform Admin | Verification, moderation, reports, restrictions, communities, jobs, support, audit | Platform-wide, privileged |
| Super Admin | Platform configuration and irreversible/high-risk actions | Highest privileged scope |
┌─────────────────────────────────────────────────────────────┐
│ HYBRID ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ Django 5.0+ │ │ FastAPI │ │
│ │ (Admin, ORM, │◄────────►│ (High-Performance │ │
│ │ Models, Auth) │ │ REST API Layer) │ │
│ └──────────────────┘ └────────────────────────┘ │
│ │
│ • PostgreSQL 16+ with advanced features │
│ • Async support for high-performance APIs │
│ • Automatic OpenAPI/Swagger documentation │
│ • Type safety with Pydantic │
│ • Django Admin for content management │
│ • Django ORM for database operations │
└─────────────────────────────────────────────────────────────┘
git clone https://github.com/pkdubey/docconnect.git && cd docconnect
cp .env.example .env
# Create & activate virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Mac/Linux
# Install dependencies
pip install -r requirements.txt
# Run migrations & seed data
python manage.py makemigrations accounts doctors hospitals jobs availability shifts messaging notifications
python manage.py migrate
python scripts/seed_data.py
# Start FastAPI server
python run.pyURLs after startup:
| Service | URL |
|---|---|
| API Swagger Docs | http://localhost:8000/api/docs |
| API ReDoc | http://localhost:8000/api/redoc |
| Django Admin | http://localhost:8000/admin |
| Health Check | http://localhost:8000/health |
Super Admin Credentials (
| Field | Value |
|---|---|
| Phone | 9999999999 |
| Password | admin123 |
| User Type | ADMIN |
⚠️ NEVER use these credentials in production. Production deployments must use randomly generated credentials passed via--phoneand--passwordCLI args or environment variables. The deployment pipeline must NOT callcreate_admin.pywith default values.
To create a Platform Admin (dev):
python scripts/create_admin.pyTo create a Super Admin (dev):
python scripts/create_admin.py --superTo create a Super Admin (production — always pass explicit credentials):
DJANGO_ENV=production python scripts/create_admin.py --phone <phone> --password <strong_password> --super
LinkedIn-style verified professional network exclusively for doctors — profiles, connections, feed & specialty communities.
┌─────────────────────────────────────────────────────────────────┐
│ DOCTOR PROFILE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ BANNER (gradient / custom image) │ │
│ │ ┌──────┐ Dr. Arjun Sharma │ │
│ │ │ 👨⚕️ │ Cardiologist · 12 yrs exp │ │
│ │ │ Photo│ AIIMS Delhi · Mumbai │ │
│ │ └──────┘ ✅ NMC Verified 🟢 Open to Opportunities │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ About Qualifications Experience │
│ Specialization Clinical Interests Registrations │
│ Connections Posts & Activity Availability Badge │
│ │
└─────────────────────────────────────────────────────────────────┘
Profile Fields:
| Field | Description |
|---|---|
first_name / last_name |
Doctor's full name |
headline |
160-char tagline (e.g. "Cardiologist · AIIMS Delhi · 12 yrs") |
about |
Rich bio / summary |
photo_file_id |
Profile photo stored on AWS S3 |
primary_specialization_id |
Linked to Specialization master table |
clinical_interests |
Array of UUID refs to specializations |
professional_location |
JSONB — city, state, pincode, coordinates |
experience_years |
Decimal (e.g. 12.5) |
open_to_opportunities |
Boolean — shows availability badge |
profile_visibility |
EVERYONE / DOCTORS_ONLY / CONNECTIONS_ONLY |
career_visibility |
VERIFIED_HOSPITALS / SELECTED_HOSPITALS / HIDDEN |
UNVERIFIED ──▶ PENDING ──▶ VERIFIED
│
└──▶ REJECTED (with reason)
│
└──▶ RESUBMISSION (controlled resubmit)
| Step | Action |
|---|---|
| 1 | Doctor submits NMC / State Council registration number |
| 2 | System stores DoctorRegistration with council_id + registration_number |
| 3 | Admin verifies via Django Admin panel |
| 4 | Status moves to VERIFIED — green badge appears on profile |
| 5 | Rejected profiles get verification_rejected_reason |
Supported Councils: NMC, MCI, Maharashtra MC, Delhi MC, Karnataka MC, Tamil Nadu MC (extensible via Council master table)
Doctor Qualifications tracked:
- Degree (MBBS / MD / MS / DM / MCh / DNB / BDS / MDS / BAMS / BHMS)
- Institution name
- Passing year
- Specialization
Doctor Experience tracked:
- Role / Designation
- Hospital name & location
- Start date / End date / Is current
- Description
| Feature | Status | Description |
|---|---|---|
| Doctor Search | ✅ Live | Full-text search by name, specialty, city, experience |
| Profile View | ✅ Live | View any verified doctor's profile |
| Visibility Controls | ✅ Live | Control who sees your profile & career info |
| Open to Opportunities | ✅ Live | Toggle availability badge visible to hospitals |
| Feed / Posts | ✅ Live | Create posts (UPDATE/CASE/ARTICLE/PHOTO), like, comment, reply |
| Connections | ✅ Live | Send / accept / decline / withdraw connection requests |
| Home Summary | ✅ Live | Single API — stats, urgent jobs, suggested doctors, unread counts |
| Hospital Follow | ✅ Live | Doctors can follow hospital pages |
| Endorsements | 🔜 Phase 3 | Peer skill endorsements |
| Feature | Status | Description |
|---|---|---|
| Specialty Groups | ✅ Phase 2 | Cardiology, Neurology, Pediatrics etc. — moderator APIs implemented |
| Case Discussions | ✅ Live | Anonymised clinical case sharing via CASE post type |
| Second Opinions | 🔜 Phase 3 | Request peer review on complex cases |
| CME Events | 🔜 Phase 3 | Continuing Medical Education tracking |
Doctor A ──▶ Start Conversation ──▶ Doctor B
│
Message Types:
• TEXT
• IMAGE
• DOCUMENT
• SHIFT_REQUEST (linked to shift)
• JOB_REFERRAL (linked to job)
API Endpoints — Network Module:
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/auth/register/ |
Register with phone + password |
| POST | /api/v1/auth/login/ |
Login with phone + password |
| POST | /api/v1/auth/send-otp/ |
Send OTP to phone |
| POST | /api/v1/auth/verify-otp/ |
Verify OTP and get tokens |
| POST | /api/v1/auth/refresh/ |
Refresh JWT token |
| POST | /api/v1/auth/logout/ |
Logout / blacklist token |
| POST | /api/v1/auth/password/forgot/ |
Forgot password — send reset challenge |
| POST | /api/v1/auth/password/reset/ |
Reset password with token |
| POST | /api/v1/auth/password/change/ |
Change password (authenticated) |
| GET | /api/v1/auth/sessions/ |
List active sessions / devices |
| DELETE | /api/v1/auth/sessions/{id}/ |
Revoke a specific session |
| POST | /api/v1/auth/sessions/revoke-all/ |
Revoke all sessions |
| DELETE | /api/v1/account/ |
Deactivate / delete account |
| POST | /api/v1/doctors/profile/ |
Create doctor profile |
| GET | /api/v1/doctors/profile/me/ |
Get my profile |
| PATCH | /api/v1/doctors/profile/me/ |
Update my profile |
| GET | /api/v1/doctors/profile/{id}/ |
View any doctor's profile |
| POST | /api/v1/doctors/profile/me/photo/ |
Upload profile photo |
| GET | /api/v1/doctors/search/ |
Search doctors (name/specialty/city/exp) |
| POST | /api/v1/doctors/profile/me/registrations/ |
Add NMC registration |
| GET | /api/v1/doctors/profile/me/registrations/ |
List my registrations |
| POST | /api/v1/doctors/profile/me/qualifications/ |
Add qualification |
| GET | /api/v1/doctors/profile/me/qualifications/ |
List qualifications |
| DELETE | /api/v1/doctors/profile/me/qualifications/{id}/ |
Delete qualification |
| POST | /api/v1/doctors/profile/me/experiences/ |
Add experience |
| GET | /api/v1/doctors/profile/me/experiences/ |
List experiences |
| PATCH | /api/v1/doctors/profile/me/experiences/{id}/ |
Update experience |
| DELETE | /api/v1/doctors/profile/me/experiences/{id}/ |
Delete experience |
| POST | /api/v1/doctors/profile/me/affiliations/ |
Add hospital affiliation |
| GET | /api/v1/doctors/profile/me/affiliations/ |
List affiliations |
| PATCH | /api/v1/doctors/profile/me/affiliations/{id}/ |
Update affiliation |
| DELETE | /api/v1/doctors/profile/me/affiliations/{id}/ |
Delete affiliation |
| GET | /api/v1/doctors/profile/me/verification/ |
Get verification status |
| POST | /api/v1/doctors/profile/me/verification/submit/ |
Submit verification documents |
| POST | /api/v1/doctors/profile/me/verification/resubmit/ |
Resubmit after rejection |
| GET | /api/v1/doctors/profile/me/status/ |
Get professional status |
| PUT | /api/v1/doctors/profile/me/status/ |
Update professional status |
| GET | /api/v1/doctors/profile/me/privacy/ |
Get privacy settings |
| PUT | /api/v1/doctors/profile/me/privacy/ |
Update privacy settings |
| POST | /api/v1/files/upload/ |
Upload file (photo/CV/credential) |
| GET | /api/v1/files/{id}/ |
Get file metadata |
| GET | /api/v1/files/{id}/signed-url/ |
Get expiring signed URL for file |
| DELETE | /api/v1/files/{id}/ |
Delete file |
| GET | /api/v1/search/doctors/ |
Search doctors (advanced filters) |
| GET | /api/v1/search/hospitals/ |
Search hospitals |
| GET | /api/v1/search/jobs/ |
Search jobs |
| GET | /api/v1/search/communities/ |
Search specialty communities |
| GET | /api/v1/search/universal/ |
Universal search (doctors/hospitals/jobs/communities) |
| POST | /api/v1/network/connections/request/ |
Send connection request |
| POST | /api/v1/network/connections/{id}/accept/ |
Accept connection |
| POST | /api/v1/network/connections/{id}/reject/ |
Reject connection |
| DELETE | /api/v1/network/connections/{id}/ |
Remove connection |
| GET | /api/v1/network/connections/ |
List connections / requests |
| POST | /api/v1/network/follow/{user_id}/ |
Follow a user |
| DELETE | /api/v1/network/follow/{user_id}/ |
Unfollow a user |
| POST | /api/v1/network/block/{user_id}/ |
Block a user |
| DELETE | /api/v1/network/block/{user_id}/ |
Unblock a user |
| GET | /api/v1/network/blocked/ |
List blocked users |
| POST | /api/v1/reports/ |
Report a profile/post/comment/job/hospital |
| GET | /api/v1/feed/home/ |
Home summary (stats, urgent jobs, suggested doctors) |
| GET | /api/v1/feed/ |
Paginated feed posts |
| POST | /api/v1/feed/posts/ |
Create a post (text/image/case/article) |
| PATCH | /api/v1/feed/posts/{id}/ |
Edit own post |
| DELETE | /api/v1/feed/posts/{id}/ |
Delete own post |
| POST | /api/v1/feed/posts/{id}/like/ |
Like / unlike a post |
| GET | /api/v1/feed/posts/{id}/comments/ |
Get comments for a post |
| POST | /api/v1/feed/posts/{id}/comments/ |
Add a comment |
| PATCH | /api/v1/feed/comments/{id}/ |
Edit own comment / reply |
| DELETE | /api/v1/feed/comments/{id}/ |
Delete own comment / reply |
| POST | /api/v1/feed/comments/{id}/reply/ |
Reply to a comment |
| GET | /api/v1/communities/ |
List specialty communities |
| GET | /api/v1/communities/{id}/ |
Community detail |
| POST | /api/v1/communities/{id}/join/ |
Join community |
| DELETE | /api/v1/communities/{id}/leave/ |
Leave community |
| GET | /api/v1/communities/{id}/posts/ |
Community posts |
| POST | /api/v1/communities/{id}/posts/ |
Post in community |
| POST | /api/v1/messages/conversations/ |
Start a conversation |
| GET | /api/v1/messages/conversations/ |
List my conversations |
| GET | /api/v1/messages/conversations/{id}/messages/ |
Get messages |
| POST | /api/v1/messages/conversations/{id}/messages/ |
Send a message |
| POST | /api/v1/messages/conversations/{id}/read/ |
Mark conversation as read |
| POST | /api/v1/messages/conversations/{id}/report/ |
Report conversation |
| POST | /api/v1/messages/conversations/{id}/block/ |
Block conversation |
| DELETE | /api/v1/messages/conversations/{id}/block/ |
Unblock conversation |
| POST | /api/v1/devices/ |
Register device for push notifications |
| DELETE | /api/v1/devices/{id}/ |
Revoke device token |
| GET | /api/v1/notifications/ |
List notifications (paginated) |
| GET | /api/v1/notifications/unread-count/ |
Get unread notification count |
| PATCH | /api/v1/notifications/{id}/read/ |
Mark notification as read |
| POST | /api/v1/notifications/read-all/ |
Mark all notifications as read |
| GET | /api/v1/notification-preferences/ |
Get per-event notification preferences |
| PUT | /api/v1/notification-preferences/ |
Update notification preferences |
Hospital-side job posting + doctor-side one-tap apply + full recruitment CRM pipeline + AI matching (Phase 2).
CRM Purpose: The hospital CRM is the recruitment and workforce operating console. It lets verified healthcare institutions discover doctors, publish jobs, manage applicants and source urgent/temporary coverage.
CRM Main Menu:
| Menu | Functions |
|---|---|
| Dashboard | Active jobs, new applicants, shortlisted doctors, interviews, urgent requirements |
| Hospital Profile | Profile, branches, departments, facilities, verification |
| Users & Roles | Owner/Admin, HR/Recruiter, branch-level access |
| Jobs | Create/edit/publish/close, applicants, status management |
| Candidates | Search doctors, filters, profile view, shortlist, notes, communication |
| Applications | Pipeline, interview, offer/hire/reject/withdraw |
| Availability Exchange | Urgent requirements, matched doctors, requests, confirmations |
| Messages | Doctor/hospital professional conversations |
| Notifications | Recruitment and workforce alerts |
| Reports/Analytics | Hiring funnel, jobs, candidate activity, workforce metrics |
| Billing | Plan, limits, invoices, subscription — if activated |
| Settings | Privacy, notification preferences, organization settings |
CRM Permission Matrix:
| Action | Hospital Admin | HR/Recruiter | Branch User |
|---|---|---|---|
| Edit organization profile | Yes | Configurable | No/limited |
| Manage users | Yes | No | No |
| Create jobs | Yes | Yes | Configurable |
| View candidates | Yes | Yes | Assigned/branch scope |
| Change application status | Yes | Yes | Configurable |
| Create urgent requirement | Yes | Yes | Configurable |
| Billing | Yes | No | No |
| Audit logs | Yes | Limited | No |
Exact permissions must be finalized before backend RBAC implementation.
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Admin │──▶│ OTP │──▶│ Hospital │──▶│ Branches │──▶│ Verified │
│ Phone │ │ Verify │ │ Details │ │ Depts │ │ Hospital │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
Hospital Profile Fields:
| Field | Description |
|---|---|
name |
Hospital / Clinic name |
type |
HOSPITAL / CLINIC / NURSING_HOME / MEDICAL_COLLEGE |
location |
JSONB — address, city, state, pincode, coordinates |
bed_count |
Number of beds |
verification_status |
UNVERIFIED → PENDING → VERIFIED |
logo_file_id |
Logo stored on AWS S3 |
Hospital Structure:
Hospital
└── Branches (multiple locations)
└── Departments (Cardiology, ICU, OPD...)
└── Staff (ADMIN / HR / RECRUITER roles)
Job Creation Fields:
| Field | Description |
|---|---|
title |
Job title / role |
department_id |
Linked department |
qualification_ids |
Required qualifications |
specialty_id |
Required specialization |
experience_min_years |
Minimum experience required |
location |
JSONB — city, state, pincode, coordinates |
salary_min / salary_max |
Salary range |
salary_visibility |
PUBLIC / ON_REQUEST / HIDDEN |
shift_type |
DAY / NIGHT / ROTATIONAL / FLEXIBLE |
joining_requirement |
Joining date / notice period |
job_type |
FULL_TIME / PART_TIME / VISITING / LOCUM / CONTRACT |
description |
Full job description |
positions |
Number of openings |
is_urgent |
Boolean — shows urgent badge |
closing_date |
Application deadline / auto-expire date |
status |
DRAFT → PUBLISHED → CLOSED / EXPIRED / FILLED |
Hospital HR can search and filter doctors using:
- Qualification
- Specialization
- Experience (years)
- Location / city / state
- Verified doctor only
- Professional status
- Available now
- Locum availability
- Visiting consultant availability
- Distance / radius (km)
| Action | Description |
|---|---|
| View profile | View allowed professional profile fields per privacy settings |
| Shortlist | Add doctor to shortlist for a job |
| Reject | Mark candidate as not suitable |
| Move pipeline | Move through APPLIED → SHORTLISTED → INTERVIEW → OFFERED → HIRED |
| Send message | Send professional message via messaging module |
| Invite to opportunity | Invite doctor to apply for a specific job |
| Add internal notes | Add HR-only notes on candidate (stored in application metadata) |
| Record interview outcome | Update interview result (PASS/FAIL/PENDING) |
| Issue offer / mark hired | Send offer letter details, mark as HIRED on acceptance |
APPLIED
│
▼
PROFILE_VIEWED ◀── Hospital HR views doctor profile
│
▼
SHORTLISTED ◀── Added to shortlist
│
▼
INTERVIEW ◀── Interview scheduled
│
├──▶ OFFERED ◀── Offer letter sent
│ │
│ └──▶ HIRED ◀── Doctor accepts offer
│
└──▶ REJECTED
(Doctor can WITHDRAW at any stage)
Every status change is logged in ApplicationHistory with:
from_status/to_statuschanged_by(user who made the change)notes(optional reason)
1. Hospital creates ShiftRequirement
(specialty, qualification, date, start/end time,
location, compensation, doctors_required, urgency, notes)
│
▼
2. System finds eligible available doctors
(matches availability type, date, location, compensation)
│
▼
3. HR reviews matching candidates list
│
▼
4. Hospital sends ShiftRequest to selected doctor
│
▼
5. Doctor accepts / declines
│
▼
6. Hospital confirms (CONFIRMED_BY_HOSPITAL)
│
▼
7. Shift completed or cancelled
(all state changes timestamped and auditable)
Important: Per the V2 specification, matching weights are NOT hardcoded. They are product-approved configuration values stored in
matching_configstable. The factors below are the V1 matching inputs — weights must be approved before production use.
┌─────────────────────────────────────────────────────────────┐
│ MATCHING ENGINE │
├─────────────────────────────────────────────────────────────┤
│ │
│ V1 Matching Factors (weights = configurable): │
│ • verification status │
│ • specialization match │
│ • qualification match │
│ • experience (years) │
│ • date availability │
│ • time availability │
│ • location / distance │
│ • preferred radius │
│ • job type preference │
│ • professional status │
│ │
│ Output: match_score + score_components[] + reasons[] │
│ Config: versioned via matching_configs table │
│ │
└─────────────────────────────────────────────────────────────┘
API Endpoints — Career Marketplace:
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/hospitals/register/ |
Register new hospital |
| GET | /api/v1/hospitals/me/ |
Get my hospital profile |
| PATCH | /api/v1/hospitals/me/ |
Update hospital profile |
| POST | /api/v1/hospitals/me/verification/submit/ |
Submit hospital verification documents |
| GET | /api/v1/hospitals/me/verification/ |
Get hospital verification status |
| POST | /api/v1/hospitals/me/branches/ |
Add hospital branch |
| GET | /api/v1/hospitals/me/branches/ |
List branches |
| PATCH | /api/v1/hospitals/me/branches/{id}/ |
Update branch |
| DELETE | /api/v1/hospitals/me/branches/{id}/ |
Deactivate branch |
| POST | /api/v1/hospitals/me/departments/ |
Add department |
| GET | /api/v1/hospitals/me/departments/ |
List departments |
| POST | /api/v1/hospitals/me/users/ |
Add hospital user (HR/Recruiter/Branch User) |
| GET | /api/v1/hospitals/me/users/ |
List hospital users |
| PATCH | /api/v1/hospitals/me/users/{id}/ |
Update user role/branch/status |
| DELETE | /api/v1/hospitals/me/users/{id}/ |
Revoke user membership |
| POST | /api/v1/hospitals/me/invite-user/ |
Invite HR / Recruiter |
| GET | /api/v1/hospitals/me/staff/ |
List hospital staff |
| POST | /api/v1/hospitals/me/upload-logo/ |
Upload hospital logo |
| GET | /api/v1/hospitals/{id}/ |
View public hospital profile |
| POST | /api/v1/jobs/ |
Create job posting (auto-published) |
| PATCH | /api/v1/jobs/{id}/ |
Update job posting |
| POST | /api/v1/jobs/{id}/publish/ |
Publish a draft job |
| POST | /api/v1/jobs/{id}/close/ |
Close a job posting |
| GET | /api/v1/jobs/ |
List jobs (specialty/city/type/search/urgent filters) |
| GET | /api/v1/jobs/{id}/ |
Get job details |
| POST | /api/v1/jobs/{id}/save/ |
Save a job |
| DELETE | /api/v1/jobs/{id}/save/ |
Unsave a job |
| GET | /api/v1/doctors/me/saved-jobs/ |
List saved jobs |
| GET | /api/v1/jobs/my-applications/ |
Doctor's applications (with status filter) |
| POST | /api/v1/jobs/{id}/apply/ |
One-tap apply |
| POST | /api/v1/jobs/{id}/withdraw/ |
Withdraw application |
| GET | /api/v1/jobs/{id}/applications/ |
Hospital — view applicants |
| PATCH | /api/v1/jobs/applications/{id}/status/ |
Update application status (logs history) |
| POST | /api/v1/applications/{id}/notes/ |
Add internal note to application |
| GET | /api/v1/applications/{id}/notes/ |
List application notes |
| POST | /api/v1/applications/{id}/interview/ |
Schedule interview |
| PATCH | /api/v1/applications/{id}/interview/{interview_id}/ |
Update interview outcome |
| POST | /api/v1/applications/{id}/offer/ |
Send offer |
| POST | /api/v1/applications/{id}/invite/ |
Invite doctor to apply |
| GET | /api/v1/jobs/{id}/matches/ |
Get matched doctors for a job |
| GET | /api/v1/doctors/me/job-recommendations/ |
Get recommended jobs for doctor |
| GET | /api/v1/masters/specialties/ |
List specialties |
| GET | /api/v1/masters/qualifications/ |
List qualifications |
| GET | /api/v1/masters/job-types/ |
List job types |
| GET | /api/v1/masters/shift-types/ |
List shift types |
Structured locum & part-time marketplace — doctors post availability, hospitals post urgent requirements, system matches & manages full shift lifecycle.
┌─────────────────────────────────────────────────────────────┐
│ DOCTOR AVAILABILITY POSTING │
├─────────────────────────────────────────────────────────────┤
│ │
│ Dr. Priya Mehta — Anesthesiologist │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Type: LOCUM │ │
│ │ From: 15 Aug 2025 → 30 Aug 2025 │ │
│ │ Location: Mumbai, Maharashtra (50 km radius) │ │
│ │ Min Pay: ₹8,000 / shift │ │
│ │ Slots: Mon 09:00–17:00 | Wed 09:00–17:00 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Availability Types:
| Type | Description |
|---|---|
LOCUM |
Short-term fill-in shifts |
VISITING |
Regular visiting consultant slots |
TEMPORARY |
Fixed-term contract (weeks/months) |
PART_TIME |
Ongoing part-time engagement |
Availability Slots — each availability can have multiple time slots:
slot_date— specific datestart_time/end_time— time windowis_booked— auto-updated when shift is confirmed
┌─────────────────────────────────────────────────────────────┐
│ HOSPITAL SHIFT REQUIREMENT │
├─────────────────────────────────────────────────────────────┤
│ │
│ Apollo Hospital, Mumbai — ICU Department │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Specialty: Anesthesiology │ │
│ │ Date: 18 Aug 2025 │ │
│ │ Time: 08:00 – 20:00 (12 hr shift) │ │
│ │ Doctors: 2 required │ │
│ │ Pay: ₹12,000 / shift │ │
│ │ Urgency: 🔴 IMMEDIATE │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Urgency Levels:
| Level | Description |
|---|---|
NORMAL |
Standard requirement, planned in advance |
URGENT |
Required within 24–48 hours |
IMMEDIATE |
Required today / emergency fill |
Requirement Status Flow:
OPEN ──▶ FILLED
│
├──▶ CANCELLED
└──▶ EXPIRED (auto after requirement_date passes)
┌─────────────────────────────────────────────────────────────┐
│ MATCHING ALGORITHM │
├─────────────────────────────────────────────────────────────┤
│ │
│ Hospital posts ShiftRequirement │
│ │ │
│ ▼ │
│ System filters DoctorAvailability where: │
│ • availability_type matches requirement type │
│ • available_from ≤ requirement_date ≤ available_until │
│ • preferred_location within preferred_radius_km │
│ • minimum_compensation ≤ requirement compensation │
│ • slot exists for requirement date & time │
│ │ │
│ ▼ │
│ Matched doctors list returned to hospital │
│ Hospital sends ShiftRequest to selected doctors │
│ │
└─────────────────────────────────────────────────────────────┘
Hospital creates ShiftRequirement (status: OPEN)
│
▼
Hospital sends ShiftRequest to matched doctor
│ (status: REQUESTED)
▼
Doctor responds:
├──▶ ACCEPTED_BY_DOCTOR
│ │
│ ▼
│ Hospital confirms:
│ ├──▶ CONFIRMED_BY_HOSPITAL
│ │ │
│ │ ▼
│ │ Shift completed:
│ │ └──▶ COMPLETED
│ │
│ └──▶ (Hospital ignores → doctor can cancel)
│
└──▶ DECLINED_BY_DOCTOR
Either party can CANCEL at any stage
Shift Request Status Reference:
| Status | Triggered By | Description |
|---|---|---|
REQUESTED |
Hospital | Hospital sends request to doctor |
ACCEPTED_BY_DOCTOR |
Doctor | Doctor accepts the shift |
DECLINED_BY_DOCTOR |
Doctor | Doctor declines |
CONFIRMED_BY_HOSPITAL |
Hospital | Hospital confirms after doctor accepts |
COMPLETED |
Hospital | Shift successfully completed |
CANCELLED |
Either | Cancelled before completion |
API Endpoints — Availability Exchange:
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/availability/ |
Doctor posts availability (with slots) |
| GET | /api/v1/availability/me/ |
List my availabilities |
| PATCH | /api/v1/availability/{id}/ |
Update availability |
| DELETE | /api/v1/availability/{id}/ |
Deactivate availability |
| GET | /api/v1/availability/{id}/slots/ |
List slots for an availability |
| POST | /api/v1/availability/{id}/slots/ |
Add slot to availability |
| PATCH | /api/v1/availability/slots/{slot_id}/ |
Update a slot |
| DELETE | /api/v1/availability/slots/{slot_id}/ |
Delete a slot |
| GET | /api/v1/availability/preferences/ |
Get availability preferences |
| PUT | /api/v1/availability/preferences/ |
Update availability preferences |
| POST | /api/v1/shifts/requirements/ |
Hospital posts shift requirement |
| GET | /api/v1/shifts/requirements/ |
List open shift requirements (urgency/city/specialty filters) |
| PATCH | /api/v1/shifts/requirements/{id}/ |
Update shift requirement |
| GET | /api/v1/shifts/requirements/mine/ |
Hospital's own requirements |
| POST | /api/v1/shifts/requirements/{id}/match/ |
Get matched doctors for a requirement |
| GET | /api/v1/shifts/requirements/{id}/matched-doctors/ |
Get matched doctors for a requirement |
| POST | /api/v1/shifts/requirements/{id}/request/ |
Doctor requests a shift |
| PATCH | /api/v1/shifts/requests/{id}/respond/ |
Doctor accepts / declines |
| PATCH | /api/v1/shifts/requests/{id}/confirm/ |
Hospital confirms shift |
| PATCH | /api/v1/shifts/requests/{id}/complete/ |
Hospital marks shift completed |
| PATCH | /api/v1/shifts/requests/{id}/cancel/ |
Cancel shift request (either party) |
| GET | /api/v1/shifts/requests/{id}/history/ |
Shift request state history |
| GET | /api/v1/shifts/requests/mine/ |
Doctor's shift requests |
Admin CRM for verification, moderation, reports, restrictions, support, audit & analytics.
| Module | Admin Capabilities |
|---|---|
| Overview | Doctors, hospitals, verified accounts, jobs, applications, urgent requirements, reports, active users |
| Doctor Verification | Queue, document review, approve/reject with reason, resubmission control, waiting time |
| Hospital Verification | Organization review, documents, approve/reject, branches |
| User Management | Search, view, restrict, suspend, restore, deactivate — reason required, audit logged |
| Moderation | Posts/comments/reports — patient privacy concerns, misinformation flags, harassment, reason required |
| Communities | Create/edit/archive specialty communities, manage moderators (✅ Phase 2 implemented) |
| Jobs | Monitor jobs, remove policy-violating jobs, investigate suspicious activity |
| Reports | Case queue, severity, evidence, resolution, escalation |
| Support | User tickets/issues and internal admin notes |
| Audit | Sensitive actions, verification decisions, restrictions, content removals — immutable log |
| Billing | Plans, entitlements, subscriptions, invoices/refunds (feature-flagged) |
| Settings | Specialties, qualifications, status values, configurable matching weights |
| Step | Action |
|---|---|
| 1 | Receive submission — doctor/hospital submits registration details & documents |
| 2 | Validate required fields and documents are present |
| 3 | Check registration information using the approved verification process |
| 4 | Approve or reject with mandatory reason |
| 5 | Record reviewer, timestamp and evidence in AuditLog |
| 6 | Notify user of outcome via in-app + push notification |
| 7 | Allow controlled resubmission for rejected cases |
PATIENT_PRIVACY_CONCERNPOTENTIAL_MEDICAL_MISINFORMATIONSPAMHARASSMENTCOPYRIGHT_CONCERNFAKE_DOCTOR_FALSE_CREDENTIALSPROFESSIONAL_MISCONDUCT_CONCERNOTHER_POLICY_VIOLATION
- Two-step confirmation for irreversible actions (deactivate/delete)
- Reason required for all rejection / suspension / removal actions (400 if missing)
- Every privileged action writes an immutable
AuditLogentry (performed_by,target_type,target_id,metadata) - Role check on every admin endpoint — 403 if
user_type != ADMIN - Role separation between reviewer and super-admin for high-risk actions
- Private access to credential documents — signed URLs only, never public
- Export controls for sensitive data
- Search and filters across all case queues
- Internal support notes (
is_internal=True) are hidden from end users - Report severity levels:
LOW/MEDIUM/HIGH/CRITICAL - Matching config activation deactivates all other versions atomically
SUBMITTED ──▶ UNDER_REVIEW ──▶ ACTIONED
│
├──▶ DISMISSED
└──▶ ESCALATED
Report Model Fields:
| Field | Description |
|---|---|
reporter |
User who filed the report |
target_type |
PROFILE / POST / COMMENT / JOB / HOSPITAL |
target_id |
UUID of the reported object |
reason |
One of the 8 reason codes above |
severity |
LOW / MEDIUM / HIGH / CRITICAL |
status |
SUBMITTED → UNDER_REVIEW → ACTIONED / DISMISSED / ESCALATED |
reviewed_by |
Admin who actioned the report |
resolution_notes |
Admin notes on resolution |
resolved_at |
Timestamp of resolution |
| Field | Description |
|---|---|
user |
Ticket owner |
subject / description |
Ticket content |
category |
GENERAL / VERIFICATION / BILLING / TECHNICAL |
status |
OPEN → IN_PROGRESS → RESOLVED / CLOSED |
assigned_to |
Admin assigned to ticket |
resolved_at |
Timestamp of resolution |
messages |
Thread of SupportMessage records |
is_internal |
Admin-only internal notes hidden from user |
MatchingConfig
├── version (e.g. "v1", "v2") — unique
├── weights JSONB — {"specialization_match": 0.3, "experience": 0.2, ...}
├── is_active only one config active at a time
├── approved_by admin who created/approved
└── description optional notes
| Metric | Description |
|---|---|
| Doctor verification turnaround | Avg hours from submission to VERIFIED |
| Hospital verification turnaround | Avg hours from submission to VERIFIED |
| Verified doctors by specialty / location | Top 10 specialties with verified doctor counts |
| Active hospitals | Verified hospital count |
| Jobs posted / filled | Total, published, filled, urgent |
| Application funnel | Count per status: APPLIED → SHORTLISTED → INTERVIEW → OFFERED → HIRED |
| Urgent requirements filled | Count of IMMEDIATE/URGENT shift requirements with status FILLED |
| Shift acceptance rate | % of shift requests accepted by doctors |
| Shift completion rate | % of shift requests completed |
| Report resolution time | Avg hours from report submission to resolution |
| Network growth & active engagement | Total connections, accepted connections, active users |
| Event Code | Trigger | Recipients | Default Channels |
|---|---|---|---|
CONNECTION_REQUEST |
New connection request | Target doctor | In-app + push |
CONNECTION_ACCEPTED |
Request accepted | Requester | In-app + push |
POST_INTERACTION |
Comment/reaction | Post owner | In-app + push |
NEW_MESSAGE |
New message | Recipient | In-app + push |
RECOMMENDED_JOB |
New/relevant job | Doctor | In-app + push |
APPLICATION_UPDATE |
Application status changes | Doctor | In-app + push |
INTERVIEW_UPDATE |
Interview created/updated | Doctor + HR | In-app + push |
SHIFT_REQUEST |
Hospital sends shift request | Doctor | In-app + push |
SHIFT_ACCEPTED |
Doctor accepts | Hospital/HR | In-app + push |
SHIFT_CONFIRMED |
Hospital confirms | Doctor | In-app + push |
SHIFT_CANCELLED |
Shift cancelled | Affected parties | In-app + push |
VERIFICATION_UPDATE |
Verification status changes | Account owner | In-app + push |
REPORT_UPDATE |
Report resolution | Reporter (policy-based) | In-app |
SUPPORT_UPDATE |
Support ticket response | Ticket requester | In-app + push/email |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/admin/dashboard/ |
Platform overview metrics (includes open reports & tickets) |
| GET | /api/v1/admin/doctors/verification-queue/ |
Doctor verification queue (includes waiting_hours) |
| GET | /api/v1/admin/doctors/verification-cases/{id}/ |
Verification case detail |
| POST | /api/v1/admin/doctors/verification-cases/{id}/approve/ |
Approve doctor verification — writes AuditLog |
| POST | /api/v1/admin/doctors/verification-cases/{id}/reject/ |
Reject doctor verification — reason required, writes AuditLog |
| POST | /api/v1/admin/doctors/verification-cases/{id}/resubmit/ |
Allow resubmission — writes AuditLog |
| GET | /api/v1/admin/hospitals/verification-queue/ |
Hospital verification queue (includes waiting_hours) |
| POST | /api/v1/admin/hospitals/verification-cases/{id}/approve/ |
Approve hospital verification — writes AuditLog |
| POST | /api/v1/admin/hospitals/verification-cases/{id}/reject/ |
Reject hospital verification — reason required, writes AuditLog |
| GET | /api/v1/admin/users/ |
List all users (filter: user_type, status, search) |
| POST | /api/v1/admin/users/{id}/restrict/ |
Restrict user — reason required, writes AuditLog |
| POST | /api/v1/admin/users/{id}/suspend/ |
Suspend user — reason required, writes AuditLog |
| POST | /api/v1/admin/users/{id}/restore/ |
Restore user — reason required, writes AuditLog |
| POST | /api/v1/admin/users/{id}/deactivate/ |
Deactivate user — reason required, writes AuditLog |
| GET | /api/v1/admin/reports/ |
Reports queue (filter: status, severity, target_type) |
| GET | /api/v1/admin/reports/{id}/ |
Report detail |
| POST | /api/v1/admin/reports/{id}/action/ |
Action a report — writes AuditLog |
| POST | /api/v1/admin/reports/{id}/dismiss/ |
Dismiss a report — writes AuditLog |
| POST | /api/v1/admin/reports/{id}/escalate/ |
Escalate a report — writes AuditLog |
| POST | /api/v1/admin/posts/{id}/moderate/ |
Moderate a post — reason required, writes AuditLog |
| POST | /api/v1/admin/jobs/{id}/moderate/ |
Moderate a job — reason required, writes AuditLog |
| POST | /api/v1/admin/communities/ |
Create specialty community — writes AuditLog |
| PATCH | /api/v1/admin/communities/{id}/ |
Update community — writes AuditLog |
| POST | /api/v1/admin/communities/{id}/archive/ |
Archive community — writes AuditLog |
| GET | /api/v1/admin/audit-logs/ |
Audit log records (filter: action, target_type) |
| GET | /api/v1/admin/analytics/overview/ |
Full operational analytics (turnaround, funnel, shift rates, resolution time) |
| GET | /api/v1/admin/support/tickets/ |
Admin: list all tickets (filter: status, category) |
| PATCH | /api/v1/admin/support/tickets/{id}/ |
Update ticket status (admin) |
| POST | /api/v1/admin/support/tickets/{id}/resolve/ |
Resolve ticket |
| POST | /api/v1/admin/support/tickets/{id}/messages/ |
Admin reply or internal note on ticket — is_internal flag supported |
| GET | /api/v1/admin/matching-configs/ |
List all matching weight configs |
| POST | /api/v1/admin/matching-configs/ |
Create new matching config version |
| POST | /api/v1/admin/matching-configs/{id}/activate/ |
Activate a matching config (deactivates others) |
| POST | /api/v1/admin/settings/specialties/ |
Create specialty (admin) |
| PATCH | /api/v1/admin/settings/specialties/{id}/ |
Update specialty (admin) |
| POST | /api/v1/admin/settings/qualifications/ |
Create qualification (admin) |
| POST | /api/v1/support/tickets/ |
Create support ticket |
| GET | /api/v1/support/tickets/ |
List my support tickets (filter: status) |
| GET | /api/v1/support/tickets/{id}/ |
Ticket detail + messages (internal notes hidden) |
| POST | /api/v1/support/tickets/{id}/messages/ |
Add message to ticket |
| GET | /api/v1/billing/plans/ |
List billing plans |
| GET | /api/v1/billing/subscription/ |
Current hospital subscription |
| POST | /api/v1/billing/subscription/ |
Subscribe to a plan |
| PATCH | /api/v1/billing/subscription/ |
Update/cancel subscription |
| GET | /api/v1/billing/invoices/ |
List invoices |
| GET | /api/v1/billing/invoices/{id}/ |
Invoice detail |
| POST | /api/v1/billing/webhooks/{provider}/ |
Payment webhook (idempotent) |
| POST | /api/v1/admin/billing/refunds/ |
Issue refund |
Android-native doctor app — verified professional identity, networking, jobs, availability exchange & clinical community.
| Area | Screens |
|---|---|
| Onboarding | Splash, login, register, OTP/verification, credential submission, verification status |
| Home | Professional feed, recommended jobs, recommended doctors/communities, notifications |
| Network | Doctor search, filters, profile, connection requests, connections, following |
| Jobs | Recommended, nearby, urgent, saved, applied; job detail; apply; application tracker |
| Availability | Status, availability calendar, time slots, preferences, current/previous availability |
| Communities | Specialty list, community feed, posts, discussions |
| Messages | Conversation list, chat, attachments, professional context |
| Profile | Professional identity, experience, hospitals, qualifications, interests, privacy |
| Settings | Privacy, notifications, blocked users, account/security, support, logout |
1. Create account (phone + password or OTP)
│
▼
2. Complete professional identity
(name, photo, headline, specialization, experience, location, languages)
│
▼
3. Enter medical registration
(registration number, medical council, registration year, documents)
│
▼
4. Submit verification
│
▼
5. Show verification state:
├─► PENDING — awaiting admin review
├─► VERIFIED — green badge unlocked
└─► REJECTED — reason shown + resubmission path
│
▼
6. Until VERIFIED: restrict actions that require verified status
(applying to jobs, posting availability, messaging hospitals)
Verification-gated actions:
| Action | Requires Verified |
|---|---|
| Apply to jobs | Yes |
| Post availability | Yes |
| Message hospitals | Yes |
| Browse feed / posts | No |
| Search doctors | No |
| Send connection requests | No |
| Field | Description |
|---|---|
first_name / last_name |
Doctor's full name |
photo_file_id |
Profile photo (S3) |
headline |
160-char tagline |
about |
Rich bio / summary |
primary_specialization_id |
Primary specialty |
clinical_interests |
Secondary specialties (array) |
experience_years |
Total experience (decimal) |
qualifications |
Degree, institution, year |
experiences |
Role, hospital, dates, is_current |
affiliations |
Current/previous hospital affiliations (JSONB) |
languages |
Spoken languages (e.g. ["English", "Hindi"]) |
career_preferences |
Job type, location, salary preferences (JSONB) |
professional_location |
City, state, pincode, coordinates |
open_to_opportunities |
Availability badge for hospitals |
profile_visibility |
EVERYONE / DOCTORS_ONLY / CONNECTIONS_ONLY |
career_visibility |
VERIFIED_HOSPITALS / SELECTED_HOSPITALS / HIDDEN |
verification_status |
UNVERIFIED / PENDING / VERIFIED / REJECTED |
| Relationship | Messaging Allowed | Profile Data Visible |
|---|---|---|
| No relationship | No (doctors only after connection) | Name, headline, specialty, location per profile_visibility |
| Connection request sent/received | No | Same as above |
| Connected | Yes | Full professional profile |
| Blocked | No | Hidden |
Messaging is only allowed between connected doctors. Hospitals can message doctors directly via the hospital CRM (professional context only).
- Post category must be selected from:
UPDATE/CASE/ARTICLE/PHOTO CASEposts requirepatient_privacy_confirmed = truebefore submission- PII auto-detection blocks posts containing: phone numbers, Aadhaar (12-digit), email addresses, patient IDs (PT\d+, IPD\d+)
pii_flagged = trueis set server-side if PII patterns are detected in non-CASE posts (flagged for moderation)- Report and moderation controls available on every post and comment
- Feed remains professional — generic social content is subject to moderation
PII patterns blocked/flagged:
| Pattern | Example |
|---|---|
| Indian mobile number | 9876543210 |
| Aadhaar number | 123456789012 |
| Email address | patient@gmail.com |
| Patient ID | PT001234, IPD/5678 |
Browse tabs:
Recommended ── match_score + match_factors shown per job
Nearby ── filtered by professional_location
Urgent ── is_urgent = true
Saved ── doctor's saved_jobs list
Applied ── my-applications with status filter
Job Detail:
└─ match_score (0–100) + match_factors breakdown
└─ salary visibility: PUBLIC / ON_REQUEST / HIDDEN
└─ what information is shared on apply (profile fields)
Apply:
└─ One-tap apply uses professional profile
└─ Optional CV attachment (file_id)
└─ Confirmation screen shows exactly what is shared
Application Tracker:
APPLIED → PROFILE_VIEWED → SHORTLISTED → INTERVIEW → OFFERED → HIRED
└→ REJECTED
Doctor can WITHDRAW at any stage before HIRED/REJECTED
Match Score Factors (V1):
| Factor | Weight |
|---|---|
| Specialization match | 40 pts |
| Experience ≥ required | 30 pts |
| Open to opportunities | 15 pts |
| Verified doctor | 15 pts |
Doctor sets availability:
Type: LOCUM / VISITING / TEMPORARY / PART_TIME
Dates: available_from → available_until
Location: city + preferred_radius_km
Min compensation: private (never shown publicly)
Slots: date + start_time + end_time
Calendar rules:
└─ Adding a slot checks for overlapping ACCEPTED/CONFIRMED shifts → 409 if conflict
└─ Deactivating availability blocked if pending/confirmed shift requests exist
Shift request flow:
Hospital sends request → Doctor accepts/declines → Hospital confirms → Completed
Doctor can cancel before COMPLETED
Hospital can cancel at any stage
| Edge Case | Behaviour |
|---|---|
| Verification rejected | Show rejection reason + resubmit button; restrict verified-only actions |
| Expired / invalid credential | Admin rejects with reason; doctor must resubmit updated documents |
| Hospital affiliation changed | Doctor updates affiliation via PATCH /api/v1/doctors/profile/me/affiliations/{id}/ |
| Doctor changes status while application active | Application remains; doctor can withdraw; hospital sees updated status |
| Doctor deletes availability with active shift request | 409 — must cancel shift requests first |
| Overlapping shifts | 409 on slot creation and shift request if accepted/confirmed shift overlaps |
| Shift cancelled by hospital | ShiftRequest status → CANCELLED; doctor's slot is_booked reset; notification sent |
| Doctor blocks hospital/user | Blocked user hidden from feed/search; messaging disabled |
| Message/report abuse | Report submitted via POST /api/v1/reports/; conversation block via messaging endpoints |
| Document upload failure | UPLOAD_INVALID (400) with file type/size reason; retry allowed |
| Account deletion | User status → DELETED; active applications → WITHDRAWN; availabilities deactivated; pending shift requests → CANCELLED |
Source of truth for all backend decisions — entities, state machines, API groups, matching engine, privacy enforcement, security and API contract standards.
Build a role-based platform API supporting Doctor, Hospital/HR and Platform Admin workflows. The backend is the authoritative source of truth for verification, privacy, matching, application, availability and shift states. All privacy rules are enforced at the query/serialization layer — hiding a field only in the UI is insufficient.
| Django App | Models / Tables |
|---|---|
accounts |
users, otp_challenges, refresh_sessions |
doctors |
doctor_profiles, doctor_registrations, doctor_qualifications, doctor_experiences, doctor_affiliations, doctor_connections, follows, blocks, doctor_posts, post_likes, post_comments |
hospitals |
hospitals, hospital_branches, hospital_departments, hospital_users, hospital_follows |
jobs |
job_posts, job_applications, application_histories, job_saves |
availability |
doctor_availabilities, availability_slots |
shifts |
shift_requirements, shift_requests, shift_status_history |
messaging |
conversations, conversation_participants, messages |
notifications |
notifications, device_tokens, notification_preferences |
core |
specializations, qualifications, councils, communities, community_members, audit_logs, reports, report_evidence, support_tickets, support_messages, matching_configs, plans, subscriptions, entitlements, invoices, payments |
| Object | States |
|---|---|
| Doctor verification | UNVERIFIED → PENDING → VERIFIED / REJECTED → RESUBMISSION |
| Hospital verification | UNVERIFIED → PENDING → VERIFIED / REJECTED → RESUBMISSION |
| Job application | APPLIED → PROFILE_VIEWED → SHORTLISTED → INTERVIEW → OFFERED → HIRED / REJECTED / WITHDRAWN |
| Shift request | REQUESTED → ACCEPTED_BY_DOCTOR → CONFIRMED_BY_HOSPITAL → COMPLETED / CANCELLED |
| Professional status | AVAILABLE_NOW / FULL_TIME / LOCUM / VISITING / PART_TIME / NOT_LOOKING |
| Report | SUBMITTED → UNDER_REVIEW → ACTIONED / DISMISSED / ESCALATED |
| Subscription | TRIALING → ACTIVE → PAST_DUE → CANCELLED / EXPIRED |
| Invoice | DRAFT → OPEN → PAID / VOID / UNCOLLECTIBLE |
| Payment | PENDING → CAPTURED / FAILED → REFUNDED / PARTIALLY_REFUNDED |
| API Domain | Router File | Minimum Responsibility |
|---|---|---|
| Auth | auth.py |
Register, login, OTP, refresh, logout, password reset, session/device management |
| Doctor | doctors.py |
Profile CRUD, credentials, documents, verification, experiences, affiliations, professional status |
| Hospital | hospitals.py |
Profile, branches, departments, verification, hospital users/roles |
| Discovery | search.py |
Doctor search, hospital search, job search, community search, filters, pagination |
| Network | network.py |
Connection request/accept/reject/remove, follow/unfollow, block/unblock |
| Feed | feed.py |
Create/edit/delete post, comments, reactions, feed retrieval, PII detection, report |
| Community | communities.py |
List, join/leave, posts, moderation |
| Jobs | jobs.py |
Create/publish/close, save, apply, application status, candidate shortlist |
| Matching | jobs.py |
Job→doctor matches and doctor→job recommendations with transparent score breakdown |
| Availability | availability.py |
Calendar/slots, preferences, matching, urgent requirements |
| Shift | shifts.py |
Request, accept/decline, confirm, complete, cancel, status history |
| Messaging | messaging.py |
Conversations, messages, attachments, read receipts, block/report |
| Notifications | notifications.py |
List, read, preferences, push token registration |
| Admin | admin.py |
Verification queues, moderation, reports, user restrictions, communities, jobs, audit logs |
| Billing | billing.py |
Plans, subscriptions, entitlements, invoices, payment webhooks |
| Support | support.py |
Tickets, messages, internal notes |
| Masters | masters.py |
Specialties, qualifications, councils, job/shift types |
| Files | files.py |
Upload, signed URLs, delete |
Weights are not hardcoded. They are product-approved values stored in the matching_configs table (MatchingConfig model). The backend must not invent production weights without product approval.
Matching Factors (weights = configurable via matching_configs):
• verification_status • specialization_match
• qualification_match • experience_years
• date_availability • time_availability
• location_distance • preferred_radius_km
• job_type_preference • professional_status
Output per match:
match_score: 0–100
score_components: [{factor, points, max_points}]
reasons: ["Specialization match", "Experience match", ...]
Score components are stored/returned so the UI can explain why a doctor/job matched.
| Rule | Implementation |
|---|---|
| Phone & personal email never public | Excluded from all public serializers; only returned to the owner |
| Career visibility | VERIFIED_HOSPITALS / SELECTED_HOSPITALS / HIDDEN — enforced at query level |
| Detailed availability | Only visible to verified healthcare institutions |
| Profile visibility | EVERYONE / DOCTORS_ONLY / CONNECTIONS_ONLY — enforced at query level |
| Application snapshot | JobApplication.metadata stores the exact profile/document snapshot shared with the hospital at apply time |
| Credential documents | Private S3 objects; access only via expiring signed URLs; never public |
| Minimum compensation | Never returned in any public or hospital-facing API response |
| Item | Status | Notes |
|---|---|---|
| JWT access + refresh lifecycle | ✅ | RefreshSession model; revocation via revoked_at |
| Secure token rotation | ✅ | New refresh token issued on each refresh |
| RBAC + object-level authorization | ✅ | user_type check + hospital/doctor ownership checks per endpoint |
| Rate limiting | ✅ | slowapi on auth, search, messaging, reports |
| Encrypted transport | ✅ | HTTPS enforced via nginx + HTTPSRedirectMiddleware |
| Secure secret storage | ✅ | All secrets via .env / AWS Secrets Manager in production |
| Private object storage | ✅ | AWS S3 private bucket for credentials/documents |
| Signed/expiring document URLs | ✅ | GET /api/v1/files/{id}/signed-url/ |
| File virus/type validation | ✅ | MIME type + size check on upload; UPLOAD_INVALID (400) on failure |
| Audit logs for sensitive actions | ✅ | AuditLog model; written on every verification/restriction/removal action |
| Database backups | ✅ | Configured via AWS RDS automated backups in production |
| Monitoring & structured logs | ✅ | Sentry DSN + structured logging middleware |
Every endpoint must document:
| Field | Description |
|---|---|
| Method + Path | HTTP verb and URL pattern |
| Auth Role | Required user_type or ANONYMOUS |
| Request Schema | Pydantic model with field-level validation rules |
| Field Validation | min/max length, regex, required vs optional |
| Response Schema | Pydantic model for success response |
| Error Codes | All possible error.code values from the standard error table |
| Pagination | page + page_size query params; meta.total + meta.has_next in response |
| Idempotency | Whether the endpoint is idempotent; payment webhooks require idempotency key |
| Permission Checks | Object-level checks beyond role (e.g. hospital ownership, connection status) |
| Side Effects | DB writes, notifications triggered, audit log entries written |
| Notification Event | Which NotificationEvent code is fired (see Section 5.4) |
| Audit Event | Which AuditLog.action string is written |
Standard response envelope:
// Success (single)
{"success": true, "data": {...}, "message": "..."}
// Success (list)
{"success": true, "data": [...], "meta": {"page": 1, "page_size": 20, "total": 125, "has_next": true}}
// Error
{"success": false, "error": {"code": "ERR_CODE", "message": "Human-readable", "fields": {"field": "reason"}}}The following models were added to complete the Spec 02 entity list:
| Model | App | Table | Purpose |
|---|---|---|---|
DoctorAffiliation |
doctors |
doctor_affiliations |
Current/past hospital affiliations with role, dates |
Follow |
doctors |
follows |
Doctor-to-doctor or doctor-to-hospital follow relationship |
Block |
doctors |
blocks |
User-level block; hides from feed/search, disables messaging |
JobSave |
jobs |
job_saves |
Doctor saves a job for later (replaces metadata JSONB approach) |
ShiftStatusHistory |
shifts |
shift_status_history |
Immutable audit trail for every shift request state transition |
DeviceToken |
notifications |
device_tokens |
FCM/APNs push tokens per device per user |
NotificationPreference |
notifications |
notification_preferences |
Per-user, per-event push + in-app channel preferences |
Plan |
core |
plans |
Billing plan definitions (name, price, cycle, features, limits) |
Subscription |
core |
subscriptions |
Hospital subscription to a plan with lifecycle status |
Entitlement |
core |
entitlements |
Active feature entitlements derived from a subscription |
Invoice |
core |
invoices |
Billing invoices linked to subscriptions |
Payment |
core |
payments |
Individual payment records with provider IDs and refund tracking |
Migrations created:
doctors/0011_add_affiliation_follow_block.pyjobs/0003_add_job_save.pyshifts/0002_add_shift_status_history.pynotifications/0002_add_device_token_notification_preference.pycore/0004_add_billing_models.py
// Success (single object)
{"success": true, "data": {...}, "message": "..."}
// Success (list)
{"success": true, "data": [...], "meta": {"page": 1, "page_size": 20, "total": 125, "has_next": true}}
// Error
{"success": false, "error": {"code": "ERR_CODE", "message": "Human-readable message", "fields": {"field": "reason"}}}| Code | Meaning | HTTP |
|---|---|---|
AUTH_REQUIRED |
Access token missing/invalid | 401 |
AUTH_FORBIDDEN |
Role/object permission denied | 403 |
TOKEN_EXPIRED |
Access token expired | 401 |
SESSION_REVOKED |
Refresh/session revoked | 401 |
VALIDATION_ERROR |
Request field validation failed | 400 |
OTP_INVALID |
OTP invalid/expired | 400 |
RESOURCE_NOT_FOUND |
Resource does not exist or is not visible | 404 |
DUPLICATE_RESOURCE |
Unique relationship/resource already exists | 409 |
INVALID_STATE_TRANSITION |
Requested state change not allowed | 409 |
VERIFICATION_REQUIRED |
Action requires verified account | 403 |
PRIVACY_RESTRICTED |
Resource/field not visible to requester | 403/404 |
BLOCKED_RELATIONSHIP |
Blocked user relationship prevents action | 403 |
SHIFT_CONFLICT |
Accepted/confirmed shift overlaps existing commitment | 409 |
APPLICATION_CLOSED |
Job no longer accepts applications | 409 |
UPLOAD_INVALID |
File type/size/security validation failed | 400 |
FILE_ACCESS_DENIED |
Private file access denied | 403 |
RATE_LIMITED |
Too many requests | 429 |
IDEMPOTENCY_CONFLICT |
Same key used for incompatible request | 409 |
MODERATION_REQUIRED |
Content held for moderation | 202 |
SERVER_ERROR |
Unexpected server error | 500 |
| Data | Public/Everyone | Doctors Only | Connections Only | Verified Hospitals |
|---|---|---|---|---|
| Name / photo / headline | Per profile visibility | Per setting | Per setting | Per setting |
| Phone / personal email | Never public | Controlled | Controlled | Controlled; not public |
| Medical registration details | Not exposed by default | Privacy-controlled | Privacy-controlled | Permitted professional fields only |
| Career opportunity status | Only if career visibility permits | If permitted | If permitted | Primary audience |
| Detailed availability | Not public | Generally restricted | Generally restricted | Primarily verified institutions |
| Min compensation | Never public | Never public | Never public | Private to doctor |
| Credential documents | Never public | Never public | Never public | Authorized access via signed URL only |
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Doctor Mobile App │ │ Hospital CRM │ │
│ │ (Android Native) │ │ (React Web) │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ └──────────┬─────────────────┘ │
│ │ │
└────────────────────────┼────────────────────────────────────────────────────┘
│ HTTPS / REST API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY / NGINX │
│ (Load Balancer + SSL Termination) │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Auth │ │ Doctors │ │ Network │ │ Jobs │ │ │
│ │ │ Router │ │ Router │ │ Router │ │ Router │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Avail- │ │ Messages │ │ Notific- │ │ Admin │ │ │
│ │ │ ability │ │ Router │ │ ations │ │ Router │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Django 5.0+ Core Layer │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Models │ │ Admin │ │ ORM │ │ Celery │ │ │
│ │ │ Layer │ │ Interface│ │ Queries │ │ Tasks │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA & CACHE LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Celery + Redis │ │
│ │ 16+ │ │ 7.2+ │ │ (Background Tasks)│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ AWS S3 (File Storage) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA FLOW DIAGRAM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ DOCTOR REGISTRATION FLOW: │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Mobile │──▶│ OTP │──▶│ Profile │──▶│ NMC │──▶│ Verified │ │
│ │ Number │ │ Verify │ │ Create │ │ Verify │ │ Profile │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ │
│ │
│ JOB APPLICATION FLOW: │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Browse │──▶│ Apply │──▶│ Shortlist│──▶│ Interview│──▶│ Hired/ │ │
│ │ Jobs │ │ One-Tap │ │ │ │ │ │ Rejected │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ │
│ │
│ SHIFT REQUEST FLOW: │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Create │──▶│ Match │──▶│ Send │──▶│ Accept/ │──▶│ Confirm/ │ │
│ │ Request │ │ Doctors │ │ Request │ │ Decline │ │ Complete │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ │
│ │
│ HOSPITAL REGISTRATION FLOW: │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Admin │──▶│ OTP │──▶│ Hospital │──▶│ Document │──▶│ Verified │ │
│ │ Phone │ │ Verify │ │ Details │ │ Upload │ │ Hospital │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Backend Core | Django | 5.0.6 | ORM, Admin, Models, Auth |
| API Layer | FastAPI | 0.115+ | High-performance REST API |
| Database | PostgreSQL | 16+ | Primary database with advanced features |
| Cache/Broker | Redis | 7.2+ | Caching and Celery broker |
| Task Queue | Celery | 5.4+ | Background task processing |
| API Docs | FastAPI Swagger | - | Automatic OpenAPI documentation |
| Validation | Pydantic | 2.13+ | Data validation and serialization |
| Auth | SimpleJWT | 5.3+ | JWT access + refresh tokens |
| WSGI Bridge | a2wsgi | 1.10+ | Mount Django under FastAPI |
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Mobile App | Android Native | - | Doctor mobile application |
| CRM Web | React | 18+ | Hospital administration interface |
| State Management | Zustand/Redux | - | Client state management |
| API Client | React Query | - | Data fetching and caching |
| Component | Technology | Purpose |
|---|---|---|
| Containerization | Docker | Container runtime |
| Orchestration | Docker Compose | Local development |
| Hosting | AWS EC2 / ECS | Production hosting |
| CI/CD | GitHub Actions | Automated deployment |
| Monitoring | Sentry / Prometheus | Error tracking |
| Logging | ELK Stack | Log aggregation |
-- Required PostgreSQL extensions
CREATE EXTENSION IF NOT EXISTS pg_trgm; -- Trigram similarity for fuzzy search
CREATE EXTENSION IF NOT EXISTS pgcrypto; -- Cryptographic functions
CREATE EXTENSION IF NOT EXISTS uuid-ossp; -- UUID generation
CREATE EXTENSION IF NOT EXISTS postgis; -- Geospatial queries
CREATE EXTENSION IF NOT EXISTS fuzzystrmatch; -- Fuzzy string matching
CREATE EXTENSION IF NOT EXISTS unaccent; -- Unaccent textThe schema below reflects the actual Django models. Additional fields
photo_base64,cover_base64(DoctorProfile) andlogo_base64(Hospital) are stored as base64 text for dev convenience alongside S3 file IDs.
-- ============================================================
-- CORE TABLES
-- ============================================================
-- 1. Users Table
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
phone VARCHAR(15) UNIQUE NOT NULL,
email VARCHAR(255) UNIQUE,
user_type VARCHAR(20) NOT NULL CHECK (user_type IN ('DOCTOR', 'HOSPITAL_ADMIN', 'HOSPITAL_HR', 'ADMIN')),
status VARCHAR(20) DEFAULT 'ACTIVE' CHECK (status IN ('ACTIVE', 'INACTIVE', 'SUSPENDED', 'DELETED')),
is_super_admin BOOLEAN DEFAULT FALSE, -- explicit Super Admin flag (separate from is_superuser)
is_staff BOOLEAN DEFAULT FALSE,
is_superuser BOOLEAN DEFAULT FALSE,
last_login TIMESTAMP WITH TIME ZONE,
metadata JSONB DEFAULT '{}',
search_vector TSVECTOR,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 2. OTP Challenges Table
CREATE TABLE otp_challenges (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
phone VARCHAR(15) NOT NULL,
purpose VARCHAR(20) NOT NULL CHECK (purpose IN ('LOGIN', 'REGISTER', 'RESET_PASSWORD')),
otp_hash VARCHAR(255) NOT NULL,
expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
attempts INTEGER DEFAULT 0,
max_attempts INTEGER DEFAULT 5,
resend_count INTEGER DEFAULT 0,
consumed_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 3. Refresh Sessions Table
CREATE TABLE refresh_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
token_hash VARCHAR(255) NOT NULL,
device_id VARCHAR(255),
device_name VARCHAR(255),
ip_address INET,
user_agent TEXT,
expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
revoked_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- ============================================================
-- DOCTOR MODULE TABLES
-- ============================================================
-- 4. Doctor Profiles
CREATE TABLE doctor_profiles (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
first_name VARCHAR(80) NOT NULL,
last_name VARCHAR(80) NOT NULL,
photo_file_id UUID,
headline VARCHAR(160),
about TEXT,
primary_specialization_id UUID,
clinical_interests UUID[] DEFAULT '{}',
professional_location JSONB,
experience_years DECIMAL(4,1) DEFAULT 0,
open_to_opportunities BOOLEAN DEFAULT FALSE,
verification_status VARCHAR(20) DEFAULT 'UNVERIFIED'
CHECK (verification_status IN ('UNVERIFIED', 'PENDING', 'VERIFIED', 'REJECTED')),
verification_rejected_reason TEXT,
profile_visibility VARCHAR(20) DEFAULT 'EVERYONE'
CHECK (profile_visibility IN ('EVERYONE', 'DOCTORS_ONLY', 'CONNECTIONS_ONLY')),
career_visibility VARCHAR(20) DEFAULT 'VERIFIED_HOSPITALS'
CHECK (career_visibility IN ('VERIFIED_HOSPITALS', 'SELECTED_HOSPITALS', 'HIDDEN')),
search_vector TSVECTOR,
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Create GIN indexes for JSON fields
CREATE INDEX idx_doctor_location_gin ON doctor_profiles USING GIN (professional_location);
CREATE INDEX idx_doctor_metadata_gin ON doctor_profiles USING GIN (metadata);
CREATE INDEX idx_doctor_search_gin ON doctor_profiles USING GIN (search_vector);
-- 5. Doctor Registrations
CREATE TABLE doctor_registrations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
council_id UUID NOT NULL,
registration_number VARCHAR(50) NOT NULL,
registration_year INTEGER NOT NULL,
is_primary BOOLEAN DEFAULT TRUE,
verification_status VARCHAR(20) DEFAULT 'PENDING'
CHECK (verification_status IN ('PENDING', 'VERIFIED', 'REJECTED')),
verified_at TIMESTAMP WITH TIME ZONE,
verified_by UUID REFERENCES users(id),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(council_id, registration_number)
);
-- 6. Doctor Qualifications
CREATE TABLE doctor_qualifications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
degree VARCHAR(100) NOT NULL,
institution VARCHAR(255) NOT NULL,
year INTEGER NOT NULL,
specialization VARCHAR(100),
file_id UUID,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 7. Doctor Experiences
CREATE TABLE doctor_experiences (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
role VARCHAR(100) NOT NULL,
hospital_name VARCHAR(255) NOT NULL,
location VARCHAR(255),
start_date DATE NOT NULL,
end_date DATE,
is_current BOOLEAN DEFAULT FALSE,
description TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- ============================================================
-- HOSPITAL MODULE TABLES
-- ============================================================
-- 8. Hospitals
CREATE TABLE hospitals (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
type VARCHAR(50) NOT NULL CHECK (type IN ('HOSPITAL', 'CLINIC', 'NURSING_HOME', 'MEDICAL_COLLEGE')),
logo_file_id UUID,
about TEXT,
location JSONB NOT NULL,
bed_count INTEGER,
phone VARCHAR(20),
email VARCHAR(255),
website VARCHAR(255),
verification_status VARCHAR(20) DEFAULT 'UNVERIFIED'
CHECK (verification_status IN ('UNVERIFIED', 'PENDING', 'VERIFIED', 'REJECTED')),
verified_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 9. Hospital Branches
CREATE TABLE hospital_branches (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
hospital_id UUID NOT NULL REFERENCES hospitals(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
location JSONB NOT NULL,
phone VARCHAR(20),
is_primary BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 10. Hospital Departments
CREATE TABLE hospital_departments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
hospital_id UUID NOT NULL REFERENCES hospitals(id) ON DELETE CASCADE,
branch_id UUID REFERENCES hospital_branches(id) ON DELETE CASCADE,
name VARCHAR(100) NOT NULL,
active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 11. Hospital Users
CREATE TABLE hospital_users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
hospital_id UUID NOT NULL REFERENCES hospitals(id) ON DELETE CASCADE,
branch_id UUID REFERENCES hospital_branches(id) ON DELETE SET NULL,
role VARCHAR(20) NOT NULL CHECK (role IN ('ADMIN', 'HR', 'RECRUITER')),
designation VARCHAR(100),
department_id UUID REFERENCES hospital_departments(id) ON DELETE SET NULL,
status VARCHAR(20) DEFAULT 'ACTIVE'
CHECK (status IN ('ACTIVE', 'INACTIVE', 'SUSPENDED')),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- ============================================================
-- JOBS & APPLICATIONS TABLES
-- ============================================================
-- 12. Job Posts
CREATE TABLE job_posts (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
hospital_id UUID NOT NULL REFERENCES hospitals(id) ON DELETE CASCADE,
branch_id UUID REFERENCES hospital_branches(id) ON DELETE SET NULL,
department_id UUID REFERENCES hospital_departments(id) ON DELETE SET NULL,
title VARCHAR(160) NOT NULL,
specialty_id UUID NOT NULL,
qualification_ids UUID[] NOT NULL,
description TEXT NOT NULL,
responsibilities TEXT,
requirements TEXT,
location JSONB NOT NULL,
salary_min DECIMAL(12,2),
salary_max DECIMAL(12,2),
salary_visibility VARCHAR(20) DEFAULT 'PUBLIC'
CHECK (salary_visibility IN ('PUBLIC', 'ON_REQUEST', 'HIDDEN')),
currency VARCHAR(3) DEFAULT 'INR',
job_type VARCHAR(20) NOT NULL
CHECK (job_type IN ('FULL_TIME', 'PART_TIME', 'VISITING', 'LOCUM', 'CONTRACT')),
experience_min_years DECIMAL(4,1) DEFAULT 0,
experience_max_years DECIMAL(4,1),
shift_type VARCHAR(20) DEFAULT 'DAY'
CHECK (shift_type IN ('DAY', 'NIGHT', 'ROTATIONAL', 'FLEXIBLE')),
joining_requirement VARCHAR(50),
positions INTEGER DEFAULT 1,
is_urgent BOOLEAN DEFAULT FALSE,
status VARCHAR(20) DEFAULT 'DRAFT'
CHECK (status IN ('DRAFT', 'PUBLISHED', 'CLOSED', 'EXPIRED', 'FILLED')),
posted_by UUID NOT NULL REFERENCES users(id),
published_at TIMESTAMP WITH TIME ZONE,
closing_date TIMESTAMP WITH TIME ZONE,
search_vector TSVECTOR,
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 13. Job Applications
CREATE TABLE job_applications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
job_id UUID NOT NULL REFERENCES job_posts(id) ON DELETE CASCADE,
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
cv_file_id UUID,
status VARCHAR(20) DEFAULT 'APPLIED'
CHECK (status IN ('APPLIED', 'PROFILE_VIEWED', 'SHORTLISTED',
'INTERVIEW', 'OFFERED', 'HIRED', 'REJECTED', 'WITHDRAWN')),
applied_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(job_id, doctor_id)
);
-- 14. Application History
CREATE TABLE application_histories (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
application_id UUID NOT NULL REFERENCES job_applications(id) ON DELETE CASCADE,
from_status VARCHAR(20),
to_status VARCHAR(20) NOT NULL,
changed_by UUID NOT NULL REFERENCES users(id),
notes TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- ============================================================
-- AVAILABILITY EXCHANGE TABLES
-- ============================================================
-- 15. Doctor Availability
CREATE TABLE doctor_availabilities (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
availability_type VARCHAR(20) NOT NULL
CHECK (availability_type IN ('LOCUM', 'VISITING', 'TEMPORARY', 'PART_TIME')),
available_from DATE NOT NULL,
available_until DATE NOT NULL,
preferred_location JSONB,
preferred_radius_km INTEGER,
minimum_compensation DECIMAL(12,2),
currency VARCHAR(3) DEFAULT 'INR',
notes TEXT,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 16. Availability Slots
CREATE TABLE availability_slots (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
availability_id UUID NOT NULL REFERENCES doctor_availabilities(id) ON DELETE CASCADE,
slot_date DATE NOT NULL,
start_time TIME NOT NULL,
end_time TIME NOT NULL,
is_booked BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
CHECK (start_time < end_time)
);
-- 17. Shift Requirements
CREATE TABLE shift_requirements (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
hospital_id UUID NOT NULL REFERENCES hospitals(id) ON DELETE CASCADE,
branch_id UUID REFERENCES hospital_branches(id) ON DELETE SET NULL,
specialty_id UUID NOT NULL,
qualification_ids UUID[] NOT NULL,
requirement_date DATE NOT NULL,
start_time TIME NOT NULL,
end_time TIME NOT NULL,
location JSONB NOT NULL,
compensation DECIMAL(12,2) NOT NULL,
currency VARCHAR(3) DEFAULT 'INR',
doctors_required INTEGER DEFAULT 1,
urgency VARCHAR(20) DEFAULT 'NORMAL'
CHECK (urgency IN ('NORMAL', 'URGENT', 'IMMEDIATE')),
notes TEXT,
status VARCHAR(20) DEFAULT 'OPEN'
CHECK (status IN ('OPEN', 'FILLED', 'CANCELLED', 'EXPIRED')),
created_by UUID NOT NULL REFERENCES users(id),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 18. Shift Requests
CREATE TABLE shift_requests (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
requirement_id UUID NOT NULL REFERENCES shift_requirements(id) ON DELETE CASCADE,
doctor_id UUID NOT NULL REFERENCES doctor_profiles(id) ON DELETE CASCADE,
status VARCHAR(30) DEFAULT 'REQUESTED'
CHECK (status IN ('REQUESTED', 'ACCEPTED_BY_DOCTOR', 'DECLINED_BY_DOCTOR',
'CONFIRMED_BY_HOSPITAL', 'COMPLETED', 'CANCELLED')),
requested_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
accepted_at TIMESTAMP WITH TIME ZONE,
declined_at TIMESTAMP WITH TIME ZONE,
confirmed_at TIMESTAMP WITH TIME ZONE,
completed_at TIMESTAMP WITH TIME ZONE,
cancelled_at TIMESTAMP WITH TIME ZONE,
notes TEXT,
UNIQUE(requirement_id, doctor_id)
);
-- ============================================================
-- MESSAGING & NOTIFICATIONS TABLES
-- ============================================================
-- 19. Conversations
CREATE TABLE conversations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
type VARCHAR(20) NOT NULL CHECK (type IN ('DIRECT', 'GROUP')),
title VARCHAR(255),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 20. Conversation Participants
CREATE TABLE conversation_participants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
last_read_at TIMESTAMP WITH TIME ZONE,
is_active BOOLEAN DEFAULT TRUE,
joined_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(conversation_id, user_id)
);
-- 21. Messages
CREATE TABLE messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
sender_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
content TEXT,
file_id UUID,
file_type VARCHAR(50),
file_name VARCHAR(255),
file_size INTEGER,
message_type VARCHAR(20) DEFAULT 'TEXT'
CHECK (message_type IN ('TEXT', 'IMAGE', 'DOCUMENT', 'SHIFT_REQUEST', 'JOB_REFERRAL')),
metadata JSONB,
read_at TIMESTAMP WITH TIME ZONE,
delivered_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- 22. Notifications
CREATE TABLE notifications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
type VARCHAR(50) NOT NULL,
title VARCHAR(255) NOT NULL,
body TEXT,
data_json JSONB,
deep_link VARCHAR(255),
is_read BOOLEAN DEFAULT FALSE,
read_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- ============================================================
-- INDEXES FOR PERFORMANCE
-- ============================================================
-- GiST index for geospatial queries
CREATE INDEX idx_hospital_location_gist ON hospitals USING GIST (location);
CREATE INDEX idx_doctor_location_gist ON doctor_profiles USING GIST (professional_location);
-- Full-text search indexes
CREATE INDEX idx_users_search_gin ON users USING GIN (search_vector);
CREATE INDEX idx_job_search_gin ON job_posts USING GIN (search_vector);
-- Array field indexes
CREATE INDEX idx_job_qualifications_gin ON job_posts USING GIN (qualification_ids);
CREATE INDEX idx_doctor_interests_gin ON doctor_profiles USING GIN (clinical_interests);
-- Composite indexes for common queries
CREATE INDEX idx_job_hospital_status ON job_posts(hospital_id, status);
CREATE INDEX idx_job_specialty_status ON job_posts(specialty_id, status);
CREATE INDEX idx_application_job_status ON job_applications(job_id, status);
CREATE INDEX idx_shift_requirement_status ON shift_requirements(hospital_id, status);
-- ============================================================
-- TRIGGERS FOR SEARCH VECTORS
-- ============================================================
-- Auto-update search vectors
CREATE OR REPLACE FUNCTION update_user_search_vector() RETURNS TRIGGER AS $$
BEGIN
NEW.search_vector =
setweight(to_tsvector('english', COALESCE(NEW.phone, '')), 'A') ||
setweight(to_tsvector('english', COALESCE(NEW.email, '')), 'B');
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER user_search_vector_update
BEFORE INSERT OR UPDATE ON users
FOR EACH ROW
EXECUTE FUNCTION update_user_search_vector();FastAPI is mounted alongside Django using a2wsgi. Django handles ORM, Admin and models; FastAPI handles all REST API endpoints. See fastapi_app/main.py for the full implementation.
Entry point: run.py starts uvicorn serving the combined app on port 8000.
from fastapi.middleware.cors import CORSMiddleware from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials from contextlib import asynccontextmanager import asyncio from typing import Optional
import os import django os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'docconnect_backend.settings') django.setup()
from django.contrib.auth import get_user_model from doctors.models import DoctorProfile from jobs.models import JobPost
app = FastAPI( title="DocConnect API", description="Verified Professional Network for Doctors", version="1.0.0", docs_url="/api/docs", redoc_url="/api/redoc", openapi_url="/api/openapi.json" )
app.add_middleware( CORSMiddleware, allow_origins=[""], allow_credentials=True, allow_methods=[""], allow_headers=["*"], )
security = HTTPBearer()
async def get_current_user( credentials: HTTPAuthorizationCredentials = Depends(security) ): """Get current authenticated user from JWT token""" from rest_framework_simplejwt.tokens import AccessToken from rest_framework_simplejwt.exceptions import InvalidToken, TokenError
token = credentials.credentials
try:
access_token = AccessToken(token)
user_id = access_token['user_id']
User = get_user_model()
user = User.objects.get(id=user_id)
if user.status != 'ACTIVE':
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="User account is not active"
)
return user
except (InvalidToken, TokenError, User.DoesNotExist):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials",
headers={"WWW-Authenticate": "Bearer"},
)
async def get_current_doctor( current_user = Depends(get_current_user) ): """Get current authenticated doctor""" if current_user.user_type != 'DOCTOR': raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="User is not a doctor" ) try: return current_user.doctor_profile except DoctorProfile.DoesNotExist: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail="Doctor profile not found" )
from pydantic import BaseModel, Field, EmailStr, validator from typing import Optional, List, Dict, Any from datetime import datetime, date, time from decimal import Decimal from enum import Enum
class UserType(str, Enum): DOCTOR = "DOCTOR" HOSPITAL_ADMIN = "HOSPITAL_ADMIN" HOSPITAL_HR = "HOSPITAL_HR" ADMIN = "ADMIN"
class VerificationStatus(str, Enum): UNVERIFIED = "UNVERIFIED" PENDING = "PENDING" VERIFIED = "VERIFIED" REJECTED = "REJECTED"
class OTPRequest(BaseModel): phone: str = Field(..., pattern=r'^[6-9]\d{9}$') purpose: str = Field(..., pattern=r'^(LOGIN|REGISTER|RESET_PASSWORD)$')
class OTPVerify(BaseModel): phone: str = Field(..., pattern=r'^[6-9]\d{9}$') otp: str = Field(..., min_length=6, max_length=6) device_id: Optional[str] = None
class TokenResponse(BaseModel): access_token: str refresh_token: str token_type: str = "bearer"
class Location(BaseModel): address: Optional[str] = None city: str state: str pincode: Optional[str] = None coordinates: Optional[Dict[str, float]] = None
class DoctorRegistration(BaseModel): council_id: str registration_number: str registration_year: int
class DoctorQualification(BaseModel): degree: str institution: str year: int specialization: Optional[str] = None
class DoctorExperience(BaseModel): role: str hospital_name: str location: Optional[str] = None start_date: date end_date: Optional[date] = None is_current: bool = False description: Optional[str] = None
class DoctorProfileCreate(BaseModel): first_name: str = Field(..., min_length=1, max_length=80) last_name: str = Field(..., min_length=1, max_length=80) headline: Optional[str] = Field(None, max_length=160) about: Optional[str] = None primary_specialization_id: Optional[str] = None clinical_interests: Optional[List[str]] = [] professional_location: Optional[Location] = None experience_years: Optional[float] = Field(0, ge=0, le=60)
class DoctorProfileResponse(BaseModel): id: str user_id: str first_name: str last_name: str full_name: str photo_file_id: Optional[str] headline: Optional[str] about: Optional[str] primary_specialization_id: Optional[str] clinical_interests: List[str] professional_location: Optional[Location] experience_years: float open_to_opportunities: bool verification_status: VerificationStatus is_verified: bool created_at: datetime updated_at: datetime
class JobType(str, Enum): FULL_TIME = "FULL_TIME" PART_TIME = "PART_TIME" VISITING = "VISITING" LOCUM = "LOCUM" CONTRACT = "CONTRACT"
class SalaryVisibility(str, Enum): PUBLIC = "PUBLIC" ON_REQUEST = "ON_REQUEST" HIDDEN = "HIDDEN"
class JobCreate(BaseModel): title: str = Field(..., min_length=3, max_length=160) specialty_id: str qualification_ids: List[str] description: str responsibilities: Optional[str] = None requirements: Optional[str] = None location: Location salary_min: Optional[Decimal] = Field(None, ge=0) salary_max: Optional[Decimal] = Field(None, ge=0) salary_visibility: SalaryVisibility = SalaryVisibility.PUBLIC currency: str = "INR" job_type: JobType experience_min_years: float = 0 experience_max_years: Optional[float] = None shift_type: str = "DAY" joining_requirement: Optional[str] = None positions: int = Field(1, ge=1) is_urgent: bool = False
class JobResponse(BaseModel): id: str hospital_id: str hospital_name: str title: str specialty_id: str description: str location: Location salary_min: Optional[Decimal] salary_max: Optional[Decimal] salary_visibility: SalaryVisibility job_type: JobType experience_min_years: float experience_max_years: Optional[float] is_urgent: bool status: str created_at: datetime published_at: Optional[datetime] match_score: Optional[int] = None
class AvailabilityType(str, Enum): LOCUM = "LOCUM" VISITING = "VISITING" TEMPORARY = "TEMPORARY" PART_TIME = "PART_TIME"
class AvailabilitySlot(BaseModel): slot_date: date start_time: time end_time: time
class AvailabilityCreate(BaseModel): availability_type: AvailabilityType available_from: date available_until: date preferred_location: Optional[Location] = None preferred_radius_km: Optional[int] = Field(None, ge=1, le=500) minimum_compensation: Optional[Decimal] = Field(None, ge=0) currency: str = "INR" notes: Optional[str] = None slots: List[AvailabilitySlot]
class ShiftRequirementCreate(BaseModel): specialty_id: str qualification_ids: List[str] requirement_date: date start_time: time end_time: time location: Location compensation: Decimal = Field(..., ge=0) currency: str = "INR" doctors_required: int = Field(1, ge=1) urgency: str = "NORMAL" notes: Optional[str] = None
class HospitalType(str, Enum): HOSPITAL = "HOSPITAL" CLINIC = "CLINIC" NURSING_HOME = "NURSING_HOME" MEDICAL_COLLEGE = "MEDICAL_COLLEGE"
class HospitalAdminRole(str, Enum): ADMIN = "ADMIN" HR = "HR" RECRUITER = "RECRUITER"
class HospitalRegisterRequest(BaseModel): # Admin user details phone: str = Field(..., pattern=r'^[6-9]\d{9}$') email: EmailStr # Hospital details name: str = Field(..., min_length=3, max_length=255) type: HospitalType about: Optional[str] = None location: Location bed_count: Optional[int] = Field(None, ge=1) hospital_phone: Optional[str] = None hospital_email: Optional[EmailStr] = None website: Optional[str] = None
class HospitalResponse(BaseModel): id: str name: str type: HospitalType about: Optional[str] location: Location bed_count: Optional[int] phone: Optional[str] email: Optional[str] website: Optional[str] verification_status: VerificationStatus created_at: datetime
class HospitalBranchCreate(BaseModel): name: str = Field(..., min_length=2, max_length=255) location: Location phone: Optional[str] = None is_primary: bool = False
class HospitalDepartmentCreate(BaseModel): name: str = Field(..., min_length=2, max_length=100) branch_id: Optional[str] = None
class HospitalUserInvite(BaseModel): phone: str = Field(..., pattern=r'^[6-9]\d{9}$') email: EmailStr role: HospitalAdminRole designation: Optional[str] = None branch_id: Optional[str] = None department_id: Optional[str] = None
from fastapi import APIRouter, Query, Body, File, UploadFile from django.db.models import Q from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank
auth_router = APIRouter(prefix="/api/v1/auth", tags=["Authentication"])
@auth_router.post("/send-otp/", response_model=Dict[str, Any]) async def send_otp(request: OTPRequest): """Send OTP to user's phone number""" from accounts.models import OTPChallenge from core.services.sms import send_otp_sms import secrets import hashlib from datetime import timedelta from django.utils import timezone
# Generate OTP
otp = str(secrets.randbelow(900000) + 100000)
otp_hash = hashlib.sha256(otp.encode()).hexdigest()
expires_at = timezone.now() + timedelta(seconds=300)
# Store OTP
OTPChallenge.objects.create(
phone=request.phone,
purpose=request.purpose,
otp_hash=otp_hash,
expires_at=expires_at
)
# Send OTP
await send_otp_sms(request.phone, otp)
return {
"success": True,
"message": "OTP sent successfully",
"expires_in": 300
}
@auth_router.post("/verify-otp/", response_model=TokenResponse) async def verify_otp(request: OTPVerify): """Verify OTP and authenticate user""" from accounts.models import OTPChallenge, RefreshSession from rest_framework_simplejwt.tokens import RefreshToken from django.contrib.auth import get_user_model import hashlib from django.utils import timezone
User = get_user_model()
# Find OTP
challenges = OTPChallenge.objects.filter(
phone=request.phone,
purpose='LOGIN',
consumed_at__isnull=True,
expires_at__gt=timezone.now()
).order_by('-created_at')
if not challenges.exists():
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="No valid OTP found"
)
challenge = challenges.first()
otp_hash = hashlib.sha256(request.otp.encode()).hexdigest()
if challenge.otp_hash != otp_hash:
challenge.attempts += 1
challenge.save()
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Invalid OTP"
)
# Mark as consumed
challenge.consumed_at = timezone.now()
challenge.save()
# Get or create user
user, created = User.objects.get_or_create(
phone=request.phone,
defaults={'user_type': 'DOCTOR'}
)
# Generate tokens
refresh = RefreshToken.for_user(user)
return TokenResponse(
access_token=str(refresh.access_token),
refresh_token=str(refresh)
)
hospital_router = APIRouter(prefix="/api/v1/hospitals", tags=["Hospitals"])
@hospital_router.post("/register/", response_model=HospitalResponse, status_code=201) async def register_hospital( data: HospitalRegisterRequest, current_user = Depends(get_current_user) ): """Register a new hospital and link admin user""" from hospitals.models import Hospital, HospitalUser
if current_user.user_type not in ('HOSPITAL_ADMIN', 'ADMIN'):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Only hospital admins can register a hospital"
)
if HospitalUser.objects.filter(user=current_user).exists():
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="User is already associated with a hospital"
)
hospital = Hospital.objects.create(
name=data.name,
type=data.type,
about=data.about,
location=data.location.dict(),
bed_count=data.bed_count,
phone=data.hospital_phone,
email=str(data.hospital_email) if data.hospital_email else None,
website=data.website,
verification_status='PENDING'
)
HospitalUser.objects.create(
user=current_user,
hospital=hospital,
role='ADMIN'
)
return HospitalResponse(
id=str(hospital.id),
name=hospital.name,
type=hospital.type,
about=hospital.about,
location=data.location,
bed_count=hospital.bed_count,
phone=hospital.phone,
email=hospital.email,
website=hospital.website,
verification_status=hospital.verification_status,
created_at=hospital.created_at
)
@hospital_router.get("/me/", response_model=HospitalResponse) async def get_my_hospital( current_user = Depends(get_current_user) ): """Get hospital profile of the logged-in admin""" from hospitals.models import HospitalUser
try:
hospital_user = HospitalUser.objects.select_related('hospital').get(user=current_user)
h = hospital_user.hospital
return HospitalResponse(
id=str(h.id),
name=h.name,
type=h.type,
about=h.about,
location=h.location,
bed_count=h.bed_count,
phone=h.phone,
email=h.email,
website=h.website,
verification_status=h.verification_status,
created_at=h.created_at
)
except HospitalUser.DoesNotExist:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="No hospital associated with this user"
)
@hospital_router.post("/me/branches/", status_code=201) async def add_branch( branch: HospitalBranchCreate, current_user = Depends(get_current_user) ): """Add a branch to the hospital""" from hospitals.models import HospitalUser, HospitalBranch
try:
hospital_user = HospitalUser.objects.get(user=current_user, role='ADMIN')
except HospitalUser.DoesNotExist:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a hospital admin")
b = HospitalBranch.objects.create(
hospital=hospital_user.hospital,
name=branch.name,
location=branch.location.dict(),
phone=branch.phone,
is_primary=branch.is_primary
)
return {"success": True, "branch_id": str(b.id), "name": b.name}
@hospital_router.post("/me/departments/", status_code=201) async def add_department( dept: HospitalDepartmentCreate, current_user = Depends(get_current_user) ): """Add a department to the hospital""" from hospitals.models import HospitalUser, HospitalDepartment
try:
hospital_user = HospitalUser.objects.get(user=current_user, role='ADMIN')
except HospitalUser.DoesNotExist:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a hospital admin")
d = HospitalDepartment.objects.create(
hospital=hospital_user.hospital,
branch_id=dept.branch_id,
name=dept.name
)
return {"success": True, "department_id": str(d.id), "name": d.name}
@hospital_router.post("/me/invite-user/", status_code=201) async def invite_hospital_user( invite: HospitalUserInvite, current_user = Depends(get_current_user) ): """Invite HR/Recruiter to the hospital account""" from hospitals.models import HospitalUser from django.contrib.auth import get_user_model
try:
hospital_user = HospitalUser.objects.get(user=current_user, role='ADMIN')
except HospitalUser.DoesNotExist:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a hospital admin")
User = get_user_model()
invited_user, _ = User.objects.get_or_create(
phone=invite.phone,
defaults={'email': str(invite.email), 'user_type': 'HOSPITAL_HR'}
)
if HospitalUser.objects.filter(user=invited_user).exists():
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="User already associated with a hospital"
)
HospitalUser.objects.create(
user=invited_user,
hospital=hospital_user.hospital,
role=invite.role,
designation=invite.designation,
branch_id=invite.branch_id,
department_id=invite.department_id
)
return {"success": True, "message": f"User {invite.phone} added as {invite.role}"}
@hospital_router.post("/me/upload-logo/") async def upload_hospital_logo( file: UploadFile = File(...), current_user = Depends(get_current_user) ): """Upload hospital logo to S3""" from hospitals.models import HospitalUser from core.services.storage import upload_file_to_s3
try:
hospital_user = HospitalUser.objects.get(user=current_user, role='ADMIN')
except HospitalUser.DoesNotExist:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a hospital admin")
if file.content_type not in ('image/jpeg', 'image/png', 'image/webp'):
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Only JPEG/PNG/WEBP allowed")
file_id = await upload_file_to_s3(file, folder="hospital-logos")
hospital_user.hospital.logo_file_id = file_id
hospital_user.hospital.save(update_fields=['logo_file_id'])
return {"success": True, "file_id": str(file_id)}
doctor_router = APIRouter(prefix="/api/v1/doctors", tags=["Doctors"])
@doctor_router.post("/profile/", response_model=DoctorProfileResponse) async def create_doctor_profile( profile: DoctorProfileCreate, current_user = Depends(get_current_user) ): """Create doctor profile""" if current_user.user_type != 'DOCTOR': raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="User is not a doctor" )
doctor_profile = DoctorProfile.objects.create(
user=current_user,
first_name=profile.first_name,
last_name=profile.last_name,
headline=profile.headline,
about=profile.about,
primary_specialization_id=profile.primary_specialization_id,
clinical_interests=profile.clinical_interests or [],
professional_location=profile.professional_location.dict() if profile.professional_location else {},
experience_years=profile.experience_years
)
return DoctorProfileResponse.from_orm(doctor_profile)
@doctor_router.get("/profile/me/", response_model=DoctorProfileResponse) async def get_my_profile( current_doctor = Depends(get_current_doctor) ): """Get current doctor's profile""" return DoctorProfileResponse.from_orm(current_doctor)
@doctor_router.get("/search/") async def search_doctors( search: Optional[str] = Query(None), specialty: Optional[str] = Query(None), city: Optional[str] = Query(None), state: Optional[str] = Query(None), experience_min: Optional[float] = Query(None), experience_max: Optional[float] = Query(None), lat: Optional[float] = Query(None), lng: Optional[float] = Query(None), radius: Optional[int] = Query(50), page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), current_user = Depends(get_current_user) ): """Search doctors with advanced filters""" queryset = DoctorProfile.objects.filter(verification_status='VERIFIED')
# Full-text search
if search:
vector = SearchVector('first_name', 'last_name', 'headline', 'about')
query = SearchQuery(search)
queryset = queryset.annotate(
rank=SearchRank(vector, query)
).filter(rank__gte=0.1).order_by('-rank')
# Filters
if specialty:
queryset = queryset.filter(primary_specialization_id=specialty)
if city:
queryset = queryset.filter(professional_location__city__icontains=city)
if state:
queryset = queryset.filter(professional_location__state__icontains=state)
if experience_min:
queryset = queryset.filter(experience_years__gte=experience_min)
if experience_max:
queryset = queryset.filter(experience_years__lte=experience_max)
# Geospatial search
if lat and lng:
from django.contrib.gis.geos import Point
from django.contrib.gis.db.models.functions import Distance
point = Point(lng, lat, srid=4326)
queryset = queryset.filter(
professional_location__has_key='coordinates'
).annotate(
distance=Distance('professional_location__coordinates', point)
).filter(distance__lte=radius * 1000)
# Pagination
offset = (page - 1) * page_size
total = queryset.count()
results = queryset[offset:offset + page_size]
return {
"results": [DoctorProfileResponse.from_orm(d) for d in results],
"total": total,
"page": page,
"page_size": page_size,
"total_pages": (total + page_size - 1) // page_size
}
job_router = APIRouter(prefix="/api/v1/jobs", tags=["Jobs"])
@job_router.post("/", response_model=JobResponse) async def create_job( job: JobCreate, current_user = Depends(get_current_user) ): """Create a new job posting""" from hospitals.models import HospitalUser
# Check if user is hospital staff
try:
hospital_user = HospitalUser.objects.get(user=current_user)
hospital = hospital_user.hospital
except HospitalUser.DoesNotExist:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="User is not associated with a hospital"
)
# Create job
job_post = JobPost.objects.create(
hospital=hospital,
title=job.title,
specialty_id=job.specialty_id,
qualification_ids=job.qualification_ids,
description=job.description,
responsibilities=job.responsibilities,
requirements=job.requirements,
location=job.location.dict(),
salary_min=job.salary_min,
salary_max=job.salary_max,
salary_visibility=job.salary_visibility,
currency=job.currency,
job_type=job.job_type,
experience_min_years=job.experience_min_years,
experience_max_years=job.experience_max_years,
shift_type=job.shift_type,
joining_requirement=job.joining_requirement,
positions=job.positions,
is_urgent=job.is_urgent,
status='PUBLISHED',
posted_by=current_user,
published_at=datetime.now()
)
return JobResponse.from_orm(job_post)
@job_router.get("/") async def list_jobs( specialty: Optional[str] = Query(None), city: Optional[str] = Query(None), job_type: Optional[str] = Query(None), search: Optional[str] = Query(None), page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), current_user = Depends(get_current_user) ): """List jobs with filters""" queryset = JobPost.objects.filter(status='PUBLISHED')
if specialty:
queryset = queryset.filter(specialty_id=specialty)
if city:
queryset = queryset.filter(location__city__icontains=city)
if job_type:
queryset = queryset.filter(job_type=job_type)
if search:
vector = SearchVector('title', 'description')
query = SearchQuery(search)
queryset = queryset.annotate(
rank=SearchRank(vector, query)
).filter(rank__gte=0.1).order_by('-rank')
# Pagination
offset = (page - 1) * page_size
total = queryset.count()
results = queryset[offset:offset + page_size]
return {
"results": [JobResponse.from_orm(j) for j in results],
"total": total,
"page": page,
"page_size": page_size,
"total_pages": (total + page_size - 1) // page_size
}
@job_router.get("/{job_id}/", response_model=JobResponse) async def get_job( job_id: str, current_user = Depends(get_current_user) ): """Get job details""" try: job = JobPost.objects.get(id=job_id, status='PUBLISHED') return JobResponse.from_orm(job) except JobPost.DoesNotExist: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail="Job not found" )
@job_router.post("/{job_id}/apply/") async def apply_to_job( job_id: str, cv_file_id: Optional[str] = None, current_doctor = Depends(get_current_doctor) ): """Apply to a job""" from jobs.models import JobApplication
try:
job = JobPost.objects.get(id=job_id, status='PUBLISHED')
except JobPost.DoesNotExist:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Job not found"
)
# Check if already applied
if JobApplication.objects.filter(job=job, doctor=current_doctor).exists():
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Already applied to this job"
)
# Create application
application = JobApplication.objects.create(
job=job,
doctor=current_doctor,
cv_file_id=cv_file_id,
status='APPLIED'
)
return {
"success": True,
"message": "Application submitted successfully",
"application_id": str(application.id),
"status": application.status
}
availability_router = APIRouter(prefix="/api/v1/availability", tags=["Availability"])
@availability_router.post("/") async def create_availability( availability: AvailabilityCreate, current_doctor = Depends(get_current_doctor) ): """Create doctor availability""" from availability.models import DoctorAvailability, AvailabilitySlot
# Create availability
avail = DoctorAvailability.objects.create(
doctor=current_doctor,
availability_type=availability.availability_type,
available_from=availability.available_from,
available_until=availability.available_until,
preferred_location=availability.preferred_location.dict() if availability.preferred_location else {},
preferred_radius_km=availability.preferred_radius_km,
minimum_compensation=availability.minimum_compensation,
currency=availability.currency,
notes=availability.notes,
is_active=True
)
# Create slots
for slot in availability.slots:
AvailabilitySlot.objects.create(
availability=avail,
slot_date=slot.slot_date,
start_time=slot.start_time,
end_time=slot.end_time
)
return {
"success": True,
"message": "Availability created successfully",
"availability_id": str(avail.id)
}
shift_router = APIRouter(prefix="/api/v1/shifts", tags=["Shifts"])
@shift_router.post("/requirements/") async def create_shift_requirement( requirement: ShiftRequirementCreate, current_user = Depends(get_current_user) ): """Create a shift requirement""" from shifts.models import ShiftRequirement from hospitals.models import HospitalUser
try:
hospital_user = HospitalUser.objects.get(user=current_user)
hospital = hospital_user.hospital
except HospitalUser.DoesNotExist:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="User is not associated with a hospital"
)
shift_req = ShiftRequirement.objects.create(
hospital=hospital,
specialty_id=requirement.specialty_id,
qualification_ids=requirement.qualification_ids,
requirement_date=requirement.requirement_date,
start_time=requirement.start_time,
end_time=requirement.end_time,
location=requirement.location.dict(),
compensation=requirement.compensation,
currency=requirement.currency,
doctors_required=requirement.doctors_required,
urgency=requirement.urgency,
notes=requirement.notes,
created_by=current_user
)
return {
"success": True,
"message": "Shift requirement created successfully",
"requirement_id": str(shift_req.id)
}
app.include_router(auth_router) app.include_router(hospital_router) app.include_router(doctor_router) app.include_router(job_router) app.include_router(availability_router)
docconnect/
├── manage.py
├── run.py # FastAPI + Django combined runner
├── requirements.txt
├── .env
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── README.md
│
├── docconnect_backend/ # Django Project
│ ├── __init__.py
│ ├── settings/
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── development.py
│ │ ├── production.py
│ │ └── test.py
│ ├── urls.py
│ ├── celery.py
│ ├── wsgi.py
│ └── asgi.py
│
├── fastapi_app/ # FastAPI Application
│ ├── __init__.py
│ ├── main.py # Main FastAPI app + Django mount
│ ├── dependencies.py # get_current_user / get_current_doctor
│ ├── schemas.py # Shared Pydantic models
│ ├── routers/ # API routers
│ │ ├── __init__.py
│ │ ├── admin.py # Admin CRM: verification, users, reports, moderation,
│ │ │ # communities, audit logs, analytics, settings, matching config
│ │ ├── auth.py # Register, Login, OTP, Refresh, Logout
│ │ ├── availability.py # Doctor availability + slots
│ │ ├── billing.py # Plans, subscriptions, invoices, webhooks, refunds
│ │ ├── communities.py # Specialty communities
│ │ ├── devices.py # Push notification device tokens
│ │ ├── doctors.py # Profile, Search, Qualifications, Experience
│ │ ├── feed.py # Home, Posts, Likes, Comments, Replies
│ │ ├── files.py # File upload, signed URLs
│ │ ├── hospitals.py # Register, Branches, Departments, Staff
│ │ ├── jobs.py # Post, Apply, Withdraw, CRM pipeline
│ │ ├── masters.py # Specialties, qualifications, councils, job/shift types
│ │ ├── messaging.py # Conversations + Messages
│ │ ├── network.py # Connections, follow, block, reports
│ │ ├── notifications.py # List, Read, Unread count, preferences
│ │ ├── search.py # Universal search
│ │ ├── shifts.py # Requirements, Requests, Lifecycle
│ │ └── support.py # Support tickets + admin ticket management
│ └── middleware/
│ ├── __init__.py
│ ├── auth.py
│ └── logging.py
│
├── apps/ # Django Apps
│ ├── accounts/ # User, OTPChallenge, RefreshSession
│ ├── doctors/ # DoctorProfile, Connection, Post, PostLike, PostComment
│ ├── hospitals/ # Hospital, Branch, Department, HospitalUser, HospitalFollow
│ ├── jobs/ # JobPost, JobApplication, ApplicationHistory
│ ├── availability/ # DoctorAvailability, AvailabilitySlot
│ ├── shifts/ # ShiftRequirement, ShiftRequest
│ ├── messaging/ # Conversation, ConversationParticipant, Message
│ ├── notifications/ # Notification
│ └── core/ # Community, CommunityMember, AuditLog, Report,
│ # SupportTicket, SupportMessage, MatchingConfig,
│ # Specialization, Qualification, Council
│ # + services: Encryption, SMS, S3 storage
│
├── tests/
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_doctors.py
│ ├── test_jobs.py
│ └── test_availability.py
│
├── scripts/
│ ├── seed_data.py
│ ├── create_admin.py
│ └── update_search_vectors.py
│
├── templates/ # Django HTML templates (web UI)
├── nginx/
│ └── nginx.conf
└── docs/
- Python 3.11+ (3.13 / 3.14 also tested on Windows)
- PostgreSQL 16+
- Redis 7.2+
# 1. Clone repository
git clone https://github.com/pkdubey/docconnect.git
cd docconnect
# 2. Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Mac/Linux
# 3. Install dependencies
pip install -r requirements.txt
# 4. Create .env file
cp .env.example .env
# Edit .env with your DB credentials
# 5. Setup PostgreSQL (run in psql as postgres user)
# CREATE DATABASE docconnect_db;
# CREATE USER docconnect_user WITH PASSWORD 'docconnect_password';
# GRANT ALL PRIVILEGES ON DATABASE docconnect_db TO docconnect_user;
# 6. Create migrations for all apps
python manage.py makemigrations accounts doctors hospitals jobs availability shifts messaging notifications
python manage.py makemigrations core
# 7. Run all migrations
python manage.py migrate
# 8. Seed master data (specializations, qualifications, councils)
python scripts/seed_data.py
# 9. Create superuser
python -c "import django, os; os.environ.setdefault('DJANGO_SETTINGS_MODULE','docconnect_backend.settings.development'); django.setup(); from apps.accounts.models import User; User.objects.create_superuser(phone='9999999999', user_type='ADMIN', password='admin123')"
# 10. Start FastAPI server (serves everything on port 8000)
python run.py
# 11. (Optional) Run Celery worker in a separate terminal
celery -A docconnect_backend worker -l info| URL | Description |
|---|---|
| http://localhost:8000/ | API root |
| http://localhost:8000/api/docs | Swagger UI (interactive API docs) |
| http://localhost:8000/api/redoc | ReDoc API docs |
| http://localhost:8000/api/openapi.json | OpenAPI schema |
| http://localhost:8000/health | Health check |
| http://localhost:8000/admin/ | Django Admin panel |
| Field | Value |
|---|---|
| Phone | 9999999999 |
| Password | admin123 |
| User Type | ADMIN |
Note: Change password immediately in production via Django Admin → Users.
If you are on Python 3.14 (Windows), the following pinned versions are required in requirements.txt — they ship pre-built wheels for 3.14:
pydantic[email]==2.13.4
pydantic-core==2.46.4
psycopg[binary]==3.3.4
fastapi==0.115.12
uvicorn[standard]==0.34.3
# Build and run with Docker Compose
docker-compose up -d --build
# Run migrations
docker-compose exec backend python manage.py migrate
# Create superuser
docker-compose exec backend python manage.py createsuperuser
# View logs
docker-compose logs -f# .env.example
# Django
DJANGO_SECRET_KEY=your-secret-key-min-50-chars
DEBUG=False
ALLOWED_HOSTS=api.docconnect.com,www.docconnect.com
DJANGO_SETTINGS_MODULE=docconnect_backend.settings.production
# Database
DB_NAME=docconnect_db
DB_USER=docconnect_user
DB_PASSWORD=your-db-password
DB_HOST=postgres
DB_PORT=5432
# Redis
REDIS_URL=redis://redis:6379/1
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/2
# AWS S3
AWS_ACCESS_KEY_ID=<aws-access-key>
AWS_SECRET_ACCESS_KEY=<aws-secret-key>
AWS_STORAGE_BUCKET_NAME=docconnect-media
AWS_S3_REGION_NAME=ap-south-1
AWS_S3_CUSTOM_DOMAIN=cdn.docconnect.com # optional CloudFront
# Email
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=<email>
EMAIL_HOST_PASSWORD=<app-password>
DEFAULT_FROM_EMAIL=noreply@docconnect.com
# SMS (e.g. MSG91 / Twilio)
SMS_PROVIDER=msg91 # msg91 | twilio
SMS_API_KEY=<sms-api-key>
SMS_SENDER_ID=DOCCON
SMS_OTP_TEMPLATE_ID=<template-id>
# Firebase (Push Notifications)
FCM_SERVER_KEY=<fcm-server-key>
# Sentry
SENTRY_DSN=<sentry-dsn>
SENTRY_ENVIRONMENT=production
# JWT
JWT_SECRET_KEY=<jwt-secret-min-32-chars>
JWT_ACCESS_TOKEN_LIFETIME_MINUTES=60
JWT_REFRESH_TOKEN_LIFETIME_DAYS=30
# NMC Verification API (optional)
NMC_API_BASE_URL=https://api.nmc.org.in
NMC_API_KEY=<nmc-api-key># Build production Docker images
docker-compose -f docker-compose.production.yml build
# Push to registry
docker tag docconnect-backend:latest your-registry/docconnect-backend:latest
docker push your-registry/docconnect-backend:latest
# Deploy to server
ssh user@your-server
docker pull your-registry/docconnect-backend:latest
docker-compose -f docker-compose.production.yml up -d
# Run migrations
docker-compose -f docker-compose.production.yml exec backend python manage.py migrate
# Collect static files
docker-compose -f docker-compose.production.yml exec backend python manage.py collectstatic --noinput- Swagger UI:
http://localhost:8000/api/docs - ReDoc:
http://localhost:8000/api/redoc - OpenAPI JSON:
http://localhost:8000/api/openapi.json
All endpoints are documented in Sections 2–5 per module. Use Swagger UI at
/api/docsfor interactive reference.
| POST | /api/v1/auth/register/ | Register with phone + password |
| POST | /api/v1/auth/login/ | Login with phone + password |
| POST | /api/v1/auth/send-otp/ | Send OTP to phone |
| POST | /api/v1/auth/verify-otp/ | Verify OTP and get tokens |
| POST | /api/v1/auth/refresh/ | Refresh JWT token |
| POST | /api/v1/auth/logout/ | Logout / blacklist token |
| POST | /api/v1/auth/password/forgot/ | Forgot password — send reset challenge |
| POST | /api/v1/auth/password/reset/ | Reset password with token |
| POST | /api/v1/auth/password/change/ | Change password (authenticated) |
| GET | /api/v1/auth/sessions/ | List active sessions / devices |
| DELETE | /api/v1/auth/sessions/{id}/ | Revoke a specific session |
| POST | /api/v1/auth/sessions/revoke-all/ | Revoke all sessions |
| DELETE | /api/v1/account/ | Deactivate / delete account |
| Doctors | | |
| POST | /api/v1/doctors/profile/ | Create doctor profile |
| GET | /api/v1/doctors/profile/me/ | Get my profile |
| PATCH | /api/v1/doctors/profile/me/ | Update my profile |
| GET | /api/v1/doctors/profile/{id}/ | View any doctor's profile |
| POST | /api/v1/doctors/profile/me/photo/ | Upload profile photo |
| GET | /api/v1/doctors/search/ | Search doctors |
| POST | /api/v1/doctors/profile/me/registrations/ | Add NMC registration |
| GET | /api/v1/doctors/profile/me/registrations/ | List registrations |
| POST | /api/v1/doctors/profile/me/qualifications/ | Add qualification |
| GET | /api/v1/doctors/profile/me/qualifications/ | List qualifications |
| DELETE | /api/v1/doctors/profile/me/qualifications/{id}/ | Delete qualification |
| POST | /api/v1/doctors/profile/me/experiences/ | Add experience |
| GET | /api/v1/doctors/profile/me/experiences/ | List experiences |
| PATCH | /api/v1/doctors/profile/me/experiences/{id}/ | Update experience |
| DELETE | /api/v1/doctors/profile/me/experiences/{id}/ | Delete experience |
| POST | /api/v1/doctors/profile/me/affiliations/ | Add hospital affiliation |
| GET | /api/v1/doctors/profile/me/affiliations/ | List affiliations |
| PATCH | /api/v1/doctors/profile/me/affiliations/{id}/ | Update affiliation |
| DELETE | /api/v1/doctors/profile/me/affiliations/{id}/ | Delete affiliation |
| GET | /api/v1/doctors/profile/me/verification/ | Get verification status |
| POST | /api/v1/doctors/profile/me/verification/submit/ | Submit verification documents |
| POST | /api/v1/doctors/profile/me/verification/resubmit/ | Resubmit after rejection |
| GET | /api/v1/doctors/profile/me/status/ | Get professional status |
| PUT | /api/v1/doctors/profile/me/status/ | Update professional status |
| GET | /api/v1/doctors/profile/me/privacy/ | Get privacy settings |
| PUT | /api/v1/doctors/profile/me/privacy/ | Update privacy settings |
| Files | | |
| POST | /api/v1/files/upload/ | Upload file (photo/CV/credential) |
| GET | /api/v1/files/{id}/ | Get file metadata |
| GET | /api/v1/files/{id}/signed-url/ | Get expiring signed URL for file |
| DELETE | /api/v1/files/{id}/ | Delete file |
| Search | | |
| GET | /api/v1/search/doctors/ | Search doctors (advanced filters) |
| GET | /api/v1/search/hospitals/ | Search hospitals |
| GET | /api/v1/search/jobs/ | Search jobs |
| GET | /api/v1/search/communities/ | Search specialty communities |
| GET | /api/v1/search/universal/ | Universal search (doctors/hospitals/jobs/communities) |
| Network | | |
| POST | /api/v1/network/connections/request/ | Send connection request |
| POST | /api/v1/network/connections/{id}/accept/ | Accept connection |
| POST | /api/v1/network/connections/{id}/reject/ | Reject connection |
| DELETE | /api/v1/network/connections/{id}/ | Remove connection |
| GET | /api/v1/network/connections/ | List connections / requests |
| POST | /api/v1/network/follow/{user_id}/ | Follow a user |
| DELETE | /api/v1/network/follow/{user_id}/ | Unfollow a user |
| POST | /api/v1/network/block/{user_id}/ | Block a user |
| DELETE | /api/v1/network/block/{user_id}/ | Unblock a user |
| GET | /api/v1/network/blocked/ | List blocked users |
| POST | /api/v1/reports/ | Report a profile/post/comment/job/hospital |
| Feed & Posts | | |
| GET | /api/v1/feed/home/ | Home summary |
| GET | /api/v1/feed/ | Paginated feed posts |
| POST | /api/v1/feed/posts/ | Create post |
| PATCH | /api/v1/feed/posts/{id}/ | Edit own post |
| DELETE | /api/v1/feed/posts/{id}/ | Delete own post |
| POST | /api/v1/feed/posts/{id}/like/ | Like / unlike a post |
| GET | /api/v1/feed/posts/{id}/comments/ | Get comments |
| POST | /api/v1/feed/posts/{id}/comments/ | Add comment |
| PATCH | /api/v1/feed/comments/{id}/ | Edit comment / reply |
| DELETE | /api/v1/feed/comments/{id}/ | Delete comment / reply |
| POST | /api/v1/feed/comments/{id}/reply/ | Reply to comment |
| Communities | | |
| GET | /api/v1/communities/ | List specialty communities |
| GET | /api/v1/communities/{id}/ | Community detail |
| POST | /api/v1/communities/{id}/join/ | Join community |
| DELETE | /api/v1/communities/{id}/leave/ | Leave community |
| GET | /api/v1/communities/{id}/posts/ | Community posts |
| POST | /api/v1/communities/{id}/posts/ | Post in community |
| Hospitals | | |
| POST | /api/v1/hospitals/register/ | Register new hospital |
| GET | /api/v1/hospitals/me/ | Get my hospital profile |
| PATCH | /api/v1/hospitals/me/ | Update hospital profile |
| POST | /api/v1/hospitals/me/verification/submit/ | Submit hospital verification documents |
| GET | /api/v1/hospitals/me/verification/ | Get hospital verification status |
| POST | /api/v1/hospitals/me/branches/ | Add branch |
| GET | /api/v1/hospitals/me/branches/ | List branches |
| PATCH | /api/v1/hospitals/me/branches/{id}/ | Update branch |
| DELETE | /api/v1/hospitals/me/branches/{id}/ | Deactivate branch |
| POST | /api/v1/hospitals/me/departments/ | Add department |
| GET | /api/v1/hospitals/me/departments/ | List departments |
| POST | /api/v1/hospitals/me/users/ | Add hospital user |
| GET | /api/v1/hospitals/me/users/ | List hospital users |
| PATCH | /api/v1/hospitals/me/users/{id}/ | Update user role/branch/status |
| DELETE | /api/v1/hospitals/me/users/{id}/ | Revoke user membership |
| POST | /api/v1/hospitals/me/invite-user/ | Invite HR / Recruiter |
| GET | /api/v1/hospitals/me/staff/ | List staff |
| POST | /api/v1/hospitals/me/upload-logo/ | Upload logo |
| GET | /api/v1/hospitals/{id}/ | View public hospital profile |
| Jobs | | |
| POST | /api/v1/jobs/ | Create job posting |
| PATCH | /api/v1/jobs/{id}/ | Update job posting |
| POST | /api/v1/jobs/{id}/publish/ | Publish a draft job |
| POST | /api/v1/jobs/{id}/close/ | Close a job posting |
| GET | /api/v1/jobs/ | List jobs |
| GET | /api/v1/jobs/{id}/ | Get job details |
| POST | /api/v1/jobs/{id}/save/ | Save a job |
| DELETE | /api/v1/jobs/{id}/save/ | Unsave a job |
| GET | /api/v1/doctors/me/saved-jobs/ | List saved jobs |
| GET | /api/v1/jobs/my-applications/ | My applications |
| POST | /api/v1/jobs/{id}/apply/ | Apply to job |
| POST | /api/v1/jobs/{id}/withdraw/ | Withdraw application |
| GET | /api/v1/jobs/{id}/applications/ | View applicants |
| PATCH | /api/v1/jobs/applications/{id}/status/ | Update application status |
| POST | /api/v1/applications/{id}/notes/ | Add internal note |
| GET | /api/v1/applications/{id}/notes/ | List application notes |
| POST | /api/v1/applications/{id}/interview/ | Schedule interview |
| PATCH | /api/v1/applications/{id}/interview/{interview_id}/ | Update interview outcome |
| POST | /api/v1/applications/{id}/offer/ | Send offer |
| POST | /api/v1/applications/{id}/invite/ | Invite doctor to apply |
| GET | /api/v1/jobs/{id}/matches/ | Get matched doctors for a job |
| GET | /api/v1/doctors/me/job-recommendations/ | Get recommended jobs for doctor |
| Master Data | | |
| GET | /api/v1/masters/specialties/ | List specialties |
| GET | /api/v1/masters/qualifications/ | List qualifications |
| GET | /api/v1/masters/job-types/ | List job types |
| GET | /api/v1/masters/shift-types/ | List shift types |
| Availability | | |
| POST | /api/v1/availability/ | Post availability |
| GET | /api/v1/availability/me/ | List my availabilities |
| PATCH | /api/v1/availability/{id}/ | Update availability |
| DELETE | /api/v1/availability/{id}/ | Deactivate availability |
| GET | /api/v1/availability/{id}/slots/ | List slots |
| POST | /api/v1/availability/{id}/slots/ | Add slot |
| PATCH | /api/v1/availability/slots/{slot_id}/ | Update a slot |
| DELETE | /api/v1/availability/slots/{slot_id}/ | Delete a slot |
| GET | /api/v1/availability/preferences/ | Get availability preferences |
| PUT | /api/v1/availability/preferences/ | Update availability preferences |
| Shifts | | |
| POST | /api/v1/shifts/requirements/ | Post shift requirement |
| GET | /api/v1/shifts/requirements/ | List open requirements |
| PATCH | /api/v1/shifts/requirements/{id}/ | Update shift requirement |
| GET | /api/v1/shifts/requirements/mine/ | My hospital's requirements |
| POST | /api/v1/shifts/requirements/{id}/match/ | Get matched doctors |
| GET | /api/v1/shifts/requirements/{id}/matched-doctors/ | Get matched doctors |
| POST | /api/v1/shifts/requirements/{id}/request/ | Doctor requests shift |
| PATCH | /api/v1/shifts/requests/{id}/respond/ | Doctor accepts/declines |
| PATCH | /api/v1/shifts/requests/{id}/confirm/ | Hospital confirms |
| PATCH | /api/v1/shifts/requests/{id}/complete/ | Mark completed |
| PATCH | /api/v1/shifts/requests/{id}/cancel/ | Cancel request |
| GET | /api/v1/shifts/requests/{id}/history/ | Shift request state history |
| GET | /api/v1/shifts/requests/mine/ | My shift requests |
| Messaging | | |
| POST | /api/v1/messages/conversations/ | Start conversation |
| GET | /api/v1/messages/conversations/ | List conversations |
| GET | /api/v1/messages/conversations/{id}/messages/ | Get messages |
| POST | /api/v1/messages/conversations/{id}/messages/ | Send message |
| POST | /api/v1/messages/conversations/{id}/read/ | Mark conversation as read |
| POST | /api/v1/messages/conversations/{id}/report/ | Report conversation |
| POST | /api/v1/messages/conversations/{id}/block/ | Block conversation |
| DELETE | /api/v1/messages/conversations/{id}/block/ | Unblock conversation |
| Devices & Notifications | | |
| POST | /api/v1/devices/ | Register device for push notifications |
| DELETE | /api/v1/devices/{id}/ | Revoke device token |
| GET | /api/v1/notifications/ | List notifications |
| GET | /api/v1/notifications/unread-count/ | Unread count |
| PATCH | /api/v1/notifications/{id}/read/ | Mark as read |
| POST | /api/v1/notifications/read-all/ | Mark all as read |
| GET | /api/v1/notification-preferences/ | Get notification preferences |
| PUT | /api/v1/notification-preferences/ | Update notification preferences |
| Admin CRM | | |
| GET | /api/v1/admin/dashboard/ | Platform overview metrics |
| GET | /api/v1/admin/doctors/verification-queue/ | Doctor verification queue |
| GET | /api/v1/admin/doctors/verification-cases/{id}/ | Verification case detail |
| POST | /api/v1/admin/doctors/verification-cases/{id}/approve/ | Approve doctor verification |
| POST | /api/v1/admin/doctors/verification-cases/{id}/reject/ | Reject doctor verification |
| POST | /api/v1/admin/doctors/verification-cases/{id}/resubmit/ | Allow resubmission |
| GET | /api/v1/admin/hospitals/verification-queue/ | Hospital verification queue |
| POST | /api/v1/admin/hospitals/verification-cases/{id}/approve/ | Approve hospital verification |
| POST | /api/v1/admin/hospitals/verification-cases/{id}/reject/ | Reject hospital verification |
| GET | /api/v1/admin/users/ | List all users |
| POST | /api/v1/admin/users/{id}/restrict/ | Restrict user |
| POST | /api/v1/admin/users/{id}/suspend/ | Suspend user |
| POST | /api/v1/admin/users/{id}/restore/ | Restore user |
| POST | /api/v1/admin/users/{id}/deactivate/ | Deactivate user |
| GET | /api/v1/admin/reports/ | Reports queue |
| GET | /api/v1/admin/reports/{id}/ | Report detail |
| POST | /api/v1/admin/reports/{id}/action/ | Action a report |
| POST | /api/v1/admin/reports/{id}/dismiss/ | Dismiss a report |
| POST | /api/v1/admin/reports/{id}/escalate/ | Escalate a report |
| POST | /api/v1/admin/posts/{id}/moderate/ | Moderate a post |
| POST | /api/v1/admin/jobs/{id}/moderate/ | Moderate a job |
| POST | /api/v1/admin/communities/ | Create specialty community |
| PATCH | /api/v1/admin/communities/{id}/ | Update community |
| POST | /api/v1/admin/communities/{id}/archive/ | Archive community |
| GET | /api/v1/admin/audit-logs/ | Audit log records |
| GET | /api/v1/admin/analytics/overview/ | Analytics overview |
| Support | | |
| POST | /api/v1/support/tickets/ | Create support ticket |
| GET | /api/v1/support/tickets/ | List my support tickets |
| GET | /api/v1/support/tickets/{id}/ | Ticket detail + messages |
| POST | /api/v1/support/tickets/{id}/messages/ | Add message to ticket |
| PATCH | /api/v1/admin/support/tickets/{id}/ | Update ticket status (admin) |
| POST | /api/v1/admin/support/tickets/{id}/resolve/ | Resolve ticket |
| Billing | | |
| GET | /api/v1/billing/plans/ | List billing plans |
| GET | /api/v1/billing/subscription/ | Current hospital subscription |
| POST | /api/v1/billing/subscription/ | Subscribe to a plan |
| PATCH | /api/v1/billing/subscription/ | Update/cancel subscription |
| GET | /api/v1/billing/invoices/ | List invoices |
| GET | /api/v1/billing/invoices/{id}/ | Invoice detail |
| POST | /api/v1/billing/webhooks/{provider}/ | Payment webhook (idempotent) |
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Client │────▶│ Send │────▶│ Verify │────▶│ JWT │
│ │ │ OTP │ │ OTP │ │ Tokens │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│
▼
┌─────────────┐
│ API Calls │
│ with JWT │
└─────────────┘
- HTTPS enforced via
HTTPSRedirectMiddleware+ nginx SSL termination - Rate limiting via
slowapion auth, search, messaging and report endpoints - CORS restricted to allowed origins in production
- Trusted host middleware enabled in production
- Data encryption for sensitive fields via
apps/core/services/encryption.py(Fernet/AES-256)
Sensitive fields are encrypted at rest using DataEncryption in apps/core/services/encryption.py. The encryption key is sourced from DJANGO_SECRET_KEY via environment variable — never hardcoded.
# Run all tests
pytest
# Run specific test file
pytest tests/test_auth.py
# Run with coverage
pytest --cov=fastapi_app --cov=apps tests/
# Generate coverage report
pytest --cov=fastapi_app --cov=apps --cov-report=html tests/See tests/ directory for full test suite including:
test_auth.py— OTP, login, token rotationtest_doctors.py— Profile, verification, searchtest_jobs.py— Job posting, apply, pipelinetest_availability.py— Slots, shift lifecycletest_security_rbac.py— 21 RBAC scenarios (see Section 21H)
| Problem | Cause | Fix |
|---|---|---|
django.db.utils.OperationalError |
PostgreSQL not running | sudo service postgresql start |
ModuleNotFoundError: No module named 'django' |
Virtualenv not activated | source venv/bin/activate |
| FastAPI returns 401 on all requests | JWT secret mismatch | Ensure JWT_SECRET_KEY matches in .env |
| Celery tasks not executing | Redis not running | redis-server or docker-compose up redis |
postgis extension missing |
PostGIS not installed | sudo apt install postgresql-16-postgis-3 |
| OTP SMS not delivered | Invalid SMS_API_KEY |
Check provider dashboard for key validity |
# Django logs
docker-compose logs backend
# FastAPI logs
docker-compose logs fastapi
# Celery logs
docker-compose logs celery
# All services
docker-compose logs -f- Phone + password registration & login
- OTP-based authentication
- JWT session management with refresh rotation & revocation
- Doctor profile with NMC verification (UNVERIFIED → PENDING → VERIFIED → REJECTED → RESUBMISSION)
- Doctor qualifications, experience & hospital affiliations
- Doctor professional status & privacy settings
- Doctor search (name / specialty / city / experience)
- Feed posts (UPDATE / CASE / ARTICLE / PHOTO) with patient-privacy confirmation
- Post likes, comments & threaded replies
- Doctor connections (send / accept / decline / withdraw)
- Follow / unfollow users
- Block / unblock users
- Home summary API (stats, urgent jobs, suggested doctors)
- Hospital follow
- Hospital registration, branches, departments, staff (ADMIN/HR/RECRUITER roles)
- Hospital verification workflow
- Job posting (DRAFT → PUBLISHED → CLOSED) & one-tap apply
- Job save / unsave
- Recruitment CRM pipeline with full history log (notes, interview, offer)
- Doctor availability & slot management
- Availability preferences
- Shift requirements & full shift lifecycle (request/accept/confirm/complete/cancel)
- Shift state history
- Doctor-shift matching algorithm (configurable weights via matching_configs)
- Job-doctor matching with score components & reasons
- Direct messaging (conversations + messages)
- Messaging read receipts, block/report conversation
- Device token registration for push notifications
- Notifications (list, read, unread count, preferences)
- File upload with signed URLs (photos, logos, credentials)
- Universal search (doctors / hospitals / jobs / communities)
- Reports — DB-backed
Reportmodel with severity, reason codes, lifecycle - Django Admin panel
- Docker Compose setup
- Admin CRM — verification queues with turnaround time
- Admin CRM — user management (restrict/suspend/restore/deactivate) with reason + AuditLog
- Admin CRM — content moderation (posts/jobs) with reason + AuditLog
- Admin CRM — reports queue with severity/target_type filters + action/dismiss/escalate
- Admin CRM — community management with AuditLog
- Admin CRM — audit logs with action/target_type filters
- Admin CRM — full operational analytics (turnaround, funnel, shift rates, resolution time)
- Admin CRM — support tickets (DB-backed SupportTicket/SupportMessage, internal notes)
- Admin CRM — matching config management (versioned weights, activate)
- Admin CRM — settings CRUD (specialties, qualifications)
- Admin CRM — Super Admin endpoints (create/deactivate/update-permissions for admin users)
- Admin CRM — hospital verification case detail endpoint
- Admin CRM — user detail endpoint
- Admin CRM — support ticket assign endpoint
- Module 6 — Doctor Mobile App spec: navigation, onboarding flow, verification-gated actions
- Module 6 —
languages+career_preferencesfields on DoctorProfile - Module 6 — CASE post patient-privacy confirmation required (
patient_privacy_confirmed) - Module 6 — Server-side PII detection on posts (phone/Aadhaar/email/patient ID)
- Module 6 —
match_score+match_factorsreturned on job list for doctors - Module 6 — Slot overlap check against accepted/confirmed shifts (409)
- Module 6 — Deactivate availability blocked if active shift requests exist (409)
- Module 6 — Account deletion cascades: withdraw applications, deactivate availability, cancel shift requests
- Spec 02 —
DoctorAffiliationmodel with proper DB table (replaces JSONB metadata) - Spec 02 —
Followmodel (DB-backed doctor/hospital follow relationship) - Spec 02 —
Blockmodel (DB-backed user block; replaces metadata array) - Spec 02 —
JobSavemodel (DB-backed job saves; replaces metadata array) - Spec 02 —
ShiftStatusHistorymodel (immutable shift state audit trail) - Spec 02 —
DeviceTokenmodel (FCM/APNs push tokens per device) - Spec 02 —
NotificationPreferencemodel (per-user per-event channel preferences) - Spec 02 —
Plan/Subscription/Entitlementbilling models - Spec 02 —
Invoice/Paymentbilling models with provider ID + refund tracking - Spec 02 — Privacy enforcement rules documented and enforced at query/serialization layer
- Spec 02 — Security & infrastructure checklist documented
- Spec 02 — API contract standard (method, auth role, schema, errors, pagination, side effects, audit event)
- Gap Audit —
is_super_adminfield onUsermodel (explicit Platform Admin vs Super Admin distinction) - Gap Audit —
require_super_admin()dependency independencies.py(separate fromrequire_admin()) - Gap Audit — Super Admin endpoints: create/deactivate/update-permissions for admin users (
/api/v1/admin/super/admin-users/) - Gap Audit — Matching config create + activate restricted to Super Admin only
- Gap Audit — Super Admin self-deactivation blocked (400)
- Gap Audit — Platform Admin cannot touch Super Admin accounts (403)
- Gap Audit —
permissionsJSONField onHospitalUserfor custom per-user permission overrides - Gap Audit —
ReportEvidencemodel (report_evidencetable) with private S3 file reference - Gap Audit —
create_admin.pyproduction credential guard (blocks default phone/password inDJANGO_ENV=production) - Gap Audit —
create_admin.py--superflag to setis_super_admin=True - Gap Audit — Security/RBAC test suite (
tests/test_security_rbac.py) covering 13 audit scenarios - Gap Audit — Community moderators deferred to Phase 2 (documented below)
- Gap Audit — Geospatial: JSONB coordinates used for V1; PostGIS
PointFielddeferred to Phase 2 - Gap Audit — Base64 fields (
photo_base64,cover_base64,logo_base64) marked deprecated; production path isfile_id+ S3 - Billing — plans, subscription, invoices, webhooks, refunds (Hospital Admin only)
- Support — user tickets, admin ticket management, internal notes, assign, resolve
- Masters — specialties, qualifications, councils, job types, shift types
- Communities — list, join/leave, posts (Phase 2: moderators)
- Candidate discovery — hospital HR can search/filter doctors with availability filters
- Community moderator add/remove APIs —
POST/DELETE /api/v1/admin/communities/{id}/moderators/,CommunityMember.is_moderatorfield, migrationcore/0007 - Geospatial radius search (Haversine/JSONB) —
GET /api/v1/search/doctors/nearby/+GET /api/v1/search/hospitals/nearby/ - WebSocket real-time messaging — Django Channels 4.1,
channels-redis,apps/messaging/consumers.py,routing.py, ASGI updated - Super Admin MFA/2FA (TOTP via
pyotp) —fastapi_app/routers/mfa.py: setup, verify, login, disable, status endpoints;User.totp_secret+User.mfa_enabledfields, migrationaccounts/0004 - iOS APNs push notification support —
devices.pyrewritten to useDeviceTokenDB model;platform: APNSaccepted,bundle_idfield, update-on-re-register logic,GET /api/v1/devices/list endpoint; migrationnotifications/0004 - Hospital verification via document OCR —
apps/core/services/ocr.py(AWS Textract);POST /api/v1/admin/hospitals/verification-cases/{id}/ocr/extracts text + fields;POST .../ocr/confirm/approves after review; audit logged; graceful fallback in dev mode - PostGIS
PointFieldgeospatial —USE_POSTGIS=trueenablesdjango.contrib.gis+PointField(srid=4326, geography=True)onDoctorProfileandHospital; migrationsdoctors/0014+hospitals/0007runCREATE EXTENSION IF NOT EXISTS postgis+AlterField; JSONB Haversine fallback preserved when disabled - Specialty communities group discussions UI — backend API complete (
GET/POST /api/v1/communities/{id}/posts/); frontend/mobile UI deferred to Phase 3
- CME credit tracking —
CMEEvent+CMECreditmodels;GET/POST /api/v1/cme/events/,GET/POST/DELETE /api/v1/cme/credits/,GET /api/v1/cme/credits/summary/; migrationcore/0008 - Billing & subscription management (feature-flagged) —
Plan/Subscription/Entitlement/Invoice/Paymentmodels + full billing router already implemented - Peer endorsements & skill recommendations —
Endorsementmodel;POST /api/v1/endorsements/,GET /api/v1/endorsements/received/{doctor_id}/, skill summary + delete; migrationcore/0008 - Second opinion & case referral network —
SecondOpinionRequestmodel;POST /api/v1/second-opinions/, sent/received lists, respond, complete, cancel; migrationcore/0008 - Hospital analytics dashboard (applications, hires, shift fill rate) —
HospitalAnalyticsSnapshotmodel + live aggregation;GET /api/v1/analytics/hospital/dashboard/,GET /api/v1/analytics/hospital/snapshots/; migrationcore/0008 - Multi-language support (English, Hindi, Tamil, Telugu) —
preferred_languagefield onDoctorProfile(BCP-47:en/hi/ta/te); migrationdoctors/0015 - Telemedicine / video consultation scheduling —
TelemedicineSessionmodel;POST /api/v1/telemedicine/sessions/, list, get, status update; migrationcore/0008
Audit completed against the DOC-CONNECT — FINAL BACKEND GAP AUDIT & FIX REQUIREMENTS specification.
| Item | Evidence |
|---|---|
| Doctor verification workflow (UNVERIFIED→PENDING→VERIFIED→REJECTED→RESUBMISSION) | DoctorProfile.verification_status + admin endpoints |
| Hospital verification workflow | Hospital.verification_status + admin endpoints |
HospitalUser model with user, role, hospital_id, branch_id, department_id, permissions, status |
apps/hospitals/models.py + migration 0005 |
Branch User architecture via HospitalUser.role + branch_id (no duplicate user_type) |
Documented in Section 3.0 |
Hospital scope isolation — /me/ endpoints resolve hospital from authenticated user's HospitalUser |
fastapi_app/routers/hospitals.py — _get_active_admin_hu / _get_active_hu |
Inactive HospitalUser blocked — status='ACTIVE' enforced on every hospital endpoint |
_get_active_admin_hu / _get_active_hu helpers |
Report model with severity, reason codes, lifecycle, reviewer, resolution |
apps/core/models.py |
ReportEvidence model — private S3 file reference, never public |
apps/core/models.py + migration core/0005 |
AuditLog model — immutable, written on every privileged action |
apps/core/models.py + admin.py |
JWT rotation + RefreshSession revocation |
apps/accounts/models.py + auth.py router |
Suspended/deleted user blocked at get_current_user |
fastapi_app/dependencies.py |
MatchingConfig — versioned weights, never hardcoded |
apps/core/models.py |
Billing models (Plan, Subscription, Entitlement, Invoice, Payment) |
apps/core/models.py |
is_super_admin field on User |
apps/accounts/models.py + migration accounts/0002 |
require_admin() / require_super_admin() in dependencies.py |
fastapi_app/dependencies.py |
Super Admin endpoints (/super/admin-users/) |
fastapi_app/routers/admin.py |
| Super Admin self-deactivation blocked (400) | deactivate_admin_user endpoint |
| Platform Admin cannot suspend/restrict/deactivate Super Admin (403) | _update_user_status_with_audit guard |
dismiss_report / escalate_report FK assignment via .save() (not .update()) |
fastapi_app/routers/admin.py |
create_admin.py production credential guard |
scripts/create_admin.py — DJANGO_ENV=production block |
| Billing 403 for non-HOSPITAL_ADMIN | fastapi_app/routers/billing.py |
| Hospital A cannot access Hospital B jobs/staff | jobs.py — job__hospital=hu.hospital scope check |
photo_base64, cover_base64, logo_base64 marked deprecated |
apps/doctors/models.py, apps/hospitals/models.py |
| Community moderators deferred to Phase 2 with explicit code comment | fastapi_app/routers/admin.py |
| Item | Gap Found | Fix Applied |
|---|---|---|
dismiss_report / escalate_report |
Used .update() with FK object — silently fails in Django |
Changed to .get() + .save() with explicit field list |
| Platform Admin → Super Admin protection | _update_user_status_with_audit had no Super Admin guard |
Added if target.is_super_admin and not performed_by.is_super_admin: raise 403 |
| Community moderators documentation | README claimed "manage moderators" as live | Added Phase 2 note in admin.py and README |
| Base64 fields | No deprecation notice in models | Added # DEPRECATED: comments on all three base64 fields |
| Item | Implementation |
|---|---|
| RBAC tests: Platform Admin cannot suspend/restrict/deactivate Super Admin | tests/test_security_rbac.py — tests 19, 20 |
| RBAC test: Platform Admin cannot modify Super Admin permissions | tests/test_security_rbac.py — test 20 |
| RBAC test: Super Admin can suspend regular user | tests/test_security_rbac.py — test 21 |
| Item | Reason | Where Documented |
|---|---|---|
PostGIS PointField geospatial |
V1 uses Haversine/JSONB; PostGIS requires django.contrib.gis + DB extension + data migration |
README Section 10.4 + roadmap |
| Hospital verification via document OCR | Third-party OCR provider not yet selected | Phase 3 roadmap |
| CME credit tracking | Product spec not finalized | Phase 3 roadmap |
| Peer endorsements | Product spec not finalized | Phase 3 roadmap |
| Migration | App | Change |
|---|---|---|
accounts/0002_add_is_super_admin.py |
accounts |
is_super_admin BooleanField(default=False) on users |
accounts/0004_add_mfa_fields.py |
accounts |
totp_secret CharField + mfa_enabled BooleanField on users |
hospitals/0005_add_hospitaluser_permissions.py |
hospitals |
permissions JSONField(default=dict) on hospital_users |
core/0005_add_report_evidence.py |
core |
New report_evidence table |
core/0007_community_moderator_mfa.py |
core |
is_moderator BooleanField(default=False) on community_members |
| Method | Endpoint | Change |
|---|---|---|
| POST | /api/v1/admin/super/admin-users/ |
Added — Super Admin creates Platform/Super Admin user |
| POST | /api/v1/admin/super/admin-users/{id}/deactivate/ |
Added — Super Admin deactivates admin user |
| PATCH | /api/v1/admin/super/admin-users/{id}/permissions/ |
Added — Super Admin updates is_super_admin flag |
| POST | /api/v1/admin/matching-configs/ |
Changed — requires Super Admin (not Platform Admin) |
| POST | /api/v1/admin/matching-configs/{id}/activate/ |
Changed — requires Super Admin (not Platform Admin) |
| GET | /api/v1/billing/plans/ |
Changed — requires HOSPITAL_ADMIN or ADMIN; HR/Doctor = 403 |
| Endpoint Group | Before | After |
|---|---|---|
| All admin endpoints | user_type == 'ADMIN' |
require_admin() — Platform Admin or Super Admin |
| Matching config create/activate | Any admin | require_super_admin() — Super Admin only |
Admin user management (/super/) |
Not implemented | require_super_admin() — Super Admin only |
| Super Admin self-deactivation | Not guarded | Returns 400 |
| Platform Admin acting on Super Admin | Not guarded | Returns 403 |
File: tests/test_security_rbac.py — 21 test cases total
| Test | Scenario |
|---|---|
test_doctor_cannot_access_admin_dashboard |
Doctor → Admin API = 403 |
test_doctor_cannot_access_admin_users |
Doctor → Admin users list = 403 |
test_suspended_user_blocked |
Suspended user → protected API = 403 |
test_invalid_token_rejected |
Invalid token → 401 |
test_no_token_rejected |
No token → 403 |
test_platform_admin_cannot_create_admin_user |
Platform Admin → /super/ = 403 |
test_platform_admin_cannot_activate_matching_config |
Platform Admin → matching config activate = 403 |
test_platform_admin_cannot_deactivate_admin_user |
Platform Admin → deactivate admin = 403 |
test_super_admin_can_access_dashboard |
Super Admin → dashboard = 200 |
test_super_admin_cannot_deactivate_own_account |
Super Admin self-deactivate = 400 |
test_hospital_a_cannot_access_hospital_b_staff |
Hospital A → Hospital B staff = not in results |
test_branch_user_identified_via_hospital_user |
Branch User = HospitalUser.role + branch_id |
test_hr_cannot_access_billing |
HR → billing = 403 |
test_revoked_refresh_token_rejected |
Revoked refresh → 401 |
test_report_evidence_model_exists |
ReportEvidence model + DB table exists |
test_user_has_is_super_admin_field |
User.is_super_admin field exists |
test_hospital_user_has_permissions_field |
HospitalUser.permissions field exists |
test_unauthenticated_doctor_search_blocked |
No token → search = 403 |
test_hr_cannot_access_billing_plans |
HR → /billing/plans/ = 403 |
test_doctor_cannot_access_billing_plans |
Doctor → /billing/plans/ = 403 |
test_hospital_a_cannot_access_hospital_b_jobs |
Hospital A → Hospital B job close = 403/404 |
test_inactive_hospital_user_cannot_manage_staff |
Inactive HospitalUser → staff management = 403 |
test_report_evidence_not_publicly_accessible |
Private evidence file → requires auth |
test_doctor_cannot_access_another_doctors_private_profile |
Doctor A → Doctor B private profile = 404/403 |
test_platform_admin_cannot_suspend_super_admin |
Platform Admin → suspend Super Admin = 403 |
test_platform_admin_cannot_restrict_super_admin |
Platform Admin → restrict Super Admin = 403 |
test_platform_admin_cannot_deactivate_super_admin |
Platform Admin → deactivate Super Admin = 403 |
test_platform_admin_cannot_modify_super_admin_permissions |
Platform Admin → modify Super Admin permissions = 403 |
test_super_admin_can_suspend_regular_user |
Super Admin → suspend regular user = 200 |
| Decision | Owner | Notes |
|---|---|---|
| Community moderator workflow | Product | Define moderator role, permissions, add/remove flow before Phase 2 |
| PostGIS migration strategy | Engineering | Decide on django.contrib.gis adoption; requires DB extension + data migration for existing JSONB coordinates |
| Super Admin MFA/2FA provider | Engineering/Security | Select TOTP library (e.g. pyotp) or SMS 2FA; required before production Super Admin accounts |
Custom HospitalUser.permissions schema |
Product | Define allowed permission keys and values before enabling custom permission overrides |
| Sensitive data export approval chain | Product/Legal | Define who approves exports, what data is exportable, audit requirements |
| Base64 field deprecation timeline | Engineering | Set a migration deadline for clients still using photo_base64/cover_base64/logo_base64 |
-
Code Style
- Python: Black, isort, flake8
- Use type hints
- Write docstrings
-
Branch Strategy
main- Productiondevelop- Developmentfeature/*- New featuresfix/*- Bug fixes
-
Commit Messages
feat:New featurefix:Bug fixdocs:Documentationtest:Testsrefactor:Code refactor
- Fork the repository
- Create feature branch
- Write tests
- Update documentation
- Submit pull request
This project is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
- Email: support@docconnect.com
- Website: https://docconnect.com
- GitHub: https://github.com/pkdubey/docconnect
DocConnect — Building Trusted Doctor Professional Network
Last updated: July 2025 | Version 2.4 | Maintained by Pavan Kumar Dubey