ultracite— rules

<h1 align="center">Criterion - Islamic Knowledge Assistant</h1>

<p align="center"> <strong>An AI-powered Da'i (invitor to Islam)</strong> bringing authentic Islamic guidance to seekers worldwide. </p>

<p align="center"> Built on the Quran and authentic Hadith. Free forever. For the sake of Allah. </p>

<p align="center"> <a href="#mission"><strong>Mission</strong></a> · <a href="#features"><strong>Features</strong></a> · <a href="#tech-stack"><strong>Tech Stack</strong></a> · <a href="#getting-started"><strong>Getting Started</strong></a> · <a href="#mcp-server"><strong>MCP Server</strong></a> · <a href="#documentation"><strong>Documentation</strong></a> </p> <br/>

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 App Router with React 19 & Tailwind CSS
• Vercel AI SDK for LLM integration and streaming
• XAI Grok 4 for intelligent natural language responses
• PostgreSQL with pgvector for vector search
• Drizzle ORM for type-safe database access
• Google Gemini text-embedding-004 (768 dimensions)
• HNSW indexes for <150ms similarity search
• Auth.js for authentication
• Deployed on Vercel

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)
• API Keys:
• XAI API Key (for Grok LLM)
• Google AI Studio API Key (for embeddings)

Installation

1. Clone the repository

git clone <repo-url>
cd criterion

1. Install dependencies

pnpm install

1. Set up environment variables

Create a .env.local file:

# Database
POSTGRES_URL=postgresql://...

# AI APIs
XAI_API_KEY=xai-...
GOOGLE_GENERATIVE_AI_API_KEY=...

# Authentication (optional)
AUTH_SECRET=...

1. Enable pgvector extension

pnpm db:enable-pgvector

1. Run database migrations

pnpm db:migrate

1. Ingest Quran data (generates embeddings for 6,236 verses)

pnpm ingest:quran

This will take 10-15 minutes to complete.

1. Test the Quran search

pnpm test:quran

1. Start the development server

pnpm dev

Your app should now be running on localhost:3000.

Available Commands

Development

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm start        # Start production server

Database

pnpm db:generate  # Generate Drizzle schema
pnpm db:migrate   # Run migrations
pnpm db:studio    # Open Drizzle Studio (GUI)

Data Ingestion & Testing

# 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:

{
  "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

Architecture Overview

components/
├── Chat UI (QuranVerses, HadithNarrations, MessageActions)
├── Search Pages (Quran and Hadith semantic search with filters)
├── Hadith Components (reusable HadithCard for search and chat)
├── Quran Pages (shared components for context, language selection)
└── UI Components (buttons, inputs, etc.)

lib/
├── ai/
│   ├── embeddings.ts (vector search logic)
│   ├── prompts.ts (Da'i system prompts)
│   └── tools/ (queryQuran, queryHadith, requestSuggestions)
├── db/
│   ├── schema.ts (Drizzle ORM definitions)
│   └── queries.ts (database functions)
└── monitoring/ (performance tracking)

app/
├── (chat)/api/chat (main chat endpoint)
├── quran/search/ (Quran search page and API)
├── hadith/search/ (Hadith search page and API)
├── quran/ (Quran reading pages)
└── (auth)/ (authentication)

Data Attribution

• Quran Text: Tanzil.net — Creative Commons Attribution 3.0
• Quran Translations: Multiple sources with proper attribution
• Hadith Collections: Sunnah.com, IslamicNetwork.com
• Embeddings: Google Gemini text-embedding-004

Our Commitment

Criterion is built with these commitments:

• ✅ Never monetize Islamic knowledge
• ✅ Always cite sources with proper references
• ✅ Never fabricate verses or hadiths
• ✅ Focus on fundamentals — avoid sectarian debates
• ✅ Build for the community — this belongs to all Muslims and benefits all humanity
• ✅ Stay at the forefront — leverage state-of-the-art technology

Contributing

We welcome contributions from developers, scholars, and community members who share our mission. Please see CONTRIBUTING.md for guidelines.

License

• Quran Text: Creative Commons Attribution 3.0 (Tanzil.net)
• Hadith Data: From verified Islamic sources with proper attribution
• Code: See LICENSE file for details

"Invite to the way of your Lord with wisdom and good instruction, and argue with them in a way that is best." — Quran 16:125

_May Allah accept this work and make it a means of guidance for seekers everywhere. Ameen._