Vandana reddy Balannagari requested to merge feat/auto-doc-assign into develop Apr 21, 2026

Merge Request

Overview

This MR introduces an Intelligent Consultation Workflow System for the medical camp application. It enhances patient handling by incorporating specialization-based routing, intelligent doctor suggestion, and controlled manual assignment.

The objective is to:

Route patients based on specialization
Suggest appropriate doctors dynamically
Ensure controlled and validated consultation workflow
Improve system reliability and real-time visibility

What does this MR do and why?

This MR replaces the earlier auto doctor assignment approach with a rule-driven, human-controlled workflow system.

Motivation:

Avoid incorrect or random doctor assignments
Enable specialization-based patient routing
Balance doctor workload efficiently
Enforce valid queue transitions

Approach:

Introduced specialization tracking at registration level
Built intelligent doctor suggestion system
Enforced manual assignment with strict validation
Added helper API for specialization selection in frontend

Trade-offs:

Increased frontend interaction (modal selection)
Additional API calls before assignment
Gains better control, accuracy, and scalability

Changes Made

Added specialization column to consultation_queue table
Enhanced patient registration API to accept specialization
Implemented intelligent doctor suggestion system
Enforced manual doctor assignment (removed auto-assign)
Added validation for consultation transitions
Introduced active specializations API
Enhanced SocketIO payloads with specialization data
Added normalization and unit tests for robustness

Technical Details

Database Changes

Modified consultation_queue:
- Added specialization field
- Used for filtering and assignment decisions

API Enhancements

POST /api/v1/patients/{book_no}/register
- Accepts specialization
- Initializes patient queue entry
- Handles re-registration:
  - Updates specialization
  - Clears existing doctor assignment

GET /api/v1/queue/suggest-doctor
- Automatically detects patient specialization using book_no
- Filters doctors:
  - Assigned to current camp
  - Actively logged in
- Calculates workload:
  - in_consultation
  - waiting
- Returns sorted list (least busy first)

PUT /api/v1/queue/status-update
- Requires doctor_id for in_consultation
- Blocks invalid transitions
- Enforces manual assignment
- Removes background auto-assignment logic

GET /api/v1/doctors/active-specializations
- Returns unique list of specializations
- Filters only:
  - Active camp doctors
  - Logged-in doctors
- Used for frontend specialization selection

Architecture Decisions

Implemented state-machine-like workflow validation
Replaced auto assignment with human-in-the-loop control
Backend acts as:
- Validation layer
- Decision engine
- Queue manager

Real-Time Communication

Updated SocketIO broadcaster:
- Added requested_specialization field
Ensures all clients stay synchronized with queue updates

Data Integrity & Robustness

Applied normalization (trim + lower) for specialization
Prevents mismatches due to casing or whitespace
Added unit tests for:
- Doctor filtering
- Load calculation
- Assignment validation

Type of Change

Related Issues / References

Implements specialization-based consultation workflow
Replaces legacy auto doctor assignment system
Improves queue management and doctor allocation logic

Screenshots or Screen Recordings

Verified APIs via Swagger/Postman:
- Registration with specialization
- Doctor suggestion
- Status update with doctor assignment

How to Validate Locally

POST /api/v1/patients/{book_no}/register?specialization=dentist

Fetch suggested doctors:

GET /api/v1/queue/suggest-doctor?book_no={book_no}

Assign doctor and start consultation:

PUT /api/v1/queue/status-update?book_no={book_no}&status=in_consultation&doctor_id={doctor_id}

Fetch available specializations:

GET /api/v1/doctors/active-specializations

Expected Behavior:

Patient is registered with specialization
Doctors are filtered correctly
Least busy doctor appears first
Consultation starts only after manual selection
Invalid transitions are blocked

Testing Done

Unit tests added/updated
API endpoint tests passing

Test Cases Covered:

Scenario	Expected Result	Status
Register patient with specialization	Success	✅
Suggest doctor based on specialization	Filtered list	✅
Doctor sorting by workload	Correct order	✅
Start consultation without doctor_id	Blocked (400)	✅
Valid doctor assignment	Success	✅
Active specializations fetch	Unique filtered list	✅

Test Commands Run:

pytest
pytest tests/ -v
pytest --cov=app

Code Quality Checklist

Code Standards

Python & FastAPI Best Practices

Clean service layer
Async handling correct
Pydantic validation used
Optimized queries

API Design

RESTful structure
Proper status codes
Input validation enforced
Role-based access supported

Database & Migrations

Migration added
Reversible migration
Data integrity maintained

Security

No sensitive data exposure
ORM used (safe queries)
Input sanitization applied

Error Handling

Graceful error responses
Proper logging implemented

Documentation

API documentation updated
Code comments added
README update (optional)

Known Limitations / Technical Debt

Frontend must implement modal-based doctor selection
Real-time updates depend on SocketIO client integration

Additional Notes

Introduces a core workflow engine for consultation system
Designed for scalability across multiple camps
Enables future enhancements like analytics and automation

MR Acceptance Checklist

Quality & Correctness

Works as intended
No regressions
Edge cases handled

Maintainability

Clean and modular code
Easy to extend
Follows project patterns

Acceptance Review

Reviewed by teammate
Reviewed by product owner

closes #98 (closed)

feat: added the aytomated doctor assign after the registration