Add Elasticsearch as optional search backend

.env.example

@@ -44,3 +44,11 @@ SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
 METADATA_ALBUM_CACHE_MAX_SIZE=1000
 METADATA_ARTIST_CACHE_MAX_SIZE=500
 METADATA_ROTATION_PRIORITY=2.0
+
+### Elasticsearch (optional — omit ELASTICSEARCH_URL to use PostgreSQL pg_trgm only)
+# ELASTICSEARCH_URL=http://localhost:9200
+# ELASTICSEARCH_USERNAME=
+# ELASTICSEARCH_PASSWORD=
+# ELASTICSEARCH_INDEX_PREFIX=
+# ELASTICSEARCH_PORT=9200
+# CI_ELASTICSEARCH_PORT=9201

CLAUDE.md

@@ -46,6 +46,20 @@ Server timeout is 5 seconds globally; SSE routes have no timeout.
 
 Swagger API docs are served at `/api-docs` from `app.yaml`.
 
+### Search (`apps/backend/services/search/`)
+
+Library catalog search uses a facade pattern that routes to either Elasticsearch or PostgreSQL pg_trgm:
+
+- **`elasticsearch.client.ts`** -- Singleton ES client. Returns `null` when `ELASTICSEARCH_URL` is unset (graceful degradation).
+- **`elasticsearch.indices.ts`** -- Index mapping and lifecycle (`ensureLibraryIndex()` called at startup).
+- **`elasticsearch.search.ts`** -- ES query implementations (`searchLibraryES`, `findSimilarArtistES`, `searchAlbumsByTitleES`, `searchByArtistES`). All return `LibraryArtistViewEntry[]`.
+- **`elasticsearch.sync.ts`** -- Stub for dual-write sync and bulk reindex (PR 2).
+- **`index.ts`** -- Facade: tries ES first, falls back to pg_trgm on error. Exports `searchLibrary`, `findSimilarArtist`, `searchAlbumsByTitle`, `searchByArtist`.
+
+The original pg_trgm implementations in `library.service.ts` are renamed with `pgTrgm` prefix (e.g., `pgTrgmSearchLibrary`) and re-exported via the facade under the original names. No callers need to change imports.
+
+Feature flag: set `ELASTICSEARCH_URL` to enable ES, unset to disable. Instant rollback by unsetting the env var.
+
 ### Auth Server (`apps/auth`)
 
 Express wrapper around better-auth with these plugins: admin, username, anonymous, bearer, jwt, organization.
@@ -250,6 +264,13 @@ GitHub Actions workflow (`.github/workflows/test.yml`) runs on PRs to `main`:
 - `DISCOGS_API_KEY`, `DISCOGS_API_SECRET`
 - `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
 
+### Elasticsearch (optional)
+
+- `ELASTICSEARCH_URL` -- e.g. `http://localhost:9200` (omit to disable ES and use pg_trgm only)
+- `ELASTICSEARCH_USERNAME`, `ELASTICSEARCH_PASSWORD` -- optional, for production auth
+- `ELASTICSEARCH_INDEX_PREFIX` -- optional, for test isolation (e.g. `ci_`)
+- `ELASTICSEARCH_PORT` (default 9200), `CI_ELASTICSEARCH_PORT` (default 9201)
+
 ### Slack
 
 - `SLACK_WXYC_REQUESTS_APP_ID`, `SLACK_WXYC_REQUESTS_CLIENT_ID`

apps/backend/app.ts

@@ -17,6 +17,8 @@ import { activeShow } from './middleware/checkActiveShow.js';
 import errorHandler from './middleware/errorHandler.js';
 import { requestIdMiddleware } from './middleware/requestId.js';
 import { requirePermissions } from '@wxyc/authentication';
+import { isElasticsearchEnabled, getElasticsearchClient } from './services/search/elasticsearch.client.js';
+import { ensureLibraryIndex } from './services/search/elasticsearch.indices.js';
 
 const port = process.env.PORT || 8080;
 const app = express();
@@ -73,12 +75,29 @@ app.get('/testAuth', requirePermissions({ flowsheet: ['read'] }), async (req, re
 
 //endpoint for healthchecks
 app.get('/healthcheck', async (req, res) => {
-  res.json({ message: 'Healthy!' });
+  let elasticsearch: 'disabled' | 'connected' | 'unavailable' = 'disabled';
+
+  if (isElasticsearchEnabled()) {
+    try {
+      const client = getElasticsearchClient();
+      await client!.ping();
+      elasticsearch = 'connected';
+    } catch {
+      elasticsearch = 'unavailable';
+    }
+  }
+
+  res.json({ message: 'Healthy!', elasticsearch });
 });
 
 Sentry.setupExpressErrorHandler(app);
 app.use(errorHandler);
 
+// Ensure ES index exists at startup (non-blocking — failure doesn't prevent server start)
+ensureLibraryIndex().catch((err) => {
+  console.error('[Elasticsearch] Failed to ensure library index at startup:', err);
+});
+
 const server = app.listen(port, () => {
   console.log(`listening on port: ${port}!`);
 });

apps/backend/package.json

@@ -16,6 +16,7 @@
   "author": "AyBruno",
   "license": "MIT",
   "dependencies": {
+    "@elastic/elasticsearch": "^8.19.1",
     "@sentry/node": "^10.40.0",
     "@wxyc/authentication": "*",
     "@wxyc/database": "*",

apps/backend/services/library.service.ts

@@ -323,7 +323,7 @@ function viewRowToLibraryResult(row: LibraryArtistViewEntry): LibraryResult {
  * @param limit - Maximum results to return
  * @returns Array of enriched library results
  */
-export async function searchLibrary(
+export async function pgTrgmSearchLibrary(
   query?: string,
   artist?: string,
   title?: string,
@@ -387,7 +387,7 @@ export async function searchLibrary(
  * @param threshold - Minimum similarity score (0.0 to 1.0) to accept
  * @returns Corrected artist name if a good match is found, null otherwise
  */
-export async function findSimilarArtist(artistName: string, threshold = 0.85): Promise<string | null> {
+export async function pgTrgmFindSimilarArtist(artistName: string, threshold = 0.85): Promise<string | null> {
   // Use pg_trgm similarity function to find close matches
   const query = sql`
     SELECT DISTINCT artist_name,
@@ -424,7 +424,7 @@ export async function findSimilarArtist(artistName: string, threshold = 0.85): P
  * @param limit - Maximum results to return
  * @returns Array of enriched library results
  */
-export async function searchAlbumsByTitle(albumTitle: string, limit = 5): Promise<EnrichedLibraryResult[]> {
+export async function pgTrgmSearchAlbumsByTitle(albumTitle: string, limit = 5): Promise<EnrichedLibraryResult[]> {
   const query = sql`
     SELECT *,
       similarity(${library_artist_view.album_title}, ${albumTitle}) as sim
@@ -467,7 +467,7 @@ export async function searchAlbumsByTitle(albumTitle: string, limit = 5): Promis
  * @param limit - Maximum results to return
  * @returns Array of enriched library results
  */
-export async function searchByArtist(artistName: string, limit = 5): Promise<EnrichedLibraryResult[]> {
+export async function pgTrgmSearchByArtist(artistName: string, limit = 5): Promise<EnrichedLibraryResult[]> {
   const query = sql`
     SELECT *,
       similarity(${library_artist_view.artist_name}, ${artistName}) as sim
@@ -516,3 +516,7 @@ export function filterResultsByArtist(
 
   return filtered;
 }
+
+// Re-export the search facade under the original function names.
+// All callers continue to import from this file unchanged.
+export { searchLibrary, findSimilarArtist, searchAlbumsByTitle, searchByArtist } from './search/index.js';

apps/backend/services/search/elasticsearch.client.ts

@@ -0,0 +1,40 @@
+import { Client } from '@elastic/elasticsearch';
+
+let client: Client | null = null;
+
+/**
+ * Returns true when Elasticsearch is configured via the ELASTICSEARCH_URL env var.
+ */
+export function isElasticsearchEnabled(): boolean {
+  return !!process.env.ELASTICSEARCH_URL;
+}
+
+/**
+ * Returns the singleton Elasticsearch client, or null when ES is disabled.
+ *
+ * Does NOT throw on missing config — callers use null to degrade gracefully.
+ */
+export function getElasticsearchClient(): Client | null {
+  if (!isElasticsearchEnabled()) {
+    return null;
+  }
+
+  if (!client) {
+    const config: ConstructorParameters<typeof Client>[0] = {
+      node: process.env.ELASTICSEARCH_URL,
+      requestTimeout: 5000,
+      maxRetries: 2,
+    };
+
+    if (process.env.ELASTICSEARCH_USERNAME && process.env.ELASTICSEARCH_PASSWORD) {
+      config.auth = {
+        username: process.env.ELASTICSEARCH_USERNAME,
+        password: process.env.ELASTICSEARCH_PASSWORD,
+      };
+    }
+
+    client = new Client(config);
+  }
+
+  return client;
+}

apps/backend/services/search/elasticsearch.indices.ts

@@ -0,0 +1,52 @@
+import { getElasticsearchClient } from './elasticsearch.client.js';
+
+const INDEX_BASE_NAME = 'wxyc_library';
+
+export const LIBRARY_INDEX_MAPPING = {
+  settings: { number_of_shards: 1, number_of_replicas: 0 },
+  mappings: {
+    properties: {
+      id: { type: 'integer' },
+      artist_name: { type: 'text', fields: { keyword: { type: 'keyword' } } },
+      alphabetical_name: { type: 'text', fields: { keyword: { type: 'keyword' } } },
+      album_title: { type: 'text', fields: { keyword: { type: 'keyword' } } },
+      label: { type: 'text', fields: { keyword: { type: 'keyword' } } },
+      genre_name: { type: 'keyword' },
+      format_name: { type: 'keyword' },
+      rotation_bin: { type: 'keyword' },
+      code_letters: { type: 'keyword' },
+      code_artist_number: { type: 'integer' },
+      code_number: { type: 'integer' },
+      add_date: { type: 'date' },
+    },
+  },
+} as const;
+
+/**
+ * Returns the index name, honoring the optional ELASTICSEARCH_INDEX_PREFIX
+ * env var for test isolation (e.g., `ci_wxyc_library`).
+ */
+export function getLibraryIndexName(): string {
+  const prefix = process.env.ELASTICSEARCH_INDEX_PREFIX ?? '';
+  return `${prefix}${INDEX_BASE_NAME}`;
+}
+
+/**
+ * Idempotently creates the library index if it does not already exist.
+ * Safe to call at startup — does nothing when ES is disabled or the index exists.
+ */
+export async function ensureLibraryIndex(): Promise<void> {
+  const client = getElasticsearchClient();
+  if (!client) return;
+
+  const indexName = getLibraryIndexName();
+  const exists = await client.indices.exists({ index: indexName });
+
+  if (!exists) {
+    await client.indices.create({
+      index: indexName,
+      body: LIBRARY_INDEX_MAPPING,
+    });
+    console.log(`[Elasticsearch] Created index '${indexName}'`);
+  }
+}

apps/backend/services/search/elasticsearch.search.ts

@@ -0,0 +1,161 @@
+import type { LibraryArtistViewEntry } from '@wxyc/database';
+import { getElasticsearchClient } from './elasticsearch.client.js';
+import { getLibraryIndexName } from './elasticsearch.indices.js';
+
+/**
+ * Map an ES hit _source to the LibraryArtistViewEntry shape used by the rest
+ * of the codebase, so the facade can swap backends transparently.
+ */
+function hitToViewEntry(source: Record<string, unknown>): LibraryArtistViewEntry {
+  return {
+    id: source.id as number,
+    artist_name: source.artist_name as string,
+    alphabetical_name: source.alphabetical_name as string,
+    album_title: source.album_title as string,
+    label: (source.label as string) ?? null,
+    genre_name: source.genre_name as string,
+    format_name: source.format_name as string,
+    rotation_bin: (source.rotation_bin as string) ?? null,
+    code_letters: source.code_letters as string,
+    code_artist_number: source.code_artist_number as number,
+    code_number: source.code_number as number,
+    add_date: source.add_date as unknown as Date,
+  };
+}
+
+/**
+ * Full library search via Elasticsearch.
+ *
+ * Supports three modes matching the pg_trgm implementation:
+ * 1. Free-text query across artist_name and album_title (multi_match)
+ * 2. Separate artist + title filters (bool/should)
+ * 3. Returns empty when no parameters are provided
+ */
+export async function searchLibraryES(
+  query?: string,
+  artist?: string,
+  title?: string,
+  limit = 5
+): Promise<LibraryArtistViewEntry[]> {
+  if (!query && !artist && !title) return [];
+
+  const client = getElasticsearchClient()!;
+  const index = getLibraryIndexName();
+
+  let body: Record<string, unknown>;
+
+  if (query) {
+    body = {
+      query: {
+        multi_match: {
+          query,
+          fields: ['artist_name^2', 'album_title'],
+          fuzziness: 'AUTO',
+        },
+      },
+    };
+  } else {
+    const should: Record<string, unknown>[] = [];
+    if (artist) {
+      should.push({ match: { artist_name: { query: artist, fuzziness: 'AUTO', boost: 2 } } });
+    }
+    if (title) {
+      should.push({ match: { album_title: { query: title, fuzziness: 'AUTO' } } });
+    }
+    body = {
+      query: {
+        bool: {
+          should,
+          minimum_should_match: 1,
+        },
+      },
+    };
+  }
+
+  const response = await client.search({ index, size: limit, body });
+  return (response.hits.hits as Array<{ _source: Record<string, unknown> }>).map((hit) => hitToViewEntry(hit._source));
+}
+
+/**
+ * Find a similar artist name using ES fuzzy matching.
+ * Returns the corrected name if a close but different match is found, null otherwise.
+ */
+export async function findSimilarArtistES(artistName: string, _threshold?: number): Promise<string | null> {
+  const client = getElasticsearchClient()!;
+  const index = getLibraryIndexName();
+
+  const response = await client.search({
+    index,
+    size: 1,
+    body: {
+      query: {
+        match: {
+          artist_name: {
+            query: artistName,
+            fuzziness: 'AUTO',
+          },
+        },
+      },
+      _source: ['artist_name'],
+    },
+  });
+
+  const hits = response.hits.hits as Array<{ _source: { artist_name: string } }>;
+  if (hits.length === 0) return null;
+
+  const match = hits[0]._source.artist_name;
+  if (match.toLowerCase() === artistName.toLowerCase()) return null;
+
+  console.log(`[Elasticsearch] Corrected artist '${artistName}' to '${match}'`);
+  return match;
+}
+
+/**
+ * Search for albums by title with fuzzy matching.
+ */
+export async function searchAlbumsByTitleES(albumTitle: string, limit = 5): Promise<LibraryArtistViewEntry[]> {
+  const client = getElasticsearchClient()!;
+  const index = getLibraryIndexName();
+
+  const response = await client.search({
+    index,
+    size: limit,
+    body: {
+      query: {
+        match: {
+          album_title: {
+            query: albumTitle,
+            fuzziness: 'AUTO',
+          },
+        },
+      },
+    },
+  });
+
+  return (response.hits.hits as Array<{ _source: Record<string, unknown> }>).map((hit) => hitToViewEntry(hit._source));
+}
+
+/**
+ * Search the library by artist name with fuzzy matching.
+ */
+export async function searchByArtistES(artistName: string, limit = 5): Promise<LibraryArtistViewEntry[]> {
+  const client = getElasticsearchClient()!;
+  const index = getLibraryIndexName();
+
+  const response = await client.search({
+    index,
+    size: limit,
+    body: {
+      query: {
+        match: {
+          artist_name: {
+            query: artistName,
+            fuzziness: 'AUTO',
+          },
+        },
+      },
+    },
+  });
+
+  return (response.hits.hits as Array<{ _source: Record<string, unknown> }>).map((hit) => hitToViewEntry(hit._source));
+}