added

NEXTJS_INTEGRATION_GUIDE.md

@@ -1,960 +1,483 @@
-# 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
+## SanadCheck LLM API – Next.js Integration (with Authentication)
+
+This guide shows how to securely integrate the SanadCheck API into a Next.js 13/14+ (App Router) project, with proper JWT handling (access + refresh), protected server actions, and client usage examples.
+
+---
+## 1. High-Level Architecture
+
+Recommended pattern: keep ALL direct calls to the FastAPI service on the server (Next.js Route Handlers / Server Actions) so refresh tokens never reach the browser's JS runtime.
+
+Flow:
+1. User submits credentials (email/password) via a client component form.
+2. Form calls a Next.js Route Handler: `POST /api/auth/login`.
+3. Route handler forwards to FastAPI `/auth/login`.
+4. Response contains: `access_token`, `refresh_token`, `expires_in`, `user`.
+5. Next handler sets:
+	 - `sc_refresh` (HttpOnly, Secure, SameSite=Strict) – refresh token
+	 - `sc_access` (HttpOnly OR short-lived in-memory re-fetched via server action) – access token
+	 - Optionally store decoded `user` object in a signed cookie or re-fetch via `/auth/me` per request.
+6. Client components fetch data by calling internal Next.js API routes (proxy) that attach `Authorization: Bearer <access_token>`.
+7. If access token expired, the proxy handler uses the refresh token cookie to get a new pair (rotate!) transparently.
+
+Why this pattern:
+- Avoids XSS exposure of refresh tokens
+- Centralizes refresh logic
+- Enables SSR + Server Actions with authenticated context
+
+---
+## 2. Backend Endpoints Used
+
+Auth:
+- `POST /auth/register`
+- `POST /auth/login`
+- `POST /auth/refresh`
+- `POST /auth/logout`
+- `GET  /auth/me`
+- `GET  /auth/sessions`
+
+Core Hadith Analysis (all protected except `/api/v1/health` + some analytics):
+- `POST /api/v1/extract-narrators`
+- `POST /api/v1/analyze-narrator`
+- `POST /api/v1/analyze-narrator-chain`
+- `POST /api/v1/extract-and-analyze`
+- `GET  /api/v1/user/extractions`
+- `GET  /api/v1/user/analyses`
+- `GET  /api/v1/analytics/stats` (public)
+- `GET  /api/v1/analytics/popular-narrators` (public)
+- `GET  /api/v1/health` (public)
+
+Rate limit errors will return 429 and headers: `X-RateLimit-*`.
+
+---
+## 3. Environment Variables (Next.js)
+
+In `.env.local`:
 ```
-
-### 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
+SANAD_API_BASE_URL=http://localhost:8000   # FastAPI base
+NEXT_PUBLIC_SANAD_PUBLIC_BASE=/api/sanad    # Public-facing proxy base (optional)
 ```
 
-### 3. Project Structure
+Never expose service keys. Only the public base URL may be exposed.
 
+---
+## 4. Directory Structure (Suggested)
 ```
-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
+app/
+	api/
+		auth/
+			login/route.ts
+			register/route.ts
+			logout/route.ts
+			refresh/route.ts          # (Optional explicit refresh)
+			me/route.ts
+		sanad/
+			extract-narrators/route.ts
+			analyze-narrator/route.ts
+			extract-and-analyze/route.ts
+			user/
+				extractions/route.ts
+				analyses/route.ts
+			analytics/
+				stats/route.ts
+				popular-narrators/route.ts
+	(UI pages & components...)
+lib/
+	apiClient.ts
+	auth.ts
+	tokens.ts
+middleware.ts (optional token freshness logic)
+components/
+	AuthProvider.tsx
+	LoginForm.tsx
 ```
 
-## Authentication Service
-
-### TypeScript Types (`src/lib/types.ts`)
+---
+## 5. TypeScript Models
 
-```typescript
+Create `lib/types.ts`:
+```ts
 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;
+	id: string;
+	email: string;
+	username: string;
+	full_name: string;
+	role: string;
+	is_active: boolean;
 }
 
 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;
+	access_token: string;
+	refresh_token: string;
+	token_type: 'bearer';
+	expires_in: number; // seconds
+	user: User;
 }
 
 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;
+	narrators: string[];
+	sanad_chain: string;
+	success: boolean;
+	message?: 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;
-  };
+	narrator_name: string;
+	reliability_grade: string;
+	confidence_level: string;
+	reasoning: string;
+	scholarly_consensus: string;
+	known_issues?: string[] | null;
+	biographical_info: string;
+	recommendation: string;
+	success: boolean;
+	message?: 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();
+---
+## 6. Secure Token Handling Strategy
+
+| Aspect | Recommendation |
+|--------|---------------|
+| Access Token | Short-lived (minutes). Store in httpOnly cookie `sc_access` or re-fetch via server action each request. |
+| Refresh Token | HttpOnly + Secure cookie `sc_refresh` only. Never expose to JS. |
+| Rotation | Always replace both tokens on refresh (server enforces blacklisting). |
+| Expiry Tracking | Store `exp` in cookie or decode server-side. Trigger refresh when <60s left. |
+| Logout | Clear both cookies + call backend `/auth/logout` with current access token. |
+
+Cookie examples (set in route handlers):
+```ts
+cookies().set('sc_refresh', refreshToken, {
+	httpOnly: true,
+	secure: process.env.NODE_ENV === 'production',
+	sameSite: 'strict',
+	path: '/',
+	maxAge: 60 * 60 * 24 * 7, // adjust to backend refresh expiry
+});
+cookies().set('sc_access', accessToken, {
+	httpOnly: true,
+	secure: process.env.NODE_ENV === 'production',
+	sameSite: 'strict',
+	path: '/',
+	maxAge: 60 * 15,
+});
 ```
 
-### 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');
-  }
-}
-```
+---
+## 7. Generic Fetch Wrapper (Server)
 
-## React Hooks for Authentication
+`lib/apiClient.ts`:
+```ts
+import { cookies } from 'next/headers';
 
-### Authentication Hook (`src/hooks/useAuth.ts`)
+const BASE = process.env.SANAD_API_BASE_URL!;
 
-```typescript
-'use client';
+async function refreshIfNeeded(): Promise<string | null> {
+	const store = cookies();
+	const access = store.get('sc_access')?.value;
+	if (access) return access; // Or decode & check exp
 
-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 refresh = store.get('sc_refresh')?.value;
+	if (!refresh) return null;
 
-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>
-  );
+	// Call internal refresh route (not FastAPI directly)
+	const res = await fetch(`${process.env.NEXT_PUBLIC_SANAD_PUBLIC_BASE || ''}/auth/refresh`, { method: 'POST' });
+	if (!res.ok) return null;
+	const data = await res.json();
+	return cookies().get('sc_access')?.value || null; // After handler sets new cookie
 }
 
-export function useAuth() {
-  const context = useContext(AuthContext);
-  if (context === undefined) {
-    throw new Error('useAuth must be used within an AuthProvider');
-  }
-  return context;
+export async function sanadFetch<T>(path: string, init: RequestInit = {}): Promise<T> {
+	const token = await refreshIfNeeded();
+	const headers = new Headers(init.headers || {});
+	if (token) headers.set('Authorization', `Bearer ${token}`);
+	headers.set('Content-Type', 'application/json');
+
+	const res = await fetch(`${BASE}${path}`, { ...init, headers, cache: 'no-store' });
+	if (res.status === 429) {
+		const limit = res.headers.get('X-RateLimit-Limit');
+		const reset = res.headers.get('X-RateLimit-Reset');
+		throw new Error(`Rate limited. Limit=${limit} resets at=${reset}`);
+	}
+	if (!res.ok) {
+		const body = await res.text();
+		throw new Error(`Sanad API error ${res.status}: ${body}`);
+	}
+	return res.json() as Promise<T>;
 }
 ```
 
-## Protected Routes & Middleware
-
-### Next.js Middleware (`src/middleware.ts`)
+---
+## 8. Route Handler Examples (Proxy Pattern)
+
+`app/api/auth/login/route.ts`:
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+
+export async function POST(req: NextRequest) {
+	const creds = await req.json();
+	const res = await fetch(`${process.env.SANAD_API_BASE_URL}/auth/login`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify(creds),
+	});
+	if (!res.ok) {
+		return NextResponse.json({ error: 'Login failed' }, { status: res.status });
+	}
+	const data = await res.json();
+	const c = cookies();
+	c.set('sc_refresh', data.refresh_token, { httpOnly: true, secure: true, sameSite: 'strict', path: '/', maxAge: data.expires_in * 4 });
+	c.set('sc_access', data.access_token, { httpOnly: true, secure: true, sameSite: 'strict', path: '/', maxAge: data.expires_in });
+	return NextResponse.json({ user: data.user });
+}
+```
 
-```typescript
+`app/api/auth/refresh/route.ts`:
+```ts
+import { cookies } from 'next/headers';
 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 async function POST() {
+	const refresh = cookies().get('sc_refresh')?.value;
+	if (!refresh) return NextResponse.json({ error: 'No refresh token' }, { status: 401 });
+
+	const res = await fetch(`${process.env.SANAD_API_BASE_URL}/auth/refresh`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ refresh_token: refresh }),
+	});
+	if (!res.ok) return NextResponse.json({ error: 'Refresh failed' }, { status: 401 });
+	const data = await res.json();
+	const c = cookies();
+	c.set('sc_refresh', data.refresh_token, { httpOnly: true, secure: true, sameSite: 'strict', path: '/', maxAge: data.expires_in * 4 });
+	c.set('sc_access', data.access_token, { httpOnly: true, secure: true, sameSite: 'strict', path: '/', maxAge: data.expires_in });
+	return NextResponse.json({ status: 'refreshed' });
 }
+```
 
-export const config = {
-  matcher: [
-    '/((?!api|_next/static|_next/image|favicon.ico).*)',
-  ],
-};
+`app/api/sanad/extract-narrators/route.ts`:
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { sanadFetch } from '@/lib/apiClient';
+
+export async function POST(req: NextRequest) {
+	const body = await req.json();
+	try {
+		const data = await sanadFetch('/api/v1/extract-narrators', { method: 'POST', body: JSON.stringify(body) });
+		return NextResponse.json(data);
+	} catch (e: any) {
+		return NextResponse.json({ error: e.message }, { status: 500 });
+	}
+}
 ```
 
-### Protected Route Component (`src/components/ui/ProtectedRoute.tsx`)
+Add similar handlers for `analyze-narrator`, `extract-and-analyze`, etc.
 
-```typescript
-'use client';
+---
+## 9. Client Hook (Optional Thin Layer)
 
-import { useAuth } from '@/hooks/useAuth';
-import { useRouter } from 'next/navigation';
-import { useEffect, ReactNode } from 'react';
+`lib/useSanad.ts` (Client Component safe):
+```ts
+import { useState } from 'react';
 
-interface ProtectedRouteProps {
-  children: ReactNode;
-  requiredRole?: 'user' | 'admin' | 'researcher';
+export function useSanad() {
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	async function post<T>(path: string, payload: any): Promise<T | null> {
+		setLoading(true); setError(null);
+		try {
+			const res = await fetch(`/api/sanad${path}`, { method: 'POST', body: JSON.stringify(payload) });
+			const json = await res.json();
+			if (!res.ok) throw new Error(json.error || 'Request failed');
+			return json as T;
+		} catch (e: any) { setError(e.message); return null; }
+		finally { setLoading(false); }
+	}
+
+	return { post, loading, error };
 }
+```
 
-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}</>;
+Usage in a component:
+```tsx
+const { post, loading, error } = useSanad();
+async function handleExtract(text: string) {
+	const data = await post('/extract-narrators', { hadith_text: text });
+	console.log(data);
 }
 ```
 
-## Components
+---
+## 10. Server Action Example (Optional)
 
-### 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';
+If you prefer server actions instead of route handlers for some flows:
+```ts
+'use server';
+import { sanadFetch } from '@/lib/apiClient';
 
-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>
-  );
+export async function extractNarratorsAction(hadith: string) {
+	return sanadFetch('/api/v1/extract-narrators', { method: 'POST', body: JSON.stringify({ hadith_text: hadith }) });
 }
 ```
+Call inside a Server Component or via form action.
 
-### Hadith Analysis Component (`src/components/analysis/HadithAnalyzer.tsx`)
-
-```typescript
+---
+## 11. Login Form (Client) Example
+```tsx
 '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>
-  );
+
+export function LoginForm() {
+	const [email, setEmail] = useState('');
+	const [password, setPassword] = useState('');
+	const [error, setError] = useState<string | null>(null);
+
+	async function submit(e: React.FormEvent) {
+		e.preventDefault(); setError(null);
+		const res = await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify({ email, password }) });
+		const data = await res.json();
+		if (!res.ok) setError(data.error || 'Login failed');
+		// success: user available in data.user, tokens stored as cookies
+	}
+
+	return (
+		<form onSubmit={submit} className="space-y-2">
+			<input value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" />
+			<input type="password" value={password} onChange={e => setPassword(e.target.value)} placeholder="Password" />
+			<button type="submit">Login</button>
+			{error && <p className="text-red-500">{error}</p>}
+		</form>
+	);
 }
 ```
 
-## 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>
-  );
+---
+## 12. Handling Rate Limits & Errors
+
+Pattern:
+```ts
+try {
+	const res = await sanadFetch('/api/v1/analyze-narrator', { method: 'POST', body: JSON.stringify({ narrator_name }) });
+} catch (e: any) {
+	if (e.message.includes('429')) {
+		// show friendly message / retry after header
+	}
 }
 ```
+Consider exponential backoff for bursts and surface `X-RateLimit-Remaining` to show usage.
 
-### Dashboard Page (`src/app/dashboard/page.tsx`)
-
-```typescript
-'use client';
+---
+## 13. Logout Flow
+Route handler `app/api/auth/logout/route.ts`:
+```ts
+import { cookies } from 'next/headers';
+import { NextResponse } from 'next/server';
 
-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>
-  );
+export async function POST() {
+	const access = cookies().get('sc_access')?.value;
+	if (access) {
+		await fetch(`${process.env.SANAD_API_BASE_URL}/auth/logout`, {
+			method: 'POST',
+			headers: { Authorization: `Bearer ${access}` }
+		}).catch(() => {});
+	}
+	const c = cookies();
+	c.delete('sc_access');
+	c.delete('sc_refresh');
+	return NextResponse.json({ status: 'logged_out' });
 }
 ```
+Client call:
+```ts
+await fetch('/api/auth/logout', { method: 'POST' });
+```
 
-## Error Handling
-
-### Global Error Handler (`src/lib/errorHandler.ts`)
-
-```typescript
-import { AxiosError } from 'axios';
-
-export interface ApiErrorResponse {
-  detail: string;
-  status_code?: number;
+---
+## 14. Middleware (Optional Early Refresh)
+
+`middleware.ts` (basic sketch – only if you want silent refresh before protected routes):
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function middleware(req: NextRequest) {
+	const access = req.cookies.get('sc_access');
+	if (!access) {
+		const refresh = req.cookies.get('sc_refresh');
+		if (refresh) {
+			await fetch(new URL('/api/auth/refresh', req.url), { method: 'POST' });
+		}
+	}
+	return NextResponse.next();
 }
 
-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 const config = { matcher: ['/dashboard/:path*', '/analysis/:path*'] };
+```
 
-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);
-  }
-}
+---
+## 15. Security Checklist
+
+- Use `Secure` cookies in production (HTTPS)
+- Set `SameSite=Strict` to mitigate CSRF (or use custom CSRF token if cross-site embedding needed)
+- Do NOT store refresh tokens in `localStorage` or JS-accessible cookies
+- Rotate tokens on every refresh
+- Handle logout on 401 loops (e.g., if refresh also fails)
+
+---
+## 16. Minimal End-to-End Example
+
+1. User visits `/login` → submits form
+2. `/api/auth/login` sets cookies
+3. User navigates to `/dashboard` (protected)
+4. Server component calls server action or `fetch('/api/sanad/extract-narrators')`
+5. Handler attaches Authorization header → FastAPI processes → returns JSON
+6. Access token expires → next call triggers `/api/auth/refresh` implicitly → cookies updated
+7. User clicks logout → `/api/auth/logout` → cookies cleared + token blacklisted
+
+---
+## 17. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 401 on every request | Missing Authorization header | Ensure proxy sets header after refresh |
+| 401 after refresh | Refresh token expired/blacklisted | Force logout & re-login |
+| 429 errors | Rate limit exceeded | Slow down / show user retry time |
+| CORS errors (if bypassing proxy) | Direct browser → FastAPI without proper CORS | Always use Next.js proxy or configure CORS on backend |
+| Cookie not set in prod | Missing `secure` or domain mismatch | Set correct domain & HTTPS |
+
+---
+## 18. Next Steps / Enhancements
+
+- Add SWR/React Query for caching
+- Add optimistic UI for chain analysis
+- Add user session list page using `/auth/sessions`
+- Implement progress indicators for long analyses
+
+---
+## 19. Quick Reference (Cheat Sheet)
+
+Auth Cycle:
+```
+POST /api/auth/login            -> sets cookies
+POST /api/auth/refresh          -> rotates tokens
+POST /api/auth/logout           -> clears + blacklists
+GET  /api/auth/me               -> user profile
 ```
 
-## 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();
-});
+Core Calls:
+```
+POST /api/sanad/extract-narrators
+POST /api/sanad/analyze-narrator
+POST /api/sanad/extract-and-analyze
+GET  /api/sanad/user/extractions
+GET  /api/sanad/user/analyses
 ```
 
-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.
+---
+## 20. Summary
+
+Use a proxy pattern + HttpOnly cookies to keep tokens safe, centralize refresh logic, and provide a clean developer experience in your Next.js app. The snippets above can be copied directly and adjusted to your folder naming. Expand with caching & UI state management as needed.
+
+If you need a tailored example repository scaffold, ask and we can generate it.
+

app/api/routes.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, HTTPException, status, Depends, Request
+from fastapi import APIRouter, HTTPException, status, Depends, Request, Body
 from fastapi.responses import JSONResponse
 from typing import List, Dict, Any
 from datetime import datetime
@@ -36,9 +36,9 @@ router = APIRouter(prefix="/api/v1", tags=["hadith-analysis"])
 )
 @authenticated_user_limit()
 async def extract_narrators(
-    request: HadithTextRequest, 
+    request: HadithTextRequest,
     http_request: Request,
-    current_user: User = Depends(get_current_active_user)
+    current_user: User = Depends(get_current_active_user),
 ) -> NarratorExtractionResponse:
     """
     Extract narrators from hadith text.
@@ -59,12 +59,14 @@ async def extract_narrators(
     """
     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
+
+        processing_time = int(
+            (time.time() - start_time) * 1000
+        )  # Convert to milliseconds
 
         # Store extraction record in database
         extraction_record = NarratorExtractionRecord(
@@ -75,9 +77,9 @@ async def extract_narrators(
             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)
+            ip_address=get_user_ip(http_request),
         )
-        
+
         await db_service.store_extraction_record(extraction_record)
 
         if not result.success:
@@ -101,14 +103,14 @@ async def extract_narrators(
             success=False,
             error_message=str(e),
             processing_time_ms=processing_time,
-            ip_address=get_user_ip(http_request)
+            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)}",
@@ -124,7 +126,8 @@ async def extract_narrators(
 @authenticated_user_limit()
 async def analyze_narrator(
     request: NarratorAnalysisRequest,
-    current_user: User = Depends(get_current_active_user)
+    http_request: Request,
+    current_user: User = Depends(get_current_active_user),
 ) -> NarratorAnalysisResponse:
     """
     Analyze narrator reliability based on the model's internal knowledge.
@@ -145,11 +148,11 @@ async def analyze_narrator(
     """
     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
@@ -165,9 +168,9 @@ async def analyze_narrator(
             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
+            processing_time_ms=processing_time,
         )
-        
+
         await db_service.store_analysis_record(analysis_record)
 
         if not result.success:
@@ -195,8 +198,9 @@ async def analyze_narrator(
 )
 @authenticated_user_limit()
 async def analyze_narrator_chain(
-    narrator_names: List[str],
-    current_user: User = Depends(get_current_active_user)
+    request: Request,
+    narrator_names: List[str] = Body(...),
+    current_user: User = Depends(get_current_active_user),
 ) -> NarratorChainAnalysisResponse:
     """
     Analyze a complete chain of narrators with enhanced data sources.
@@ -272,7 +276,8 @@ async def analyze_narrator_chain(
 @authenticated_user_limit()
 async def extract_and_analyze_hadith(
     request: HadithTextRequest,
-    current_user: User = Depends(get_current_active_user)
+    http_request: Request,
+    current_user: User = Depends(get_current_active_user),
 ) -> ExtractAndAnalyzeResponse:
     """
     Complete hadith analysis workflow: extraction + chain analysis.
@@ -377,7 +382,7 @@ async def health_check():
             "Complete hadith workflow analysis",
             "JWT Authentication",
             "Rate limiting",
-            "Database storage"
+            "Database storage",
         ],
     }
 
@@ -386,12 +391,13 @@ async def health_check():
 @router.get(
     "/user/extractions",
     summary="Get user's extraction history",
-    description="Get the current user's narrator extraction history"
+    description="Get the current user's narrator extraction history",
 )
 @authenticated_user_limit()
 async def get_user_extractions(
+    request: Request,
     current_user: User = Depends(get_current_active_user),
-    limit: int = 50
+    limit: int = 50,
 ):
     """Get user's extraction history."""
     db_service = DatabaseService()
@@ -402,12 +408,13 @@ async def get_user_extractions(
 @router.get(
     "/user/analyses",
     summary="Get user's analysis history",
-    description="Get the current user's narrator analysis history"
+    description="Get the current user's narrator analysis history",
 )
 @authenticated_user_limit()
 async def get_user_analyses(
+    request: Request,
     current_user: User = Depends(get_current_active_user),
-    limit: int = 50
+    limit: int = 50,
 ):
     """Get user's analysis history."""
     db_service = DatabaseService()
@@ -418,7 +425,7 @@ async def get_user_analyses(
 @router.get(
     "/analytics/stats",
     summary="Get extraction statistics",
-    description="Get overall platform statistics (public)"
+    description="Get overall platform statistics (public)",
 )
 async def get_platform_stats():
     """Get platform-wide extraction statistics."""
@@ -430,7 +437,7 @@ async def get_platform_stats():
 @router.get(
     "/analytics/popular-narrators",
     summary="Get popular narrators",
-    description="Get most frequently analyzed narrators (public)"
+    description="Get most frequently analyzed narrators (public)",
 )
 async def get_popular_narrators(limit: int = 10):
     """Get most analyzed narrators."""

app/main.py

@@ -116,5 +116,5 @@ async def shutdown_event():
 if __name__ == "__main__":
     # Run the application
     uvicorn.run(
-        "app:app", host="0.0.0.0", port=8000, reload=settings.DEBUG, log_level="info"
+        "app.main:app", host="0.0.0.0", port=8000, reload=settings.DEBUG, log_level="info"
     )