A production-ready RAG-powered learning assistant that combines document processing with conversational AI to help students and researchers interact with their materials more effectively.
- Smart Document Processing: Upload and process PDFs, DOCX, TXT, and Markdown files
- RAG System: Retrieval-Augmented Generation with configurable relevance thresholds
- Semantic Search: OpenAI embeddings with Pinecone vector database
- Text Selection: Highlight text for contextual explanations
- Chat Persistence: Document-scoped conversation history with offline support
- Production Security: CSRF protection, rate limiting, security headers
- Node.js 20+
- OpenAI API key
- Pinecone API key and index
# Clone the repository
git clone https://github.com/codeme-ne/checkstBot.git
cd checkstBot
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your API keys
# Run the development server
npm run devOpen http://localhost:3000 in your browser.
OPENAI_API_KEY=sk-your-openai-key-here
PINECONE_API_KEY=your-pinecone-key-here
PINECONE_INDEX=your-pinecone-index-nameSee .env.example for all available options.
| Layer | Technology |
|---|---|
| Framework | Next.js 14 (Pages Router) |
| Language | TypeScript (strict mode) |
| Styling | Tailwind CSS |
| Embeddings | OpenAI text-embedding-ada-002 |
| Vector DB | Pinecone |
| LLM | OpenAI GPT-4 |
checkstBot/
├── components/ # React components (11 specialized)
│ ├── ChatInterface.tsx # Chat UI with persistence
│ ├── EnhancedDocumentViewer.tsx # Smart document factory
│ ├── PDFViewer.tsx # PDF rendering
│ ├── MarkdownViewer.tsx # Markdown display
│ ├── TextViewer.tsx # Plain text display
│ ├── MessageBubble.tsx # Chat message rendering
│ ├── FileUpload.tsx # Drag-and-drop upload
│ ├── SelectionTooltip.tsx # Text selection actions
│ └── ...
├── lib/ # Core services
│ ├── rag.ts # RAG pipeline orchestration
│ ├── embedding.ts # OpenAI embeddings
│ ├── vector-db.ts # Pinecone operations
│ ├── document-parser.ts # File parsing
│ ├── csrf.ts # CSRF protection
│ └── rate-limit.ts # Request throttling
├── pages/ # Next.js pages (Pages Router)
│ ├── api/
│ │ ├── upload.ts # Document upload endpoint
│ │ ├── chat.ts # Chat completion endpoint
│ │ └── csrf.ts # CSRF token endpoint
│ └── index.tsx # Main application
├── __tests__/ # Test suite (53 tests)
└── styles/ # Tailwind styles
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Upload │───>│ Parse & │───>│ Generate │
│ Document │ │ Chunk │ │ Embeddings │
└─────────────┘ └─────────────┘ └─────────────┘
│
v
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Return │<───│ LLM with │<───│ Store in │
│ Response │ │ Context │ │ Pinecone │
└─────────────┘ └─────────────┘ └─────────────┘
^
│
┌─────────────┐ ┌─────────────┐
│ User │───>│ Semantic │
│ Query │ │ Search │
└─────────────┘ └─────────────┘
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint
npm run type-check # Run TypeScript checks
npm run test # Run test suite
npm run test -- --watch # TDD modeThis project follows Test-Driven Development (TDD). See CONTRIBUTING.md for the TDD workflow.
# Run all tests
npm run test
# Run with coverage
npm run test -- --coverage
# Watch mode for TDD
npm run test -- --watchSee SECURITY.md for:
- Vulnerability reporting process
- Security features implemented
- AI/RAG-specific security considerations
- Best practices for deployers
- Push to GitHub
- Connect to Vercel
- Add environment variables in Vercel dashboard
- Deploy
node scripts/pre-deploy-check.jsWe welcome contributions! Please see CONTRIBUTING.md for:
- Development setup
- TDD workflow
- Pull request guidelines
- Code style requirements
MIT - see the LICENSE file for details.
Built for enhanced learning and research.