{"id":28936266,"url":"https://github.com/buhahemal/ai-faq-assistant","last_synced_at":"2026-05-07T17:38:54.628Z","repository":{"id":300535662,"uuid":"1006403069","full_name":"buhahemal/ai-faq-assistant","owner":"buhahemal","description":"A lightweight, embedding-based support bot that answers user questions using semantic search over predefined FAQs. Powered by Node.js and transformer embeddings, this solution works offline, is easy to deploy, and perfect for enhancing in-product support.","archived":false,"fork":false,"pushed_at":"2025-06-22T08:21:13.000Z","size":74,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-22T09:20:13.128Z","etag":null,"topics":["customer-support","express","faq-assistant","nodejs","question-answering","semantic-search","support-bot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buhahemal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T07:26:09.000Z","updated_at":"2025-06-22T09:15:29.000Z","dependencies_parsed_at":"2025-06-22T09:20:16.046Z","dependency_job_id":null,"html_url":"https://github.com/buhahemal/ai-faq-assistant","commit_stats":null,"previous_names":["buhahemal/ai-faq-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/buhahemal/ai-faq-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buhahemal%2Fai-faq-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buhahemal%2Fai-faq-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buhahemal%2Fai-faq-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buhahemal%2Fai-faq-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buhahemal","download_url":"https://codeload.github.com/buhahemal/ai-faq-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buhahemal%2Fai-faq-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32749341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["customer-support","express","faq-assistant","nodejs","question-answering","semantic-search","support-bot"],"created_at":"2025-06-22T20:08:10.895Z","updated_at":"2026-05-07T17:38:54.617Z","avatar_url":"https://github.com/buhahemal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI FAQ Assistant\n\nA production-ready, modular AI FAQ Assistant that uses semantic search to find the most relevant answers to user questions. Built with Node.js, Express, and the `all-MiniLM-L6-v2` model for high-quality semantic embeddings.\n\n## 🏗️ Architecture\n\nThis project follows a **modular, production-ready architecture** with clear separation of concerns:\n\n- **MVC Pattern with Service Layer**: Models, Controllers, Services, and Routes\n- **Configuration Management**: Centralized environment-based configuration\n- **Error Handling**: Comprehensive error handling with custom error classes\n- **Validation**: Request validation and sanitization\n- **Security**: Built-in security middleware (Helmet, CORS, Rate Limiting)\n- **Monitoring**: Health checks, statistics, and system monitoring\n\n## 📁 Project Structure\n\n```\nai-faq-assistant/\n├── src/                          # Source code\n│   ├── config/                   # Configuration files\n│   ├── controllers/              # Request handlers\n│   ├── middleware/               # Express middleware\n│   ├── models/                   # Data models\n│   ├── routes/                   # Route definitions\n│   ├── services/                 # Business logic\n│   ├── app.js                    # Express app setup\n│   └── server.js                 # Server entry point\n├── data/                         # Data files\n├── docs/                         # Documentation\n├── tests/                        # Test files\n└── package.json                  # Dependencies and scripts\n```\n\n## ✨ Features\n\n- **Semantic Search**: Uses cosine similarity to find the most relevant question-answer pairs\n- **Multiple Answers**: Support for multiple answers per question with primary answer designation\n- **Categories \u0026 Tags**: Organized knowledge base with categories and tags\n- **Production Ready**: Security middleware, rate limiting, error handling\n- **Modular Design**: Clean, maintainable, and extensible codebase\n- **Configuration Management**: Environment-based configuration\n- **Monitoring**: Health checks, statistics, and system status\n- **Hot Reloading**: Reload QA data without restarting the server\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18.0.0 or higher\n- npm or yarn package manager\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd ai-faq-assistant\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Configure environment** (optional)\n   ```bash\n   cp env.example .env\n   # Edit .env with your configuration\n   ```\n\n4. **Start the server**\n   ```bash\n   # Development\n   npm run dev\n   \n   # Production\n   npm start\n   ```\n\nThe server will start on `http://localhost:3000` (or the port specified in the `PORT` environment variable).\n\n## 📋 API Endpoints\n\n### Health \u0026 Status\n- `GET /` - Health check\n- `GET /support/stats` - System statistics\n- `GET /admin/status` - Detailed system status\n\n### Support Queries\n- `POST /support/query` - Submit question (returns primary answer)\n- `POST /support/query/all-answers` - Submit question (returns all answers)\n\n### QA Management\n- `GET /support/qa-pairs` - Get all QA pairs\n- `GET /support/qa-pairs/:id` - Get specific QA pair\n\n### Search \u0026 Discovery\n- `GET /support/search/category/:category` - Search by category\n- `GET /support/search/tags` - Search by tags\n- `GET /support/categories` - Get all categories\n- `GET /support/tags` - Get all tags\n\n### Admin Functions\n- `POST /admin/reload-data` - Reload QA data\n- `POST /admin/save-data` - Save QA data\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file based on `env.example`:\n\n```bash\n# Server Configuration\nPORT=3000\nHOST=localhost\nNODE_ENV=development\n\n# AI Model Configuration\nAI_MODEL=Xenova/all-MiniLM-L6-v2\n\n# Rate Limiting\nRATE_LIMIT_MAX=30\n\n# Data Configuration\nQA_DATA_PATH=./data/qa_data.json\n```\n\n### Configuration Hierarchy\n\n1. **Environment Variables** (highest priority)\n2. **Default Values** (fallback)\n3. **Hard-coded Values** (lowest priority)\n\n## 📊 Data Structure\n\nThe QA data supports multiple answers per question:\n\n```json\n{\n  \"id\": \"qa_001\",\n  \"question\": \"How do I reset my password?\",\n  \"answers\": [\n    {\n      \"id\": \"ans_001_01\",\n      \"answer\": \"To reset your password...\",\n      \"is_primary\": true,\n      \"tags\": [\"password\", \"login\"],\n      \"category\": \"account_management\"\n    },\n    {\n      \"id\": \"ans_001_02\",\n      \"answer\": \"Alternative method...\",\n      \"is_primary\": false,\n      \"tags\": [\"password\", \"support\"],\n      \"category\": \"account_management\"\n    }\n  ],\n  \"tags\": [\"password\", \"login\", \"security\"],\n  \"category\": \"account_management\",\n  \"difficulty\": \"easy\",\n  \"last_updated\": \"2024-01-15T10:00:00.000Z\"\n}\n```\n\n## 🧪 Testing\n\n### Example Requests\n\n**Health Check:**\n```bash\ncurl http://localhost:3000/\n```\n\n**Submit Query:**\n```bash\ncurl -X POST http://localhost:3000/support/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"question\": \"How do I reset my password?\"}'\n```\n\n**Get Statistics:**\n```bash\ncurl http://localhost:3000/support/stats\n```\n\n**Search by Category:**\n```bash\ncurl http://localhost:3000/support/search/category/account_management\n```\n\n## 🔒 Security Features\n\n- **Helmet**: Security headers\n- **CORS**: Cross-origin resource sharing\n- **Rate Limiting**: Protection against abuse (30 requests/minute)\n- **Input Validation**: Request sanitization and validation\n- **Error Handling**: Secure error responses\n- **Request Logging**: Basic request logging\n\n## 📈 Monitoring \u0026 Observability\n\n### Built-in Monitoring\n- Health check endpoints\n- System statistics\n- Memory usage tracking\n- Uptime monitoring\n- Request logging\n\n### Metrics Available\n- Total questions and answers\n- Categories and tags\n- Average answers per question\n- System performance metrics\n\n## 🚀 Deployment\n\n### Production Setup\n\n1. **Environment Configuration**\n   ```bash\n   NODE_ENV=production\n   PORT=3000\n   RATE_LIMIT_MAX=100\n   ```\n\n2. **Security Hardening**\n   - Enable HTTPS\n   - Configure CORS properly\n   - Set up monitoring\n   - Use environment variables\n\n3. **Performance Optimization**\n   - Enable caching\n   - Optimize AI model loading\n   - Configure connection pooling\n\n### Docker Deployment\n\n```dockerfile\nFROM node:18-alpine\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --only=production\nCOPY . .\nEXPOSE 3000\nCMD [\"npm\", \"start\"]\n```\n\n### Cloud Platforms\n\nThis application can be deployed to:\n- **Heroku**: Just push to your Heroku git repository\n- **Railway**: Connect your GitHub repository\n- **Vercel**: Deploy as a Node.js function\n- **AWS/GCP/Azure**: Use container services or app platforms\n\n## 🔄 Customization\n\n### Adding New QA Pairs\n\nEdit the `data/qa_data.json` file:\n\n```json\n{\n  \"id\": \"qa_new\",\n  \"question\": \"Your new question?\",\n  \"answers\": [\n    {\n      \"id\": \"ans_new_01\",\n      \"answer\": \"Your answer here.\",\n      \"is_primary\": true,\n      \"tags\": [\"tag1\", \"tag2\"],\n      \"category\": \"your_category\"\n    }\n  ],\n  \"tags\": [\"tag1\", \"tag2\"],\n  \"category\": \"your_category\",\n  \"difficulty\": \"easy\"\n}\n```\n\n### Changing the AI Model\n\nUpdate the `AI_MODEL` environment variable:\n\n```bash\nAI_MODEL=your-model-name\n```\n\n### Adding New Endpoints\n\n1. Create a new controller in `src/controllers/`\n2. Add routes in `src/routes/`\n3. Register routes in `src/app.js`\n\n## 🛠️ Development\n\n### Scripts\n\n```bash\nnpm start          # Start production server\nnpm run dev        # Start development server with auto-restart\nnpm run lint       # Run ESLint\nnpm run lint:fix   # Fix ESLint issues\n```\n\n### Project Structure Details\n\nSee [PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) for detailed architecture documentation.\n\n## 📚 Documentation\n\n- [Project Structure](docs/PROJECT_STRUCTURE.md) - Detailed architecture overview\n- [API Documentation](docs/API_DOCUMENTATION.md) - Complete API reference\n- [Postman Collection](AI_FAQ_Assistant.postman_collection.json) - Ready-to-use API collection\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🆘 Support\n\nFor issues and questions:\n1. Check the documentation\n2. Review the troubleshooting section\n3. Open an issue on GitHub\n\n---\n\n**Built with ❤️ using Node.js, Express, and Transformers.js**\n\n*This modular, production-ready AI FAQ Assistant provides a solid foundation for building intelligent support systems with semantic search capabilities.* ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuhahemal%2Fai-faq-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuhahemal%2Fai-faq-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuhahemal%2Fai-faq-assistant/lists"}