Typesense Search Integration

+-------------------+      +-------------------+      +------------------+
|  Frontend         |      |  Rails API        |      |  Typesense       |
|  (React Query)    | ---> |  SearchController | ---> |  Server          |
|                   |      |                   |      |                  |
|  useFacilitySearch|      |  search service   |      |  facilities_env  |
|  usePractitioner  |      |  Typesense / PG   |      |  practitioners_  |
|  Search           |      |  fallback         |      |  env             |
+-------------------+      +--------+----------+      +------------------+
                                    |
                                    v (fallback)
                           +-------------------+
                           |  PostgreSQL        |
                           |  ILIKE queries     |
                           +-------------------+

+-------------------+      +-------------------+      +------------------+
|  Model callbacks  | ---> |  TypesenseSyncQueue| ---> |  TypesenseSyncJob|
|  (after_commit)   |      |  (buffer table)   |      |  (Sidekiq)       |
+-------------------+      +-------------------+      +------------------+

# macOS (Homebrew)
brew install typesense/tap/typesense-server
typesense-server --data-dir=/tmp/typesense-data --api-key=dev_typesense_api_key

# Docker
docker run -p 8108:8108 \
  -v /tmp/typesense-data:/data \
  typesense/typesense:27.1 \
  --data-dir /data \
  --api-key=dev_typesense_api_key

rails credentials:edit

typesense_url: "https://typesense.example.com"
typesense_api_key: "your_production_api_key"

bundle exec rake typesense:health
bundle exec rake typesense:create_collections
bundle exec rake typesense:reindex

get 'facilities/search', to: 'search#facilities'
get 'practitioners/search', to: 'search#practitioners'

GET /identity/facilities/search?q=downtown&city=Bangalore&page=1&per_page=10

{
  "data": [
    {
      "id": "abc-123",
      "name": "Downtown Medical Center",
      "display_name": "Downtown Medical Center",
      "service_level": "hospital",
      "city": "Bangalore",
      "state": "Karnataka",
      "active": true,
      "specialties": ["Cardiology", "Orthopedics"],
      "offers_telemedicine": true
    }
  ],
  "meta": {
    "source": "typesense",
    "found": 42,
    "page": 1,
    "search_time_ms": 3
  }
}

GET /identity/practitioners/search?q=cardio&specialty=Cardiology&facets=true

{
  "data": [
    {
      "id": "role-456",
      "practitioner_id": "doc-789",
      "name": "Dr. Priya Sharma",
      "display_name": "Dr. Priya Sharma",
      "specialty": "Cardiology",
      "facility_name": "Heart Care Hospital",
      "city": "Mumbai",
      "consultation_fee": 800.0,
      "gender": "female",
      "qualifications": ["MBBS", "MD"],
      "languages": ["English", "Hindi"],
      "active": true
    }
  ],
  "meta": {
    "source": "typesense",
    "found": 15,
    "page": 1,
    "search_time_ms": 2
  }
}

GET /identity/facilities/search?lat=12.9716&lng=77.5946&radius=5

# backend/domains/shared/concerns/typesense_indexable.rb
module Shared::Concerns::TypesenseIndexable
  extend ActiveSupport::Concern

  included do
    after_commit :enqueue_typesense_upsert, on: %i[create update]
    after_commit :enqueue_typesense_delete, on: :destroy
  end
end

class Identity::Facility < Identity::BaseRecord
  include Shared::Concerns::TypesenseIndexable
end

bundle exec rake typesense:reindex

# Check health
bundle exec rake typesense:health

# Create collections (safe to run multiple times)
bundle exec rake typesense:create_collections

# Full reindex
bundle exec rake typesense:reindex

# Reindex only practitioners
bundle exec rake typesense:reindex_collection[practitioners]

# Check sync queue status
bundle exec rake typesense:queue_status
# Output:
#   Typesense Sync Queue:
#     Pending:     12
#     Dead letter: 0
#     Total:       1543

def facilities
  results = if typesense_enabled?
              search_facilities_typesense
            else
              search_facilities_postgres
            end

  render json: { data: results[:hits], meta: results[:meta] }
rescue ::Typesense::Error::ServerError,
       ::Typesense::Error::TimeoutError,
       ::Typesense::Error::HTTPError => e
  Rails.logger.warn("Typesense unavailable, PG fallback: #{e.message}")
  results = search_facilities_postgres
  render json: { data: results[:hits], meta: results[:meta].merge(fallback: true) }
end

import { apiClient } from '../../client';
import type {
  FacilitySearchParams,
  FacilitySearchResult,
  PractitionerSearchParams,
  PractitionerSearchResult,
  SearchResponse,
} from './types';

export async function searchFacilities(
  params?: FacilitySearchParams
): Promise<SearchResponse<FacilitySearchResult>> {
  const response = await apiClient.get<SearchResponse<FacilitySearchResult>>(
    '/identity/facilities/search',
    { params }
  );
  return response.data;
}

export async function searchPractitioners(
  params?: PractitionerSearchParams
): Promise<SearchResponse<PractitionerSearchResult>> {
  const response = await apiClient.get<SearchResponse<PractitionerSearchResult>>(
    '/identity/practitioners/search',
    { params }
  );
  return response.data;
}

import { useQuery } from '@tanstack/react-query';
import { identityKeys } from './keys';
import { searchFacilities, searchPractitioners } from './api';
import type { FacilitySearchParams, PractitionerSearchParams } from './types';

export function useFacilitySearch(params?: FacilitySearchParams) {
  return useQuery({
    queryKey: identityKeys.search.facilities(params),
    queryFn: () => searchFacilities(params),
    enabled: !!(params?.q && params.q.length >= 2) || !!(params?.lat && params?.lng),
    staleTime: 60_000,
  });
}

export function usePractitionerSearch(params?: PractitionerSearchParams) {
  return useQuery({
    queryKey: identityKeys.search.practitioners(params),
    queryFn: () => searchPractitioners(params),
    enabled:
      !!(params?.q && params.q.length >= 2) ||
      !!(params?.lat && params?.lng) ||
      !!params?.specialty,
    staleTime: 60_000,
  });
}

identityKeys.search.all()                   // ['identity', 'search']
identityKeys.search.facilities(params)      // ['identity', 'search', 'facilities', params]
identityKeys.search.practitioners(params)   // ['identity', 'search', 'practitioners', params]

import { useFacilitySearch, usePractitionerSearch } from '@kulcare/shared-services';

function DoctorFinder() {
  const [query, setQuery] = useState('');
  const [specialty, setSpecialty] = useState('');

  const { data, isLoading } = usePractitionerSearch({
    q: query,
    specialty,
    per_page: 20,
  });

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      {isLoading && <Spinner />}
      {data?.data.map((practitioner) => (
        <DoctorCard key={practitioner.id} doctor={practitioner} />
      ))}
      <p>Found {data?.meta.found} results in {data?.meta.search_time_ms}ms</p>
      {data?.meta.fallback && <p>Using fallback search (limited functionality)</p>}
    </div>
  );
}

interface FacilitySearchParams {
  q?: string;
  lat?: number;
  lng?: number;
  radius?: number;
  city?: string;
  service_level?: string;
  telemedicine?: string;
  page?: number;
  per_page?: number;
}

interface PractitionerSearchParams {
  q?: string;
  specialty?: string;
  city?: string;
  gender?: string;
  max_fee?: number;
  role_type?: string;
  lat?: number;
  lng?: number;
  radius?: number;
  facets?: string;
  page?: number;
  per_page?: number;
}

interface SearchResponse<T> {
  data: T[];
  meta: {
    source: 'typesense' | 'postgres';
    found: number;
    page: number;
    search_time_ms?: number;
    fallback?: boolean;
  };
}

# backend/domains/<domain>/services/typesense/<entity>_collection.rb
module <Domain>
  module Typesense
    class <Entity>Collection < Shared::Typesense::BaseCollection
      class << self
        def collection_name
          "<entity>_#{Rails.env}"
        end

        def schema
          {
            'name' => collection_name,
            'fields' => [
              { 'name' => 'id', 'type' => 'string' },
              { 'name' => 'name', 'type' => 'string' },
              # Add your fields here. See Typesense docs for field types:
              # string, int32, int64, float, bool, string[], geopoint
              # Use 'facet' => true for fields you want to filter on.
              # Use 'optional' => true for nullable fields.
              # Use 'index' => false for fields you only want to store, not search.
              { 'name' => 'active', 'type' => 'bool' },
              { 'name' => 'popularity_score', 'type' => 'int32' }
            ],
            'default_sorting_field' => 'popularity_score'
          }
        end

        def serialize(record)
          {
            'id' => record.id.to_s,
            'name' => record.name,
            'active' => record.active?,
            'popularity_score' => 0
          }.compact
        end

        def source_scope
          <Domain>::<Entity>.where(active: true)
        end

        protected

        def build_search_params(params)
          search = {
            'q' => params[:q].presence || '*',
            'query_by' => 'name',
            'per_page' => [(params[:per_page] || 20).to_i, 250].min,
            'page' => (params[:page] || 1).to_i
          }

          filters = []
          filters << "active:=true"
          # Add your filters here

          search['filter_by'] = filters.join(' && ') if filters.any?
          search
        end

        def default_query_by
          'name'
        end
      end
    end
  end
end

class <Domain>::<Entity> < <Domain>::BaseRecord
  include Shared::Concerns::TypesenseIndexable
end

COLLECTION_MAP = {
  'Identity::Facility' => 'Identity::Typesense::FacilitiesCollection',
  'Identity::PractitionerRole' => 'Identity::Typesense::PractitionersCollection',
  '<Domain>::<Entity>' => '<Domain>::Typesense::<Entity>Collection',
}.freeze

def typesense_collections
  [
    Identity::Typesense::FacilitiesCollection,
    Identity::Typesense::PractitionersCollection,
    <Domain>::Typesense::<Entity>Collection,
  ]
end

get '<entities>/search', to: 'search#<entities>'

bundle exec rake typesense:create_collections
bundle exec rake typesense:reindex_collection[<entity>]