Getting Started Guide

These are steps required to set up the project, load the initial data, and run the test suite.

Prerequisites

  • Python 3.13+

  • pip (Python package installer)

  • A virtual environment tool

Project Setup

  1. Clone the Repository

    First, clone the project repository to local machine.

    git clone https://github.com/zz-xx/ERISA-Recovery-Challenge.git

  2. Create and Activate a Virtual Environment

    Create a virtual environment. venv was used in development since it’s bundled with python but virtualenv can also be used.

    # On Windows
python -m venv env
.\\env\\Scripts\\activate

# On macOS/Linux
python3 -m venv env
source env/bin/activate

  3. Install Dependencies

    Make sure virtual environment is active. Then install all the required Python packages from the requirements.txt file.

    pip install -r requirements.txt

Database Setup and Data Loading

  1. Switch to project directory

    cd src

  2. Run Database Migrations

    Before loading data, we need to create the database schema.

    python manage.py makemigrations claims

    python manage.py migrate

  3. Load Claim Data

    Use the custom load_claim_data command to populate the database from the CSV files. This command requires the paths to the claims and details files and supports --delimiter and --mode.

    Note

    The sample data files use a pipe (|) as a delimiter.

    python manage.py load_claim_data data/claim_list_data.csv data/claim_detail_data.csv --delimiter "|"

python manage.py load_claim_data data/claim_list_data.csv data/claim_detail_data.csv --delimiter "|" --mode overwrite

    Note

    • append (default) only creates missing records and skips existing ones. Skipped counts are reported in the summary.

    • overwrite clears existing Claim data (cascades remove related details/notes), then inserts the rows from the CSVs.

    • On Windows PowerShell, escape the pipe delimiter as "`|" instead of "|".

    Caution

    Using --mode overwrite deletes all existing Claim rows and cascades to related ClaimDetail and Note records. Back up annotations/flags if you need to preserve them.

    Sample tiny CSVs for local testing are included at src/data/dummy using the | delimiter:

    python manage.py load_claim_data data/dummy/dummy_claims.csv data/dummy/dummy_details.csv --delimiter "|"

python manage.py load_claim_data data/dummy/dummy_claims.csv data/dummy/dummy_details.csv --delimiter "|" --mode overwrite

  4. Create a Superuser Account

    To log in to the application and the Django admin dashboard, create a superuser account. Follow the prompts to set a username, email, and password.

    python manage.py createsuperuser

Running the Application

Once the setup is complete, run the local development server:

python manage.py runserver

Access the application at http://127.0.0.1:8000/. Login with the username and password created in previous step.

Authentication

The main dashboard view (ClaimListView) requires authentication. Unauthenticated users are redirected to the login page (/login/). You can either:

  • Log in using the superuser created above, or

  • Visit /register/ to create a basic account, then log in.

Running the Test Suite

Run the test suite.

Run Basic Tests

This command runs all tests within the claims app and provides detailed output.

python manage.py test claims --verbosity=2

Check Test Coverage

Click to see the total test coverage. To calculate total test coverage locally, use the coverage package.

# First, run the tests under coverage monitoring
coverage run manage.py test claims

# Then, generate a simple report in the terminal
coverage report -m

# Or, generate a detailed, interactive HTML report
coverage html

The HTML report index.html will be available in the src/htmlcov directory.

Logs

Application logs are written to logs/app.log with rotation (see Django LOGGING settings). This can be helpful when running data ingestion to review summaries and any row-level errors.

CSV File Schemas

Claims CSV:

id,patient_name,billed_amount,paid_amount,status,insurer_name,discharge_date
101,Jane Smith,1200.50,1000.00,PAID,Acme Insurance,2025-09-01

Claim Details CSV:

id,claim_id,cpt_codes,denial_reason
1,101,"99214,99215","Prior authorization required"

Notes

  • Status values are normalized to upper-case and must be one of PAID, DENIED, or UNDER REVIEW.

  • The cpt_codes field expects a comma-separated list of codes. The UI renders each code as a tag.

  • In overwrite mode, deleting Claims cascades to related ClaimDetail and Note records.