added

.env.example

@@ -0,0 +1,42 @@
+# API Configuration
+API_TITLE="Sanad LLM API"
+API_DESCRIPTION="A FastAPI application for hadith narrator analysis"
+API_VERSION="1.0.0"
+DEBUG=True
+PORT=8000
+HOST="0.0.0.0"
+
+# Allowed CORS origins (comma-separated)
+ALLOWED_ORIGINS="http://localhost:3000,http://localhost:8000,http://localhost:5173"
+
+# JWT Configuration
+JWT_SECRET_KEY="your-super-secret-jwt-key-change-this-in-production"
+JWT_ALGORITHM="HS256"
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
+
+# Supabase Configuration
+SUPABASE_URL="https://your-project.supabase.co"
+SUPABASE_SERVICE_KEY="your-supabase-service-role-key"
+SUPABASE_ANON_KEY="your-supabase-anon-key"
+
+# Redis Configuration (for rate limiting)
+REDIS_URL="redis://localhost:6379"
+REDIS_HOST="localhost"
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=""
+
+# Rate Limiting
+RATE_LIMIT_REQUESTS_PER_MINUTE=60
+RATE_LIMIT_BURST=10
+
+# LLM Configuration
+GOOGLE_API_KEY="your-google-api-key"
+GROQ_API_KEY="your-groq-api-key"
+
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/sanad_llm"
+
+# Logging
+LOG_LEVEL="INFO"

AUTHENTICATION.md

@@ -0,0 +1,295 @@
+# SanadCheck LLM API - Authentication & Database Implementation
+
+This document outlines the JWT authentication, rate limiting, and database storage features that have been implemented for the SanadCheck LLM API.
+
+## Features Implemented
+
+### 🔐 JWT Authentication with Supabase
+- User registration and login using Supabase Auth
+- JWT token generation and validation
+- Session management with token refresh
+- Role-based access control (User, Admin, Researcher)
+- Token blacklisting for logout functionality
+
+### 🚀 Rate Limiting
+- Redis-based rate limiting with SlowAPI
+- Different limits for authenticated vs anonymous users
+- IP-based and user-based rate limiting
+- Burst protection and graceful degradation
+
+### 📊 Database Storage
+- All narrator extractions and analyses are stored in Supabase
+- User analytics and usage tracking
+- Performance metrics and success rates
+- Popular narrators tracking
+
+### 🔒 Protected Routes
+- All API endpoints now require JWT authentication
+- Rate limiting applied to all endpoints
+- IP tracking for security and analytics
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Supabase Setup
+
+1. Create a new Supabase project at [supabase.com](https://supabase.com)
+2. Copy your project URL and service role key
+3. Run the SQL scripts in the `sql/` directory in your Supabase SQL Editor:
+   - First: `sql/create_tables.sql`
+   - Then: `sql/sample_data.sql`
+
+### 3. Redis Setup (Optional)
+
+For production, install and configure Redis:
+
+```bash
+# On Ubuntu/Debian
+sudo apt update
+sudo apt install redis-server
+
+# On Fedora
+sudo dnf install redis
+
+# Start Redis
+sudo systemctl start redis
+sudo systemctl enable redis
+```
+
+For development, the API will work with in-memory rate limiting if Redis is not available.
+
+### 4. Environment Configuration
+
+Copy `.env.example` to `.env` and update with your values:
+
+```bash
+cp .env.example .env
+```
+
+Required environment variables:
+- `SUPABASE_URL`: Your Supabase project URL
+- `SUPABASE_SERVICE_KEY`: Your Supabase service role key
+- `JWT_SECRET_KEY`: A secure secret key for JWT signing
+- `REDIS_URL`: Redis connection URL (optional)
+
+### 5. Run the Application
+
+```bash
+# Development
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Production
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## API Usage
+
+### Authentication Flow
+
+1. **Register a new user:**
+```bash
+curl -X POST "http://localhost:8000/auth/register" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "securepassword",
+    "username": "username",
+    "full_name": "Full Name"
+  }'
+```
+
+2. **Login:**
+```bash
+curl -X POST "http://localhost:8000/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "securepassword"
+  }'
+```
+
+3. **Use the access token for API calls:**
+```bash
+curl -X POST "http://localhost:8000/api/v1/extract-narrators" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -d '{
+    "hadith_text": "حدثنا محمد بن إسماعيل..."
+  }'
+```
+
+### Available Endpoints
+
+#### Authentication
+- `POST /auth/register` - Register new user
+- `POST /auth/login` - Login user
+- `POST /auth/refresh` - Refresh access token
+- `POST /auth/logout` - Logout user
+- `GET /auth/me` - Get current user info
+- `GET /auth/sessions` - Get user sessions
+
+#### Hadith Analysis (Protected)
+- `POST /api/v1/extract-narrators` - Extract narrators from hadith
+- `POST /api/v1/analyze-narrator` - Analyze single narrator
+- `POST /api/v1/analyze-narrator-chain` - Analyze narrator chain
+- `POST /api/v1/extract-and-analyze` - Complete analysis workflow
+
+#### Analytics (Mixed Access)
+- `GET /api/v1/user/extractions` - Get user's extraction history (Protected)
+- `GET /api/v1/user/analyses` - Get user's analysis history (Protected)
+- `GET /api/v1/analytics/stats` - Get platform statistics (Public)
+- `GET /api/v1/analytics/popular-narrators` - Get popular narrators (Public)
+
+#### Utility
+- `GET /api/v1/health` - Health check (Public)
+
+## Database Schema
+
+### Tables Created
+1. **users** - Extended user profiles linked to Supabase auth
+2. **user_sessions** - JWT session tracking
+3. **narrator_extractions** - Records of narrator extraction requests
+4. **narrator_analyses** - Records of narrator analysis requests
+
+### Security Features
+- Row Level Security (RLS) enabled on all tables
+- Users can only access their own data
+- Service role has full access for admin operations
+- Automatic user profile creation on signup
+
+## Rate Limiting
+
+### Default Limits
+- **Anonymous users**: 60 requests/minute
+- **Authenticated users**: 120 requests/minute
+- **Admin users**: 300 requests/minute
+- **Burst protection**: 10 requests/second
+
+### Rate Limit Headers
+Responses include rate limit information:
+- `X-RateLimit-Limit`: Request limit
+- `X-RateLimit-Remaining`: Remaining requests
+- `X-RateLimit-Reset`: Reset time
+
+## Analytics and Monitoring
+
+### User Analytics
+- Track extraction and analysis usage per user
+- Monitor success rates and processing times
+- Popular narrator trends
+- User activity patterns
+
+### Platform Statistics
+- Overall success rates
+- Average processing times
+- Most analyzed narrators
+- User growth metrics
+
+## Security Considerations
+
+### JWT Security
+- Tokens have expiration times
+- Refresh tokens for long-term access
+- Token blacklisting on logout
+- Secure secret key required
+
+### Database Security
+- Row Level Security (RLS) enforced
+- User data isolation
+- SQL injection protection
+- Parameterized queries
+
+### Rate Limiting
+- Prevents abuse and DoS attacks
+- IP-based and user-based tracking
+- Graceful degradation when limits exceeded
+
+## Data Collection for NLP
+
+All user interactions are stored for machine learning purposes:
+
+### Extraction Data
+- Original hadith texts
+- Extracted narrator names
+- Extraction success/failure rates
+- Processing times
+- User feedback (future feature)
+
+### Analysis Data
+- Narrator names analyzed
+- Reliability grades assigned
+- Confidence levels
+- User preferences and patterns
+
+This data can be used to:
+- Improve narrator extraction accuracy
+- Train better reliability assessment models
+- Understand user behavior patterns
+- Optimize processing performance
+
+## Development Notes
+
+### Code Structure
+```
+app/
+├── auth/                 # Authentication routes
+├── middleware/           # JWT auth and rate limiting
+├── services/            # Database and business logic
+├── api/                 # Protected API routes
+├── db/                  # Data models
+└── config/              # Settings and configuration
+
+sql/                     # Database schema and setup
+├── create_tables.sql    # Main schema
+└── sample_data.sql      # Functions and sample data
+```
+
+### Key Components
+- **AuthMiddleware**: JWT token handling and validation
+- **RateLimitMiddleware**: Redis-based rate limiting
+- **DatabaseService**: Supabase database operations
+- **Protected Routes**: All endpoints require authentication
+
+## Future Enhancements
+
+1. **User Feedback System**: Allow users to rate extraction/analysis quality
+2. **Advanced Analytics**: Machine learning insights from user data
+3. **Bulk Operations**: Support for batch processing
+4. **API Versioning**: Maintain backward compatibility
+5. **Caching Layer**: Redis caching for frequent narrator lookups
+6. **Audit Logging**: Detailed security and usage logs
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Supabase Connection Failed**
+   - Check `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` in `.env`
+   - Verify Supabase project is active
+   - Ensure SQL scripts were executed
+
+2. **Redis Connection Failed**
+   - Rate limiting will use in-memory storage
+   - Install and start Redis service
+   - Check `REDIS_URL` in `.env`
+
+3. **JWT Token Invalid**
+   - Check `JWT_SECRET_KEY` in `.env`
+   - Verify token hasn't expired
+   - Ensure token isn't blacklisted
+
+4. **Rate Limit Exceeded**
+   - Wait for rate limit window to reset
+   - Use authenticated requests for higher limits
+   - Contact admin for limit increases
+
+### Logs and Debugging
+- Set `DEBUG=True` in `.env` for detailed error messages
+- Check application logs for authentication errors
+- Monitor Supabase logs for database issues
+- Use `/health` endpoint to verify service status

NEXTJS_INTEGRATION_GUIDE.md

@@ -0,0 +1,960 @@
+# SanadCheck API Authentication Integration Guide for Next.js
+
+This comprehensive guide shows how to integrate the SanadCheck LLM API authentication system into a Next.js application. The backend provides JWT-based authentication with Supabase, rate limiting, and comprehensive session management.
+
+## Table of Contents
+1. [Backend API Overview](#backend-api-overview)
+2. [Next.js Setup](#nextjs-setup)
+3. [Authentication Service](#authentication-service)
+4. [API Client Setup](#api-client-setup)
+5. [React Hooks for Authentication](#react-hooks-for-authentication)
+6. [Protected Routes & Middleware](#protected-routes--middleware)
+7. [Components](#components)
+8. [Usage Examples](#usage-examples)
+9. [Error Handling](#error-handling)
+10. [Best Practices](#best-practices)
+
+## Backend API Overview
+
+The SanadCheck API provides the following authentication endpoints:
+
+### Authentication Endpoints
+- `POST /auth/register` - User registration
+- `POST /auth/login` - User login
+- `POST /auth/refresh` - Token refresh
+- `POST /auth/logout` - User logout
+- `GET /auth/me` - Get current user info
+- `GET /auth/sessions` - Get user sessions
+
+### Protected API Endpoints
+- `POST /api/v1/extract-narrators` - Extract narrators from hadith
+- `POST /api/v1/analyze-narrator` - Analyze individual narrator
+- `POST /api/v1/analyze-chain` - Analyze narrator chain
+- `POST /api/v1/extract-and-analyze` - Complete analysis
+
+### Rate Limiting
+- Anonymous users: Limited requests per IP
+- Authenticated users: Higher limits per user ID
+- Redis-based with burst protection
+
+## Next.js Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install axios js-cookie next-auth
+# or
+yarn add axios js-cookie next-auth
+```
+
+### 2. Environment Variables
+
+Create `.env.local`:
+
+```env
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_API_VERSION=v1
+NEXTAUTH_SECRET=your-nextauth-secret
+NEXTAUTH_URL=http://localhost:3000
+```
+
+### 3. Project Structure
+
+```
+src/
+├── lib/
+│   ├── api.ts              # API client configuration
+│   ├── auth.ts             # Authentication service
+│   └── types.ts            # TypeScript types
+├── hooks/
+│   └── useAuth.ts          # Authentication hooks
+├── middleware.ts           # Next.js middleware for route protection
+├── components/
+│   ├── auth/
+│   │   ├── LoginForm.tsx
+│   │   ├── RegisterForm.tsx
+│   │   └── AuthProvider.tsx
+│   └── ui/
+│       └── ProtectedRoute.tsx
+├── pages/
+│   ├── auth/
+│   │   ├── login.tsx
+│   │   └── register.tsx
+│   ├── dashboard.tsx
+│   └── api/
+│       └── auth/
+│           └── [...nextauth].ts
+```
+
+## Authentication Service
+
+### TypeScript Types (`src/lib/types.ts`)
+
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  username?: string;
+  full_name?: string;
+  role: 'user' | 'admin' | 'researcher';
+  is_active: boolean;
+  created_at?: string;
+  last_login?: string;
+}
+
+export interface AuthResponse {
+  access_token: string;
+  refresh_token?: string;
+  token_type: string;
+  expires_in: number;
+  user: User;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface RegisterRequest {
+  email: string;
+  password: string;
+  username?: string;
+  full_name?: string;
+}
+
+export interface ApiError {
+  detail: string;
+  status_code?: number;
+}
+
+// Hadith Analysis Types
+export interface HadithTextRequest {
+  text: string;
+  language?: string;
+}
+
+export interface NarratorExtractionResponse {
+  narrators: string[];
+  sanad_chain: string;
+  success: boolean;
+  metadata: {
+    processing_time_ms: number;
+    text_length: number;
+    extraction_method: string;
+  };
+}
+
+export interface NarratorAnalysisRequest {
+  narrator_name: string;
+  context?: string;
+}
+
+export interface NarratorAnalysisResponse {
+  narrator: string;
+  reliability_grade: string;
+  confidence_level: string;
+  reasoning: string;
+  scholarly_consensus: string;
+  known_issues?: string;
+  biographical_info: string;
+  recommendation: string;
+  success: boolean;
+  metadata: {
+    processing_time_ms: number;
+    analysis_method: string;
+  };
+}
+```
+
+### API Client (`src/lib/api.ts`)
+
+```typescript
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import Cookies from 'js-cookie';
+
+class ApiClient {
+  private client: AxiosInstance;
+  private baseURL: string;
+
+  constructor() {
+    this.baseURL = process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:8000';
+    
+    this.client = axios.create({
+      baseURL: this.baseURL,
+      timeout: 30000,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    this.setupInterceptors();
+  }
+
+  private setupInterceptors() {
+    // Request interceptor to add auth token
+    this.client.interceptors.request.use(
+      (config) => {
+        const token = Cookies.get('access_token');
+        if (token) {
+          config.headers.Authorization = `Bearer ${token}`;
+        }
+        return config;
+      },
+      (error) => Promise.reject(error)
+    );
+
+    // Response interceptor for token refresh
+    this.client.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        const originalRequest = error.config;
+
+        if (error.response?.status === 401 && !originalRequest._retry) {
+          originalRequest._retry = true;
+
+          try {
+            const refreshToken = Cookies.get('refresh_token');
+            if (refreshToken) {
+              const response = await this.refreshToken(refreshToken);
+              const { access_token } = response.data;
+              
+              Cookies.set('access_token', access_token, { 
+                expires: 7, 
+                secure: process.env.NODE_ENV === 'production' 
+              });
+              
+              originalRequest.headers.Authorization = `Bearer ${access_token}`;
+              return this.client(originalRequest);
+            }
+          } catch (refreshError) {
+            // Refresh failed, logout user
+            this.logout();
+            window.location.href = '/auth/login';
+          }
+        }
+
+        return Promise.reject(error);
+      }
+    );
+  }
+
+  // Auth methods
+  async login(credentials: LoginRequest): Promise<AxiosResponse<AuthResponse>> {
+    return this.client.post('/auth/login', credentials);
+  }
+
+  async register(userData: RegisterRequest): Promise<AxiosResponse<AuthResponse>> {
+    return this.client.post('/auth/register', userData);
+  }
+
+  async refreshToken(refresh_token: string): Promise<AxiosResponse<AuthResponse>> {
+    return this.client.post('/auth/refresh', { refresh_token });
+  }
+
+  async logout(): Promise<void> {
+    try {
+      await this.client.post('/auth/logout');
+    } catch (error) {
+      console.error('Logout error:', error);
+    } finally {
+      Cookies.remove('access_token');
+      Cookies.remove('refresh_token');
+    }
+  }
+
+  async getCurrentUser(): Promise<AxiosResponse<User>> {
+    return this.client.get('/auth/me');
+  }
+
+  async getUserSessions(): Promise<AxiosResponse<{ sessions: any[] }>> {
+    return this.client.get('/auth/sessions');
+  }
+
+  // Hadith Analysis API methods
+  async extractNarrators(data: HadithTextRequest): Promise<AxiosResponse<NarratorExtractionResponse>> {
+    return this.client.post(`/api/${process.env.NEXT_PUBLIC_API_VERSION}/extract-narrators`, data);
+  }
+
+  async analyzeNarrator(data: NarratorAnalysisRequest): Promise<AxiosResponse<NarratorAnalysisResponse>> {
+    return this.client.post(`/api/${process.env.NEXT_PUBLIC_API_VERSION}/analyze-narrator`, data);
+  }
+
+  async analyzeNarratorChain(data: { narrators: string[] }): Promise<AxiosResponse<any>> {
+    return this.client.post(`/api/${process.env.NEXT_PUBLIC_API_VERSION}/analyze-chain`, data);
+  }
+
+  async extractAndAnalyze(data: HadithTextRequest): Promise<AxiosResponse<any>> {
+    return this.client.post(`/api/${process.env.NEXT_PUBLIC_API_VERSION}/extract-and-analyze`, data);
+  }
+}
+
+export const apiClient = new ApiClient();
+```
+
+### Authentication Service (`src/lib/auth.ts`)
+
+```typescript
+import { apiClient } from './api';
+import { User, LoginRequest, RegisterRequest, AuthResponse } from './types';
+import Cookies from 'js-cookie';
+
+export class AuthService {
+  static async login(credentials: LoginRequest): Promise<{ user: User; tokens: AuthResponse }> {
+    try {
+      const response = await apiClient.login(credentials);
+      const authData = response.data;
+
+      // Store tokens in secure cookies
+      Cookies.set('access_token', authData.access_token, { 
+        expires: 7, 
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'strict'
+      });
+      
+      if (authData.refresh_token) {
+        Cookies.set('refresh_token', authData.refresh_token, { 
+          expires: 30, 
+          secure: process.env.NODE_ENV === 'production',
+          sameSite: 'strict'
+        });
+      }
+
+      return {
+        user: authData.user,
+        tokens: authData
+      };
+    } catch (error: any) {
+      throw new Error(error.response?.data?.detail || 'Login failed');
+    }
+  }
+
+  static async register(userData: RegisterRequest): Promise<{ user: User; tokens: AuthResponse }> {
+    try {
+      const response = await apiClient.register(userData);
+      const authData = response.data;
+
+      // Store tokens in secure cookies
+      Cookies.set('access_token', authData.access_token, { 
+        expires: 7, 
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'strict'
+      });
+      
+      if (authData.refresh_token) {
+        Cookies.set('refresh_token', authData.refresh_token, { 
+          expires: 30, 
+          secure: process.env.NODE_ENV === 'production',
+          sameSite: 'strict'
+        });
+      }
+
+      return {
+        user: authData.user,
+        tokens: authData
+      };
+    } catch (error: any) {
+      throw new Error(error.response?.data?.detail || 'Registration failed');
+    }
+  }
+
+  static async logout(): Promise<void> {
+    await apiClient.logout();
+  }
+
+  static async getCurrentUser(): Promise<User | null> {
+    try {
+      const token = Cookies.get('access_token');
+      if (!token) return null;
+
+      const response = await apiClient.getCurrentUser();
+      return response.data;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  static isAuthenticated(): boolean {
+    return !!Cookies.get('access_token');
+  }
+
+  static getToken(): string | undefined {
+    return Cookies.get('access_token');
+  }
+}
+```
+
+## React Hooks for Authentication
+
+### Authentication Hook (`src/hooks/useAuth.ts`)
+
+```typescript
+'use client';
+
+import { useState, useEffect, useContext, createContext, ReactNode } from 'react';
+import { User, LoginRequest, RegisterRequest } from '@/lib/types';
+import { AuthService } from '@/lib/auth';
+
+interface AuthContextType {
+  user: User | null;
+  loading: boolean;
+  error: string | null;
+  login: (credentials: LoginRequest) => Promise<void>;
+  register: (userData: RegisterRequest) => Promise<void>;
+  logout: () => Promise<void>;
+  clearError: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadUser();
+  }, []);
+
+  const loadUser = async () => {
+    try {
+      setLoading(true);
+      const currentUser = await AuthService.getCurrentUser();
+      setUser(currentUser);
+    } catch (error) {
+      console.error('Failed to load user:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const login = async (credentials: LoginRequest) => {
+    try {
+      setLoading(true);
+      setError(null);
+      const { user } = await AuthService.login(credentials);
+      setUser(user);
+    } catch (error: any) {
+      setError(error.message);
+      throw error;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const register = async (userData: RegisterRequest) => {
+    try {
+      setLoading(true);
+      setError(null);
+      const { user } = await AuthService.register(userData);
+      setUser(user);
+    } catch (error: any) {
+      setError(error.message);
+      throw error;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const logout = async () => {
+    try {
+      setLoading(true);
+      await AuthService.logout();
+      setUser(null);
+    } catch (error) {
+      console.error('Logout error:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const clearError = () => setError(null);
+
+  return (
+    <AuthContext.Provider
+      value={{
+        user,
+        loading,
+        error,
+        login,
+        register,
+        logout,
+        clearError,
+      }}
+    >
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return context;
+}
+```
+
+## Protected Routes & Middleware
+
+### Next.js Middleware (`src/middleware.ts`)
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('access_token')?.value;
+  const { pathname } = request.nextUrl;
+
+  // Define protected routes
+  const protectedRoutes = ['/dashboard', '/profile', '/analysis'];
+  const authRoutes = ['/auth/login', '/auth/register'];
+
+  // Check if the current route is protected
+  const isProtectedRoute = protectedRoutes.some(route => 
+    pathname.startsWith(route)
+  );
+
+  // Check if the current route is an auth route
+  const isAuthRoute = authRoutes.some(route => 
+    pathname.startsWith(route)
+  );
+
+  // Redirect to login if accessing protected route without token
+  if (isProtectedRoute && !token) {
+    return NextResponse.redirect(new URL('/auth/login', request.url));
+  }
+
+  // Redirect to dashboard if accessing auth routes while logged in
+  if (isAuthRoute && token) {
+    return NextResponse.redirect(new URL('/dashboard', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
+};
+```
+
+### Protected Route Component (`src/components/ui/ProtectedRoute.tsx`)
+
+```typescript
+'use client';
+
+import { useAuth } from '@/hooks/useAuth';
+import { useRouter } from 'next/navigation';
+import { useEffect, ReactNode } from 'react';
+
+interface ProtectedRouteProps {
+  children: ReactNode;
+  requiredRole?: 'user' | 'admin' | 'researcher';
+}
+
+export function ProtectedRoute({ children, requiredRole }: ProtectedRouteProps) {
+  const { user, loading } = useAuth();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!loading) {
+      if (!user) {
+        router.push('/auth/login');
+        return;
+      }
+
+      if (requiredRole && user.role !== requiredRole && user.role !== 'admin') {
+        router.push('/unauthorized');
+        return;
+      }
+    }
+  }, [user, loading, router, requiredRole]);
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-gray-900"></div>
+      </div>
+    );
+  }
+
+  if (!user) {
+    return null;
+  }
+
+  if (requiredRole && user.role !== requiredRole && user.role !== 'admin') {
+    return null;
+  }
+
+  return <>{children}</>;
+}
+```
+
+## Components
+
+### Login Form (`src/components/auth/LoginForm.tsx`)
+
+```typescript
+'use client';
+
+import { useState } from 'react';
+import { useAuth } from '@/hooks/useAuth';
+import { useRouter } from 'next/navigation';
+import Link from 'next/link';
+
+export function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const { login, loading, error, clearError } = useAuth();
+  const router = useRouter();
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    clearError();
+
+    try {
+      await login({ email, password });
+      router.push('/dashboard');
+    } catch (error) {
+      // Error is handled by the useAuth hook
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-8 p-6 bg-white rounded-lg shadow-md">
+      <h2 className="text-2xl font-bold mb-6 text-center">Login to SanadCheck</h2>
+      
+      {error && (
+        <div className="mb-4 p-3 bg-red-100 border border-red-400 text-red-700 rounded">
+          {error}
+        </div>
+      )}
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium text-gray-700">
+            Email
+          </label>
+          <input
+            type="email"
+            id="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            required
+            className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-gray-700">
+            Password
+          </label>
+          <input
+            type="password"
+            id="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            required
+            minLength={6}
+            className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500"
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Signing in...' : 'Sign in'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center text-sm text-gray-600">
+        Don't have an account?{' '}
+        <Link href="/auth/register" className="font-medium text-indigo-600 hover:text-indigo-500">
+          Sign up
+        </Link>
+      </p>
+    </div>
+  );
+}
+```
+
+### Hadith Analysis Component (`src/components/analysis/HadithAnalyzer.tsx`)
+
+```typescript
+'use client';
+
+import { useState } from 'react';
+import { apiClient } from '@/lib/api';
+import { HadithTextRequest, NarratorExtractionResponse } from '@/lib/types';
+
+export function HadithAnalyzer() {
+  const [text, setText] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<NarratorExtractionResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleAnalyze = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!text.trim()) return;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const response = await apiClient.extractNarrators({ text });
+      setResult(response.data);
+    } catch (err: any) {
+      setError(err.response?.data?.detail || 'Analysis failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-4xl mx-auto p-6">
+      <h2 className="text-2xl font-bold mb-6">Hadith Narrator Analysis</h2>
+
+      <form onSubmit={handleAnalyze} className="mb-8">
+        <div>
+          <label htmlFor="hadith-text" className="block text-sm font-medium text-gray-700 mb-2">
+            Enter Hadith Text (Arabic)
+          </label>
+          <textarea
+            id="hadith-text"
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            rows={6}
+            className="w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500"
+            placeholder="أخبرنا..."
+            required
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading || !text.trim()}
+          className="mt-4 px-6 py-2 bg-indigo-600 text-white rounded-md hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Analyzing...' : 'Analyze Narrators'}
+        </button>
+      </form>
+
+      {error && (
+        <div className="mb-4 p-4 bg-red-100 border border-red-400 text-red-700 rounded">
+          Error: {error}
+        </div>
+      )}
+
+      {result && (
+        <div className="bg-white rounded-lg shadow-md p-6">
+          <h3 className="text-lg font-semibold mb-4">Analysis Results</h3>
+          
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+            <div>
+              <h4 className="font-medium text-gray-900 mb-2">Extracted Narrators</h4>
+              <ul className="space-y-1">
+                {result.narrators.map((narrator, index) => (
+                  <li key={index} className="text-gray-700 bg-gray-50 px-3 py-1 rounded">
+                    {narrator}
+                  </li>
+                ))}
+              </ul>
+            </div>
+
+            <div>
+              <h4 className="font-medium text-gray-900 mb-2">Sanad Chain</h4>
+              <p className="text-gray-700 bg-gray-50 p-3 rounded">
+                {result.sanad_chain}
+              </p>
+            </div>
+          </div>
+
+          <div className="mt-4 text-sm text-gray-500">
+            Processing time: {result.metadata.processing_time_ms}ms
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Usage Examples
+
+### App Layout with Authentication (`src/app/layout.tsx`)
+
+```typescript
+import { AuthProvider } from '@/hooks/useAuth';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'SanadCheck - Hadith Narrator Analysis',
+  description: 'AI-powered hadith narrator analysis and validation',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <AuthProvider>
+          {children}
+        </AuthProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Dashboard Page (`src/app/dashboard/page.tsx`)
+
+```typescript
+'use client';
+
+import { ProtectedRoute } from '@/components/ui/ProtectedRoute';
+import { HadithAnalyzer } from '@/components/analysis/HadithAnalyzer';
+import { useAuth } from '@/hooks/useAuth';
+
+export default function Dashboard() {
+  const { user, logout } = useAuth();
+
+  return (
+    <ProtectedRoute>
+      <div className="min-h-screen bg-gray-50">
+        <nav className="bg-white shadow-sm border-b">
+          <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+            <div className="flex justify-between h-16">
+              <div className="flex items-center">
+                <h1 className="text-xl font-semibold">SanadCheck Dashboard</h1>
+              </div>
+              <div className="flex items-center space-x-4">
+                <span className="text-gray-700">Welcome, {user?.username || user?.email}</span>
+                <button
+                  onClick={logout}
+                  className="text-gray-500 hover:text-gray-700"
+                >
+                  Logout
+                </button>
+              </div>
+            </div>
+          </div>
+        </nav>
+
+        <main className="py-8">
+          <HadithAnalyzer />
+        </main>
+      </div>
+    </ProtectedRoute>
+  );
+}
+```
+
+## Error Handling
+
+### Global Error Handler (`src/lib/errorHandler.ts`)
+
+```typescript
+import { AxiosError } from 'axios';
+
+export interface ApiErrorResponse {
+  detail: string;
+  status_code?: number;
+}
+
+export class AppError extends Error {
+  public statusCode: number;
+  public isOperational: boolean;
+
+  constructor(message: string, statusCode = 500, isOperational = true) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export function handleApiError(error: AxiosError<ApiErrorResponse>): AppError {
+  const message = error.response?.data?.detail || error.message || 'An unexpected error occurred';
+  const statusCode = error.response?.status || 500;
+
+  switch (statusCode) {
+    case 401:
+      return new AppError('Authentication required', 401);
+    case 403:
+      return new AppError('Access denied', 403);
+    case 404:
+      return new AppError('Resource not found', 404);
+    case 429:
+      return new AppError('Rate limit exceeded. Please try again later.', 429);
+    case 500:
+      return new AppError('Server error. Please try again later.', 500);
+    default:
+      return new AppError(message, statusCode);
+  }
+}
+```
+
+## Best Practices
+
+### 1. Security
+- Store tokens in secure, httpOnly cookies when possible
+- Use HTTPS in production
+- Implement proper CORS policies
+- Validate all inputs on both client and server
+- Use environment variables for sensitive data
+
+### 2. Performance
+- Implement proper loading states
+- Use React.memo for expensive components
+- Debounce API calls for search functionality
+- Cache user data appropriately
+
+### 3. Error Handling
+- Provide meaningful error messages
+- Implement retry logic for network failures
+- Handle rate limiting gracefully
+- Log errors for debugging
+
+### 4. User Experience
+- Show loading indicators
+- Implement optimistic updates where appropriate
+- Provide clear feedback for all actions
+- Handle offline scenarios
+
+### 5. Code Organization
+- Separate API logic from UI components
+- Use TypeScript for type safety
+- Follow consistent naming conventions
+- Implement proper error boundaries
+
+### 6. Testing
+```typescript
+// Example test for authentication hook
+import { renderHook, act } from '@testing-library/react';
+import { useAuth } from '@/hooks/useAuth';
+
+test('should login user successfully', async () => {
+  const { result } = renderHook(() => useAuth());
+
+  await act(async () => {
+    await result.current.login({
+      email: 'test@example.com',
+      password: 'password123'
+    });
+  });
+
+  expect(result.current.user).toBeTruthy();
+  expect(result.current.error).toBeNull();
+});
+```
+
+This comprehensive guide provides everything needed to integrate the SanadCheck API authentication system into a Next.js application. The implementation includes proper error handling, security practices, and a scalable architecture for hadith analysis features.

app/api/routes.py

@@ -1,6 +1,8 @@
-from fastapi import APIRouter, HTTPException, status
+from fastapi import APIRouter, HTTPException, status, Depends, Request
 from fastapi.responses import JSONResponse
 from typing import List, Dict, Any
+from datetime import datetime
+import time
 
 from app.db.models import (
     HadithTextRequest,
@@ -14,8 +16,14 @@ from app.db.models import (
     ExtractionResult,
     ChainAnalysisResult,
     ExtractAndAnalyzeMetadata,
+    User,
+    NarratorExtractionRecord,
+    NarratorAnalysisRecord,
 )
 from app.agent.services import get_llm_service
+from app.middleware import get_current_active_user, get_user_ip
+from app.middleware.rate_limit import limiter, authenticated_user_limit
+from app.services.database import DatabaseService
 
 router = APIRouter(prefix="/api/v1", tags=["hadith-analysis"])
 
@@ -26,7 +34,12 @@ router = APIRouter(prefix="/api/v1", tags=["hadith-analysis"])
     summary="Extract narrators from hadith text",
     description="Analyzes Arabic hadith text and extracts the chain of narrators (sanad)",
 )
-async def extract_narrators(request: HadithTextRequest) -> NarratorExtractionResponse:
+@authenticated_user_limit()
+async def extract_narrators(
+    request: HadithTextRequest, 
+    http_request: Request,
+    current_user: User = Depends(get_current_active_user)
+) -> NarratorExtractionResponse:
     """
     Extract narrators from hadith text.
 
@@ -36,6 +49,7 @@ async def extract_narrators(request: HadithTextRequest) -> NarratorExtractionRes
 
     Args:
         request: Contains the hadith text to analyze
+        current_user: Current authenticated user
 
     Returns:
         NarratorExtractionResponse with extracted narrator names and chain
@@ -43,9 +57,28 @@ async def extract_narrators(request: HadithTextRequest) -> NarratorExtractionRes
     Raises:
         HTTPException: If the analysis fails
     """
+    start_time = time.time()
+    db_service = DatabaseService()
+    
     try:
         llm_service = get_llm_service()
         result = await llm_service.extract_narrators(request.hadith_text)
+        
+        processing_time = int((time.time() - start_time) * 1000)  # Convert to milliseconds
+
+        # Store extraction record in database
+        extraction_record = NarratorExtractionRecord(
+            user_id=current_user.id or "",
+            hadith_text=request.hadith_text,
+            extracted_narrators=result.narrators if result.success else [],
+            sanad_chain=result.sanad_chain if result.success else "",
+            success=result.success,
+            error_message=result.message if not result.success else None,
+            processing_time_ms=processing_time,
+            ip_address=get_user_ip(http_request)
+        )
+        
+        await db_service.store_extraction_record(extraction_record)
 
         if not result.success:
             raise HTTPException(
@@ -58,6 +91,24 @@ async def extract_narrators(request: HadithTextRequest) -> NarratorExtractionRes
     except HTTPException:
         raise
     except Exception as e:
+        # Store failed extraction record
+        processing_time = int((time.time() - start_time) * 1000)
+        extraction_record = NarratorExtractionRecord(
+            user_id=current_user.id or "",
+            hadith_text=request.hadith_text,
+            extracted_narrators=[],
+            sanad_chain="",
+            success=False,
+            error_message=str(e),
+            processing_time_ms=processing_time,
+            ip_address=get_user_ip(http_request)
+        )
+        
+        try:
+            await db_service.store_extraction_record(extraction_record)
+        except:
+            pass  # Don't fail if database storage fails
+        
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Internal server error during narrator extraction: {str(e)}",
@@ -70,8 +121,10 @@ async def extract_narrators(request: HadithTextRequest) -> NarratorExtractionRes
     summary="Analyze narrator reliability",
     description="Takes a narrator name and generates an AI-powered reliability assessment based on the model's knowledge",
 )
+@authenticated_user_limit()
 async def analyze_narrator(
     request: NarratorAnalysisRequest,
+    current_user: User = Depends(get_current_active_user)
 ) -> NarratorAnalysisResponse:
     """
     Analyze narrator reliability based on the model's internal knowledge.
@@ -82,6 +135,7 @@ async def analyze_narrator(
 
     Args:
         request: Contains the narrator name to analyze
+        current_user: Current authenticated user
 
     Returns:
         NarratorAnalysisResponse with reliability grade, biographical info, and detailed analysis
@@ -89,9 +143,32 @@ async def analyze_narrator(
     Raises:
         HTTPException: If the analysis fails
     """
+    start_time = time.time()
+    db_service = DatabaseService()
+    
     try:
         llm_service = get_llm_service()
         result = await llm_service.analyze_narrator(request.narrator_name)
+        
+        processing_time = int((time.time() - start_time) * 1000)
+
+        # Store analysis record in database
+        analysis_record = NarratorAnalysisRecord(
+            user_id=current_user.id or "",
+            narrator_name=request.narrator_name,
+            reliability_grade=result.reliability_grade if result.success else "",
+            confidence_level=result.confidence_level if result.success else "",
+            reasoning=result.reasoning if result.success else "",
+            scholarly_consensus=result.scholarly_consensus if result.success else "",
+            known_issues=result.known_issues if result.success else None,
+            biographical_info=result.biographical_info if result.success else "",
+            recommendation=result.recommendation if result.success else "",
+            success=result.success,
+            error_message=result.message if not result.success else None,
+            processing_time_ms=processing_time
+        )
+        
+        await db_service.store_analysis_record(analysis_record)
 
         if not result.success:
             raise HTTPException(
@@ -116,8 +193,10 @@ async def analyze_narrator(
     summary="Analyze narrator chain",
     description="Analyzes a complete chain of narrators using enhanced Shamela data + LLM agent",
 )
+@authenticated_user_limit()
 async def analyze_narrator_chain(
     narrator_names: List[str],
+    current_user: User = Depends(get_current_active_user)
 ) -> NarratorChainAnalysisResponse:
     """
     Analyze a complete chain of narrators with enhanced data sources.
@@ -190,8 +269,10 @@ async def analyze_narrator_chain(
     summary="Extract narrators and analyze chain",
     description="Complete workflow: extract narrators from hadith text and analyze the complete chain",
 )
+@authenticated_user_limit()
 async def extract_and_analyze_hadith(
     request: HadithTextRequest,
+    current_user: User = Depends(get_current_active_user)
 ) -> ExtractAndAnalyzeResponse:
     """
     Complete hadith analysis workflow: extraction + chain analysis.
@@ -294,6 +375,65 @@ async def health_check():
             "Enhanced narrator analysis with Shamela.ws integration",
             "Narrator chain analysis",
             "Complete hadith workflow analysis",
-            "AI-powered narrator extraction",
+            "JWT Authentication",
+            "Rate limiting",
+            "Database storage"
         ],
     }
+
+
+# Analytics and User Data Routes
+@router.get(
+    "/user/extractions",
+    summary="Get user's extraction history",
+    description="Get the current user's narrator extraction history"
+)
+@authenticated_user_limit()
+async def get_user_extractions(
+    current_user: User = Depends(get_current_active_user),
+    limit: int = 50
+):
+    """Get user's extraction history."""
+    db_service = DatabaseService()
+    extractions = await db_service.get_user_extractions(current_user.id or "", limit)
+    return {"extractions": extractions}
+
+
+@router.get(
+    "/user/analyses",
+    summary="Get user's analysis history",
+    description="Get the current user's narrator analysis history"
+)
+@authenticated_user_limit()
+async def get_user_analyses(
+    current_user: User = Depends(get_current_active_user),
+    limit: int = 50
+):
+    """Get user's analysis history."""
+    db_service = DatabaseService()
+    analyses = await db_service.get_user_analyses(current_user.id or "", limit)
+    return {"analyses": analyses}
+
+
+@router.get(
+    "/analytics/stats",
+    summary="Get extraction statistics",
+    description="Get overall platform statistics (public)"
+)
+async def get_platform_stats():
+    """Get platform-wide extraction statistics."""
+    db_service = DatabaseService()
+    stats = await db_service.get_extraction_stats()
+    return {"stats": stats}
+
+
+@router.get(
+    "/analytics/popular-narrators",
+    summary="Get popular narrators",
+    description="Get most frequently analyzed narrators (public)"
+)
+async def get_popular_narrators(limit: int = 10):
+    """Get most analyzed narrators."""
+    db_service = DatabaseService()
+    narrators = await db_service.get_popular_narrators(limit)
+    return {"popular_narrators": narrators}

app/auth/__init__.py

@@ -0,0 +1 @@
+# Authentication module

app/auth/routes.py

@@ -0,0 +1,332 @@
+from fastapi import APIRouter, HTTPException, status, Depends, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from supabase import create_client, Client
+from datetime import datetime, timedelta
+from typing import Optional
+import bcrypt
+import logging
+
+from app.config.settings import settings
+from app.db.models import (
+    LoginRequest, 
+    RegisterRequest, 
+    AuthResponse, 
+    TokenRefreshRequest,
+    User, 
+    UserSession,
+    UserRole
+)
+from app.middleware import auth_middleware, get_user_ip
+from app.middleware.rate_limit import limiter, anonymous_user_limit
+
+
+router = APIRouter(prefix="/auth", tags=["authentication"])
+security = HTTPBearer()
+logger = logging.getLogger(__name__)
+
+
+# Initialize Supabase client
+def get_supabase_client() -> Client:
+    """Get Supabase client instance."""
+    if not settings.SUPABASE_URL or not settings.SUPABASE_SERVICE_KEY:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Supabase configuration is missing"
+        )
+    return create_client(settings.SUPABASE_URL, settings.SUPABASE_SERVICE_KEY)
+
+
+def hash_password(password: str) -> str:
+    """Hash password using bcrypt."""
+    salt = bcrypt.gensalt()
+    return bcrypt.hashpw(password.encode('utf-8'), salt).decode('utf-8')
+
+
+def verify_password(password: str, hashed_password: str) -> bool:
+    """Verify password against hash."""
+    return bcrypt.checkpw(password.encode('utf-8'), hashed_password.encode('utf-8'))
+
+
+async def create_user_session(
+    user_id: str, 
+    access_token: str, 
+    refresh_token: str,
+    request: Request
+) -> UserSession:
+    """Create user session record."""
+    supabase = get_supabase_client()
+    
+    session_data = {
+        "user_id": user_id,
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "expires_at": (datetime.utcnow() + timedelta(minutes=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES)).isoformat(),
+        "created_at": datetime.utcnow().isoformat(),
+        "last_used": datetime.utcnow().isoformat(),
+        "user_agent": request.headers.get("user-agent", ""),
+        "ip_address": get_user_ip(request)
+    }
+    
+    try:
+        response = supabase.table("user_sessions").insert(session_data).execute()
+        if response.data:
+            return UserSession(**response.data[0])
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create session"
+        )
+    except Exception as e:
+        logger.error(f"Error creating user session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create session"
+        )
+
+
+@router.post("/register", response_model=AuthResponse)
+@anonymous_user_limit()
+async def register(request: Request, user_data: RegisterRequest):
+    """Register a new user."""
+    supabase = get_supabase_client()
+    
+    try:
+        # Check if user already exists
+        existing_user = supabase.table("users").select("id").eq("email", user_data.email).execute()
+        if existing_user.data:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="User with this email already exists"
+            )
+        
+        # Create user using Supabase Auth
+        auth_response = supabase.auth.sign_up({
+            "email": user_data.email,
+            "password": user_data.password,
+            "options": {
+                "data": {
+                    "username": user_data.username,
+                    "full_name": user_data.full_name
+                }
+            }
+        })
+        
+        if not auth_response.user:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Failed to create user"
+            )
+        
+        # Create user record in our custom table
+        user_record = {
+            "id": auth_response.user.id,
+            "email": user_data.email,
+            "username": user_data.username,
+            "full_name": user_data.full_name,
+            "role": UserRole.USER.value,
+            "is_active": True,
+            "created_at": datetime.utcnow().isoformat()
+        }
+        
+        db_response = supabase.table("users").insert(user_record).execute()
+        if not db_response.data:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to create user record"
+            )
+        
+        user = User(**db_response.data[0])
+        
+        # Create JWT tokens
+        access_token = auth_middleware.create_access_token(data={"sub": user.id})
+        refresh_token = auth_middleware.create_refresh_token(data={"sub": user.id})
+        
+        # Create session
+        await create_user_session(user.id, access_token, refresh_token, request)
+        
+        return AuthResponse(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_type="bearer",
+            expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+            user=user
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Registration error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Registration failed"
+        )
+
+
+@router.post("/login", response_model=AuthResponse)
+@anonymous_user_limit()
+async def login(request: Request, credentials: LoginRequest):
+    """Authenticate user and return tokens."""
+    supabase = get_supabase_client()
+    
+    try:
+        # Authenticate with Supabase
+        auth_response = supabase.auth.sign_in_with_password({
+            "email": credentials.email,
+            "password": credentials.password
+        })
+        
+        if not auth_response.user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid email or password"
+            )
+        
+        # Get user from our custom table
+        user_response = supabase.table("users").select("*").eq("id", auth_response.user.id).execute()
+        if not user_response.data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User record not found"
+            )
+        
+        user = User(**user_response.data[0])
+        
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Account is disabled"
+            )
+        
+        # Update last login
+        supabase.table("users").update({
+            "last_login": datetime.utcnow().isoformat()
+        }).eq("id", user.id).execute()
+        
+        # Create JWT tokens
+        access_token = auth_middleware.create_access_token(data={"sub": user.id})
+        refresh_token = auth_middleware.create_refresh_token(data={"sub": user.id})
+        
+        # Create session
+        await create_user_session(user.id, access_token, refresh_token, request)
+        
+        return AuthResponse(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_type="bearer",
+            expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+            user=user
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Login error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication failed"
+        )
+
+
+@router.post("/refresh", response_model=AuthResponse)
+@anonymous_user_limit()
+async def refresh_token(request: Request, token_data: TokenRefreshRequest):
+    """Refresh access token using refresh token."""
+    try:
+        # Verify refresh token
+        payload = auth_middleware.verify_token(token_data.refresh_token)
+        
+        if payload.get("type") != "refresh":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token type"
+            )
+        
+        user_id = payload.get("sub")
+        if not user_id:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token"
+            )
+        
+        # Get user
+        user = await auth_middleware.get_user_from_supabase(user_id)
+        if not user or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found or inactive"
+            )
+        
+        # Create new tokens
+        new_access_token = auth_middleware.create_access_token(data={"sub": user.id})
+        new_refresh_token = auth_middleware.create_refresh_token(data={"sub": user.id})
+        
+        # Blacklist old refresh token
+        expires_at = datetime.fromtimestamp(payload.get("exp", 0))
+        auth_middleware.blacklist_token(token_data.refresh_token, expires_at)
+        
+        # Create new session
+        await create_user_session(user.id, new_access_token, new_refresh_token, request)
+        
+        return AuthResponse(
+            access_token=new_access_token,
+            refresh_token=new_refresh_token,
+            token_type="bearer",
+            expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+            user=user
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Token refresh error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token refresh failed"
+        )
+
+
+@router.post("/logout")
+async def logout(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    """Logout user and blacklist token."""
+    try:
+        token = credentials.credentials
+        payload = auth_middleware.verify_token(token)
+        
+        # Blacklist the token
+        expires_at = datetime.fromtimestamp(payload.get("exp", 0))
+        auth_middleware.blacklist_token(token, expires_at)
+        
+        # Update session as ended
+        user_id = payload.get("sub")
+        if user_id:
+            supabase = get_supabase_client()
+            supabase.table("user_sessions").update({
+                "ended_at": datetime.utcnow().isoformat()
+            }).eq("user_id", user_id).eq("access_token", token).execute()
+        
+        return {"message": "Successfully logged out"}
+        
+    except Exception as e:
+        logger.error(f"Logout error: {e}")
+        return {"message": "Logout completed"}
+
+
+@router.get("/me", response_model=User)
+async def get_current_user_info(current_user: User = Depends(auth_middleware.get_current_user)):
+    """Get current user information."""
+    return current_user
+
+
+@router.get("/sessions")
+async def get_user_sessions(current_user: User = Depends(auth_middleware.get_current_user)):
+    """Get user's active sessions."""
+    supabase = get_supabase_client()
+    
+    try:
+        response = supabase.table("user_sessions").select("*").eq("user_id", current_user.id).is_("ended_at", "null").execute()
+        return {"sessions": response.data}
+    except Exception as e:
+        logger.error(f"Error fetching sessions: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch sessions"
+        )

app/config/settings.py

@@ -1,5 +1,5 @@
 import os
-from typing import Optional
+from typing import Optional, List
 
 
 class Settings:
@@ -13,19 +13,43 @@ class Settings:
     # Environment
     ENVIRONMENT: str = os.getenv("ENVIRONMENT", "development")
     DEBUG: bool = os.getenv("DEBUG", "True").lower() == "true"
+    HOST: str = os.getenv("HOST", "0.0.0.0")
+    PORT: int = int(os.getenv("PORT", "8000"))
 
     # Google AI
     GOOGLE_API_KEY: Optional[str] = os.getenv("GOOGLE_API_KEY")
+    GROQ_API_KEY: Optional[str] = os.getenv("GROQ_API_KEY")
+
+    # JWT Configuration
+    JWT_SECRET_KEY: str = os.getenv("JWT_SECRET_KEY", "your-super-secret-jwt-key-change-this-in-production")
+    JWT_ALGORITHM: str = os.getenv("JWT_ALGORITHM", "HS256")
+    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = int(os.getenv("JWT_ACCESS_TOKEN_EXPIRE_MINUTES", "30"))
+    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = int(os.getenv("JWT_REFRESH_TOKEN_EXPIRE_DAYS", "7"))
+
+    # Supabase Configuration
+    SUPABASE_URL: Optional[str] = os.getenv("SUPABASE_URL")
+    SUPABASE_SERVICE_KEY: Optional[str] = os.getenv("SUPABASE_SERVICE_KEY")
+    SUPABASE_ANON_KEY: Optional[str] = os.getenv("SUPABASE_ANON_KEY")
+
+    # Redis Configuration
+    REDIS_URL: str = os.getenv("REDIS_URL", "redis://localhost:6379")
+    REDIS_HOST: str = os.getenv("REDIS_HOST", "localhost")
+    REDIS_PORT: int = int(os.getenv("REDIS_PORT", "6379"))
+    REDIS_DB: int = int(os.getenv("REDIS_DB", "0"))
+    REDIS_PASSWORD: str = os.getenv("REDIS_PASSWORD", "")
 
     # Rate Limiting
-    RATE_LIMIT_REQUESTS: int = int(os.getenv("RATE_LIMIT_REQUESTS", "100"))
-    RATE_LIMIT_WINDOW: int = int(os.getenv("RATE_LIMIT_WINDOW", "3600"))  # 1 hour
+    RATE_LIMIT_REQUESTS_PER_MINUTE: int = int(os.getenv("RATE_LIMIT_REQUESTS_PER_MINUTE", "60"))
+    RATE_LIMIT_BURST: int = int(os.getenv("RATE_LIMIT_BURST", "10"))
+
+    # Database
+    DATABASE_URL: Optional[str] = os.getenv("DATABASE_URL")
 
     # CORS
-    ALLOWED_ORIGINS: list = os.getenv("ALLOWED_ORIGINS", "*").split(",")
+    ALLOWED_ORIGINS: List[str] = os.getenv("ALLOWED_ORIGINS", "http://localhost:3000,http://localhost:8000,http://localhost:5173").split(",")
 
-    class Config:
-        env_file = ".env"
+    # Logging
+    LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
 
 
 settings = Settings()

app/db/models.py

@@ -1,7 +1,106 @@
 from typing import List, Optional, Dict, Any
 from pydantic import BaseModel, Field
-
-
+from datetime import datetime
+from enum import Enum
+
+
+# Authentication Models
+class UserRole(str, Enum):
+    """User roles enum."""
+    USER = "user"
+    ADMIN = "admin"
+    RESEARCHER = "researcher"
+
+
+class User(BaseModel):
+    """User model for authentication."""
+    id: Optional[str] = Field(default=None, description="User ID from Supabase")
+    email: str = Field(description="User email address")
+    username: Optional[str] = Field(default=None, description="Username")
+    full_name: Optional[str] = Field(default=None, description="Full name")
+    role: UserRole = Field(default=UserRole.USER, description="User role")
+    is_active: bool = Field(default=True, description="Whether user is active")
+    created_at: Optional[datetime] = Field(default=None, description="Account creation timestamp")
+    last_login: Optional[datetime] = Field(default=None, description="Last login timestamp")
+
+
+class UserSession(BaseModel):
+    """User session model."""
+    id: Optional[str] = Field(default=None, description="Session ID")
+    user_id: str = Field(description="User ID")
+    access_token: str = Field(description="JWT access token")
+    refresh_token: Optional[str] = Field(default=None, description="JWT refresh token")
+    expires_at: datetime = Field(description="Token expiration time")
+    created_at: Optional[datetime] = Field(default=None, description="Session creation time")
+    last_used: Optional[datetime] = Field(default=None, description="Last used timestamp")
+    user_agent: Optional[str] = Field(default=None, description="User agent string")
+    ip_address: Optional[str] = Field(default=None, description="Client IP address")
+
+
+class LoginRequest(BaseModel):
+    """Login request model."""
+    email: str = Field(description="User email")
+    password: str = Field(description="User password", min_length=6)
+
+
+class RegisterRequest(BaseModel):
+    """Registration request model."""
+    email: str = Field(description="User email")
+    password: str = Field(description="User password", min_length=6)
+    username: Optional[str] = Field(default=None, description="Username")
+    full_name: Optional[str] = Field(default=None, description="Full name")
+
+
+class AuthResponse(BaseModel):
+    """Authentication response model."""
+    access_token: str = Field(description="JWT access token")
+    refresh_token: Optional[str] = Field(default=None, description="JWT refresh token")
+    token_type: str = Field(default="bearer", description="Token type")
+    expires_in: int = Field(description="Token expiration time in seconds")
+    user: User = Field(description="User information")
+
+
+class TokenRefreshRequest(BaseModel):
+    """Token refresh request model."""
+    refresh_token: str = Field(description="Refresh token")
+
+
+# Database Storage Models
+class NarratorExtractionRecord(BaseModel):
+    """Database record for narrator extraction."""
+    id: Optional[str] = Field(default=None, description="Record ID")
+    user_id: str = Field(description="User who made the request")
+    hadith_text: str = Field(description="Original hadith text")
+    extracted_narrators: List[str] = Field(description="Extracted narrator names")
+    sanad_chain: str = Field(description="Extracted sanad chain")
+    success: bool = Field(description="Whether extraction was successful")
+    error_message: Optional[str] = Field(default=None, description="Error message if failed")
+    processing_time_ms: Optional[int] = Field(default=None, description="Processing time in milliseconds")
+    created_at: Optional[datetime] = Field(default=None, description="Creation timestamp")
+    session_id: Optional[str] = Field(default=None, description="Session ID")
+    ip_address: Optional[str] = Field(default=None, description="Client IP address")
+
+
+class NarratorAnalysisRecord(BaseModel):
+    """Database record for narrator analysis."""
+    id: Optional[str] = Field(default=None, description="Record ID")
+    user_id: str = Field(description="User who made the request")
+    extraction_id: Optional[str] = Field(default=None, description="Related extraction record ID")
+    narrator_name: str = Field(description="Analyzed narrator name")
+    reliability_grade: str = Field(description="Assigned reliability grade")
+    confidence_level: str = Field(description="Confidence level")
+    reasoning: str = Field(description="Analysis reasoning")
+    scholarly_consensus: str = Field(description="Scholarly consensus analysis")
+    known_issues: Optional[str] = Field(default=None, description="Known issues")
+    biographical_info: str = Field(description="Biographical information")
+    recommendation: str = Field(description="Usage recommendation")
+    success: bool = Field(description="Whether analysis was successful")
+    error_message: Optional[str] = Field(default=None, description="Error message if failed")
+    processing_time_ms: Optional[int] = Field(default=None, description="Processing time in milliseconds")
+    created_at: Optional[datetime] = Field(default=None, description="Creation timestamp")
+
+
+# Existing Models (keeping them for compatibility)
 class NarratorGrade(BaseModel):
     """Grade for individual narrator in the chain."""
     

app/main.py

@@ -1,4 +1,4 @@
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 import uvicorn
@@ -6,6 +6,15 @@ import os
 
 from app.config.settings import settings
 from app.api.routes import router
+from app.auth.routes import router as auth_router
+
+try:
+    from slowapi import Limiter, _rate_limit_exceeded_handler
+    from slowapi.errors import RateLimitExceeded
+    from app.middleware.rate_limit import limiter
+    RATE_LIMITING_AVAILABLE = True
+except ImportError:
+    RATE_LIMITING_AVAILABLE = False
 
 
 # Create FastAPI application
@@ -17,6 +26,23 @@ app = FastAPI(
     redoc_url="/redoc" if settings.DEBUG else None,
 )
 
+# Add rate limiting if available
+if RATE_LIMITING_AVAILABLE:
+    app.state.limiter = limiter
+    
+    @app.exception_handler(RateLimitExceeded)
+    async def rate_limit_handler(request: Request, exc: RateLimitExceeded):
+        response = JSONResponse(
+            status_code=429,
+            content={
+                "error": "Rate limit exceeded",
+                "message": f"Too many requests. Limit: {exc.detail}",
+                "retry_after": exc.retry_after
+            }
+        )
+        response.headers["Retry-After"] = str(exc.retry_after)
+        return response
+
 # Add CORS middleware
 app.add_middleware(
     CORSMiddleware,
@@ -27,6 +53,7 @@ app.add_middleware(
 )
 
 # Include API routes
+app.include_router(auth_router)
 app.include_router(router)
 
 

app/middleware/__init__.py

@@ -0,0 +1,171 @@
+from fastapi import HTTPException, status, Depends, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from jose import JWTError, jwt
+from datetime import datetime, timedelta
+from typing import Optional
+import redis
+from supabase import create_client, Client
+
+from app.config.settings import settings
+from app.db.models import User, UserSession
+
+
+class AuthMiddleware:
+    """JWT Authentication middleware with Supabase integration."""
+    
+    def __init__(self):
+        self.security = HTTPBearer()
+        self.supabase: Client = create_client(
+            settings.SUPABASE_URL, 
+            settings.SUPABASE_SERVICE_KEY
+        ) if settings.SUPABASE_URL and settings.SUPABASE_SERVICE_KEY else None
+        
+        # Redis client for token blacklisting
+        try:
+            self.redis_client = redis.Redis(
+                host=settings.REDIS_HOST,
+                port=settings.REDIS_PORT,
+                db=settings.REDIS_DB,
+                password=settings.REDIS_PASSWORD if settings.REDIS_PASSWORD else None,
+                decode_responses=True
+            )
+        except Exception:
+            self.redis_client = None
+
+    def create_access_token(self, data: dict, expires_delta: Optional[timedelta] = None) -> str:
+        """Create JWT access token."""
+        to_encode = data.copy()
+        if expires_delta:
+            expire = datetime.utcnow() + expires_delta
+        else:
+            expire = datetime.utcnow() + timedelta(minutes=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES)
+        
+        to_encode.update({"exp": expire, "type": "access"})
+        encoded_jwt = jwt.encode(to_encode, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+        return encoded_jwt
+
+    def create_refresh_token(self, data: dict, expires_delta: Optional[timedelta] = None) -> str:
+        """Create JWT refresh token."""
+        to_encode = data.copy()
+        if expires_delta:
+            expire = datetime.utcnow() + expires_delta
+        else:
+            expire = datetime.utcnow() + timedelta(days=settings.JWT_REFRESH_TOKEN_EXPIRE_DAYS)
+        
+        to_encode.update({"exp": expire, "type": "refresh"})
+        encoded_jwt = jwt.encode(to_encode, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+        return encoded_jwt
+
+    def verify_token(self, token: str) -> dict:
+        """Verify JWT token."""
+        try:
+            # Check if token is blacklisted
+            if self.redis_client and self.redis_client.get(f"blacklist:{token}"):
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Token has been revoked",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            
+            payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+            return payload
+        except JWTError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Could not validate credentials",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    def blacklist_token(self, token: str, expires_at: datetime):
+        """Add token to blacklist."""
+        if self.redis_client:
+            try:
+                # Calculate TTL until token expires
+                ttl = int((expires_at - datetime.utcnow()).total_seconds())
+                if ttl > 0:
+                    self.redis_client.setex(f"blacklist:{token}", ttl, "1")
+            except Exception:
+                pass  # If Redis is down, continue without blacklisting
+
+    async def get_user_from_supabase(self, user_id: str) -> Optional[User]:
+        """Get user from Supabase."""
+        if not self.supabase:
+            return None
+        
+        try:
+            response = self.supabase.table("users").select("*").eq("id", user_id).execute()
+            if response.data:
+                user_data = response.data[0]
+                return User(**user_data)
+            return None
+        except Exception:
+            return None
+
+    async def get_current_user(self, credentials: HTTPAuthorizationCredentials = Depends(HTTPBearer())) -> User:
+        """Get current authenticated user."""
+        token = credentials.credentials
+        payload = self.verify_token(token)
+        
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Could not validate credentials",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        # Get user from Supabase
+        user = await self.get_user_from_supabase(user_id)
+        if user is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Inactive user"
+            )
+        
+        return user
+
+    async def get_current_active_user(self, current_user: User = Depends(lambda: auth_middleware.get_current_user)) -> User:
+        """Get current active user."""
+        if not current_user.is_active:
+            raise HTTPException(status_code=400, detail="Inactive user")
+        return current_user
+
+    async def get_admin_user(self, current_user: User = Depends(lambda: auth_middleware.get_current_user)) -> User:
+        """Get current user if they have admin role."""
+        if current_user.role != "admin":
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not enough permissions"
+            )
+        return current_user
+
+
+# Create global instance
+auth_middleware = AuthMiddleware()
+
+# Dependency functions for FastAPI
+async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(HTTPBearer())) -> User:
+    """FastAPI dependency to get current user."""
+    return await auth_middleware.get_current_user(credentials)
+
+async def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
+    """FastAPI dependency to get current active user."""
+    return await auth_middleware.get_current_active_user(current_user)
+
+async def get_admin_user(current_user: User = Depends(get_current_user)) -> User:
+    """FastAPI dependency to get admin user."""
+    return await auth_middleware.get_admin_user(current_user)
+
+def get_user_ip(request: Request) -> str:
+    """Extract user IP address from request."""
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"

app/middleware/rate_limit.py

@@ -0,0 +1,152 @@
+from fastapi import Request, HTTPException, status
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+import redis
+from typing import Optional
+
+from app.config.settings import settings
+
+
+def get_client_ip(request: Request) -> str:
+    """Get client IP address for rate limiting."""
+    # Check for forwarded headers first
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    
+    real_ip = request.headers.get("X-Real-IP")
+    if real_ip:
+        return real_ip
+    
+    return get_remote_address(request)
+
+
+def get_user_id_from_token(request: Request) -> Optional[str]:
+    """Extract user ID from JWT token for user-based rate limiting."""
+    try:
+        from app.middleware import auth_middleware
+        auth_header = request.headers.get("Authorization")
+        if auth_header and auth_header.startswith("Bearer "):
+            token = auth_header.split(" ")[1]
+            payload = auth_middleware.verify_token(token)
+            return payload.get("sub")
+    except Exception:
+        pass
+    return None
+
+
+def rate_limit_key(request: Request) -> str:
+    """Generate rate limiting key based on user or IP."""
+    user_id = get_user_id_from_token(request)
+    if user_id:
+        return f"user:{user_id}"
+    return f"ip:{get_client_ip(request)}"
+
+
+# Create Redis client for rate limiting
+try:
+    redis_client = redis.Redis(
+        host=settings.REDIS_HOST,
+        port=settings.REDIS_PORT,
+        db=settings.REDIS_DB,
+        password=settings.REDIS_PASSWORD if settings.REDIS_PASSWORD else None,
+        decode_responses=True
+    )
+    # Test connection
+    redis_client.ping()
+except Exception:
+    # Fallback to in-memory storage if Redis is not available
+    redis_client = None
+
+
+# Create limiter instance
+limiter = Limiter(
+    key_func=rate_limit_key,
+    storage_uri=settings.REDIS_URL if redis_client else "memory://",
+    default_limits=[f"{settings.RATE_LIMIT_REQUESTS_PER_MINUTE}/minute"]
+)
+
+
+# Custom rate limit exceeded handler
+async def custom_rate_limit_handler(request: Request, exc: RateLimitExceeded):
+    """Custom handler for rate limit exceeded."""
+    response = HTTPException(
+        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        detail={
+            "error": "Rate limit exceeded",
+            "message": f"Too many requests. Limit: {exc.detail}",
+            "retry_after": exc.retry_after
+        }
+    )
+    return response
+
+
+# Rate limiting decorators for different tiers
+def authenticated_user_limit():
+    """Rate limit for authenticated users (higher limit)."""
+    return limiter.limit(f"{settings.RATE_LIMIT_REQUESTS_PER_MINUTE * 2}/minute")
+
+
+def anonymous_user_limit():
+    """Rate limit for anonymous users (lower limit)."""
+    return limiter.limit(f"{settings.RATE_LIMIT_REQUESTS_PER_MINUTE}/minute")
+
+
+def admin_user_limit():
+    """Rate limit for admin users (highest limit)."""
+    return limiter.limit(f"{settings.RATE_LIMIT_REQUESTS_PER_MINUTE * 5}/minute")
+
+
+def burst_limit():
+    """Burst protection limit."""
+    return limiter.limit(f"{settings.RATE_LIMIT_BURST}/second")
+
+
+# Middleware class for more granular control
+class RateLimitMiddleware:
+    """Rate limiting middleware with user-aware limits."""
+    
+    def __init__(self):
+        self.limiter = limiter
+        self.redis_client = redis_client
+    
+    async def check_rate_limit(self, request: Request, limit: str) -> bool:
+        """Check if request exceeds rate limit."""
+        try:
+            key = rate_limit_key(request)
+            
+            if self.redis_client:
+                # Use Redis for rate limiting
+                current_count = self.redis_client.incr(key)
+                if current_count == 1:
+                    # Set expiration for new key
+                    self.redis_client.expire(key, 60)  # 1 minute window
+                
+                # Parse limit (e.g., "60/minute")
+                limit_count = int(limit.split("/")[0])
+                if current_count > limit_count:
+                    return False
+            
+            return True
+        except Exception:
+            # If rate limiting fails, allow the request
+            return True
+    
+    def get_remaining_requests(self, request: Request, limit: str) -> int:
+        """Get remaining requests for the current window."""
+        try:
+            if not self.redis_client:
+                return 0
+            
+            key = rate_limit_key(request)
+            current_count = self.redis_client.get(key) or 0
+            limit_count = int(limit.split("/")[0])
+            
+            return max(0, limit_count - int(current_count))
+        except Exception:
+            return 0
+
+
+# Global instance
+rate_limit_middleware = RateLimitMiddleware()

app/services/__init__.py

@@ -0,0 +1 @@
+# Services module

app/services/database.py

@@ -0,0 +1,127 @@
+from supabase import create_client, Client
+from typing import Optional
+import logging
+
+from app.config.settings import settings
+from app.db.models import NarratorExtractionRecord, NarratorAnalysisRecord
+
+
+class DatabaseService:
+    """Service for database operations with Supabase."""
+    
+    def __init__(self):
+        self.logger = logging.getLogger(__name__)
+        self.supabase: Optional[Client] = None
+        
+        if settings.SUPABASE_URL and settings.SUPABASE_SERVICE_KEY:
+            try:
+                self.supabase = create_client(
+                    settings.SUPABASE_URL, 
+                    settings.SUPABASE_SERVICE_KEY
+                )
+            except Exception as e:
+                self.logger.error(f"Failed to initialize Supabase client: {e}")
+
+    async def store_extraction_record(self, record: NarratorExtractionRecord) -> Optional[str]:
+        """Store narrator extraction record in database."""
+        if not self.supabase:
+            self.logger.warning("Supabase client not available, skipping database storage")
+            return None
+        
+        try:
+            # Convert record to dict, excluding None id
+            record_dict = record.dict(exclude_none=True)
+            if "id" in record_dict and record_dict["id"] is None:
+                del record_dict["id"]
+            
+            # Convert datetime objects to ISO strings
+            if record.created_at:
+                record_dict["created_at"] = record.created_at.isoformat()
+            
+            response = self.supabase.table("narrator_extractions").insert(record_dict).execute()
+            
+            if response.data:
+                return response.data[0]["id"]
+            else:
+                self.logger.error("No data returned from extraction record insertion")
+                return None
+                
+        except Exception as e:
+            self.logger.error(f"Error storing extraction record: {e}")
+            return None
+
+    async def store_analysis_record(self, record: NarratorAnalysisRecord) -> Optional[str]:
+        """Store narrator analysis record in database."""
+        if not self.supabase:
+            self.logger.warning("Supabase client not available, skipping database storage")
+            return None
+        
+        try:
+            # Convert record to dict, excluding None id
+            record_dict = record.dict(exclude_none=True)
+            if "id" in record_dict and record_dict["id"] is None:
+                del record_dict["id"]
+            
+            # Convert datetime objects to ISO strings
+            if record.created_at:
+                record_dict["created_at"] = record.created_at.isoformat()
+            
+            response = self.supabase.table("narrator_analyses").insert(record_dict).execute()
+            
+            if response.data:
+                return response.data[0]["id"]
+            else:
+                self.logger.error("No data returned from analysis record insertion")
+                return None
+                
+        except Exception as e:
+            self.logger.error(f"Error storing analysis record: {e}")
+            return None
+
+    async def get_user_extractions(self, user_id: str, limit: int = 50) -> list:
+        """Get user's extraction history."""
+        if not self.supabase:
+            return []
+        
+        try:
+            response = self.supabase.table("narrator_extractions").select("*").eq("user_id", user_id).order("created_at", desc=True).limit(limit).execute()
+            return response.data or []
+        except Exception as e:
+            self.logger.error(f"Error fetching user extractions: {e}")
+            return []
+
+    async def get_user_analyses(self, user_id: str, limit: int = 50) -> list:
+        """Get user's analysis history."""
+        if not self.supabase:
+            return []
+        
+        try:
+            response = self.supabase.table("narrator_analyses").select("*").eq("user_id", user_id).order("created_at", desc=True).limit(limit).execute()
+            return response.data or []
+        except Exception as e:
+            self.logger.error(f"Error fetching user analyses: {e}")
+            return []
+
+    async def get_extraction_stats(self) -> dict:
+        """Get extraction statistics."""
+        if not self.supabase:
+            return {}
+        
+        try:
+            response = self.supabase.rpc("get_extraction_stats").execute()
+            return response.data[0] if response.data else {}
+        except Exception as e:
+            self.logger.error(f"Error fetching extraction stats: {e}")
+            return {}
+
+    async def get_popular_narrators(self, limit: int = 10) -> list:
+        """Get most analyzed narrators."""
+        if not self.supabase:
+            return []
+        
+        try:
+            response = self.supabase.rpc("get_popular_narrators", {"limit_count": limit}).execute()
+            return response.data or []
+        except Exception as e:
+            self.logger.error(f"Error fetching popular narrators: {e}")
+            return []

requirements.txt

@@ -25,7 +25,6 @@ grpcio-status==1.74.0
 h11==0.16.0
 httpcore==1.0.9
 httplib2==0.22.0
-httpx==0.28.1
 idna==3.10
 jsonpatch==1.33
 jsonpointer==3.0.0
@@ -64,3 +63,20 @@ urllib3==2.5.0
 uvicorn==0.35.0
 yarl==1.20.1
 zstandard==0.23.0
+
+# Authentication and JWT
+python-jose[cryptography]==3.3.0
+python-multipart==0.0.9
+passlib[bcrypt]==1.7.4
+
+# Supabase
+supabase==2.7.4
+postgrest==0.16.8
+
+# Redis and Rate Limiting
+redis==5.0.1
+slowapi==0.1.9
+
+# Additional dependencies for enhanced security
+cryptography==42.0.5
+bcrypt==4.1.2

sql/create_tables.sql

@@ -0,0 +1,207 @@
+-- Supabase Database Schema for SanadCheck LLM API
+-- Execute these scripts in your Supabase SQL Editor
+
+-- Enable necessary extensions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Create custom user roles enum
+CREATE TYPE user_role AS ENUM ('user', 'admin', 'researcher');
+
+-- Create users table (extends Supabase auth.users)
+CREATE TABLE IF NOT EXISTS public.users (
+    id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
+    email TEXT UNIQUE NOT NULL,
+    username TEXT UNIQUE,
+    full_name TEXT,
+    role user_role DEFAULT 'user'::user_role,
+    is_active BOOLEAN DEFAULT TRUE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    last_login TIMESTAMP WITH TIME ZONE,
+    
+    -- Constraints
+    CONSTRAINT valid_email CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'),
+    CONSTRAINT username_length CHECK (length(username) >= 3 AND length(username) <= 50),
+    CONSTRAINT full_name_length CHECK (length(full_name) <= 100)
+);
+
+-- Create user_sessions table for JWT session management
+CREATE TABLE IF NOT EXISTS public.user_sessions (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id UUID NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
+    access_token TEXT NOT NULL,
+    refresh_token TEXT,
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    last_used TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    ended_at TIMESTAMP WITH TIME ZONE,
+    user_agent TEXT,
+    ip_address INET,
+    
+    -- Indexes for performance
+    CONSTRAINT unique_access_token UNIQUE (access_token)
+);
+
+-- Create narrator_extractions table for storing extraction results
+CREATE TABLE IF NOT EXISTS public.narrator_extractions (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id UUID NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
+    session_id UUID REFERENCES public.user_sessions(id) ON DELETE SET NULL,
+    hadith_text TEXT NOT NULL,
+    extracted_narrators TEXT[] NOT NULL DEFAULT '{}',
+    sanad_chain TEXT NOT NULL,
+    success BOOLEAN NOT NULL DEFAULT FALSE,
+    error_message TEXT,
+    processing_time_ms INTEGER,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    ip_address INET,
+    
+    -- Constraints
+    CONSTRAINT hadith_text_not_empty CHECK (length(trim(hadith_text)) > 0),
+    CONSTRAINT processing_time_positive CHECK (processing_time_ms IS NULL OR processing_time_ms >= 0)
+);
+
+-- Create narrator_analyses table for storing individual narrator analysis results
+CREATE TABLE IF NOT EXISTS public.narrator_analyses (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id UUID NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
+    extraction_id UUID REFERENCES public.narrator_extractions(id) ON DELETE SET NULL,
+    narrator_name TEXT NOT NULL,
+    reliability_grade TEXT NOT NULL,
+    confidence_level TEXT NOT NULL,
+    reasoning TEXT NOT NULL,
+    scholarly_consensus TEXT NOT NULL,
+    known_issues TEXT,
+    biographical_info TEXT NOT NULL,
+    recommendation TEXT NOT NULL,
+    success BOOLEAN NOT NULL DEFAULT FALSE,
+    error_message TEXT,
+    processing_time_ms INTEGER,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Constraints
+    CONSTRAINT narrator_name_not_empty CHECK (length(trim(narrator_name)) > 0),
+    CONSTRAINT reliability_grade_valid CHECK (reliability_grade IN ('Thiqah', 'Saduq', 'Da''if', 'Matruk', 'Majhul')),
+    CONSTRAINT confidence_level_valid CHECK (confidence_level IN ('High', 'Medium', 'Low')),
+    CONSTRAINT processing_time_positive CHECK (processing_time_ms IS NULL OR processing_time_ms >= 0)
+);
+
+-- Create indexes for better performance
+CREATE INDEX IF NOT EXISTS idx_user_sessions_user_id ON public.user_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_sessions_access_token ON public.user_sessions(access_token);
+CREATE INDEX IF NOT EXISTS idx_user_sessions_expires_at ON public.user_sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_user_sessions_active ON public.user_sessions(user_id) WHERE ended_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_narrator_extractions_user_id ON public.narrator_extractions(user_id);
+CREATE INDEX IF NOT EXISTS idx_narrator_extractions_created_at ON public.narrator_extractions(created_at);
+CREATE INDEX IF NOT EXISTS idx_narrator_extractions_success ON public.narrator_extractions(success);
+
+CREATE INDEX IF NOT EXISTS idx_narrator_analyses_user_id ON public.narrator_analyses(user_id);
+CREATE INDEX IF NOT EXISTS idx_narrator_analyses_extraction_id ON public.narrator_analyses(extraction_id);
+CREATE INDEX IF NOT EXISTS idx_narrator_analyses_narrator_name ON public.narrator_analyses(narrator_name);
+CREATE INDEX IF NOT EXISTS idx_narrator_analyses_created_at ON public.narrator_analyses(created_at);
+
+-- Create updated_at trigger function
+CREATE OR REPLACE FUNCTION public.update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+-- Add updated_at trigger to users table
+CREATE TRIGGER update_users_updated_at 
+    BEFORE UPDATE ON public.users 
+    FOR EACH ROW 
+    EXECUTE FUNCTION public.update_updated_at_column();
+
+-- Row Level Security (RLS) Policies
+
+-- Enable RLS on all tables
+ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.user_sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.narrator_extractions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.narrator_analyses ENABLE ROW LEVEL SECURITY;
+
+-- Users table policies
+CREATE POLICY "Users can view own profile" ON public.users
+    FOR SELECT USING (auth.uid() = id);
+
+CREATE POLICY "Users can update own profile" ON public.users
+    FOR UPDATE USING (auth.uid() = id);
+
+CREATE POLICY "Service role can manage all users" ON public.users
+    FOR ALL USING (auth.role() = 'service_role');
+
+-- User sessions policies
+CREATE POLICY "Users can view own sessions" ON public.user_sessions
+    FOR SELECT USING (auth.uid() = user_id);
+
+CREATE POLICY "Service role can manage all sessions" ON public.user_sessions
+    FOR ALL USING (auth.role() = 'service_role');
+
+-- Narrator extractions policies
+CREATE POLICY "Users can view own extractions" ON public.narrator_extractions
+    FOR SELECT USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own extractions" ON public.narrator_extractions
+    FOR INSERT WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Service role can manage all extractions" ON public.narrator_extractions
+    FOR ALL USING (auth.role() = 'service_role');
+
+-- Narrator analyses policies
+CREATE POLICY "Users can view own analyses" ON public.narrator_analyses
+    FOR SELECT USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own analyses" ON public.narrator_analyses
+    FOR INSERT WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Service role can manage all analyses" ON public.narrator_analyses
+    FOR ALL USING (auth.role() = 'service_role');
+
+-- Grant necessary permissions
+GRANT USAGE ON SCHEMA public TO anon, authenticated;
+GRANT ALL ON ALL TABLES IN SCHEMA public TO anon, authenticated;
+GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO anon, authenticated;
+
+-- Create a function to automatically create user profile on signup
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+    INSERT INTO public.users (id, email, username, full_name)
+    VALUES (
+        NEW.id,
+        NEW.email,
+        COALESCE(NEW.raw_user_meta_data->>'username', NULL),
+        COALESCE(NEW.raw_user_meta_data->>'full_name', NULL)
+    );
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Create trigger to run the function on new user signup
+CREATE TRIGGER on_auth_user_created
+    AFTER INSERT ON auth.users
+    FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
+
+-- Create a view for user analytics
+CREATE VIEW public.user_analytics AS
+SELECT 
+    u.id,
+    u.email,
+    u.role,
+    u.created_at,
+    u.last_login,
+    COUNT(ne.id) as total_extractions,
+    COUNT(na.id) as total_analyses,
+    COUNT(us.id) as total_sessions
+FROM public.users u
+LEFT JOIN public.narrator_extractions ne ON u.id = ne.user_id
+LEFT JOIN public.narrator_analyses na ON u.id = na.user_id
+LEFT JOIN public.user_sessions us ON u.id = us.user_id
+GROUP BY u.id, u.email, u.role, u.created_at, u.last_login;
+
+-- Grant select on the view
+GRANT SELECT ON public.user_analytics TO authenticated;

sql/sample_data.sql

@@ -0,0 +1,155 @@
+-- Sample data for testing SanadCheck LLM API
+-- Execute after creating tables
+
+-- Insert sample users (these will be created through the auth system)
+-- This is just for reference - actual users will be created via the API
+
+-- Sample narrator extractions for testing
+INSERT INTO public.narrator_extractions (
+    id,
+    user_id,
+    hadith_text,
+    extracted_narrators,
+    sanad_chain,
+    success,
+    processing_time_ms,
+    created_at
+) VALUES 
+-- Note: Replace with actual user UUIDs after creating users through the API
+-- (
+--     uuid_generate_v4(),
+--     'user-uuid-here',
+--     'حدثنا محمد بن إسماعيل قال حدثنا عبد الله بن موسى قال أخبرنا إسرائيل عن أبي إسحاق عن البراء قال...',
+--     ARRAY['محمد بن إسماعيل', 'عبد الله بن موسى', 'إسرائيل', 'أبو إسحاق', 'البراء'],
+--     'محمد بن إسماعيل ← عبد الله بن موسى ← إسرائيل ← أبي إسحاق ← البراء',
+--     true,
+--     1500,
+--     NOW() - INTERVAL '1 day'
+-- );
+
+-- Create some utility functions for data analysis
+
+-- Function to get extraction statistics
+CREATE OR REPLACE FUNCTION public.get_extraction_stats()
+RETURNS TABLE (
+    total_extractions BIGINT,
+    successful_extractions BIGINT,
+    failed_extractions BIGINT,
+    success_rate NUMERIC,
+    avg_processing_time NUMERIC,
+    total_users BIGINT
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        COUNT(*) as total_extractions,
+        COUNT(*) FILTER (WHERE success = true) as successful_extractions,
+        COUNT(*) FILTER (WHERE success = false) as failed_extractions,
+        ROUND(
+            (COUNT(*) FILTER (WHERE success = true)::NUMERIC / COUNT(*)::NUMERIC) * 100, 
+            2
+        ) as success_rate,
+        ROUND(AVG(processing_time_ms), 2) as avg_processing_time,
+        COUNT(DISTINCT user_id) as total_users
+    FROM public.narrator_extractions;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to get most analyzed narrators
+CREATE OR REPLACE FUNCTION public.get_popular_narrators(limit_count INTEGER DEFAULT 10)
+RETURNS TABLE (
+    narrator_name TEXT,
+    analysis_count BIGINT,
+    avg_reliability_grade TEXT,
+    most_common_grade TEXT
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        na.narrator_name,
+        COUNT(*) as analysis_count,
+        MODE() WITHIN GROUP (ORDER BY na.reliability_grade) as most_common_grade,
+        ROUND(AVG(
+            CASE 
+                WHEN na.reliability_grade = 'Thiqah' THEN 5
+                WHEN na.reliability_grade = 'Saduq' THEN 4
+                WHEN na.reliability_grade = 'Da''if' THEN 2
+                WHEN na.reliability_grade = 'Matruk' THEN 1
+                ELSE 0
+            END
+        ), 2)::TEXT as avg_reliability_grade
+    FROM public.narrator_analyses na
+    WHERE na.success = true
+    GROUP BY na.narrator_name
+    ORDER BY analysis_count DESC
+    LIMIT limit_count;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to get user activity summary
+CREATE OR REPLACE FUNCTION public.get_user_activity(user_uuid UUID)
+RETURNS TABLE (
+    total_extractions BIGINT,
+    successful_extractions BIGINT,
+    total_analyses BIGINT,
+    successful_analyses BIGINT,
+    first_activity TIMESTAMP WITH TIME ZONE,
+    last_activity TIMESTAMP WITH TIME ZONE,
+    avg_processing_time NUMERIC
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        COUNT(ne.id) as total_extractions,
+        COUNT(ne.id) FILTER (WHERE ne.success = true) as successful_extractions,
+        COUNT(na.id) as total_analyses,
+        COUNT(na.id) FILTER (WHERE na.success = true) as successful_analyses,
+        MIN(LEAST(ne.created_at, na.created_at)) as first_activity,
+        MAX(GREATEST(ne.created_at, na.created_at)) as last_activity,
+        ROUND(AVG(COALESCE(ne.processing_time_ms, na.processing_time_ms)), 2) as avg_processing_time
+    FROM public.narrator_extractions ne
+    FULL OUTER JOIN public.narrator_analyses na ON ne.user_id = na.user_id
+    WHERE ne.user_id = user_uuid OR na.user_id = user_uuid;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_narrator_extractions_text_search ON public.narrator_extractions 
+USING gin(to_tsvector('arabic', hadith_text));
+
+CREATE INDEX IF NOT EXISTS idx_narrator_analyses_name_search ON public.narrator_analyses 
+USING gin(to_tsvector('arabic', narrator_name));
+
+-- Grant execute permissions on functions
+GRANT EXECUTE ON FUNCTION public.get_extraction_stats() TO authenticated;
+GRANT EXECUTE ON FUNCTION public.get_popular_narrators(INTEGER) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.get_user_activity(UUID) TO authenticated;
+
+-- Create a cleanup function for old sessions
+CREATE OR REPLACE FUNCTION public.cleanup_expired_sessions()
+RETURNS INTEGER AS $$
+DECLARE
+    deleted_count INTEGER;
+BEGIN
+    -- Delete sessions that have been expired for more than 7 days
+    DELETE FROM public.user_sessions 
+    WHERE expires_at < NOW() - INTERVAL '7 days';
+    
+    GET DIAGNOSTICS deleted_count = ROW_COUNT;
+    RETURN deleted_count;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Grant execute permission
+GRANT EXECUTE ON FUNCTION public.cleanup_expired_sessions() TO authenticated;
+
+-- Comments for documentation
+COMMENT ON TABLE public.users IS 'Extended user profiles linked to Supabase auth.users';
+COMMENT ON TABLE public.user_sessions IS 'JWT session tracking for security and analytics';
+COMMENT ON TABLE public.narrator_extractions IS 'Records of hadith narrator extraction requests and results';
+COMMENT ON TABLE public.narrator_analyses IS 'Records of individual narrator analysis requests and results';
+
+COMMENT ON FUNCTION public.get_extraction_stats() IS 'Returns overall statistics about extraction operations';
+COMMENT ON FUNCTION public.get_popular_narrators(INTEGER) IS 'Returns most frequently analyzed narrators';
+COMMENT ON FUNCTION public.get_user_activity(UUID) IS 'Returns activity summary for a specific user';
+COMMENT ON FUNCTION public.cleanup_expired_sessions() IS 'Removes old expired sessions to keep the database clean';