Criterion - Islamic Knowledge Assistant
An AI-powered Da'i (invitor to Islam) bringing authentic Islamic guidance to seekers worldwide.
Built on the Quran and authentic Hadith. Free forever. For the sake of Allah.
Mission ·
Features ·
Tech Stack ·
Getting Started ·
MCP Server ·
Documentation
## Mission
Criterion exists to bring authentic Islamic knowledge to anyone seeking truth, using modern technology to make divine guidance accessible to all of humanity — **freely, forever, for the sake of Allah alone.**
### Our Four Pillars
1. **Truth & Authenticity** — Every response is grounded in verified sources (Quran and Sahih Hadith). We never fabricate or hallucinate.
2. **Fundamentals & Simplicity** — We focus on core Islamic teachings that unite. We avoid sectarian debates and controversial topics.
3. **For the Sake of Allah** — Criterion will always be free, with no monetization or organizational promotion. This is Sadaqah Jariyah.
4. **State of the Art** — We use cutting-edge AI to deliver Islamic guidance effectively to the masses.
👉 **[Read the full mission and vision in MISSION.md](./MISSION.md)**
## Key Differentiators
**Mission-Aligned:**
- ✨ **Free Forever** — No paywalls, no ads, no monetization. Built fi sabilillah (for Allah's sake)
- 📚 **Fundamentals-Focused** — Avoids sectarian debates, focuses on universally accepted Islamic teachings
- 🛡️ **Trust-First** — Grade-filtered authentic Hadith (defaults to Sahih), verified sources only
- 🤝 **Seeker-Oriented** — Designed for curious minds, new Muslims, and students of knowledge
- 🕌 **Da'i Personality** — Compassionate, knowledgeable, humble guidance
**Technical Excellence:**
- 🎯 **Semantic Search** — Natural language queries return relevant verses from 6,236 Quran verses + 21,641 Hadith narrations
- 📖 **Contextual Retrieval** — Top results include ±2 surrounding verses/narrations for proper context
- 🌐 **Multilingual** — Read in English (fast) + Slovak (expandable to 10+ languages)
- 🔗 **Accurate Citations** — All responses include source references with hyperlinks (Quran.com, Sunnah.com)
- ⚡ **Fast** — <150ms query response time
## Features
### What Criterion Does
✅ **Semantic Quran Search** — Ask natural language questions, get relevant verses
✅ **Semantic Hadith Search** — Search authentic Hadith with grade & collection filtering
✅ **Contextual Understanding** — Top results include surrounding context for proper meaning
✅ **Accurate Citations** — Every response cites real sources with hyperlinks
✅ **Multilingual Reading** — English (fast) + Slovak (single JOIN <200ms)
✅ **Shareable URLs** — `/quran/search?q=patience`, `/hadith/search?q=charity`, and `/quran/2/255` with metadata
✅ **Real-time Streaming** — Progressive response generation with token-by-token delivery
✅ **Tool-Based RAG** — LLM autonomously decides when to retrieve from Quran/Hadith
### Technical Stack
- [Next.js 15](https://nextjs.org) App Router with React 19 & Tailwind CSS
- [Vercel AI SDK](https://ai-sdk.dev) for LLM integration and streaming
- [XAI Grok 4](https://x.ai) for intelligent natural language responses
- [PostgreSQL](https://neon.tech) with [pgvector](https://github.com/pgvector/pgvector) for vector search
- [Drizzle ORM](https://orm.drizzle.team) for type-safe database access
- [Google Gemini](https://ai.google.dev) text-embedding-004 (768 dimensions)
- HNSW indexes for <150ms similarity search
- [Auth.js](https://authjs.dev) for authentication
- Deployed on [Vercel](https://vercel.com)
## How It Works
### The RAG Pipeline
```
User Question
↓
XAI Grok 4 LLM (decides which tools to use)
↓
Tool Selection:
- queryQuran → 6,236 verses (top 7 for chat, top 20 for search)
- queryHadith → 21,641 hadiths from 6 collections (top 3 for chat, top 15 for search, with grade filtering)
↓
Vector Search (768-dim Gemini embeddings)
↓
Context Enhancement (top 3 get ±2 surrounding verses)
↓
LLM Generates Response with Citations
↓
Real-time Stream to User (Server-Sent Events)
```
### Data
- **6,236 Quran verses** from all 114 Surahs
- Arabic text (Tanzil Quran)
- English translation (master)
- Slovak translation (expandable)
- 768-dimensional embeddings (Gemini text-embedding-004)
- **21,641 Hadith narrations** from 6 major collections (Kutub al-Sittah subset)
- Sahih Bukhari (7,558)
- Sahih Muslim (2,920)
- Jami` at-Tirmidhi (3,951)
- Sunan Abi Dawud (5,274)
- 40 Hadith Nawawi (42)
- Riyad as-Salihin (1,896)
- Grade filtering (Sahih, Hasan, Da'if)
- 768-dimensional embeddings
### Performance
- **Quran search**: <150ms (English), <200ms (translated)
- **Hadith search**: <150ms
- **Vector search**: Powered by HNSW indexes
- **Streaming**: Real-time token-by-token delivery
## Getting Started
### Prerequisites
- Node.js 18+ and pnpm
- PostgreSQL database (recommend [Neon](https://neon.tech))
- API Keys:
- XAI API Key (for Grok LLM)
- Google AI Studio API Key (for embeddings)
### Installation
1. **Clone the repository**
```bash
git clone
cd criterion
```
2. **Install dependencies**
```bash
pnpm install
```
3. **Set up environment variables**
Create a `.env.local` file:
```bash
# Database
POSTGRES_URL=postgresql://...
# AI APIs
XAI_API_KEY=xai-...
GOOGLE_GENERATIVE_AI_API_KEY=...
# Authentication (optional)
AUTH_SECRET=...
```
4. **Enable pgvector extension**
```bash
pnpm db:enable-pgvector
```
5. **Run database migrations**
```bash
pnpm db:migrate
```
6. **Ingest Quran data** (generates embeddings for 6,236 verses)
```bash
pnpm ingest:quran
```
This will take 10-15 minutes to complete.
7. **Test the Quran search**
```bash
pnpm test:quran
```
8. **Start the development server**
```bash
pnpm dev
```
Your app should now be running on [localhost:3000](http://localhost:3000).
## Available Commands
### Development
```bash
pnpm dev # Start dev server
pnpm build # Build for production
pnpm start # Start production server
```
### Database
```bash
pnpm db:generate # Generate Drizzle schema
pnpm db:migrate # Run migrations
pnpm db:studio # Open Drizzle Studio (GUI)
```
### Data Ingestion & Testing
```bash
# Quran
pnpm clear:quran # Clear all Quran data
pnpm ingest:quran # Ingest Quran verses and generate embeddings
pnpm ingest:quran:slovak # Ingest Slovak translation
pnpm test:quran # Test Quran search functionality
# Hadith
pnpm clear:hadith # Clear all Hadith data
pnpm ingest:hadith # Ingest Hadith and generate embeddings
```
## MCP Server
Criterion exposes its semantic search capabilities through the **Model Context Protocol (MCP)**, allowing AI assistants like Claude Desktop and Cursor to search Quran and Hadith directly.
**Quick Setup:**
```json
{
"mcpServers": {
"criterion": {
"url": "https://criterion.life/api/mcp"
}
}
}
```
**Available Tools:**
- `search_quran` — Search 6,236 Quran verses
- `search_hadith` — Search 21,641 authentic Hadiths from 6 collections
- `get_verse` — Retrieve specific verse by reference (e.g., "2:255")
👉 **[Read full MCP documentation in MCP.md](./MCP.md)**
## Project Structure
```
criterion/
├── app/
│ ├── (auth)/ # Authentication routes
│ ├── (chat)/ # Chat interface and API
│ │ └── api/chat/ # Main chat endpoint
│ ├── search/ # Quran search page
│ │ └── api/ # Quran search API
│ ├── hadith/
│ │ └── search/ # Hadith search page and API
│ └── quran/ # Quran reading pages
├── lib/
│ ├── ai/
│ │ ├── embeddings.ts # Core RAG logic
│ │ ├── prompts.ts # Da'i system prompts
│ │ └── tools/
│ │ ├── query-quran.ts # Quran search tool
│ │ └── query-hadith.ts # Hadith search tool
│ └── db/
│ ├── schema.ts # Database schema
│ └── migrations/ # SQL migrations
├── components/
│ ├── chat.tsx # Main chat UI
│ ├── quran-verses.tsx # Quran display component
│ ├── hadith-narrations.tsx # Hadith carousel
│ └── hadith/
│ └── hadith-card.tsx # Reusable hadith card
├── scripts/
│ ├── ingest-quran.ts # Quran data ingestion
│ ├── ingest-hadith.ts # Hadith data ingestion
│ └── test-*.ts # Test scripts
└── data/
├── quran*.txt # Quran translations
└── *-full.json # Hadith collections
```
## Documentation
### Understanding Criterion
- **[MISSION.md](./MISSION.md)** — Our vision, values, and deeper purpose. Read this first to understand _why_ we build Criterion.
- **[CRITERION_DETAILED.md](./CRITERION_DETAILED.md)** — Comprehensive technical documentation including architecture, implementation history, and performance metrics.
- **[CRITERION.md](./CRITERION.md)** — Quick reference guide for setup and key concepts.
### Key Sections
| Document | Purpose |
| ------------------------- | ----------------------------------------------------------------------- |
| **MISSION.md** | Vision, values, pillars, and long-term goals |
| **CRITERION_DETAILED.md** | Technical architecture, database schema, components, and best practices |
| **CRITERION.md** | Quick start, commands, and core concepts |
| **README.md** | Getting started, features, and project overview |
## Architecture Overview
```
components/
├── Chat UI (QuranVerses, HadithNarrations, MessageActions)
---
