# KnowledgeScout - AI-Powered Document Q&A A modern, full-stack document question-answering system built with Next.js 15, featuring semantic search powered by AI embeddings. Upload documents, ask questions, and get instant, contextual answers.    ## ✨ Features - **🤖 AI-Powered Search** - Semantic search using vector embeddings for accurate, context-aware answers - **📄 Document Management** - Upload and manage multiple document formats (PDF, TXT, MD, DOCX) - **💬 Interactive Q&A** - Ask questions in natural language and get instant answers with source citations - **🔐 Secure Authentication** - JWT-based auth with role-based access control (Admin/User) - **⚡ Real-time Updates** - Live document processing and instant search results - **🎨 Modern UI** - Beautiful, responsive interface with dark mode support - **📊 Admin Dashboard** - Comprehensive analytics and index management tools - **🔍 Vector Search** - Fast, accurate semantic search powered by embeddings ## 🚀 Tech Stack ### Frontend - **Next.js 15** - React framework with App Router - **TypeScript** - Type-safe development - **Tailwind CSS v4** - Modern utility-first styling - **shadcn/ui** - High-quality UI components - **Lucide Icons** - Beautiful, consistent icons ### Backend - **Next.js API Routes** - Serverless API endpoints - **SQLite** (better-sqlite3) - Lightweight, embedded database - **JWT** - Secure authentication tokens - **bcryptjs** - Password hashing ### AI/ML - **Vector Embeddings** - Semantic document understanding - **Cosine Similarity** - Accurate relevance scoring - **Chunking Strategy** - Optimized text segmentation ## 📋 Prerequisites - Node.js 18+ - npm, yarn, or pnpm - Modern web browser ## 🛠️ Installation ### Option 1: Using shadcn CLI (Recommended) \`\`\`bash npx shadcn@latest init \`\`\` Follow the prompts to set up the project with all dependencies. ### Option 2: Manual Installation 1. **Clone or download the project** \`\`\`bash # If you have the ZIP file unzip knowledgescout.zip cd knowledgescout \`\`\` 2. **Install dependencies** \`\`\`bash npm install # or yarn install # or pnpm install \`\`\` 3. **Set up environment variables** Create a `.env.local` file in the root directory: \`\`\`env # JWT Secret (generate a secure random string) JWT_SECRET=your-super-secret-jwt-key-change-this-in-production # Optional: OpenAI API Key for embeddings (if using OpenAI) # OPENAI_API_KEY=your-openai-api-key \`\`\` 4. **Initialize the database** The database will be automatically created on first run. To manually initialize: \`\`\`bash npm run db:init \`\`\` 5. **Run the development server** \`\`\`bash npm run dev \`\`\` Open [http://localhost:3000](http://localhost:3000) in your browser. ## 📖 Usage ### First Time Setup 1. **Create an account** - Navigate to the home page and sign up 2. **Login** - Use your credentials to access the app 3. **Upload documents** - Go to the Documents page and upload your files 4. **Ask questions** - Navigate to the Ask page and start querying your documents ### Admin Features Admin users have access to additional features: - **Index Management** - Rebuild the search index - **System Statistics** - View document counts, chunks, and vectors - **System Health** - Monitor database and search index status To create an admin user, modify the database directly or update the user creation logic in `lib/db.ts`. ## 🏗️ Project Structure \`\`\` knowledgescout/ ├── app/ # Next.js App Router │ ├── admin/ # Admin dashboard │ ├── api/ # API routes │ │ ├── auth/ # Authentication endpoints │ │ ├── documents/ # Document management │ │ ├── ask/ # Q&A endpoint │ │ └── admin/ # Admin endpoints │ ├── ask/ # Q&A interface │ ├── docs/ # Document management │ ├── globals.css # Global styles │ └── layout.tsx # Root layout ├── components/ # React components │ ├── ui/ # shadcn/ui components │ ├── auth-provider.tsx # Auth context │ └── nav-bar.tsx # Navigation ├── lib/ # Utilities │ ├── api-client.ts # API client │ ├── auth.ts # Auth utilities │ ├── db.ts # Database layer │ ├── embeddings.ts # Vector embeddings │ └── utils.ts # Helper functions ├── public/ # Static assets └── package.json # Dependencies \`\`\` ## 🔧 Configuration ### Database The app uses SQLite with the following schema: - **users** - User accounts and authentication - **documents** - Uploaded documents metadata - **chunks** - Document text chunks for processing - **embeddings** - Vector embeddings for semantic search ### Authentication - JWT tokens with 7-day expiration - Secure password hashing with bcrypt - Role-based access control (admin/user) ### Embeddings The system uses a simple but effective embedding strategy: - Documents are split into manageable chunks - Each chunk is converted to a vector embedding - Cosine similarity is used for relevance scoring To integrate with OpenAI or other embedding providers, update `lib/embeddings.ts`. ## 🚢 Deployment ### Deploy to Vercel (Recommended) 1. Push your code to GitHub 2. Import the project in Vercel 3. Add environment variables in Vercel dashboard 4. Deploy! [](https://vercel.com/new) ### Other Platforms The app can be deployed to any platform that supports Next.js: - **Netlify** - Use the Next.js runtime - **Railway** - Deploy with automatic HTTPS - **Docker** - Build a container image ## 🔐 Security Considerations - **JWT Secret** - Use a strong, random secret in production - **Password Hashing** - bcrypt with salt rounds - **Input Validation** - Sanitize all user inputs - **File Upload** - Validate file types and sizes - **Rate Limiting** - Consider adding rate limits for API routes ## 🤝 Contributing Contributions are welcome! Please follow these steps: 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## 📝 License This project is licensed under the MIT License - see the LICENSE file for details. ## 🙏 Acknowledgments - [Next.js](https://nextjs.org/) - The React framework - [shadcn/ui](https://ui.shadcn.com/) - Beautiful UI components - [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS - [Lucide](https://lucide.dev/) - Icon library ## 📧 Support For questions or issues, please open an issue on GitHub or contact the maintainers. --- Built with ❤️ using Next.js and AI # hackthon