Laian Braum's Solution

[lzizn]

Description

Goal: Increase the efficiency of the front desk staff by providing a prioritized list of patients who are most likely to respond positively, reducing the time spent contacting patients who may not be available.

This API leverages patient demographics and behavioral data to compute a score (higher is better) that represents how likely a patient is to accepting an appointment offer.

Checklist:

• I have performed a self-review of my own code
• I have tested my code to prove my fix is effective or that my feature works
• I have commented my code in areas where it's hard to make the code speak for itself
• My changes breaks no tests

Implementation details

1. Data Normalization

   • A patient has different data fields, where each one has its own characteristics. Data Normalization transforms this data into a common scale, normally from 0 to 1, allowing one to evaluate and grade patients equally.

2. Multi-Criteria Decision Analysis (MCDA):

   • Weighs patient behavior and demographic factors to calculate a score.

3. Penalty Adjustment:

   • Applies a penalty of 0.1 point for every 10km above a distance of 100km from the facility, increasing the importance of distance, since the distance weight is only 10%. (I can't change the weights because it is a requirement, but it doesn't say anything about applying penalties... As one said in The Office: "I just Kobayashi Maru'd the whole thing")

4. Randomization of patients with low behavior score:

   • Patients that score poorly on behavior metrics most likely will have a overall bad score and won't be placed above the top. However, the poor behavior might be due to lack of invites, thus the need to provide such patients a chance to still be invited for appointments.

Technologies & Concepts Used

• Typescript (I started with JS and only moved to TS later)
• Node.js
• Express.js
• Jest
• Swagger
• Clean Architecture
• Multi-Criteria Decision Analysis (MCDA)
• Haversine Formula (Used for calculating distance between two coordinates).

API Endpoints

1. GET /api/patients-recommended

• Description: Returns an ordered list of patients most likely to accept an appointment.
• Parameters:
  • latitude (required): Latitude of the facility.
  • longitude (required): Longitude of the facility.
• Response:
  • A JSON array of patients with their computed scores.
• Swagger Documentation: Available at /api-docs

Installing and running

git clone https://github.com/lzizn/backend-interview.git
cd backend-interview
npm install
npm run dev # runs dev server with nodemon
# or
npm run start # transpiles from TS to JS (dist/) and runs with node

Running Tests

The project includes unit and integration tests written with Jest and supertest to ensure the reliability of core functions and avoid regression during development.

npm run test # runs all tests
npm run test:coverage # runs all tests and collects coverage report
npm run test:unit # only unit tests
npm run test:integration # only integration tests

Swagger

Access the Swagger UI and see the full API documentation on GET /api-docs

Test Coverage

This project has 100% of test coverage, including unit and integration tests.