{"_id":"@bilgrami/smart-search","_rev":"4-c2442a3e10119ecd1c3861f2800db28c","name":"@bilgrami/smart-search","dist-tags":{"latest":"3.1.1"},"versions":{"2.0.1":{"name":"@bilgrami/smart-search","version":"2.0.1","keywords":["search","database","cache","redis","postgresql","mysql","mongodb","supabase","fallback","performance","universal"],"author":{"url":"https://github.com/bilgrami","name":"Syd A Bilgrami"},"license":"Apache-2.0","_id":"@bilgrami/smart-search@2.0.1","maintainers":[{"name":"bilgrami","email":"bilgrami@gmail.com"}],"homepage":"https://github.com/samas-it-services/smart-search#readme","bugs":{"url":"https://github.com/samas-it-services/smart-search/issues"},"bin":{"smart-search":"bin/smart-search-cli.js"},"dist":{"shasum":"de12b0f2c98e63b971ada15ec51187950f039925","tarball":"https://registry.npmjs.org/@bilgrami/smart-search/-/smart-search-2.0.1.tgz","fileCount":37,"integrity":"sha512-Y++gcIWQwFPgbewuNjfhRNsUoSS1YUS2zUzN67irVaZx139Fv+S+iuaVWdWia2C2wVY8UlbtgXIoJWfGZtQx7g==","signatures":[{"sig":"MEUCIA/gZoSGmZvrI81wtkeWFDz1LwIknOFQxZk7TgLS5+D2AiEA5JRM/jGb/jpQGim62S4duLmVH3f709XmFg1PZiD6MQ4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":862004},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"funding":[{"url":"https://github.com/sponsors/bilgrami","type":"github"},{"url":"https://ko-fi.com/bilgrami","type":"individual"}],"gitHead":"ee0d1f7fc1e7c9b5c9b0a79a88eaab22df764be1","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src/**/*.ts","test":"vitest","build":"tsup src/index.ts --format cjs,esm --dts","lint:fix":"eslint src/**/*.ts --fix","test:all":"npm run test:unit && npm run test:e2e","test:e2e":"playwright test","test:unit":"vitest run --reporter=verbose","test:serve":"python -m http.server 3000 --directory tests/e2e","test:watch":"vitest --watch","type-check":"tsc --noEmit","screenshots":"node generate-screenshots.js","examples:all":"npm run examples:basic && npm run examples:advanced && npm run examples:multi-db","publish:test":"./scripts/test-publish.sh","publish:major":"./scripts/publish-to-npm.sh major","publish:minor":"./scripts/publish-to-npm.sh minor","publish:patch":"./scripts/publish-to-npm.sh patch","test:coverage":"vitest run --coverage","version:major":"./scripts/publish-to-npm.sh major","version:minor":"./scripts/publish-to-npm.sh minor","version:patch":"./scripts/publish-to-npm.sh patch","examples:basic":"tsx examples/basic-usage.ts","test:e2e:debug":"playwright test --debug","publish:dry-run":"./scripts/publish-to-npm.sh patch --dry-run","screenshots:all":"node generate-screenshots.js all","test:e2e:headed":"playwright test --headed","examples:advanced":"tsx examples/advanced-configuration.ts","examples:multi-db":"tsx examples/multiple-databases.ts","prepublishOnly-disabled":"npm run type-check && npm run test:unit && npm run build"},"_npmUser":{"name":"bilgrami","email":"bilgrami@gmail.com"},"repository":{"url":"git+https://github.com/samas-it-services/smart-search.git","type":"git"},"_npmVersion":"11.5.1","description":"Universal search with intelligent fallback for any database + cache combination","directories":{},"_nodeVersion":"24.5.0","dependencies":{"pg":"^8.11.0","yaml":"^2.3.0","mysql2":"^3.6.0","ioredis":"^5.3.0","mongodb":"^6.0.0","memcached":"^2.2.2","@supabase/supabase-js":"^2.38.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^7.0.0","eslint":"^8.0.0","vitest":"^1.0.0","@types/pg":"^8.10.0","typescript":"^5.0.0","@types/node":"^20.0.0","@playwright/test":"^1.40.0","@types/memcached":"^2.2.0","@vitest/coverage-v8":"^1.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"typescript":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/smart-search_2.0.1_1754753258806_0.07674196365195396","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@bilgrami/smart-search","version":"3.0.0","keywords":["search","database","cache","redis","postgresql","mysql","mongodb","supabase","fallback","performance","universal"],"author":{"url":"https://github.com/bilgrami","name":"Syd A Bilgrami"},"license":"Apache-2.0","_id":"@bilgrami/smart-search@3.0.0","maintainers":[{"name":"bilgrami","email":"bilgrami@gmail.com"}],"homepage":"https://github.com/samas-it-services/smart-search#readme","bugs":{"url":"https://github.com/samas-it-services/smart-search/issues"},"bin":{"smart-search":"bin/smart-search-cli.js"},"dist":{"shasum":"0e62c09991ea12da53abb6067a5b939db092fa93","tarball":"https://registry.npmjs.org/@bilgrami/smart-search/-/smart-search-3.0.0.tgz","fileCount":37,"integrity":"sha512-YLyM7ZeoMYAv+Nj3MbzM4lyvy2rn+3SMJPKUYJURH/VwSz1x9eL0+cyA0kg6JMbqHJblgKxTpqCSg5n6v91T6Q==","signatures":[{"sig":"MEUCIQDDmMbYlJa58z4F+TSAIHnSl96anDgRbWVGOv33+GO+QAIgecd15ZEBlGHL3XiMxr1O+YdH0NhF/H3m7bEzTM8Esjo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":861995},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"funding":[{"url":"https://github.com/sponsors/bilgrami","type":"github"},{"url":"https://ko-fi.com/bilgrami","type":"individual"}],"gitHead":"e9d80497a0414b2ed33bb7379df5ca03f1e33cdc","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src/**/*.ts","test":"vitest","build":"tsup src/index.ts --format cjs,esm --dts","lint:fix":"eslint src/**/*.ts --fix","test:all":"npm run test:unit && npm run test:e2e","test:e2e":"playwright test","test:unit":"vitest run --reporter=verbose","test:serve":"python -m http.server 3000 --directory tests/e2e","test:watch":"vitest --watch","type-check":"tsc --noEmit","screenshots":"node generate-screenshots.js","examples:all":"npm run examples:basic && npm run examples:advanced && npm run examples:multi-db","publish:test":"./scripts/test-publish.sh","publish:major":"./scripts/publish-to-npm.sh major","publish:minor":"./scripts/publish-to-npm.sh minor","publish:patch":"./scripts/publish-to-npm.sh patch","test:coverage":"vitest run --coverage","version:major":"./scripts/publish-to-npm.sh major","version:minor":"./scripts/publish-to-npm.sh minor","version:patch":"./scripts/publish-to-npm.sh patch","examples:basic":"tsx examples/basic-usage.ts","prepublishOnly":"npm run type-check && npm run test:unit && npm run build","test:e2e:debug":"playwright test --debug","publish:dry-run":"./scripts/publish-to-npm.sh patch --dry-run","screenshots:all":"node generate-screenshots.js all","test:e2e:headed":"playwright test --headed","examples:advanced":"tsx examples/advanced-configuration.ts","examples:multi-db":"tsx examples/multiple-databases.ts"},"_npmUser":{"name":"bilgrami","email":"bilgrami@gmail.com"},"repository":{"url":"git+https://github.com/samas-it-services/smart-search.git","type":"git"},"_npmVersion":"11.5.1","description":"Universal search with intelligent fallback for any database + cache combination","directories":{},"_nodeVersion":"24.5.0","dependencies":{"pg":"^8.11.0","yaml":"^2.3.0","mysql2":"^3.6.0","ioredis":"^5.3.0","mongodb":"^6.0.0","memcached":"^2.2.2","@supabase/supabase-js":"^2.38.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^7.0.0","eslint":"^8.0.0","vitest":"^1.0.0","@types/pg":"^8.10.0","typescript":"^5.0.0","@types/node":"^20.0.0","@playwright/test":"^1.40.0","@types/memcached":"^2.2.0","@vitest/coverage-v8":"^1.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"typescript":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/smart-search_3.0.0_1754753367040_0.7084982446938952","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@bilgrami/smart-search","version":"3.1.0","keywords":["search","database","cache","redis","postgresql","mysql","mongodb","supabase","fallback","performance","universal"],"author":{"url":"https://github.com/bilgrami","name":"Syd A Bilgrami"},"license":"Apache-2.0","_id":"@bilgrami/smart-search@3.1.0","maintainers":[{"name":"bilgrami","email":"bilgrami@gmail.com"}],"homepage":"https://github.com/samas-it-services/smart-search#readme","bugs":{"url":"https://github.com/samas-it-services/smart-search/issues"},"bin":{"smart-search":"bin/smart-search-cli.js"},"dist":{"shasum":"f7e0be6fee8b17e8fb5fb238c33aaa83c4ddf6ab","tarball":"https://registry.npmjs.org/@bilgrami/smart-search/-/smart-search-3.1.0.tgz","fileCount":39,"integrity":"sha512-WJutm2aRqVoK+VzQjP/vOzq88bxyHIAuJhNpa877reFU9YuZlAoYW9W7Hwusec1dKge/EC2UM3qz+4u0x6c01A==","signatures":[{"sig":"MEUCIBvlc8gjR6+UW7cE1X0wY7sJZ8QZtx1c0ydvjq38manmAiEA3eBHZzFnWGzpgoAj/1RhWBdFYUB9aHznG9mfYP9+sO8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":862973},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"funding":[{"url":"https://github.com/sponsors/bilgrami","type":"github"},{"url":"https://ko-fi.com/bilgrami","type":"individual"}],"gitHead":"d7d10bb9484974eb149174ea1b792728d0212927","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src/**/*.ts","test":"vitest","build":"tsup src/index.ts --format cjs,esm --dts","lint:fix":"eslint src/**/*.ts --fix","test:all":"npm run test:unit && npm run test:e2e","test:e2e":"playwright test","test:unit":"vitest run --reporter=verbose","test:serve":"python3 -m http.server 3000 --directory tests/e2e || python -m http.server 3000 --directory tests/e2e","test:watch":"vitest --watch","type-check":"tsc --noEmit","screenshots":"node generate-screenshots.js","examples:all":"npm run examples:basic && npm run examples:advanced && npm run examples:multi-db","publish:test":"./scripts/test-publish.sh","publish:major":"./scripts/publish-to-npm.sh major","publish:minor":"./scripts/publish-to-npm.sh minor","publish:patch":"./scripts/publish-to-npm.sh patch","test:coverage":"vitest run --coverage","test:e2e:mock":"cross-env E2E_TARGET=mock playwright test","version:major":"./scripts/publish-to-npm.sh major","version:minor":"./scripts/publish-to-npm.sh minor","version:patch":"./scripts/publish-to-npm.sh patch","examples:basic":"tsx examples/basic-usage.ts","prepublishOnly":"npm run type-check && npm run test:unit && npm run build","test:e2e:debug":"playwright test --debug","publish:dry-run":"./scripts/publish-to-npm.sh patch --dry-run","screenshots:all":"node generate-screenshots.js all","test:e2e:headed":"playwright test --headed","examples:advanced":"tsx examples/advanced-configuration.ts","examples:multi-db":"tsx examples/multiple-databases.ts"},"_npmUser":{"name":"bilgrami","email":"bilgrami@gmail.com"},"repository":{"url":"git+https://github.com/samas-it-services/smart-search.git","type":"git"},"_npmVersion":"11.9.0","description":"Universal search with intelligent fallback for any database + cache combination","directories":{},"_nodeVersion":"25.6.1","dependencies":{"pg":"^8.11.0","yaml":"^2.3.0","mysql2":"^3.6.0","ioredis":"^5.3.0","mongodb":"^6.0.0","cross-env":"^10.0.0","memcached":"^2.2.2","@supabase/supabase-js":"^2.38.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^7.0.0","eslint":"^8.0.0","vitest":"^1.0.0","@types/pg":"^8.10.0","typescript":"^5.0.0","@types/node":"^20.0.0","@playwright/test":"^1.40.0","@types/memcached":"^2.2.0","@vitest/coverage-v8":"^1.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"typescript":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/smart-search_3.1.0_1781603583676_0.17521689707784804","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@bilgrami/smart-search","version":"3.1.1","description":"Universal search with intelligent fallback for any database + cache combination","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","license":"Apache-2.0","keywords":["search","database","cache","redis","postgresql","mysql","mongodb","supabase","fallback","performance","universal"],"author":{"name":"Syd A Bilgrami","url":"https://github.com/bilgrami"},"funding":[{"type":"github","url":"https://github.com/sponsors/bilgrami"},{"type":"individual","url":"https://ko-fi.com/bilgrami"}],"homepage":"https://github.com/samas-it-services/smart-search#readme","repository":{"type":"git","url":"git+https://github.com/samas-it-services/smart-search.git"},"bugs":{"url":"https://github.com/samas-it-services/smart-search/issues"},"bin":{"smart-search":"bin/smart-search-cli.js"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest","test:unit":"vitest run --reporter=verbose","test:watch":"vitest --watch","test:coverage":"vitest run --coverage","test:e2e":"playwright test","test:e2e:mock":"cross-env E2E_TARGET=mock playwright test","test:e2e:headed":"playwright test --headed","test:e2e:debug":"playwright test --debug","test:serve":"python3 -m http.server 3000 --directory tests/e2e || python -m http.server 3000 --directory tests/e2e","test:all":"npm run test:unit && npm run test:e2e","screenshots":"node generate-screenshots.js","screenshots:all":"node generate-screenshots.js all","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","type-check":"tsc --noEmit","examples:basic":"tsx examples/basic-usage.ts","examples:advanced":"tsx examples/advanced-configuration.ts","examples:multi-db":"tsx examples/multiple-databases.ts","examples:all":"npm run examples:basic && npm run examples:advanced && npm run examples:multi-db","prepublishOnly":"npm run type-check && npm run test:unit && npm run build","version:patch":"./scripts/publish-to-npm.sh patch","version:minor":"./scripts/publish-to-npm.sh minor","version:major":"./scripts/publish-to-npm.sh major","publish:patch":"./scripts/publish-to-npm.sh patch","publish:minor":"./scripts/publish-to-npm.sh minor","publish:major":"./scripts/publish-to-npm.sh major","publish:test":"./scripts/test-publish.sh","publish:dry-run":"./scripts/publish-to-npm.sh patch --dry-run"},"peerDependencies":{"typescript":">=4.0.0"},"devDependencies":{"@playwright/test":"^1.40.0","@types/memcached":"^2.2.0","@types/node":"^20.0.0","@types/pg":"^8.10.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","@vitest/coverage-v8":"^1.0.0","eslint":"^8.0.0","tsup":"^7.0.0","tsx":"^4.0.0","typescript":"^5.0.0","vitest":"^1.0.0"},"dependencies":{"@supabase/supabase-js":"^2.38.0","cross-env":"^10.0.0","ioredis":"^5.3.0","memcached":"^2.2.2","mongodb":"^6.0.0","mysql2":"^3.6.0","pg":"^8.11.0","yaml":"^2.3.0"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"gitHead":"d7d10bb9484974eb149174ea1b792728d0212927","_id":"@bilgrami/smart-search@3.1.1","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-P0BD9406PZkosb8rMQ5TjnyOVdVKjO9XNJ24cWiZChzKSkkFvnAksm/CMYC9Z6VlGB2CZsB2XVYwzQcnuMFSRw==","shasum":"c7677ef2068ef527c53dedf42e055705f5faa257","tarball":"https://registry.npmjs.org/@bilgrami/smart-search/-/smart-search-3.1.1.tgz","fileCount":39,"unpackedSize":888642,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICfJuAMFDJKafx85V0j+3iTQg9FPZlmV7QmJl70JnWMvAiEA3zagAL1krGU2ZBlO5MzKmcKrin7XkHCMNZTSTWoopko="}]},"_npmUser":{"name":"bilgrami","email":"bilgrami@gmail.com"},"directories":{},"maintainers":[{"name":"bilgrami","email":"bilgrami@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smart-search_3.1.1_1781605704627_0.9569605765015912"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-09T15:27:38.693Z","modified":"2026-06-16T10:28:24.950Z","2.0.1":"2025-08-09T15:27:39.081Z","3.0.0":"2025-08-09T15:29:27.232Z","3.1.0":"2026-06-16T09:53:03.952Z","3.1.1":"2026-06-16T10:28:24.842Z"},"bugs":{"url":"https://github.com/samas-it-services/smart-search/issues"},"author":{"name":"Syd A Bilgrami","url":"https://github.com/bilgrami"},"license":"Apache-2.0","homepage":"https://github.com/samas-it-services/smart-search#readme","keywords":["search","database","cache","redis","postgresql","mysql","mongodb","supabase","fallback","performance","universal"],"repository":{"type":"git","url":"git+https://github.com/samas-it-services/smart-search.git"},"description":"Universal search with intelligent fallback for any database + cache combination","maintainers":[{"name":"bilgrami","email":"bilgrami@gmail.com"}],"readme":"# @bilgrami/smart-search\n\n[![npm version](https://badge.fury.io/js/@bilgrami/smart-search.svg)](https://badge.fury.io/js/@bilgrami/smart-search)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\n**Universal search with intelligent fallback for any database + cache combination**\n\n`@bilgrami/smart-search` provides a unified search interface that works with any database (PostgreSQL, MySQL, MongoDB, Supabase) and cache (Redis, Memcached, DragonflyDB) combination. Features intelligent fallback when cache is unavailable, circuit breaker patterns, and comprehensive performance monitoring.\n\n## 🌟 Support the Project\n\nThis is an open-source project developed with ❤️ by the community. If you find it useful, please consider supporting:\n\n- ⭐ **[Star on GitHub](https://github.com/samas-it-services/smart-search)** - Show your support\n- 💰 **[Sponsor on GitHub](https://github.com/sponsors/bilgrami)** - Monthly sponsorship\n- ☕ **[Buy me a coffee](https://ko-fi.com/bilgrami)** - One-time support\n- 🐦 **[Follow on X](https://x.com/sbilgrami)** - Stay updated\n\n## ✨ Features\n\n- 🔄 **Intelligent Fallback** - Automatic switching between cache and database\n- ⚡ **Circuit Breaker** - Prevents cascade failures with automatic recovery\n- 📊 **Performance Monitoring** - Built-in metrics and slow query detection\n- 🔧 **Universal Compatibility** - Works with any database and cache combination\n- 🏎️ **High Performance** - Optimized for sub-10ms response times\n- 🛡️ **Type Safe** - Full TypeScript support with comprehensive types\n- 📈 **Scalable** - Handles high-throughput search scenarios\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\nnpm install @bilgrami/smart-search\n```\n\n### 1. Generate Configuration\n\nUse our CLI to generate a configuration template:\n\n```bash\n# Generate JSON configuration\nnpx @bilgrami/smart-search init json\n\n# Or generate YAML configuration  \nnpx @bilgrami/smart-search init yaml\n```\n\nThis creates a `smart-search.config.json` or `smart-search.config.yaml` file.\n\n### 2. Configure Your Database & Cache\n\n**Option A: Configuration File (Recommended)**\n\nEdit your `smart-search.config.json`:\n\n```json\n{\n  \"database\": {\n    \"type\": \"supabase\",\n    \"connection\": {\n      \"url\": \"${SUPABASE_URL}\",\n      \"key\": \"${SUPABASE_ANON_KEY}\"\n    }\n  },\n  \"cache\": {\n    \"type\": \"redis\", \n    \"connection\": {\n      \"url\": \"${REDIS_URL}\"\n    }\n  },\n  \"search\": {\n    \"fallback\": \"database\",\n    \"tables\": {\n      \"books\": {\n        \"columns\": {\n          \"id\": \"id\",\n          \"title\": \"title\", \n          \"author\": \"author\",\n          \"description\": \"description\"\n        },\n        \"searchColumns\": [\"title\", \"author\", \"description\"],\n        \"type\": \"book\"\n      }\n    }\n  }\n}\n```\n\n**Option B: Environment Variables**\n\nSet these environment variables in your `.env` file:\n\n```bash\nSUPABASE_URL=https://your-project.supabase.co\nSUPABASE_ANON_KEY=your-anon-key\nREDIS_URL=redis://localhost:6379\n```\n\n### 3. Use SmartSearch\n\n```typescript\nimport { SmartSearchFactory } from '@bilgrami/smart-search';\n\n// Load from configuration file automatically\nconst search = SmartSearchFactory.fromConfig();\n\n// Or load from environment variables\n// const search = SmartSearchFactory.fromEnvironment();\n\n// Perform search\nconst results = await search.search('javascript programming', {\n  limit: 20,\n  filters: {\n    category: ['programming', 'technology']\n  }\n});\n\nconsole.log(`Found ${results.results.length} results in ${results.performance.searchTime}ms`);\nconsole.log(`Strategy: ${results.strategy.primary} (${results.strategy.reason})`);\n```\n\n### 4. Validate & Test Configuration\n\n```bash\n# Validate your configuration\nnpx @bilgrami/smart-search validate\n\n# Test database and cache connections\nnpx @bilgrami/smart-search test-config\n```\n\n## 📚 Complete Documentation & Guides\n\nSmart Search offers comprehensive documentation covering all aspects from basic usage to enterprise deployment patterns. Our documentation is organized into specialized guides to help you succeed with your specific use case.\n\n### 🏥 **Industry Showcase Guides**\n\nExplore real-world implementations with actual datasets and production-ready configurations:\n\n- **[PostgreSQL + Redis Healthcare Search](blog/postgres-redis-showcase.md)** - Healthcare research platform with 10K+ medical records, featuring sub-50ms search responses and advanced pagination\n- **[MySQL + DragonflyDB E-commerce](blog/mysql-dragonfly-showcase.md)** - Product catalog search with inventory management and real-time caching\n- **[MongoDB + Memcached Social Platform](blog/mongodb-memcached-showcase.md)** - Social media content search with user-generated data and flexible document structure  \n- **[Delta Lake + Redis Financial Analytics](blog/deltalake-redis-showcase.md)** - Big data analytics platform with Delta Lake 4.x features and PySpark integration\n\n### 👨‍💻 **Developer Experience Guides**\n\nTailored guidance for different experience levels and development workflows:\n\n- **[Junior Developer Quick Start](blog/smart-search-junior-developers.md)** - Step-by-step tutorials with detailed explanations and common pitfall solutions\n- **[Senior Developer Advanced Patterns](blog/smart-search-senior-developers.md)** - Enterprise architecture patterns, performance optimization, and scaling strategies\n- **[QA & Testing Guide](blog/smart-search-testers.md)** - Comprehensive testing strategies, automated validation, and quality assurance best practices\n- **[Screenshot Automation for Teams](blog/screenshot-automation-guide.md)** - Automated documentation generation and visual testing workflows\n\n### ⚙️ **Technical Deep Dive Guides**\n\nAdvanced topics for production deployments and optimization:\n\n- **[Performance Benchmarking](blog/benchmarking-guide.md)** - Performance testing methodologies, benchmarking tools, and optimization techniques\n- **[Security & Compliance](blog/security-guide.md)** - HIPAA compliance, data governance, access control, and enterprise security patterns\n- **[Data Hydration Strategies](blog/data-hydration-guide.md)** - Cache warming, data synchronization, and consistency patterns across distributed systems\n- **[Development Environment Setup](blog/development-guide.md)** - Local development, Docker containerization, and CI/CD pipeline integration\n\n### 🌍 **Platform & Deployment Guides**\n\nMulti-platform deployment and integration patterns:\n\n- **[Global Platform Deployment](blog/smart-search-global-platforms.md)** - Cross-cloud deployment strategies for AWS, GCP, Azure, and hybrid environments\n- **[Community Showcase](blog/community-showcase.md)** - Community contributions, success stories, and integration examples\n- **[Open Source Benefits](blog/open-source-benefits.md)** - Contributing guidelines, community support, and open source advantages\n\n### 🚀 **Quick Access Guides**\n\nFor rapid implementation and troubleshooting:\n\n- **[Easiest Way to Test Smart Search](blog/easiest-way-to-test-smart-search.md)** - Zero-configuration testing with Docker and sample data\n- **[Community Roadmap](blog/community-roadmap.md)** - Upcoming features, community requests, and development priorities\n- **[Smart Search Homepage](blog/smart-search-homepage.md)** - Complete feature overview and architectural highlights\n\n## 🏗️ **Multi-Database Architecture Overview**\n\nSmart Search provides a unified interface that seamlessly works across different database and cache combinations, with intelligent fallback and performance optimization.\n\n### **Supported Database & Cache Matrix**\n\n| Database | Cache | Status | Performance | Use Case |\n|----------|-------|--------|------------|-----------|\n| **PostgreSQL** | **Redis** | ✅ Production | Sub-50ms | Healthcare, Research |\n| **MySQL** | **DragonflyDB** | ✅ Production | Sub-30ms | E-commerce, CMS |\n| **MongoDB** | **Memcached** | ✅ Production | Sub-40ms | Social Media, Content |\n| **Delta Lake** | **Redis** | ✅ Production | Sub-100ms | Analytics, ML Pipelines |\n| **Supabase** | **Redis** | ✅ Production | Sub-60ms | Rapid Prototyping |\n| **SQLite** | **In-Memory** | ✅ Development | Sub-20ms | Local Development |\n\n### **Architecture Components**\n\n```mermaid\ngraph TD\n    A[Client Application] --> B[Smart Search API]\n    B --> C{Intelligent Router}\n    C -->|Cache Hit| D[Cache Layer]\n    C -->|Cache Miss| E[Database Layer]\n    \n    D --> D1[Redis]\n    D --> D2[DragonflyDB]  \n    D --> D3[Memcached]\n    \n    E --> E1[PostgreSQL]\n    E --> E2[MySQL]\n    E --> E3[MongoDB]\n    E --> E4[Delta Lake]\n    \n    B --> F[Circuit Breaker]\n    B --> G[Performance Monitor]\n    B --> H[Health Checker]\n    \n    F --> I[Fallback Strategy]\n    G --> J[Metrics Collection]\n    H --> K[Service Discovery]\n```\n\n### **Performance Characteristics**\n\nBased on real-world testing with production datasets:\n\n- **Healthcare Search (PostgreSQL + Redis)**: 99,944 medical records, <50ms avg response time, 95% cache hit rate\n- **E-commerce Search (MySQL + DragonflyDB)**: 100K+ products, <30ms avg response time, 98% cache hit rate  \n- **Social Media Search (MongoDB + Memcached)**: 1M+ posts, <40ms avg response time, 92% cache hit rate\n- **Analytics Search (Delta Lake + Redis)**: 10M+ events, <100ms avg response time, 85% cache hit rate\n\n### **Intelligent Fallback System**\n\nSmart Search automatically handles:\n- **Cache Failures**: Seamless fallback to database with performance monitoring\n- **Database Outages**: Serve stale cache data when configured for high availability\n- **Circuit Breaker**: Automatic failure detection and recovery for both cache and database layers\n- **Health Monitoring**: Real-time health checks with automatic route optimization\n\n## 🔧 Configuration Examples\n\n### Supabase + Redis Configuration (JSON)\n\n**smart-search.config.json:**\n```json\n{\n  \"database\": {\n    \"type\": \"supabase\",\n    \"connection\": {\n      \"url\": \"${SUPABASE_URL}\",\n      \"key\": \"${SUPABASE_ANON_KEY}\"\n    }\n  },\n  \"cache\": {\n    \"type\": \"redis\",\n    \"connection\": {\n      \"url\": \"${REDIS_URL}\"\n    }\n  },\n  \"search\": {\n    \"fallback\": \"database\",\n    \"tables\": {\n      \"books\": {\n        \"columns\": {\n          \"id\": \"id\",\n          \"title\": \"title\",\n          \"author\": \"author\",\n          \"description\": \"description\"\n        },\n        \"searchColumns\": [\"title\", \"author\", \"description\"],\n        \"type\": \"book\"\n      }\n    }\n  }\n}\n```\n\n### Supabase + Redis Cloud (API Key) Configuration\n\n**smart-search.config.json:**\n```json\n{\n  \"database\": {\n    \"type\": \"supabase\",\n    \"connection\": {\n      \"url\": \"${SUPABASE_URL}\",\n      \"key\": \"${SUPABASE_ANON_KEY}\"\n    }\n  },\n  \"cache\": {\n    \"type\": \"redis\",\n    \"connection\": {\n      \"host\": \"${REDIS_CLOUD_HOST}\",\n      \"port\": 12345,\n      \"apiKey\": \"${REDIS_CLOUD_API_KEY}\",\n      \"tls\": true\n    }\n  },\n  \"search\": {\n    \"fallback\": \"database\",\n    \"tables\": {\n      \"books\": {\n        \"columns\": {\n          \"id\": \"id\",\n          \"title\": \"title\", \n          \"author\": \"author\",\n          \"description\": \"description\"\n        },\n        \"searchColumns\": [\"title\", \"author\", \"description\"],\n        \"type\": \"book\"\n      }\n    }\n  }\n}\n```\n\n### MySQL + Redis Configuration (YAML)\n\n**smart-search.config.yaml:**\n```yaml\ndatabase:\n  type: mysql\n  connection:\n    host: ${DB_HOST}\n    port: 3306\n    user: ${DB_USER}\n    password: ${DB_PASSWORD}\n    database: ${DB_NAME}\n\ncache:\n  type: redis\n  connection:\n    host: ${REDIS_HOST}\n    port: 6379\n    password: ${REDIS_PASSWORD}\n\nsearch:\n  fallback: database\n  tables:\n    products:\n      columns:\n        id: product_id\n        title: product_name\n        description: product_description\n      searchColumns:\n        - product_name\n        - product_description\n      type: product\n```\n\n### MongoDB + DragonflyDB Configuration\n\n**smart-search.config.json:**\n```json\n{\n  \"database\": {\n    \"type\": \"mongodb\",\n    \"connection\": {\n      \"uri\": \"${MONGODB_URI}\"\n    }\n  },\n  \"cache\": {\n    \"type\": \"dragonfly\",\n    \"connection\": {\n      \"host\": \"${DRAGONFLY_HOST}\",\n      \"port\": 6380\n    }\n  },\n  \"search\": {\n    \"fallback\": \"database\",\n    \"tables\": {\n      \"articles\": {\n        \"columns\": {\n          \"id\": \"_id\",\n          \"title\": \"title\",\n          \"author\": \"author\"\n        },\n        \"searchColumns\": [\"title\", \"content\", \"author\"],\n        \"type\": \"article\"\n      }\n    }\n  }\n}\n```\n\n### Redis API Key Authentication\n\nFor managed Redis services that use API keys instead of passwords:\n\n**Redis Cloud Configuration:**\n```json\n{\n  \"cache\": {\n    \"type\": \"redis\",\n    \"connection\": {\n      \"host\": \"redis-12345.c1.us-east-1.redislabs.com\",\n      \"port\": 12345,\n      \"apiKey\": \"${REDIS_CLOUD_API_KEY}\",\n      \"tls\": true\n    }\n  }\n}\n```\n\n**Upstash Redis Configuration:**\n```json\n{\n  \"cache\": {\n    \"type\": \"redis\", \n    \"connection\": {\n      \"url\": \"rediss://your-endpoint.upstash.io:6380\",\n      \"apiKey\": \"${UPSTASH_REDIS_REST_TOKEN}\"\n    }\n  }\n}\n```\n\n**Environment Variables for API Key Authentication:**\n\n```bash\n# Database\nSMART_SEARCH_DB_TYPE=supabase\nSUPABASE_URL=https://your-project.supabase.co\nSUPABASE_ANON_KEY=your-anon-key\n\n# Redis with API Key (Redis Cloud)\nSMART_SEARCH_CACHE_TYPE=redis\nREDIS_HOST=redis-12345.c1.us-east-1.redislabs.com  \nREDIS_PORT=12345\nREDIS_API_KEY=your-redis-cloud-api-key\nREDIS_TLS=true\n\n# Or Upstash Redis\nREDIS_URL=rediss://your-endpoint.upstash.io:6380\nUPSTASH_REDIS_REST_TOKEN=your-upstash-token\n\n# Performance\nSMART_SEARCH_ENABLE_METRICS=true\nSMART_SEARCH_FALLBACK=database\n```\n\n**Supported Redis API Key Environment Variables:**\n- `REDIS_API_KEY` - Generic Redis API key\n- `REDIS_TOKEN` - Alternative API key variable name\n- `UPSTASH_REDIS_REST_TOKEN` - Upstash-specific token\n- `SMART_SEARCH_CACHE_API_KEY` - Package-specific API key variable\n\nThen use:\n```typescript\nimport { SmartSearchFactory } from '@bilgrami/smart-search';\n\nconst search = SmartSearchFactory.fromEnvironment();\n```\n\n## ⚡ Direct Redis Connection (NEW!)\n\nThe Smart-Search package now supports direct Redis connections for optimal performance. This feature bypasses edge functions for sub-10ms response times.\n\n### Direct Redis Provider Usage\n\n```typescript\nimport { SmartSearch } from '@bilgrami/smart-search';\nimport { DirectRedisProvider } from '@bilgrami/smart-search/providers';\n\n// Create a direct Redis provider\nconst directRedisProvider = new DirectRedisProvider({\n  host: process.env.REDIS_HOST || 'localhost',\n  port: parseInt(process.env.REDIS_PORT || '6379'),\n  password: process.env.REDIS_PASSWORD,\n  db: parseInt(process.env.REDIS_DB || '0'),\n  // Performance options\n  maxConnections: 10,\n  minConnections: 2,\n  connectionTimeout: 10000,\n  commandTimeout: 5000,\n  // Circuit breaker settings\n  maxRetriesPerRequest: 3,\n  retryDelayOnFailover: 100,\n  // TLS configuration\n  tls: process.env.REDIS_TLS === 'true' ? {} : undefined,\n  // Or use URL-based connection\n  url: process.env.REDIS_URL,\n});\n\n// Initialize SmartSearch with direct connection\nconst smartSearch = new SmartSearch({\n  database: yourDatabaseProvider, // PostgreSQL, MySQL, etc.\n  cache: directRedisProvider,    // Use direct Redis connection\n  fallback: 'database',          // Fallback to database if Redis unavailable\n  circuitBreaker: {\n    failureThreshold: 5,         // Open circuit after 5 failures\n    recoveryTimeout: 60000,      // Try recovery after 1 minute\n    healthCacheTTL: 30000,       // Cache health status for 30 seconds\n  },\n  cacheConfig: {\n    enabled: true,\n    defaultTTL: 300000,          // 5 minutes cache TTL\n  },\n  performance: {\n    enableMetrics: true,\n    slowQueryThreshold: 1000,    // Log queries slower than 1 second\n  }\n});\n\n// Perform search with direct Redis connection\nconst { results, performance, strategy } = await smartSearch.search('javascript', {\n  limit: 20,\n  offset: 0,\n  filters: {\n    category: ['programming', 'web-development'],\n    language: ['en', 'es']\n  },\n  sortBy: 'relevance',\n  sortOrder: 'desc'\n});\n\nconsole.log(`Found ${results.length} results in ${performance.searchTime}ms`);\nconsole.log(`Strategy: ${strategy.primary} (${strategy.reason})`);\n```\n\n### Performance Benefits\n\n- **Direct Redis connections** provide 50%+ faster response times than edge function approach\n- **Sub-10ms response times** for search operations\n- **Reduced network hops** and latency\n- **Optimized connection pooling** with configurable connection limits\n\n### Configuration Options\n\n```typescript\nconst directRedisConfig: DirectRedisConfig = {\n  // Basic connection\n  host: 'localhost',           // Redis host (default: localhost)\n  port: 6379,                 // Redis port (default: 6379)\n  password: 'your-password',  // Redis password\n  username: 'your-username',  // Redis ACL username\n  apiKey: 'your-api-key',     // For API key authentication (Redis Cloud, Upstash, etc.)\n  db: 0,                      // Redis database number\n  url: 'redis://localhost:6379', // Redis connection URL\n\n  // Connection settings\n  connectTimeout: 10000,      // Connection timeout (default: 10000ms)\n  lazyConnect: true,          // Lazy connection (default: true)\n  retryDelayOnFailover: 100,  // Failover retry delay (default: 100ms)\n  maxRetriesPerRequest: 3,    // Max retries (default: 3)\n  tls: {},                    // TLS configuration\n\n  // Performance options\n  keepAlive: 30000,          // Keep alive interval (default: 30000ms)\n  maxConnections: 10,        // Maximum connections in pool (default: 10)\n  minConnections: 2,         // Minimum connections in pool (default: 2)\n  connectionTimeout: 10000,  // Connection timeout (default: 10000ms)\n  commandTimeout: 5000,      // Command timeout (default: 5000ms)\n};\n```\n\n## 🎛️ Advanced Configuration\n\n```typescript\nconst search = new SmartSearch({\n  database: databaseProvider,\n  cache: cacheProvider,\n  fallback: 'database',\n  circuitBreaker: {\n    failureThreshold: 5,        // Open circuit after 5 failures\n    recoveryTimeout: 30000,     // Try recovery after 30 seconds\n    healthCacheTTL: 10000       // Cache health status for 10 seconds\n  },\n  cache: {\n    enabled: true,\n    defaultTTL: 300000,         // 5 minute default cache TTL\n    maxSize: 10000              // Maximum cached items\n  },\n  performance: {\n    enableMetrics: true,        // Enable performance tracking\n    logQueries: false,          // Log all queries (debug mode)\n    slowQueryThreshold: 1000    // Log queries slower than 1 second\n  }\n});\n```\n\n## 📊 Performance Monitoring\n\n```typescript\n// Get search statistics\nconst stats = await search.getSearchStats();\nconsole.log('Cache Health:', stats.cacheHealth);\nconsole.log('Database Health:', stats.databaseHealth);\nconsole.log('Circuit Breaker:', stats.circuitBreaker);\nconsole.log('Recommended Strategy:', stats.recommendedStrategy);\n\n// Perform search with performance tracking\nconst { results, performance, strategy } = await search.search('query');\nconsole.log(`Search completed in ${performance.searchTime}ms`);\nconsole.log(`Results: ${performance.resultCount}`);\nconsole.log(`Strategy: ${performance.strategy} (cache hit: ${performance.cacheHit})`);\n```\n\n## 🔄 Circuit Breaker Pattern\n\nThe circuit breaker automatically handles failures:\n\n```typescript\n// Circuit breaker states:\n// - CLOSED: Normal operation, requests flow through\n// - OPEN: Failures detected, requests go to fallback\n// - HALF_OPEN: Testing if service recovered\n\nconst stats = await search.getSearchStats();\nif (stats.circuitBreaker.isOpen) {\n  console.log(`Circuit breaker is OPEN (${stats.circuitBreaker.failureCount} failures)`);\n  console.log(`Next retry in: ${stats.circuitBreaker.nextRetryTime - Date.now()}ms`);\n}\n```\n\n## 🛠️ Provider Development\n\nCreate custom providers by implementing the provider interfaces:\n\n```typescript\nimport { DatabaseProvider, SearchResult, SearchOptions, HealthStatus } from '@bilgrami/smart-search';\n\nclass CustomDatabaseProvider implements DatabaseProvider {\n  name = 'CustomDB';\n\n  async connect(): Promise<void> {\n    // Implementation\n  }\n\n  async search(query: string, options: SearchOptions): Promise<SearchResult[]> {\n    // Implementation\n  }\n\n  async checkHealth(): Promise<HealthStatus> {\n    // Implementation\n  }\n\n  // ... other required methods\n}\n```\n\n## 🎯 Showcases & Demos\n\nWe provide comprehensive showcase applications demonstrating real-world usage patterns with different database and cache combinations:\n\n### Interactive Showcases\n\n| **Showcase** | **Database + Cache** | **Industry Focus** | **Port** | **Features** |\n|--------------|---------------------|-------------------|----------|-------------|\n| [**PostgreSQL + Redis**](./showcases/postgres-redis/) | PostgreSQL + Redis | Healthcare Research | 3002 | Advanced full-text search, GIN indexes, relevance ranking |\n| [**MySQL + DragonflyDB**](./showcases/mysql-dragonfly/) | MySQL + DragonflyDB | Financial Services | 3003 | FULLTEXT indexes, high-performance caching |\n| [**MongoDB + Memcached**](./showcases/mongodb-memcached/) | MongoDB + Memcached | E-commerce Retail | 3004 | Text indexes, aggregation pipelines, distributed caching |\n| [**Delta Lake + Redis**](./showcases/deltalake-redis/) | Delta Lake + Redis | Financial Analytics | 3005 | ACID transactions, time travel, columnar storage |\n\n### Data Scale Options\n\nEach showcase supports multiple dataset sizes for performance testing:\n\n- **Tiny (1K records)** - Quick demos and development\n- **Small (10K records)** - Standard testing and integration\n- **Medium (100K records)** - Performance benchmarking\n- **Large (1M+ records)** - Production-scale testing\n\n### Running Showcases\n\nThe enhanced screenshot generation system provides comprehensive Docker-integrated testing and documentation generation:\n\n#### **Basic Usage**\n\n```bash\n# Generate screenshots for a specific showcase\n./scripts/generate-screenshots-docker.sh postgres-redis\n\n# Generate screenshots for all showcases (comprehensive demo)\n./scripts/generate-screenshots-docker.sh all\n\n# Keep Docker services running for development/debugging\n./scripts/generate-screenshots-docker.sh deltalake-redis --keep-services\n```\n\n#### **Development & Testing Workflows**\n\n```bash\n# 🏥 Healthcare Research Testing\n# Generates screenshots with medical data, clinical trials, drug information\n./scripts/generate-screenshots-docker.sh postgres-redis\n# → Creates: screenshots/blog/postgres-redis/\n# → Demonstrates: PostgreSQL full-text search, GIN indexes, healthcare data patterns\n\n# 💰 Financial Analytics Testing  \n# Generates screenshots with trading data, market analysis, portfolio management\n./scripts/generate-screenshots-docker.sh mysql-dragonfly\n# → Creates: screenshots/blog/mysql-dragonfly/\n# → Demonstrates: MySQL FULLTEXT search, DragonflyDB caching, financial datasets\n\n# 🛒 E-commerce Platform Testing\n# Generates screenshots with product catalogs, customer data, order histories\n./scripts/generate-screenshots-docker.sh mongodb-memcached\n# → Creates: screenshots/blog/mongodb-memcached/\n# → Demonstrates: MongoDB text indexes, Memcached distribution, retail workflows\n\n# 📊 Big Data Analytics Testing\n# Generates screenshots with time-series data, ACID transactions, columnar storage\n./scripts/generate-screenshots-docker.sh deltalake-redis\n# → Creates: screenshots/blog/deltalake-redis/\n# → Demonstrates: Delta Lake time travel, Spark processing, analytics patterns\n```\n\n#### **Documentation Generation**\n\n```bash\n# Generate blog post screenshots with real data\n./scripts/generate-screenshots-docker.sh all\n\n# Specific use cases:\n# 📝 Create documentation for healthcare guide\n./scripts/generate-screenshots-docker.sh postgres-redis\n\n# 📈 Create financial analytics screenshots\n./scripts/generate-screenshots-docker.sh deltalake-redis --keep-services\n\n# 🔄 Full platform demonstration (all 4 showcases)\n./scripts/generate-screenshots-docker.sh all\n```\n\n#### **Performance Testing Scenarios**\n\nThe screenshot system now supports separate folders for different dataset sizes and displays the dataset size prominently in the UI with distinctive colors:\n\n```bash\n# 🟢 Tiny Dataset Testing (1K records) - Teal/Green Badge\nDATA_SIZE=tiny ./scripts/generate-screenshots-docker.sh postgres-redis\n# → Creates: screenshots/blog/postgres-redis/tiny/\n# → UI shows: \"TINY DATASET\" badge in teal/green\n# → Records: \"1,000 Healthcare Records\"\n\n# 🔵 Small Dataset Testing (10K records) - Blue Badge  \nDATA_SIZE=small ./scripts/generate-screenshots-docker.sh mysql-dragonfly\n# → Creates: screenshots/blog/mysql-dragonfly/small/\n# → UI shows: \"SMALL DATASET\" badge in blue\n# → Records: \"10,000 Financial Records\"\n\n# 🟠 Medium Dataset Testing (100K records) - Orange Badge\nDATA_SIZE=medium ./scripts/generate-screenshots-docker.sh mongodb-memcached\n# → Creates: screenshots/blog/mongodb-memcached/medium/\n# → UI shows: \"MEDIUM DATASET\" badge in orange\n# → Records: \"100,000 E-commerce Records\"\n\n# 🔴 Large Dataset Testing (1M+ records) - Red Badge\nDATA_SIZE=large ./scripts/generate-screenshots-docker.sh deltalake-redis\n# → Creates: screenshots/blog/deltalake-redis/large/\n# → UI shows: \"LARGE DATASET\" badge in red\n# → Records: \"1,000,000+ Analytics Records\"\n```\n\n**Visual Dataset Indicators:**\n- **Badge Color**: Each dataset size has a distinctive background color for easy identification\n- **Record Count**: Prominently displayed total records being searched\n- **Cache Status**: Real-time cache connection and item count\n- **Responsive Design**: Both desktop and mobile screenshots show dataset information\n\n**Performance Comparison Examples:**\n```bash\n# Compare response times across different dataset sizes\nDATA_SIZE=tiny ./scripts/generate-screenshots-docker.sh postgres-redis    # ~5-10ms queries\nDATA_SIZE=medium ./scripts/generate-screenshots-docker.sh postgres-redis  # ~25-100ms queries  \nDATA_SIZE=large ./scripts/generate-screenshots-docker.sh postgres-redis   # ~100-500ms queries\n\n# Each generates screenshots in separate folders showing:\n# - Different colored dataset badges (teal → orange → red)\n# - Varying record counts (1K → 100K → 1M+)\n# - Performance impact visualization\n```\n\n#### **Advanced Usage Patterns**\n\n```bash\n# Development Mode - Keep services running for interactive testing\n./scripts/generate-screenshots-docker.sh postgres-redis --keep-services\n# → Access at: http://localhost:3002\n# → Test queries: /api/search?q=diabetes\n# → View metrics: /api/stats\n\n# CI/CD Integration - Skip data seeding for faster runs  \n./scripts/generate-screenshots-docker.sh mongodb-memcached --no-seed\n\n# Continuous Documentation - Generate screenshots on code changes\nfor showcase in postgres-redis mysql-dragonfly mongodb-memcached deltalake-redis; do\n  ./scripts/generate-screenshots-docker.sh $showcase\ndone\n```\n\n#### **What Each Screenshot Captures**\n\n| **Screenshot Type** | **Purpose** | **Content** |\n|-------------------|-------------|-------------|\n| **Homepage Overview** | Initial platform view | Clean interface, feature highlights, data size selector |\n| **Search Results** | Core functionality demo | Real search results with relevant data, performance metrics |\n| **Industry-Specific Queries** | Domain expertise | Healthcare terms, financial symbols, retail categories |\n| **Performance Statistics** | Technical metrics | Response times, cache hit rates, database performance |\n| **Mobile Responsive** | Cross-platform compatibility | Mobile-optimized views, touch-friendly interface |\n\nEach showcase generates 8-12 professional screenshots automatically, perfect for:\n- **Blog Posts**: Visual demonstrations of real-world usage\n- **Documentation**: Technical guides with actual screenshots  \n- **Presentations**: Professional slides with live data examples\n- **Marketing Materials**: Compelling visuals of platform capabilities\n\n## 📝 Blog Posts & Documentation\n\nComprehensive guides and tutorials for different user personas:\n\n### 🏥 **Industry-Specific Guides**\n\n| **Blog Post** | **Focus** | **Database + Cache** | **Use Case** |\n|---------------|-----------|---------------------|--------------|\n| [**PostgreSQL + Redis for Healthcare**](./blog/postgres-redis-showcase.md) | Healthcare Research | PostgreSQL + Redis | Medical data search, research papers, clinical trials |\n| [**MySQL + DragonflyDB for Finance**](./blog/mysql-dragonfly-showcase.md) | Financial Services | MySQL + DragonflyDB | Trading data, market analysis, portfolio management |\n| [**MongoDB + Memcached for Retail**](./blog/mongodb-memcached-showcase.md) | E-commerce | MongoDB + Memcached | Product catalogs, customer analytics, inventory |\n| [**Delta Lake + Redis Analytics**](./blog/deltalake-redis-showcase.md) | Big Data Analytics | Delta Lake + Redis | Time-series data, ACID transactions, data versioning |\n\n### 👨‍💻 **Developer Guides**\n\n| **Blog Post** | **Target Audience** | **Key Topics** |\n|---------------|-------------------|----------------|\n| [**Smart Search for Junior Developers**](./blog/smart-search-junior-developers.md) | Junior Developers | Getting started, basic concepts, simple integrations |\n| [**Smart Search for Senior Developers**](./blog/smart-search-senior-developers.md) | Senior Developers | Advanced patterns, performance optimization, architecture |\n| [**Smart Search for Testers**](./blog/smart-search-testers.md) | QA Engineers | Testing strategies, performance benchmarks, automation |\n| [**Screenshot Generation Guide**](./blog/screenshot-generator-junior-developers.md) | All Developers | Documentation automation, visual testing, CI/CD integration |\n\n### 🔧 **Technical Deep Dives**\n\n- **Performance Comparison**: Benchmarks across database and cache combinations\n- **Scaling Strategies**: Handling millions of records with different architectures  \n- **Production Deployment**: Best practices for high-availability setups\n- **Monitoring & Observability**: Metrics, logging, and alerting strategies\n\n## 🚀 **New Features & Enhancements**\n\n### Delta Lake Integration\n- **ACID Transactions**: Reliable data consistency with schema enforcement\n- **Time Travel Queries**: Access historical versions and audit data changes\n- **Columnar Storage**: Optimized Parquet format with compression and predicate pushdown\n- **Large Scale Processing**: Handle millions of records with Spark integration\n\n### Enhanced Data Management\n- **Real Public Datasets**: Healthcare, finance, retail, education, and real estate data\n- **Multiple Load Sizes**: Tiny (1K), Small (10K), Medium (100K), Large (1M+) records\n- **Automated Data Downloads**: Scripts to fetch real datasets from public APIs\n- **Docker Integration**: Automated seeding and health checks for all services\n\n### Improved Developer Experience\n- **Docker-First Development**: Complete development environment with `docker-compose`\n- **Automated Screenshots**: Generate documentation screenshots from real running services\n- **Health Monitoring**: Built-in health checks and performance metrics\n- **Load Testing**: Performance benchmarks across different data sizes\n\n### Production-Ready Features\n- **Circuit Breaker Pattern**: Automatic failover and recovery\n- **Performance Monitoring**: Built-in metrics collection and slow query detection\n- **Multiple Cache Backends**: Redis, DragonflyDB, Memcached, In-Memory support\n- **Flexible Configuration**: JSON, YAML, and environment variable support\n\n## 📋 Technical Specification Tables\n\n### Multi-Strategy Search Performance Comparison\n\n| **Strategy** | **Response Time** | **Cache Hit Rate** | **Use Case** | **Failure Handling** | **Resource Usage** |\n|--------------|------------------|-------------------|--------------|---------------------|-------------------|\n| **⚡ Cache-First** | 10-30ms | 90-95% | Real-time search, frequent queries | Automatic database fallback | Low CPU, High memory |\n| **🗄️ Database-Only** | 40-80ms | 0% (bypassed) | Real-time data, audit trails | N/A (direct database) | High CPU, Low memory |\n| **🔧 Circuit Breaker** | 100-180ms | Variable | Fault-tolerant systems, failover | Automatic recovery with backoff | Medium CPU/memory |\n| **🤖 Hybrid** | 8-80ms | 60-80% | Intelligent routing, mixed workloads | Smart routing with fallback | Balanced CPU/memory |\n\n### Dataset Size Performance Benchmarks\n\n| **Data Size** | **UI Badge Color** | **Record Count** | **Avg Response Time** | **Cache Performance** | **Docker Command** | **Screenshot Command** |\n|---------------|-------------------|------------------|----------------------|---------------------|-------------------|----------------------|\n| **Tiny** | 🟢 Teal/Green | ~1,000 | 5-15ms | >95% hit rate | `DATA_SIZE=tiny docker-compose up -d` | `DATA_SIZE=tiny ./scripts/generate-screenshots-docker.sh postgres-redis` |\n| **Small** | 🔵 Blue | ~10,000 | 15-35ms | 85-95% hit rate | `DATA_SIZE=small docker-compose up -d` | `DATA_SIZE=small ./scripts/generate-screenshots-docker.sh postgres-redis` |\n| **Medium** | 🟠 Orange | ~100,000 | 25-100ms | 70-85% hit rate | `DATA_SIZE=medium docker-compose up -d` | `DATA_SIZE=medium ./scripts/generate-screenshots-docker.sh postgres-redis` |\n| **Large** | 🔴 Red | ~1,000,000+ | 100-500ms | 50-70% hit rate | `DATA_SIZE=large docker-compose up -d` | `DATA_SIZE=large ./scripts/generate-screenshots-docker.sh postgres-redis` |\n\n### Database + Cache Combinations Technical Specifications\n\n| **Showcase** | **Database** | **Memory** | **Cache** | **Memory** | **Industry** | **Port** | **Specialty Features** | **Container Commands** |\n|--------------|-------------|-----------|-----------|-----------|-------------|----------|----------------------|----------------------|\n| **PostgreSQL + Redis** | PostgreSQL 15 | 512MB | Redis 7.2 | 256MB | Healthcare | 3002 | GIN indexes, tsvector ranking, real-time subscriptions | `docker-compose -f docker/postgres-redis.docker-compose.yml up -d` |\n| **MySQL + DragonflyDB** | MySQL 8.0 | 512MB | DragonflyDB | 256MB | Financial | 3003 | FULLTEXT search, high-performance multi-threading | `docker-compose -f docker/mysql-dragonfly.docker-compose.yml up -d` |\n| **MongoDB + Memcached** | MongoDB 6.0 | 512MB | Memcached | 128MB | E-commerce | 3004 | Text indexes, aggregation pipelines, distributed caching | `docker-compose -f docker/mongodb-memcached.docker-compose.yml up -d` |\n| **Delta Lake + Redis** | Delta Lake | 1GB | Redis Stack | 512MB | Analytics | 3005 | ACID transactions, time travel, columnar storage | `docker-compose -f docker/deltalake-redis.docker-compose.yml up -d` |\n\n### Multi-Strategy Screenshot Generation Commands\n\n| **Strategy** | **Description** | **Response Time** | **Visual Indicators** | **API Command** | **Screenshot Command** |\n|--------------|-----------------|-------------------|---------------------|----------------|----------------------|\n| **Cache-First** | Redis-optimized fast responses | 10-30ms | Green borders, ⚡ icons | `curl \"localhost:3002/api/search?q=diabetes&strategy=cache-first\"` | Select \"⚡ Cache-First\" in UI dropdown |\n| **Database-Only** | Direct PostgreSQL queries | 40-80ms | Blue borders, 🗄️ icons | `curl \"localhost:3002/api/search?q=diabetes&strategy=database-only\"` | Select \"🗄️ Database-Only\" in UI dropdown |\n| **Circuit Breaker** | Simulated failover scenarios | 100-180ms | Orange warnings, 🔧 icons | `curl \"localhost:3002/api/search?q=diabetes&strategy=circuit-breaker\"` | Select \"🔧 Circuit Breaker\" in UI dropdown |\n| **Hybrid** | Intelligent query routing | 8-80ms | Purple hybrid, 🤖 icons | `curl \"localhost:3002/api/search?q=diabetes&strategy=hybrid\"` | Select \"🤖 Hybrid\" in UI dropdown |\n\n### Health Check Commands Reference\n\n| **Component** | **Health Check Command** | **Expected Response** | **Troubleshooting** |\n|---------------|-------------------------|---------------------|-------------------|\n| **Application** | `curl http://localhost:3002/api/health` | `{\"success\":true,\"status\":\"healthy\"}` | Check container logs: `docker logs docker-saMas-smart-search-postgres-redis-showcase` |\n| **PostgreSQL** | `docker exec docker-saMas-smart-search-postgres-main pg_isready -U search_user -d smartsearch_healthcare` | `accepting connections` | Verify connection: `docker exec -it docker-saMas-smart-search-postgres-main psql -U search_user -d smartsearch_healthcare` |\n| **Redis** | `docker exec docker-saMas-smart-search-redis-main redis-cli ping` | `PONG` | Check Redis CLI: `docker exec -it docker-saMas-smart-search-redis-main redis-cli` |\n| **All Services** | `docker ps --filter \"name=docker-saMas-smart-search\" --format \"table {{.Names}}\\t{{.Status}}\"` | All containers `Up` | Restart services: `docker-compose down && docker-compose up -d` |\n| **Search Stats** | `curl http://localhost:3002/api/stats` | JSON with dataset info | Check API logs and database connections |\n\n### Development Workflow Commands\n\n| **Use Case** | **Command** | **Purpose** | **Output Location** |\n|--------------|-------------|-------------|-------------------|\n| **Quick Demo** | `DATA_SIZE=tiny ./scripts/generate-screenshots-docker.sh postgres-redis` | Fast testing with 1K records | `screenshots/blog/postgres-redis/tiny/` |\n| **Performance Testing** | `DATA_SIZE=medium ./scripts/generate-screenshots-docker.sh postgres-redis` | Standard benchmarking with 100K records | `screenshots/blog/postgres-redis/medium/` |\n| **Production Scale** | `DATA_SIZE=large ./scripts/generate-screenshots-docker.sh postgres-redis` | Production testing with 1M+ records | `screenshots/blog/postgres-redis/large/` |\n| **Manual Testing** | `DATA_SIZE=medium docker-compose -f docker/postgres-redis.docker-compose.yml up -d` | Interactive development and debugging | Browser: `http://localhost:3002` |\n| **All Strategies** | `./scripts/generate-screenshots-docker.sh postgres-redis` | Complete strategy comparison screenshots | Multiple strategy folders with UI variations |\n| **Health Monitor** | `watch 'curl -s http://localhost:3002/api/health && curl -s http://localhost:3002/api/stats'` | Continuous health and performance monitoring | Real-time terminal output |\n\n### Production Deployment Specifications\n\n| **Environment** | **Database Config** | **Cache Config** | **Memory Requirements** | **CPU Requirements** | **Network** |\n|-----------------|-------------------|----------------|----------------------|-------------------|------------|\n| **Development** | PostgreSQL 15 (512MB) | Redis 7.2 (256MB) | 2GB total | 2 cores | Local networking |\n| **Staging** | PostgreSQL 15 (1GB) | Redis 7.2 (512MB) | 4GB total | 4 cores | Private VPC |\n| **Production** | PostgreSQL 15 (2-4GB) | Redis Cluster (1-2GB) | 8-16GB total | 8+ cores | Load balanced, multi-AZ |\n| **High Scale** | Read replicas (4-8GB) | Redis Cluster (2-4GB) | 16-32GB total | 16+ cores | CDN, global distribution |\n\n**Key Features by Environment:**\n- **Development**: Single-node setup, Docker Compose, local testing\n- **Staging**: Multi-container setup, automated health checks, integration testing\n- **Production**: High availability, automatic failover, comprehensive monitoring\n- **High Scale**: Horizontal scaling, multiple regions, advanced caching strategies\n\n## 📚 API Reference\n\n### SmartSearch Class\n\n#### Constructor\n\n```typescript\nconstructor(config: SmartSearchConfig)\n```\n\n#### Methods\n\n- `search(query: string, options?: SearchOptions)` - Perform intelligent search\n- `getSearchStats()` - Get performance and health statistics\n- `getCacheHealth()` - Get current cache health status\n- `forceHealthCheck()` - Force refresh of health status\n- `clearCache(pattern?: string)` - Clear cache data\n\n### Search Options\n\n```typescript\ninterface SearchOptions {\n  limit?: number;              // Maximum results (default: 20)\n  offset?: number;             // Pagination offset (default: 0)\n  filters?: SearchFilters;     // Search filters\n  sortBy?: 'relevance' | 'date' | 'views' | 'name';  // Sort criteria\n  sortOrder?: 'asc' | 'desc';  // Sort direction\n  cacheEnabled?: boolean;      // Enable/disable caching for this search\n  cacheTTL?: number;          // Custom cache TTL for this search\n}\n```\n\n### Search Filters\n\n```typescript\ninterface SearchFilters {\n  type?: string[];             // Filter by result types\n  category?: string[];         // Filter by categories\n  language?: string[];         // Filter by languages\n  visibility?: string[];       // Filter by visibility\n  dateRange?: {               // Filter by date range\n    start?: string;\n    end?: string;\n  };\n  custom?: Record<string, any>; // Custom filters\n}\n```\n\n## 🧪 Testing\n\n### Unit Tests\n```bash\n# Run unit tests\nnpm run test:unit\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### End-to-End Testing with Playwright\n\nSmart Search includes comprehensive E2E tests using Playwright to test showcase applications and generate blog post screenshots.\n\n#### Prerequisites\n```bash\n# Install Playwright (already included in devDependencies)\nnpm install\n\n# Install Playwright browsers\nnpx playwright install\n```\n\n#### Running E2E Tests\n\n```bash\n# Run all E2E tests\nnpm run test:e2e\n\n# Run tests with browser UI (headed mode)\nnpm run test:e2e:headed\n\n# Run tests in debug mode\nnpm run test:e2e:debug\n\n# Run specific showcase tests\nnpx playwright test --grep \"postgres-redis\"\n```\n\n#### Using the Test Showcase Script\n\nWe provide a comprehensive testing script for easy showcase testing:\n\n```bash\n# Install Playwright dependencies\n./scripts/test-showcase.sh install\n\n# Run all showcase tests\n./scripts/test-showcase.sh test\n\n# Run tests with interactive UI\n./scripts/test-showcase.sh test-ui\n\n# Generate blog post screenshots\n./scripts/test-showcase.sh screenshots postgres-redis\n\n# Run performance benchmarks\n./scripts/test-showcase.sh performance\n\n# Debug tests interactively\n./scripts/test-showcase.sh debug\n\n# View HTML test report\n./scripts/test-showcase.sh report\n\n# Clean test artifacts\n./scripts/test-showcase.sh clean\n```\n\n#### Screenshot Generation for Blog Posts\n\nAutomatically generate high-quality screenshots for blog posts and documentation:\n\n```bash\n# Generate screenshots for PostgreSQL + Redis showcase\n./scripts/test-showcase.sh screenshots postgres-redis\n\n# Generated screenshots will be in screenshots/blog/:\n# - 01-homepage-overview.png\n# - 02-search-results-postgresql.png\n# - 03-search-results-redis.png\n# - 04-search-results-typescript.png\n# - 05-search-results-performance.png\n# - 06-results-section-detail.png\n# - 07-performance-stats.png\n# - 08-performance-info-detail.png\n# - 09-filtered-results.png\n# - 10-filter-controls.png\n# - 11-mobile-homepage.png\n# - 12-mobile-search-results.png\n# - 13-api-examples.png\n# - 14-no-results-state.png\n# - 15-initial-empty-state.png\n```\n\n#### Test Configuration\n\nThe Playwright configuration includes:\n- **Multi-browser testing**: Chrome, Firefox, Safari, Mobile Chrome, Mobile Safari\n- **Automatic server startup**: Starts showcase applications during tests\n- **Screenshot capture**: On test failures and for blog posts\n- **Performance monitoring**: Response time and throughput measurement\n- **Global setup/teardown**: Docker service management and cleanup\n\n#### Custom Test Utilities\n\n```javascript\n// Screenshot generator utility\nconst ScreenshotGenerator = require('./tests/utils/screenshot-generator');\n\nconst generator = new ScreenshotGenerator({\n  baseURL: 'http://localhost:3002',\n  outputDir: 'screenshots/blog',\n  viewport: { width: 1200, height: 800 }\n});\n\nawait generator.init();\nawait generator.generateBlogScreenshots();\nawait generator.close();\n```\n\n#### Environment Variables\n\n```bash\n# Run tests with visible browser\nHEADLESS=false npm run test:e2e\n\n# Slow down actions for debugging\nSLOW_MO=1000 npm run test:e2e\n\n# Enable Playwright debug mode\nPWDEBUG=1 npm run test:e2e\n\n# Stop Docker services after tests\nSTOP_DOCKER=true npm run test:e2e\n```\n\n#### Continuous Integration\n\nFor CI/CD pipelines:\n\n```bash\n# Install dependencies and browsers\nnpm install\nnpx playwright install --with-deps\n\n# Start Docker services\n./scripts/docker-dev.sh start\n\n# Run tests\nnpm run test:all\n\n# Generate coverage report\nnpm run test:coverage\n\n# Stop services\n./scripts/docker-dev.sh stop\n```\n\n### Linting and Type Checking\n\n```bash\n# Run ESLint\nnpm run lint\n\n# Fix linting issues\nnpm run lint:fix\n\n# TypeScript type checking\nnpm run type-check\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with TypeScript for type safety\n- Inspired by enterprise-grade search architectures\n- Community-driven development\n\n---\n\n**Made with ❤️ by [Syed A Bilgrami](https://github.com/bilgrami)**\n\nSupport this project: [GitHub Sponsors](https://github.com/sponsors/bilgrami) | [Ko-fi](https://ko-fi.com/bilgrami) | [Follow on X](https://x.com/sbilgrami)","readmeFilename":"README.md"}