# manish-9245/scalable-llm-search architecture

> Architecture diagram of the GitHub repository manish-9245/scalable-llm-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manish-9245/scalable-llm-search
- Repository: https://github.com/manish-9245/scalable-llm-search

## Overview

#### Purpose and Entry Points
Indriya AI is a local-first luxury-jewellery search, voice, and concierge backend with an administrative AI ingestion pipeline. The Fastify application starts in `server.js`, serves the browser UI from `public/index.html` and `public/app.js`, and exposes search, chat, transcription, ingestion, queue-admin, and health routes.

#### HTTP Coordination and Runtime Boundaries
`server.js` is the request coordinator: it accepts text/voice interactions, invokes local search and localization paths, and dispatches privileged ingestion work. It runs in Node.js/Fastify; static UI and local ONNX/WASM inference execute alongside the service. Deployment packaging is defined by `Dockerfile` and Railway settings in `railway.json`.

#### Query Understanding and Local Concierge
The local parsing layer converts raw customer wording into structured filters, including typo correction, jewellery terminology, vernacular mappings, price ranges, purity/color normalization, and exclusions. Core vocabulary and parsing logic are in `src/utils/terminology.js`, `src/utils/slang.js`, and `src/utils/QueryBuilder.js`. Multilingual template-based conversational output is configured in `src/config/translations.js`; this customer-facing path is intentionally independent of cloud LLM calls.

#### Adaptive Hybrid Search
`src/services/searchService.js` executes the primary retrieval flow: parsed filters become relational, GIN-array exclusion/tag, and pgvector semantic retrieval streams, then are merged through reciprocal-rank fusion. `src/services/discoveryService.js` supports discovery-oriented catalog access. Embeddings use local MiniLM/ONNX inference configured through `src/config/llm.js`, while database access is centralized in `src/config/db.js`. PostgreSQL/pgvector is the durable search boundary, with schema and indexes represented by `schema.sql`.

#### Caching, Sessions, and Live Pricing
Redis provides low-latency search/product caching and BullMQ backing, configured in `src/config/redis.js` and `src/config/queue.js`. Session continuity is handled by `src/utils/sessionMerge.js`. `src/services/rateFetcherService.js` periodically fetches Indriya’s public rate fragment, derives related metal rates, persists daily values, and invalidates affected Redis keys; it is the only material product-price external data dependency.

#### Administrative Ingestion Pipeline
Ingestion is separated from customer runtime. `src/services/ingestionService.js` submits or processes background catalog enrichment; `src/mastra/agent.js` and `src/mastra/tools.js` define the Mastra/Gemini-backed multimodal analysis boundary. Gemini is used only to create structured product dossiers, which are normalized and stored in PostgreSQL. Redis/BullMQ decouples upload/request handling from this potentially slow, retryable work.

#### Voice, Initialization, and Operations
The transcription route uses local Whisper ONNX/WASM with language routing; model assets are prepared during build/startup through `src/config/pre_cache.js`. Database initialization and ontology seeding begin at `db_init.mjs`, with base schema in `schema.sql`. Structured logging is provided by `src/utils/logger.js`; queue visibility is mounted by the server. Required infrastructure is PostgreSQL 16+ with pgvector, Redis 7+, and a Gemini API key solely for ingestion.

Main entry points: [`server.js`](https://github.com/manish-9245/scalable-llm-search/blob/main/server.js) (Fastify server), [`src/services/searchService.js`](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/searchService.js) (Hybrid search), [`src/config/db.js`](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/db.js) (PostgreSQL + pgvector), [`src/services/ingestionService.js`](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/ingestionService.js) (Ingestion service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Customer Runtime"]
  node_ui["Browser UI<br/>static client<br/>[index.html]"]
  node_server["Fastify server<br/>Node.js coordinator<br/>[server.js]"]
  node_query["Query parser<br/>local NLP<br/>[QueryBuilder.js]"]
  node_terminology["Jewellery vocabulary<br/>normalization rules<br/>[terminology.js]"]
  node_translations["Conversation templates<br/>localization config<br/>[translations.js]"]
  node_voice["Local transcription<br/>Whisper ONNX/WASM<br/>[pre_cache.js]"]
  node_sessions["Session merge<br/>session continuity<br/>[sessionMerge.js]"]
end

subgraph group_data["Data &amp; Retrieval"]
  node_search["Hybrid search<br/>retrieval service<br/>[searchService.js]"]
  node_discovery["Catalog discovery<br/>discovery service"]
  node_embeddings["Local MiniLM embeddings<br/>ONNX inference<br/>[llm.js]"]
  node_postgres[("PostgreSQL + pgvector<br/>catalog database<br/>[db.js]")]
  node_schema["Schema and indexes<br/>SQL schema<br/>[schema.sql]"]
  node_redis[("Redis<br/>cache and queue backend<br/>[redis.js]")]
  node_rates["Live rate fetcher<br/>pricing service"]
  node_db_init["Database initialization<br/>bootstrap script<br/>[db_init.mjs]"]
end

subgraph group_ingestion["Admin Ingestion"]
  node_queue["BullMQ queue<br/>background jobs<br/>[queue.js]"]
  node_ingestion_service["Ingestion service<br/>catalog enrichment"]
  node_mastra["Mastra analysis agent<br/>multimodal AI boundary<br/>[agent.js]"]
  node_gemini{{"Gemini<br/>external AI API"}}
end

node_deployment["Container deployment<br/>packaging"]

node_ui -->|"HTTP and static UI"| node_server
node_server -->|"text query"| node_query
node_query -->|"normalizes terms"| node_terminology
node_server -->|"localized replies"| node_translations
node_server -->|"voice transcription"| node_voice
node_server -->|"conversation continuity"| node_sessions
node_server -->|"search request"| node_search
node_query -->|"structured filters"| node_search
node_search -->|"semantic query vector"| node_embeddings
node_search -->|"hybrid retrieval"| node_postgres
node_search -->|"read/write cache"| node_redis
node_server -->|"discovery routes"| node_discovery
node_discovery -->|"catalog access"| node_postgres
node_rates -->|"persist daily rates"| node_postgres
node_rates -->|"invalidate price keys"| node_redis
node_server -->|"privileged ingestion"| node_ingestion_service
node_ingestion_service -->|"enqueue/process jobs"| node_queue
node_queue -->|"job backing"| node_redis
node_ingestion_service -->|"product enrichment"| node_mastra
node_mastra -->|"multimodal dossier generation"| node_gemini
node_ingestion_service -->|"store normalized dossier"| node_postgres
node_schema -->|"defines tables and indexes"| node_postgres
node_db_init -->|"applies schema"| node_schema
node_deployment -->|"packages runtime"| node_server

click node_ui "https://github.com/manish-9245/scalable-llm-search/blob/main/public/index.html"
click node_server "https://github.com/manish-9245/scalable-llm-search/blob/main/server.js"
click node_query "https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/QueryBuilder.js"
click node_terminology "https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/terminology.js"
click node_translations "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/translations.js"
click node_voice "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/pre_cache.js"
click node_sessions "https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/sessionMerge.js"
click node_search "https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/searchService.js"
click node_discovery "https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/discoveryService.js"
click node_embeddings "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/llm.js"
click node_postgres "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/db.js"
click node_schema "https://github.com/manish-9245/scalable-llm-search/blob/main/schema.sql"
click node_redis "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/redis.js"
click node_rates "https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/rateFetcherService.js"
click node_queue "https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/queue.js"
click node_ingestion_service "https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/ingestionService.js"
click node_mastra "https://github.com/manish-9245/scalable-llm-search/blob/main/src/mastra/agent.js"
click node_db_init "https://github.com/manish-9245/scalable-llm-search/blob/main/db_init.mjs"
click node_deployment "https://github.com/manish-9245/scalable-llm-search/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_server,node_query,node_terminology,node_translations,node_voice,node_sessions toneBlue
class node_search,node_discovery,node_embeddings,node_postgres,node_schema,node_redis,node_rates,node_db_init toneAmber
class node_queue,node_ingestion_service,node_mastra,node_gemini toneMint
class node_deployment toneNeutral
```

## Components

### Customer Runtime

Local-first Fastify search and concierge path.

- [Browser UI](https://github.com/manish-9245/scalable-llm-search/blob/main/public/index.html): static client · `public/index.html`
- [Fastify server](https://github.com/manish-9245/scalable-llm-search/blob/main/server.js): Node.js coordinator · Serves UI and coordinates HTTP routes. · `server.js`
- [Query parser](https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/QueryBuilder.js): local NLP · Builds normalized filters without cloud LLM calls. · `src/utils/QueryBuilder.js`
- [Jewellery vocabulary](https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/terminology.js): normalization rules · `src/utils/terminology.js`
- [Conversation templates](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/translations.js): localization config · `src/config/translations.js`
- [Local transcription](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/pre_cache.js): Whisper ONNX/WASM · Language-routed voice transcription. · `src/config/pre_cache.js`
- [Session merge](https://github.com/manish-9245/scalable-llm-search/blob/main/src/utils/sessionMerge.js): session continuity · `src/utils/sessionMerge.js`

### Data & Retrieval

Catalog persistence, hybrid retrieval, and cache boundary.

- [Hybrid search](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/searchService.js): retrieval service · Combines relational, exclusion/tag, and semantic results with reciprocal-rank fusion. · `src/services/searchService.js`
- [Catalog discovery](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/discoveryService.js): discovery service · `src/services/discoveryService.js`
- [Local MiniLM embeddings](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/llm.js): ONNX inference · `src/config/llm.js`
- [PostgreSQL + pgvector](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/db.js): catalog database · Durable catalog, vectors, and daily metal rates. · `src/config/db.js`
- [Schema and indexes](https://github.com/manish-9245/scalable-llm-search/blob/main/schema.sql): SQL schema · `schema.sql`
- [Redis](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/redis.js): cache and queue backend · Search/product cache and BullMQ storage. · `src/config/redis.js`
- [Live rate fetcher](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/rateFetcherService.js): pricing service · Fetches public rates, persists derived values, and invalidates cache. · `src/services/rateFetcherService.js`
- [Database initialization](https://github.com/manish-9245/scalable-llm-search/blob/main/db_init.mjs): bootstrap script · Initializes database and seeds ontology. · `db_init.mjs`

### Admin Ingestion

Asynchronous AI catalog enrichment pipeline.

- [BullMQ queue](https://github.com/manish-9245/scalable-llm-search/blob/main/src/config/queue.js): background jobs · Decouples retryable ingestion from HTTP handling. · `src/config/queue.js`
- [Ingestion service](https://github.com/manish-9245/scalable-llm-search/blob/main/src/services/ingestionService.js): catalog enrichment · `src/services/ingestionService.js`
- [Mastra analysis agent](https://github.com/manish-9245/scalable-llm-search/blob/main/src/mastra/agent.js): multimodal AI boundary · Creates structured product dossiers through Gemini. · `src/mastra/agent.js`
- **Gemini**: external AI API · Used only for administrative ingestion.

### Other components

- [Container deployment](https://github.com/manish-9245/scalable-llm-search/blob/main/Dockerfile): packaging · `Dockerfile`

## Connections

- Browser UI → Fastify server: HTTP and static UI
- Fastify server → Query parser: text query
- Query parser → Jewellery vocabulary: normalizes terms
- Fastify server → Conversation templates: localized replies
- Fastify server → Local transcription: voice transcription
- Fastify server → Session merge: conversation continuity
- Fastify server → Hybrid search: search request
- Query parser → Hybrid search: structured filters
- Hybrid search → Local MiniLM embeddings: semantic query vector
- Hybrid search → PostgreSQL + pgvector: hybrid retrieval
- Hybrid search → Redis: read/write cache
- Fastify server → Catalog discovery: discovery routes
- Catalog discovery → PostgreSQL + pgvector: catalog access
- Live rate fetcher → PostgreSQL + pgvector: persist daily rates
- Live rate fetcher → Redis: invalidate price keys
- Fastify server → Ingestion service: privileged ingestion
- Ingestion service → BullMQ queue: enqueue/process jobs
- BullMQ queue → Redis: job backing
- Ingestion service → Mastra analysis agent: product enrichment
- Mastra analysis agent → Gemini: multimodal dossier generation
- Ingestion service → PostgreSQL + pgvector: store normalized dossier
- Schema and indexes → PostgreSQL + pgvector: defines tables and indexes
- Database initialization → Schema and indexes: applies schema
- Container deployment → Fastify server: packages runtime