Skip to content

Home

Jump to bottom
Inna Tarasyan edited this page Dec 12, 2025 · 5 revisions

PrimeDoctors — Healthcare Directory & NPI Ingestion Platform

PrimeDoctors is a Laravel 12 + Livewire 3 application that ingests the official NPI Registry (CMS/HHS) data set and transforms it into a fast, mobile-first directory of doctors, organizations, and specialties. The platform includes production-ready import commands, a complete public interface, responsive UI components, and transparent legal/about pages.

Website: https://primedoctors.store

Table of Contents

  1. Vision & Value Proposition
  2. Architecture & Tech Stack
  3. Data Model & Source of Truth
  4. Data Import Commands (Artisan)
  5. Public Pages & Flows (URLs)
  6. API & AJAX Endpoints
  7. Local Development & Build
  8. Ownership & Contact
  9. Hashtags

Vision & Value Proposition

PrimeDoctors bridges the gap between raw NPI registry data and a modern consumer-grade directory:

  • Automated ingestion keeps doctors, organizations, and specialties always fresh.
  • Powerful search: full-text, facet filters (state, city, specialty, gender), mobile autocomplete.
  • Mobile-first UX: thumb-friendly filters, full-screen search, responsive cards, accessible design.
  • Clear trust signals: privacy policy, terms, transparent data provenance, public ownership.

Architecture & Tech Stack

Backend

  • Laravel 12 (PHP 8.2)
  • Eloquent ORM
  • Controllers + JSON endpoints

Reactive UI

  • Livewire 3 components:

    • app/Livewire/DoctorsDirectory.php
    • app/Livewire/OrganizationsDirectory.php

Frontend

  • Vite 7
  • Tailwind CSS 4
  • Alpine.js
  • Axios for AJAX form submissions

Build System

  • npm run dev for the dev server
  • npm run build for production
  • composer setup complete bootstrap script

Styling

  • Tailwind utility-first
  • Custom gradients
  • Accessible filters, forms, and cards

Data Source

  • NPI Registry API v2.1 (CMS/HHS)
  • Enforces the two-filter rule for all queries

Database

  • SQLite (bundled)
  • Compatible with MySQL/PostgreSQL

Quality Tools

  • PHPUnit 11
  • Laravel Pint
  • Laravel Pail (observability/logging)

Data Model & Source of Truth

Doctors (App\Models\Doctor)

  • NPI-1 providers
  • Name, NPI, gender, taxonomy, organization name
  • City/state metadata
  • Relationship → Reviews

Organizations (App\Models\Organization)

  • NPI-2 entities
  • Name, city, state, phone
  • Inferred specialties from linked doctors

Specialties (App\Models\Specialty)

  • Taxonomy codes + descriptions
  • Populated automatically during imports

Reviews (App\Models\Review)

  • Rating + comment + name
  • Linked to doctors only

Data Provenance

All entities originate from NPI Registry API via custom Artisan import commands.

Data Import Commands (Artisan)

All commands are located in app/Console/Commands. They call https://npiregistry.cms.hhs.gov/api/ with pagination and validation.

General Rules

  • NPI API requires minimum 2 filters (state + taxonomy OR state + city).
  • Page limit: 200
  • Skip-based pagination handled automatically
  • 1s sleep between pages
  • All imports use idempotent upserts

import:doctors

Signature:

php artisan import:doctors --state=CA --taxonomy="family medicine,cardiology" --city="Los Angeles" --limit=200

Purpose: Import NPI-1 providers → Doctors table. Also extracts specialties → Specialties table.

Default behavior: If --taxonomy missing → uses a curated starter list (family medicine, cardiology, pediatrics, internal medicine, dermatology).

Filters Required:

  • --state + --taxonomy OR
  • --state + --city

import:organizations

Signature:

php artisan import:organizations --state=CA --city="Los Angeles,San Francisco" --limit=200

Purpose: Import NPI-2 organizations → Organizations table.

Filters Required:

  • --state AND at least one --city

import:specialties

Signature:

php artisan import:specialties --state=CA --taxonomy="family medicine" --city="Los Angeles" --limit=50

Purpose: Lightweight taxonomy harvesting → Specialties table.

Filters Required: Same two-filter rule.

Operational Notes

  • Progress bars show import status
  • Errors logged with HTTP status
  • Upserts prevent duplicates
  • Pagination auto-increments skip until exhausted

Public Pages & Flows (URLs)

/ — Home

  • Full-screen mobile search
  • Autocomplete specialty picker
  • Featured doctors & organizations
  • Popular specialties
  • Testimonials, articles, offers, mobile-app section
  • Partner logos

/search

  • Unified search for doctors, orgs, specialties
  • AJAX-driven (ajax-filter-form)
  • Updates #search-results container
  • Shareable URL (querystring preserved)

/doctors

  • Full directory with filters:

    • q, state, city, specialty, gender

  • AJAX rendering: HTML partials + pagination info

  • JSON mode available

  • Mobile-optimized layouts

  • Pagination: 20 per page

/doctors/{doctor}

  • Full provider profile
  • Taxonomy, location, gender, NPI
  • Booking & question modals (UI demo)
  • Review submission (AJAX)
  • Related doctors (same city + specialty)

/organizations

  • Directory with filters: q, state, city, specialty
  • AJAX list updates + city refresh
  • Organization cards show phone, city/state, specialties

/organizations/{organization}

  • Organization profile
  • Location/contact
  • Inferred specialties
  • Clinic gallery
  • “Doctors at this organization”
  • Mobile bottom action bar

/specialties

  • Paginated grid (36 per page)
  • Direct links into /doctors?specialty=...
  • Responsive layout

/about

  • Ownership & project story
  • Architecture summary
  • Transparency around data ingestion

/privacy-policy & /terms-of-use

  • Styled, structured legal pages
  • “Last updated” timestamps
  • Covers data use, rights, cookies, disclaimers

API & AJAX Endpoints

Search

GET /api/search/doctors

Lightweight autocomplete for providers.

GET /api/search/autocomplete

Unified autocomplete (doctors + orgs + specialties).

Search Result Rendering

GET /search (JSON)
GET /doctors (JSON)
GET /organizations (JSON)

Return:

  • rendered HTML partial
  • updated city options
  • pagination info
  • canonical URL

Reviews

POST /doctors/{doctor}/reviews

Creates a review via AJAX and returns updated HTML.

Local Development & Build

Setup

composer install
cp .env.example .env
php artisan key:generate

Database

php artisan migrate

Uses bundled SQLite by default.

Frontend

npm install
npm run dev

Production Build

npm run build

One-liner Full Bootstrap

composer setup

Ownership & Contact

PrimeDoctors is built and maintained solely by Inna Tarasyan (Armenia). All code, content, and data handling are personally managed.

Email: innatarasyancryptotrading@gmail.com

Hashtags

`#PrimeDoctors #Laravel #Livewire #TailwindCSS #AlpineJS #Vite #NPIRegistry #HealthcareData #DoctorDirectory #ClinicSearch #Specialties #ArtisanCommands

Clone this wiki locally