Upload 62 files

.dockerignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Documentation
+*.md
+!README.md
+docs/
+
+# Logs
+*.log
+logs/
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# Misc
+node_modules/
+coverage/

.env

@@ -0,0 +1,40 @@
+# Database Configuration
+# Neon Serverless Postgres connection string
+# Format: postgresql://user:password@host.neon.tech/dbname?sslmode=require
+DATABASE_URL=postgresql://neondb_owner:npg_KxTmt2lL1seZ@ep-winter-night-ah1gvoeu-pooler.c-3.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require
+
+# Vector Database Configuration
+# Qdrant Cloud cluster URL and API key
+QDRANT_URL=https://dd8a681c-65ea-4ca6-ac50-e7e4873fdba1.us-east4-0.gcp.cloud.qdrant.io
+QDRANT_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3MiOiJtIn0.820mM91jPhDQYvtU9O6WYu2gU9W-gTPdjaNbndmYNBY
+
+# OpenAI API Configuration
+# Get your API key from https://platform.openai.com/api-keys
+OPENAI_API_KEY=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
+# Optional: Organization ID if you have one
+OPENAI_ORG_ID=
+
+# Authentication Configuration
+# Generate with: openssl rand -hex 32
+BETTER_AUTH_SECRET=jVLDQBQkEZCtBMsGMfHTl0QtAI8Vqu8T
+# Session expiration in seconds (default: 7 days)
+SESSION_TTL=604800
+
+# Application Settings
+ENVIRONMENT=development
+LOG_LEVEL=INFO
+
+# Rate Limiting
+# Maximum requests per minute per user
+RATE_LIMIT_PER_MINUTE=20
+
+# CORS Configuration
+# Comma-separated list of allowed origins
+ALLOWED_ORIGINS=http://localhost:3000
+
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+
+# Redis Configuration (for rate limiting)
+REDIS_URL="redis://default:xTmd5Lh1uAkxqdbcYjXZVt8eCM43MH8l@redis-12427.c276.us-east-1-2.ec2.cloud.redislabs.com:12427"

Dockerfile

@@ -0,0 +1,52 @@
+# Multi-stage build for production-ready image
+
+# Stage 1: Build dependencies
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# Stage 2: Runtime
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Python dependencies from builder
+COPY --from=builder /root/.local /root/.local
+
+# Copy application code
+COPY src/ ./src/
+COPY scripts/ ./scripts/
+COPY alembic/ ./alembic/
+COPY alembic.ini ./
+
+# Make sure scripts are on path
+ENV PATH=/root/.local/bin:$PATH
+
+# Create non-root user for security
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
+
+# Run application
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

@@ -0,0 +1,46 @@
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=${DATABASE_URL}
+      - QDRANT_URL=${QDRANT_URL}
+      - QDRANT_API_KEY=${QDRANT_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OPENAI_ORG_ID=${OPENAI_ORG_ID:-}
+      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
+      - ENVIRONMENT=development
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - RATE_LIMIT_PER_MINUTE=${RATE_LIMIT_PER_MINUTE:-20}
+      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-http://localhost:3000}
+    volumes:
+      - ./src:/app/src
+      - ./scripts:/app/scripts
+    depends_on:
+      - redis
+    networks:
+      - chatbot-network
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    networks:
+      - chatbot-network
+    restart: unless-stopped
+    command: redis-server --appendonly yes
+
+volumes:
+  redis-data:
+
+networks:
+  chatbot-network:
+    driver: bridge

scripts/embed_book_content.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""
+Book content embedding script
+
+Reads markdown files from docs/ (including all nested subdirectories), chunks content by headings or word count,
+generates embeddings with OpenAI, and uploads to Qdrant vector database.
+
+Usage:
+    python backend/scripts/embed_book_content.py --book-path docs/ --collection-name humanoid-robotics-book-v1
+"""
+import argparse
+import asyncio
+import os
+import re
+import sys
+from pathlib import Path
+from typing import List, Dict, Any
+from uuid import uuid4
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from openai import AsyncOpenAI
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import Distance, VectorParams, PointStruct
+
+from src.config.settings import settings
+from src.utils.logger import setup_logging, get_logger
+
+setup_logging(level="INFO")
+logger = get_logger(__name__)
+
+
+class BookContentChunker:
+    """Chunks markdown content intelligently by headings and word limits"""
+
+    def __init__(self, chunk_size: int = 500, overlap: int = 50):
+        """
+        Initialize chunker
+
+        Args:
+            chunk_size: Target chunk size in words
+            overlap: Word overlap between chunks
+        """
+        self.chunk_size = chunk_size
+        self.overlap = overlap
+
+    def chunk_markdown(self, content: str, file_path: str) -> List[Dict[str, Any]]:
+        """
+        Chunk markdown content by headings and word limits
+
+        Args:
+            content: Markdown file content
+            file_path: Path to markdown file (for metadata)
+
+        Returns:
+            List of chunk dictionaries with content and metadata
+        """
+        chunks = []
+
+        # Extract chapter/module name from file path
+        path_obj = Path(file_path)
+        chapter = self._extract_chapter_name(path_obj)
+
+        # Split by headings (## and ###)
+        sections = re.split(r'(^#{2,3}\s+.+$)', content, flags=re.MULTILINE)
+
+        current_section_heading = "Introduction"
+        current_content = []
+
+        for i, section in enumerate(sections):
+            # Check if this is a heading
+            heading_match = re.match(r'^(#{2,3})\s+(.+)$', section.strip())
+
+            if heading_match:
+                # Save previous section if it has content
+                if current_content:
+                    section_chunks = self._chunk_section(
+                        "\n".join(current_content),
+                        chapter,
+                        current_section_heading
+                    )
+                    chunks.extend(section_chunks)
+
+                # Start new section
+                current_section_heading = heading_match.group(2).strip()
+                current_content = []
+            else:
+                # Accumulate content
+                if section.strip():
+                    current_content.append(section.strip())
+
+        # Process last section
+        if current_content:
+            section_chunks = self._chunk_section(
+                "\n".join(current_content),
+                chapter,
+                current_section_heading
+            )
+            chunks.extend(section_chunks)
+
+        return chunks
+
+    def _chunk_section(self, content: str, chapter: str, section: str) -> List[Dict[str, Any]]:
+        """Chunk a section by word count with overlap"""
+        words = content.split()
+        chunks = []
+
+        if len(words) <= self.chunk_size:
+            # Section fits in one chunk
+            chunks.append({
+                "content": content,
+                "chapter": chapter,
+                "section": section,
+                "heading": section,
+                "chunk_index": 0,
+                "word_count": len(words),
+            })
+        else:
+            # Split into multiple chunks with overlap
+            chunk_index = 0
+            start = 0
+
+            while start < len(words):
+                end = start + self.chunk_size
+                chunk_words = words[start:end]
+
+                chunks.append({
+                    "content": " ".join(chunk_words),
+                    "chapter": chapter,
+                    "section": section,
+                    "heading": section,
+                    "chunk_index": chunk_index,
+                    "word_count": len(chunk_words),
+                })
+
+                chunk_index += 1
+                start = end - self.overlap  # Overlap for context
+
+        return chunks
+
+    def _extract_chapter_name(self, path: Path) -> str:
+        """Extract chapter/module name from file path"""
+        # Try to extract from directory or filename
+        parts = path.parts
+
+        # Look for patterns like "module1-ros2", "Module 1", etc.
+        for part in reversed(parts):
+            if re.match(r'module[-\s]*\d+', part, re.IGNORECASE):
+                return part.replace('-', ' ').title()
+
+        # Fallback to filename without extension
+        return path.stem.replace('-', ' ').replace('_', ' ').title()
+
+
+class BookEmbedder:
+    """Handles embedding generation and Qdrant upload"""
+
+    def __init__(self, collection_name: str = "book_content"):
+        """
+        Initialize embedder
+
+        Args:
+            collection_name: Qdrant collection name
+        """
+        self.collection_name = collection_name
+        self.openai_client = AsyncOpenAI(api_key=settings.openai_api_key)
+        self.qdrant_client = AsyncQdrantClient(
+            url=settings.qdrant_url,
+            api_key=settings.qdrant_api_key,
+            timeout=30,  # Set a higher timeout (seconds)
+        )
+
+    async def create_collection(self):
+        """Create Qdrant collection if it doesn't exist, with improved connection error handling"""
+        try:
+            collections = await self.qdrant_client.get_collections()
+        except Exception as e:
+            logger.error(
+                "\nCannot connect to Qdrant. "
+                f"Error: {type(e).__name__}: {e}\n"
+                "-> Please make sure your Qdrant server is running and accessible at the configured URL.\n"
+                f"-> Current Qdrant URL: {settings.qdrant_url}"
+            )
+            logger.error("Exiting due to Qdrant connection failure.")
+            import sys
+            sys.exit(1)
+
+        collection_names = [col.name for col in collections.collections]
+
+        if self.collection_name not in collection_names:
+            await self.qdrant_client.create_collection(
+                collection_name=self.collection_name,
+                vectors_config=VectorParams(
+                    size=settings.vector_size,
+                    distance=Distance.COSINE,
+                ),
+            )
+            logger.info(f"Created collection: {self.collection_name}")
+        else:
+            logger.info(f"Collection already exists: {self.collection_name}")
+
+    async def embed_text(self, text: str) -> List[float]:
+        """
+        Generate embedding for text using OpenAI
+
+        Args:
+            text: Text to embed
+
+        Returns:
+            Embedding vector
+        """
+        response = await self.openai_client.embeddings.create(
+            model=settings.openai_embedding_model,
+            input=text
+        )
+        return response.data[0].embedding
+
+    async def upload_chunks(self, chunks: List[Dict[str, Any]], doc_version: str = "v1.0.0"):
+        """
+        Upload chunks with embeddings to Qdrant
+
+        Args:
+            chunks: List of chunk dictionaries
+            doc_version: Document version identifier
+        """
+        logger.info(f"Uploading {len(chunks)} chunks to Qdrant...")
+
+        points = []
+
+        for i, chunk in enumerate(chunks):
+            # Generate embedding
+            embedding = await self.embed_text(chunk["content"])
+
+            # Create point
+            point = PointStruct(
+                id=str(uuid4()),
+                vector=embedding,
+                payload={
+                    "content": chunk["content"],
+                    "chapter": chunk["chapter"],
+                    "section": chunk["section"],
+                    "heading": chunk["heading"],
+                    "chunk_index": chunk["chunk_index"],
+                    "word_count": chunk["word_count"],
+                    "doc_version": doc_version,
+                }
+            )
+            points.append(point)
+
+            # Upload in batches of 100
+            if len(points) >= 100:
+                await self.qdrant_client.upsert(
+                    collection_name=self.collection_name,
+                    points=points
+                )
+                logger.info(f"Uploaded batch {i // 100 + 1} ({len(points)} points)")
+                points = []
+
+        # Upload remaining points
+        if points:
+            await self.qdrant_client.upsert(
+                collection_name=self.collection_name,
+                points=points
+            )
+            logger.info(f"Uploaded final batch ({len(points)} points)")
+
+    async def close(self):
+        """Close connections"""
+        await self.qdrant_client.close()
+
+
+def get_all_markdown_files_recursively(root_path: Path) -> List[Path]:
+    """
+    Find all markdown files recursively (as deep as needed) in the given root_path.
+    This function will walk all subdirectories and return both *.md and *.mdx files.
+
+    Args:
+        root_path: Path to the root directory
+
+    Returns:
+        List[Path]: List of all markdown file Paths
+    """
+    md_files = list(root_path.rglob("*.md"))
+    mdx_files = list(root_path.rglob("*.mdx"))
+    all_files = md_files + mdx_files
+    return [file for file in all_files if file.is_file() and 'node_modules' not in str(file)]
+
+
+async def main():
+    """Main embedding script"""
+    parser = argparse.ArgumentParser(description="Embed book content into Qdrant")
+    parser.add_argument(
+        "--book-path",
+        type=str,
+        required=True,
+        help="Path to book content directory (e.g., docs/)"
+    )
+    parser.add_argument(
+        "--collection-name",
+        type=str,
+        default="humanoid-robotics-book-v1",
+        help="Qdrant collection name"
+    )
+    parser.add_argument(
+        "--doc-version",
+        type=str,
+        default="v1.0.0",
+        help="Document version identifier"
+    )
+
+    args = parser.parse_args()
+
+    # Initialize components
+    chunker = BookContentChunker(chunk_size=500, overlap=50)
+    embedder = BookEmbedder(collection_name=args.collection_name)
+
+    try:
+        # Create collection, with robust error handling in the constructor
+        await embedder.create_collection()
+
+        # Find all markdown files as deep as needed
+        book_path = Path(args.book_path)
+        md_files = get_all_markdown_files_recursively(book_path)
+        logger.info(f"Found {len(md_files)} markdown files (.md and .mdx) recursively in all subdirectories")
+
+        # Process each file
+        all_chunks = []
+        for md_file in md_files:
+            logger.info(f"Processing: {md_file}")
+
+            with open(md_file, 'r', encoding='utf-8') as f:
+                content = f.read()
+
+            chunks = chunker.chunk_markdown(content, str(md_file))
+            all_chunks.extend(chunks)
+            logger.info(f"  -> Generated {len(chunks)} chunks")
+
+        logger.info(f"Total chunks: {len(all_chunks)}")
+
+        # Upload to Qdrant
+        await embedder.upload_chunks(all_chunks, doc_version=args.doc_version)
+
+        logger.info("✅ Embedding complete!")
+
+    finally:
+        await embedder.close()
+
+
+if __name__ == "__main__":
+    # Run main in asyncio loop, but trap connection errors globally as a last resort
+    try:
+        asyncio.run(main())
+    except Exception as e:
+        logger.error(f"FATAL: Exception occurred: {type(e).__name__}: {e}")
+        logger.error("Please check if Qdrant is running, accessible, and credentials are set correctly.")
+        import sys
+        sys.exit(1)

src/__init__.py

@@ -0,0 +1 @@
+"""RAG Chatbot Backend Package"""

src/api/__init__.py

@@ -0,0 +1 @@
+"""API package"""

src/api/middleware/__init__.py

@@ -0,0 +1 @@
+"""Middleware package"""

src/api/middleware/auth_middleware.py

@@ -0,0 +1,148 @@
+"""Authentication middleware for protecting API endpoints
+
+Provides dependency injection for current user authentication.
+Validates JWT tokens from HTTP-only cookies and extracts user information.
+"""
+from typing import Optional
+from fastapi import Depends, HTTPException, status, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.config.database import get_db_session
+from src.models.user import User
+from src.services.auth_service import AuthService
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# HTTP Bearer scheme for Authorization header (optional fallback)
+security = HTTPBearer(auto_error=False)
+
+
+async def get_token_from_request(request: Request) -> Optional[str]:
+    """Extract JWT token from cookie or Authorization header
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        JWT token string or None
+    """
+    # First, try to get token from HTTP-only cookie
+    token = request.cookies.get("auth_token")
+    if token:
+        return token
+
+    # Fallback: try Authorization header (for API clients)
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        return auth_header.split(" ")[1]
+
+    return None
+
+
+async def get_current_user(
+    request: Request,
+    db: AsyncSession = Depends(get_db_session)
+) -> User:
+    """Dependency to get the current authenticated user
+
+    Validates JWT token from cookie/header and returns the associated user.
+    Raises 401 Unauthorized if token is invalid or user not found.
+
+    Args:
+        request: FastAPI request object
+        db: Database session
+
+    Returns:
+        Authenticated User instance
+
+    Raises:
+        HTTPException: 401 if authentication fails
+    """
+    # Extract token from request
+    token = await get_token_from_request(request)
+
+    if not token:
+        logger.warning("Authentication failed: no token provided")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Decode and validate JWT token
+    payload = AuthService.decode_jwt_token(token)
+    if not payload:
+        logger.warning("Authentication failed: invalid JWT token")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Extract user_id from token payload
+    user_id_str = payload.get("sub")
+    if not user_id_str:
+        logger.warning("Authentication failed: no user_id in token payload")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token payload",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Validate session still exists in database
+    session = await AuthService.validate_session(db, token)
+    if not session:
+        logger.warning(f"Authentication failed: session not found or expired for token")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session expired or invalid",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Get user from database
+    from uuid import UUID
+    try:
+        user_id = UUID(user_id_str)
+    except ValueError:
+        logger.warning(f"Authentication failed: invalid user_id format: {user_id_str}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid user identifier",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    user = await AuthService.get_user_by_id(db, user_id)
+    if not user:
+        logger.warning(f"Authentication failed: user {user_id} not found")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    logger.debug(f"User authenticated: {user.id}")
+    return user
+
+
+async def get_current_user_optional(
+    request: Request,
+    db: AsyncSession = Depends(get_db_session)
+) -> Optional[User]:
+    """Optional authentication dependency
+
+    Same as get_current_user but returns None instead of raising exception
+    when no valid authentication is provided.
+
+    Args:
+        request: FastAPI request object
+        db: Database session
+
+    Returns:
+        Authenticated User instance or None
+    """
+    try:
+        return await get_current_user(request, db)
+    except HTTPException:
+        return None

src/api/middleware/logging_middleware.py

@@ -0,0 +1,37 @@
+"""Logging middleware for API requests and responses.
+
+This middleware logs details of each API request and its corresponding response.
+"""
+import time
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        start_time = time.time()
+        
+        # Log request details
+        request_log_details = {
+            "method": request.method,
+            "path": request.url.path,
+            "client": request.client.host,
+        }
+        logger.info("Request started", extra=request_log_details)
+        
+        response = await call_next(request)
+        
+        process_time = (time.time() - start_time) * 1000
+        
+        # Log response details
+        response_log_details = {
+            "method": request.method,
+            "path": request.url.path,
+            "status_code": response.status_code,
+            "process_time_ms": f"{process_time:.2f}",
+        }
+        logger.info("Request finished", extra=response_log_details)
+        
+        return response

src/api/middleware/rate_limit.py

@@ -0,0 +1,76 @@
+# src/api/middleware/rate_limit.py
+from typing import Callable
+from fastapi import Request
+from fastapi.responses import JSONResponse
+import inspect
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+from src.config.settings import settings
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+def get_user_identifier(request: Request) -> str:
+    user = getattr(request.state, "user", None)
+    if user:
+        return f"user:{user.id}"
+    return f"ip:{get_remote_address(request)}"
+
+# Create limiter instance (single authoritative limiter in this module)
+limiter = Limiter(
+    key_func=get_user_identifier,
+    default_limits=[f"{settings.rate_limit_per_minute}/minute"],
+    storage_uri=settings.redis_url,
+    strategy="fixed-window"
+)
+
+async def rate_limit_dependency(request: Request):
+    """
+    FastAPI dependency to apply default rate limiting.
+
+    This wraps a small noop handler with the limiter decorator and calls it.
+    That keeps the decorator semantics without passing Request into the decorator.
+    """
+    # decorator that would normally be used on a route
+    decorator = limiter.limit(f"{settings.rate_limit_per_minute}/minute")
+
+    # a tiny handler the decorator can wrap
+    async def _noop(req: Request):
+        return None
+
+    wrapped = decorator(_noop)  # now wrapped is a callable handler
+
+    # call the wrapped handler with the request; handle whether it is awaitable
+    result = wrapped(request)
+    if inspect.isawaitable(result):
+        await result
+
+    # dependency returns truthy so route proceeds
+    return True
+
+
+def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
+    identifier = get_user_identifier(request)
+    logger.warning(f"Rate limit exceeded for {identifier}")
+
+    # Try to parse retry after defensively
+    retry_after = 60
+    try:
+        # exc.detail sometimes contains text like "Retry after 60 seconds"
+        if isinstance(exc.detail, str) and "Retry after" in exc.detail:
+            parts = exc.detail.split("Retry after")
+            if len(parts) > 1:
+                retry_after = int(''.join(filter(str.isdigit, parts[1])) or 60)
+    except Exception:
+        retry_after = 60
+
+    payload = {
+        "error": "rate_limit_exceeded",
+        "message": f"Too many requests. Please try again in {retry_after} seconds.",
+        "retry_after": int(retry_after)
+    }
+
+    return JSONResponse(status_code=429, content=payload, headers={"Retry-After": str(retry_after)})

src/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes package"""

src/api/routes/auth.py

@@ -0,0 +1,304 @@
+"""Authentication routes for user registration, login, and session management
+
+Provides endpoints for:
+- POST /auth/register - User registration
+- POST /auth/login - User login
+- POST /auth/logout - User logout
+- GET /auth/me - Get current user
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+from src.config.database import get_db_session
+from src.models.user import User
+from src.models.schemas import (
+    UserCreate,
+    UserLogin,
+    UserResponse,
+    AuthResponse,
+    MessageResponse
+)
+from src.services.auth_service import AuthService
+from src.api.middleware.auth_middleware import get_current_user, get_token_from_request
+from src.utils.logger import get_logger
+from src.utils.validators import sanitize_html
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+# Max allowed length for bcrypt hashing (EXPANDED)
+BCRYPT_PASSWORD_MAX_BYTES = 4096  # Was 72, but expanded to allow for saving a big password
+
+
+@router.post(
+    "/register",
+    response_model=AuthResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Register a new user",
+    description="Create a new user account with email and password"
+)
+async def register(
+    user_data: UserCreate,
+    response: Response,
+    db: AsyncSession = Depends(get_db_session)
+) -> AuthResponse:
+    """Register a new user account
+
+    Args:
+        user_data: User registration data (email, password)
+        response: FastAPI response object for setting cookies
+        db: Database session
+
+    Returns:
+        AuthResponse with user data and session token
+
+    Raises:
+        HTTPException: 400 if email already exists
+    """
+    # Check if user already exists
+    result = await db.execute(
+        select(User).where(User.email == user_data.email.lower())
+    )
+    existing_user = result.scalar_one_or_none()
+
+    if existing_user:
+        logger.warning(f"Registration failed: email {user_data.email} already exists")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+
+    # Truncate password to BCRYPT_PASSWORD_MAX_BYTES for hashing (now allows larger passwords)
+    password = user_data.password
+    password_bytes = password.encode("utf-8")
+    if len(password_bytes) > BCRYPT_PASSWORD_MAX_BYTES:
+        logger.warning(
+            f"Password for {user_data.email} is longer than {BCRYPT_PASSWORD_MAX_BYTES} bytes. Truncating..."
+        )
+        # Truncate the bytes and decode safely at a character boundary
+        truncated_bytes = password_bytes[:BCRYPT_PASSWORD_MAX_BYTES]
+        while True:
+            try:
+                password = truncated_bytes.decode("utf-8")
+                break
+            except UnicodeDecodeError:
+                truncated_bytes = truncated_bytes[:-1]
+    # else password remains if within byte limit
+
+    # Create new user
+    try:
+        user = await AuthService.create_user(
+            db=db,
+            email=user_data.email,
+            password=password
+        )
+    except AttributeError as e:
+        logger.error(
+            f"User creation failed due to bcrypt or passlib error: {e}. "
+            "This is likely caused by an incompatible version of bcrypt. "
+            "Please ensure 'bcrypt' and 'passlib' are installed and up to date. "
+            "Upgrade them using: pip install --upgrade bcrypt passlib"
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Server configuration error: bcrypt module issue, please contact support."
+        )
+    except Exception as e:
+        msg = str(e)
+        if "password cannot be longer than " in msg:
+            logger.error(
+                f"User creation failed: password too long for bcrypt for {user_data.email}: {e}. Manual truncation should have prevented this."
+            )
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Password cannot be longer than {BCRYPT_PASSWORD_MAX_BYTES} bytes. Please use a shorter password."
+            )
+        logger.error(f"User creation failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create user account"
+        )
+
+    # Generate JWT token
+    token = AuthService.generate_jwt_token(user.id)
+
+    # Create session in database
+    await AuthService.create_session(db=db, user_id=user.id, token=token)
+
+    # Set HTTP-only cookie with JWT token
+    response.set_cookie(
+        key="auth_token",
+        value=token,
+        httponly=True,
+        secure=True,  # Only send over HTTPS
+        samesite="lax",  # CSRF protection
+        max_age=60 * 60 * 24 * 7  # 7 days
+    )
+
+    logger.info(f"User registered and logged in: {user.id}")
+
+    return AuthResponse(
+        user=UserResponse.model_validate(user),
+        message="Registration successful"
+    )
+
+
+@router.post(
+    "/login",
+    response_model=AuthResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Login user",
+    description="Authenticate user with email and password, create session"
+)
+async def login(
+    credentials: UserLogin,
+    response: Response,
+    db: AsyncSession = Depends(get_db_session)
+) -> AuthResponse:
+    """Authenticate user and create session
+
+    Args:
+        credentials: User login credentials (email, password)
+        response: FastAPI response object for setting cookies
+        db: Database session
+
+    Returns:
+        AuthResponse with user data and session token
+
+    Raises:
+        HTTPException: 401 if credentials are invalid
+    """
+    # Truncate password to BCRYPT_PASSWORD_MAX_BYTES for hashing (now allows larger passwords)
+    password = credentials.password
+    password_bytes = password.encode("utf-8")
+    if len(password_bytes) > BCRYPT_PASSWORD_MAX_BYTES:
+        logger.warning(
+            f"Login attempt with password longer than {BCRYPT_PASSWORD_MAX_BYTES} bytes. Truncating for bcrypt."
+        )
+        truncated_bytes = password_bytes[:BCRYPT_PASSWORD_MAX_BYTES]
+        while True:
+            try:
+                password = truncated_bytes.decode("utf-8")
+                break
+            except UnicodeDecodeError:
+                truncated_bytes = truncated_bytes[:-1]
+
+    # Authenticate user
+    try:
+        user = await AuthService.authenticate_user(
+            db=db,
+            email=credentials.email,
+            password=password
+        )
+    except AttributeError as e:
+        logger.error(
+            f"User authentication failed due to bcrypt or passlib error: {e}. "
+            "Please ensure 'bcrypt' and 'passlib' are installed and up to date."
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Server configuration error: bcrypt module issue, please contact support."
+        )
+    except Exception as e:
+        msg = str(e)
+        if "password cannot be longer than " in msg:
+            logger.error(
+                f"User authentication failed: password too long for bcrypt: {e}. Manual truncation should have prevented this."
+            )
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Password cannot be longer than {BCRYPT_PASSWORD_MAX_BYTES} bytes."
+            )
+        logger.error(f"User authentication failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Server error during authentication"
+        )
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Generate JWT token
+    token = AuthService.generate_jwt_token(user.id)
+
+    # Create session in database
+    await AuthService.create_session(db=db, user_id=user.id, token=token)
+
+    # Set HTTP-only cookie with JWT token
+    response.set_cookie(
+        key="auth_token",
+        value=token,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        max_age=60 * 60 * 24 * 7  # 7 days
+    )
+
+    logger.info(f"User logged in: {user.id}")
+
+    return AuthResponse(
+        user=UserResponse.model_validate(user),
+        message="Login successful"
+    )
+
+
+@router.post(
+    "/logout",
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Logout user",
+    description="Revoke user session and clear authentication cookie"
+)
+async def logout(
+    response: Response,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db_session)
+) -> MessageResponse:
+    """Logout user by revoking session
+
+    Args:
+        response: FastAPI response object for clearing cookies
+        current_user: Authenticated user (from middleware)
+        db: Database session
+
+    Returns:
+        MessageResponse confirming logout
+    """
+    # Get token from cookie
+    from fastapi import Request
+    # Note: We need to extract token from request, but we already have current_user
+    # so we can just delete the cookie. In production, we'd also revoke the session.
+
+    # Clear HTTP-only cookie
+    response.delete_cookie(key="auth_token", httponly=True, secure=True, samesite="lax")
+
+    logger.info(f"User logged out: {current_user.id}")
+
+    return MessageResponse(message="Logout successful")
+
+
+@router.get(
+    "/me",
+    response_model=UserResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Get current user",
+    description="Get authenticated user's profile information"
+)
+async def get_current_user_profile(
+    current_user: User = Depends(get_current_user)
+) -> UserResponse:
+    """Get current authenticated user's profile
+
+    Args:
+        current_user: Authenticated user (from middleware)
+
+    Returns:
+        UserResponse with user profile data
+    """
+    return UserResponse.model_validate(current_user)

src/api/routes/chat.py

@@ -0,0 +1,264 @@
+"""Chat message endpoints for interacting with the RAG chatbot.
+
+Provides endpoints for:
+- POST /chat/message - Send a new message to the chatbot, get a RAG-powered response
+- GET /chat/history - Get chat history for a specific thread
+- GET /chat/threads - Get a list of user's chat threads
+"""
+from typing import List, Dict, Any
+from uuid import UUID, uuid4
+import time
+import asyncio
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from openai import OpenAIError, APITimeoutError, APIConnectionError, APIStatusError
+
+from src.api.middleware.auth_middleware import get_current_user
+# from src.api.middleware.rate_limit import rate_limit_dependency
+from src.config.database import get_db_session
+from src.models.user import User
+from src.models.schemas import (
+    ChatMessageCreate,
+    ChatMessageResponse,
+    ChatResponse,
+    ChatHistoryResponse
+)
+from src.models.chat_message import ChatUserRole, ChatMessage
+from src.services.chat_service import ChatService
+from src.services.rag_service import RAGService
+from src.services.vector_service import VectorService
+from src.utils.validators import sanitize_html
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/chat", tags=["Chatbot"])
+
+
+@router.post(
+    "/message",
+    response_model=ChatResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Send message to chatbot",
+    description="Send a message to the RAG chatbot and get a response based on book content"
+)
+async def send_message(
+    chat_message_data: ChatMessageCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db_session),
+    # rate_limit_status: Dict[str, Any] = Depends(rate_limit_dependency)
+) -> ChatResponse:
+    """Send a message to the RAG chatbot.
+
+    Handles full-book queries and selected-text queries.
+    Retrieves context from Qdrant, generates response using RAG service,
+    and persists both user and assistant messages to the database.
+    """
+    start_time = time.time()
+    user_id = current_user.id
+    query_mode = chat_message_data.query_mode or "full_book"
+    user_message_content = sanitize_html(chat_message_data.message, strip=True)
+    selected_text_content = sanitize_html(chat_message_data.selected_text, strip=True) if chat_message_data.selected_text else None
+
+    # Determine thread_id: create new if not provided (simple UUID for conversation grouping)
+    thread_id = chat_message_data.thread_id if chat_message_data.thread_id else str(uuid4())
+    logger.info(f"Processing message for user {user_id}, thread {thread_id}")
+
+    # 1. Save user message to DB
+    user_message_db = await ChatService.save_message(
+        db=db,
+        user_id=user_id,
+        thread_id=thread_id,
+        role=ChatUserRole.USER,
+        content=user_message_content,
+        metadata={
+            "query_mode": query_mode,
+            "selected_text": selected_text_content
+        }
+    )
+
+    # 2 & 3. Run vector search and chat history retrieval in parallel for speed
+    try:
+        # Prepare vector search task
+        if query_mode == "selection" and not selected_text_content:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="selected_text is required for 'selection' query mode"
+            )
+
+        # Determine search parameters
+        search_text = selected_text_content if query_mode == "selection" else user_message_content
+        top_k = 3 if query_mode == "selection" else 5
+
+        # Run both operations in parallel
+        context_chunks, chat_history = await asyncio.gather(
+            VectorService.search_similar_chunks(query_text=search_text, top_k=top_k),
+            ChatService.get_chat_history(db=db, user_id=user_id, thread_id=thread_id, limit=10)
+        )
+
+        # Convert history to dict format for RAG service
+        history_dicts = [
+            {"role": msg.role, "content": msg.content}
+            for msg in reversed(chat_history)  # Reverse to chronological order
+        ]
+
+    except HTTPException:
+        raise  # Re-raise validation errors
+    except Exception as e:
+        logger.error(f"Error retrieving context or history: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve relevant book content. Please try again."
+        )
+
+    # 4. Generate response using RAG service with Agents SDK
+    try:
+        rag_response = await RAGService.generate_response(
+            user_message=user_message_content,
+            context_chunks=context_chunks,
+            chat_history=history_dicts,
+            query_mode=query_mode,
+            selected_text=selected_text_content
+        )
+        assistant_message_content = rag_response["content"]
+        chunk_ids = rag_response["chunk_ids"]
+        model_used = rag_response["model_used"]
+
+    except APIStatusError as e:
+        logger.error(f"OpenAI API error (status: {e.status_code}): {e.message}")
+        if e.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="OpenAI API rate limit exceeded. Please try again shortly."
+            )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"OpenAI API error: {e.message}"
+        )
+    except APITimeoutError as e:
+        logger.error(f"OpenAI API timeout error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+            detail="OpenAI API timed out. Please try again."
+        )
+    except APIConnectionError as e:
+        logger.error(f"OpenAI API connection error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Could not connect to OpenAI API. Please check your internet connection or try again later."
+        )
+    except Exception as e:
+        logger.error(f"Generic error from RAG service: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to generate response from chatbot. Please try again."
+        )
+
+    # Calculate response time
+    response_time_ms = int((time.time() - start_time) * 1000)
+
+    # 5. Save assistant message to DB
+    assistant_message_db = await ChatService.save_message(
+        db=db,
+        user_id=user_id,
+        thread_id=thread_id,
+        role=ChatUserRole.ASSISTANT,
+        content=assistant_message_content,
+        metadata={
+            "query_mode": query_mode,
+            "selected_text_context": selected_text_content if query_mode == "selection" else None,
+            "chunk_ids": chunk_ids,
+            "model_used": model_used,
+            "response_time_ms": response_time_ms
+        }
+    )
+
+    logger.info(f"Chat response generated for user {user_id} in thread {thread_id} ({response_time_ms}ms)")
+
+    return ChatResponse(
+        user_message=ChatMessageResponse.model_validate(user_message_db),
+        assistant_message=ChatMessageResponse.model_validate(assistant_message_db),
+        thread_id=thread_id
+    )
+
+
+@router.get(
+    "/history",
+    response_model=ChatHistoryResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Get chat history",
+    description="Retrieve paginated chat message history for a specific thread"
+)
+async def get_chat_history(
+    thread_id: str,
+    limit: int = 50,
+    offset: int = 0,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db_session)
+) -> ChatHistoryResponse:
+    """Retrieve chat history for a specific thread.
+
+    Args:
+        thread_id: The ID of the conversation thread.
+        limit: The maximum number of messages to return.
+        offset: The number of messages to skip for pagination.
+        current_user: The authenticated user.
+        db: The database session.
+
+    Returns:
+        ChatHistoryResponse containing messages and total count.
+    """
+    user_id = current_user.id
+
+    messages_db = await ChatService.get_chat_history(
+        db=db,
+        user_id=user_id,
+        thread_id=thread_id,
+        limit=limit,
+        offset=offset
+    )
+
+    # Convert to Pydantic models
+    messages_response = [ChatMessageResponse.model_validate(msg) for msg in messages_db]
+
+    # Get total count for pagination metadata
+    total_messages = await db.scalar(
+        select(func.count(ChatMessage.id))
+        .where(ChatMessage.user_id == user_id, ChatMessage.thread_id == thread_id)
+    )
+
+    logger.info(f"Retrieved chat history for user {user_id}, thread {thread_id}")
+
+    return ChatHistoryResponse(
+        messages=messages_response,
+        total=total_messages if total_messages is not None else 0,
+        thread_id=thread_id
+    )
+
+
+@router.get(
+    "/threads",
+    response_model=List[Dict[str, Any]],
+    status_code=status.HTTP_200_OK,
+    summary="Get user chat threads",
+    description="Retrieve a list of all chat threads for the authenticated user"
+)
+async def get_user_chat_threads(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db_session)
+) -> List[Dict[str, Any]]:
+    """Retrieve a list of chat threads for the authenticated user.
+
+    Args:
+        current_user: The authenticated user.
+        db: The database session.
+
+    Returns:
+        A list of dictionaries, each representing a thread summary.
+    """
+    user_id = current_user.id
+    threads = await ChatService.get_user_threads(db=db, user_id=user_id)
+    logger.info(f"Retrieved {len(threads)} chat threads for user {user_id}")
+    return threads

src/api/routes/health.py

@@ -0,0 +1,73 @@
+"""Health check endpoint
+
+Provides health status for the application and its dependencies.
+"""
+from fastapi import APIRouter, status
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Dict, Any
+
+from sqlalchemy import text
+
+from src.config.database import get_engine, get_qdrant_client
+from src.config.settings import settings
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter(tags=["health"])
+
+
+class HealthResponse(BaseModel):
+    """Health check response model"""
+    status: str
+    timestamp: str
+    environment: str
+    dependencies: Dict[str, str]
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Health Check",
+    description="Check the health status of the application and its dependencies"
+)
+async def health_check() -> HealthResponse:
+    """Perform health check on application and dependencies
+
+    Returns:
+        HealthResponse with status and dependency information
+    """
+    dependencies: Dict[str, str] = {}
+
+    # Check database connection
+    try:
+        engine = get_engine()
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        dependencies["database"] = "healthy"
+    except Exception as e:
+        logger.error(f"Database health check failed: {e}")
+        dependencies["database"] = "unhealthy"
+
+    # Check Qdrant connection
+    try:
+        client = get_qdrant_client()
+        await client.get_collections()
+        dependencies["qdrant"] = "healthy"
+    except Exception as e:
+        logger.error(f"Qdrant health check failed: {e}")
+        dependencies["qdrant"] = "unhealthy"
+
+    # Overall status
+    overall_status = "healthy" if all(
+        dep_status == "healthy" for dep_status in dependencies.values()
+    ) else "degraded"
+
+    return HealthResponse(
+        status=overall_status,
+        timestamp=datetime.utcnow().isoformat(),
+        environment=settings.environment,
+        dependencies=dependencies
+    )

src/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration package"""

src/config/database.py

@@ -0,0 +1,152 @@
+"""Database and vector store configuration
+
+Provides async database engine, session management, and Qdrant client setup.
+"""
+from typing import AsyncGenerator
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    create_async_engine,
+    async_sessionmaker,
+)
+from sqlalchemy.orm import declarative_base
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import Distance, VectorParams
+
+from src.config.settings import settings
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# SQLAlchemy Base for models
+Base = declarative_base()
+
+# Global engine instance
+_engine: AsyncEngine | None = None
+
+# Global session maker
+_async_session_maker: async_sessionmaker[AsyncSession] | None = None
+
+# Global Qdrant client
+_qdrant_client: AsyncQdrantClient | None = None
+
+
+def get_engine() -> AsyncEngine:
+    """Get or create the async database engine
+
+    Returns:
+        AsyncEngine instance
+    """
+    global _engine
+
+    if _engine is None:
+        # AsyncPG connection arguments for SSL
+        connect_args = {}
+        if "neon.tech" in settings.database_url or settings.is_production:
+            # Enable SSL for Neon and production databases
+            connect_args["ssl"] = "require"
+
+        _engine = create_async_engine(
+            settings.async_database_url,
+            echo=not settings.is_production,  # Log SQL in development
+            pool_pre_ping=True,  # Verify connections before using
+            pool_size=5,
+            max_overflow=10,
+            connect_args=connect_args,
+        )
+        logger.info("Database engine created")
+
+    return _engine
+
+
+def get_session_maker() -> async_sessionmaker[AsyncSession]:
+    """Get or create the async session maker
+
+    Returns:
+        async_sessionmaker instance
+    """
+    global _async_session_maker
+
+    if _async_session_maker is None:
+        engine = get_engine()
+        _async_session_maker = async_sessionmaker(
+            engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+        logger.info("Session maker created")
+
+    return _async_session_maker
+
+
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    """Dependency for getting async database sessions
+
+    Yields:
+        AsyncSession instance
+    """
+    session_maker = get_session_maker()
+    async with session_maker() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+
+def get_qdrant_client() -> AsyncQdrantClient:
+    """Get or create the Qdrant client
+
+    Returns:
+        AsyncQdrantClient instance
+    """
+    global _qdrant_client
+
+    if _qdrant_client is None:
+        _qdrant_client = AsyncQdrantClient(
+            url=settings.qdrant_url,
+            api_key=settings.qdrant_api_key,
+            timeout=30.0,
+        )
+        logger.info("Qdrant client created")
+
+    return _qdrant_client
+
+
+async def init_qdrant_collection() -> None:
+    """Initialize Qdrant collection if it doesn't exist
+
+    Creates the collection with appropriate vector configuration.
+    """
+    client = get_qdrant_client()
+
+    # Check if collection exists
+    collections = await client.get_collections()
+    collection_names = [col.name for col in collections.collections]
+
+    if settings.qdrant_collection_name not in collection_names:
+        # Create collection with vector configuration
+        await client.create_collection(
+            collection_name=settings.qdrant_collection_name,
+            vectors_config=VectorParams(
+                size=settings.vector_size,
+                distance=Distance.COSINE,
+            ),
+        )
+        logger.info(f"Created Qdrant collection: {settings.qdrant_collection_name}")
+    else:
+        logger.info(f"Qdrant collection already exists: {settings.qdrant_collection_name}")
+
+
+async def close_database_connections() -> None:
+    """Close all database connections gracefully"""
+    global _engine, _qdrant_client
+
+    if _engine is not None:
+        await _engine.dispose()
+        logger.info("Database engine disposed")
+        _engine = None
+
+    if _qdrant_client is not None:
+        await _qdrant_client.close()
+        logger.info("Qdrant client closed")
+        _qdrant_client = None

src/config/settings.py

@@ -0,0 +1,103 @@
+"""Application settings and configuration
+
+Loads environment variables and provides type-safe configuration.
+"""
+from typing import List, Union, Optional
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from openai import AsyncOpenAI
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables"""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+
+    # Database
+    database_url: str
+
+    # Qdrant Vector Database
+    qdrant_url: str
+    qdrant_api_key: str
+    qdrant_collection_name: str = "humanoid-robotics-book-v1"
+    vector_size: int = 1536  # OpenAI text-embedding-3-small dimension
+
+    # OpenAI
+    openai_api_key: str
+    openai_embedding_model: str = "text-embedding-3-small"
+    chat_model: str = "gpt-4o-mini"  # Fast, cost-effective model for chat (was gpt-4-turbo-preview)
+
+    # Authentication
+    better_auth_secret: str
+    session_expiry_days: int = 7
+
+    # Rate Limiting
+    rate_limit_per_minute: int = 20
+    redis_url: str = "redis://localhost:6379"
+
+    # CORS
+    allowed_origins: Union[str, List[str]] = "http://localhost:3000,http://localhost:8000"
+
+    # Application
+    environment: str = "development"
+    log_level: str = "INFO"
+
+    @field_validator("allowed_origins", mode="before")
+    @classmethod
+    def parse_cors_origins(cls, v):
+        """Parse CORS origins from comma-separated string or list"""
+        if isinstance(v, str):
+            return [origin.strip() for origin in v.split(",")]
+        return v
+
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production environment"""
+        return self.environment.lower() == "production"
+
+    @property
+    def async_database_url(self) -> str:
+        """Get async database URL for SQLAlchemy
+
+        Converts postgresql:// to postgresql+asyncpg:// and removes sslmode and
+        channel_binding parameters since asyncpg uses different SSL configuration.
+        """
+        url = self.database_url
+
+        # Replace postgresql:// with postgresql+asyncpg://
+        if url.startswith("postgresql://"):
+            url = url.replace("postgresql://", "postgresql+asyncpg://", 1)
+
+        # Remove sslmode and channel_binding parameters that asyncpg doesn't support
+        # asyncpg will handle SSL automatically
+        if "sslmode=" in url or "channel_binding=" in url:
+            from urllib.parse import urlparse, parse_qs, urlencode, urlunparse
+            parsed = urlparse(url)
+            query_params = parse_qs(parsed.query)
+            # Remove sslmode and channel_binding
+            query_params.pop('sslmode', None)
+            query_params.pop('channel_binding', None)
+            # Reconstruct the query string
+            new_query = urlencode(query_params, doseq=True)
+            url = urlunparse((
+                parsed.scheme,
+                parsed.netloc,
+                parsed.path,
+                parsed.params,
+                new_query,
+                parsed.fragment
+            ))
+
+        return url
+
+
+# Global settings instance
+settings = Settings()
+
+# Global OpenAI client instance (only if API key is provided)
+openai_client = AsyncOpenAI(api_key=settings.openai_api_key) if settings.openai_api_key else None

src/main.py

@@ -0,0 +1,191 @@
+"""FastAPI application entry point
+
+Main application setup with middleware, CORS, and route configuration.
+"""
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+# Temporarily disabled for debugging
+from secure import Secure
+
+# Secure middleware configuration
+# Temporarily disabled for debugging
+secure_headers = Secure()
+from fastapi.responses import JSONResponse
+# Temporarily disabled for debugging
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+from src.config.settings import settings
+from src.config.database import init_qdrant_collection, close_database_connections
+from src.utils.logger import setup_logging, get_logger
+from src.api.routes import health, auth, chat
+
+# Setup logging
+setup_logging(
+    level=settings.log_level,
+    use_json=settings.is_production
+)
+
+logger = get_logger(__name__)
+
+
+# Rate limiter configuration (using the one from rate_limit middleware)
+# limiter = Limiter(
+#     key_func=get_remote_address,
+#     default_limits=[f"{settings.rate_limit_per_minute}/minute"]
+# )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan manager
+
+    Handles startup and shutdown events.
+    """
+    # Startup
+    logger.info("Starting up application...")
+    logger.info(f"Environment: {settings.environment}")
+
+    # Initialize Qdrant collection
+    try:
+        await init_qdrant_collection()
+    except Exception as e:
+        logger.error(f"Failed to initialize Qdrant collection: {e}")
+
+    logger.info("Application startup complete")
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down application...")
+    await close_database_connections()
+    logger.info("Application shutdown complete")
+
+
+# Create FastAPI application
+app = FastAPI(
+    title="RAG Chatbot API",
+    description="Retrieval-Augmented Generation chatbot for humanoid robotics textbook",
+    version="1.0.0",
+    docs_url="/api/docs" if not settings.is_production else None,
+    redoc_url="/api/redoc" if not settings.is_production else None,
+    lifespan=lifespan
+)
+
+# Temporarily disabled for debugging
+from src.api.middleware.logging_middleware import LoggingMiddleware
+from src.api.middleware.rate_limit import limiter, rate_limit_exceeded_handler
+
+# Add rate limiter to app state
+# Temporarily disabled for debugging
+# app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, rate_limit_exceeded_handler)
+
+# Add logging middleware
+# Temporarily disabled due to middleware stack build error
+app.add_middleware(LoggingMiddleware)
+
+# Add secure headers middleware
+# Temporarily disabled for debugging
+@app.middleware("http")
+async def secure_headers_middleware(request: Request, call_next):
+    response = await call_next(request)
+
+    try:
+        # If the Secure instance exposes an integration helper named "framework"
+        # that supports FastAPI/Starlette, use it.
+        if getattr(secure_headers, "framework", None) is not None:
+            fw = secure_headers.framework
+            # defensive: some versions expose attributes differently
+            if hasattr(fw, "fastapi"):
+                fw.fastapi(response)
+            elif hasattr(fw, "starlette"):
+                fw.starlette(response)
+            else:
+                # fallback to a generic method if one exists
+                if hasattr(secure_headers, "apply"):
+                    secure_headers.apply(response)
+                elif hasattr(secure_headers, "add"):
+                    secure_headers.add(response)
+                else:
+                    raise AttributeError("Secure instance has no recognized integration methods")
+        else:
+            # library not integrated or missing; apply safe default headers manually
+            # These are conservative, common security headers.
+            response.headers.setdefault("X-Content-Type-Options", "nosniff")
+            response.headers.setdefault("X-Frame-Options", "DENY")
+            response.headers.setdefault("Referrer-Policy", "no-referrer")
+            response.headers.setdefault("Strict-Transport-Security", "max-age=63072000; includeSubDomains; preload")
+            response.headers.setdefault("Permissions-Policy", "geolocation=()")
+            response.headers.setdefault("X-XSS-Protection", "1; mode=block")
+    except Exception:
+        # log the failure but do not crash the request pipeline
+        logger.exception("Failed to apply secure headers")
+
+    return response
+
+# CORS middleware configuration
+# Temporarily disabled for debugging
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["*"],
+    expose_headers=["X-Request-ID"],
+)
+
+
+# Exception handlers
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Global exception handler for unhandled errors
+
+    Args:
+        request: FastAPI request
+        exc: Exception that was raised
+
+    Returns:
+        JSONResponse with error details
+    """
+    logger.error(
+        f"Unhandled exception: {exc}",
+        extra={
+            "path": request.url.path,
+            "method": request.method,
+            "client": request.client.host if request.client else "unknown"
+        }
+    )
+
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal server error",
+            "message": "An unexpected error occurred" if settings.is_production else str(exc)
+        }
+    )
+
+
+# Include routers
+app.include_router(health.router, prefix="/api")
+app.include_router(auth.router, prefix="/api")
+app.include_router(chat.router, prefix="/api")
+
+
+# Root endpoint
+@app.get("/", tags=["root"])
+async def root() -> dict[str, str]:
+    """Root endpoint
+
+    Returns:
+        Welcome message
+    """
+    return {
+        "message": "RAG Chatbot API",
+        "status": "running",
+        "docs": "/api/docs" if not settings.is_production else "disabled"
+    }

src/models/__init__.py

@@ -0,0 +1,6 @@
+"""Database models package"""
+from src.models.user import User
+from src.models.session import Session
+from src.models.chat_message import ChatMessage
+
+__all__ = ["User", "Session", "ChatMessage"]

src/models/chat_message.py

@@ -0,0 +1,55 @@
+"""Chat message model for storing conversation history
+
+Represents a single question-answer exchange in the chatbot.
+Aligns with data-model.md ChatMessage entity specification.
+"""
+from datetime import datetime
+from uuid import UUID, uuid4
+from enum import Enum
+
+from sqlalchemy import Column, String, Text, TIMESTAMP, ForeignKey, text
+from sqlalchemy.dialects.postgresql import UUID as PGUUID, JSONB
+from sqlalchemy.orm import relationship
+
+from src.config.database import Base
+
+
+class ChatUserRole(str, Enum):
+    """Enum for the role of the chat message sender."""
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+class ChatMessage(Base):
+    """ChatMessage model for storing conversation history
+
+    Attributes:
+        id: Unique message identifier (UUID)
+        user_id: Foreign key to User
+        thread_id: OpenAI Agents SDK thread identifier
+        role: Message sender (user or assistant)
+        content: Message text content
+        metadata: Additional context (JSONB)
+        created_at: Message creation timestamp
+    """
+
+    __tablename__ = "chat_messages"
+
+    id = Column(
+        PGUUID(as_uuid=True),
+        primary_key=True,
+        default=uuid4,
+        server_default="gen_random_uuid()"
+    )
+    user_id = Column(PGUUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    thread_id = Column(String(255), nullable=False)
+    role = Column(String(10), nullable=False) # CHECK (role IN ('user', 'assistant')) will be added in migration
+    content = Column(Text, nullable=False)
+    message_metadata = Column('metadata', JSONB, default=dict, server_default=text("'{}'::jsonb"), nullable=False)
+    created_at = Column(TIMESTAMP, nullable=False, default=datetime.utcnow, server_default="NOW()")
+
+    # Relationships
+    user = relationship("User", back_populates="chat_messages")
+
+    def __repr__(self) -> str:
+        return f"<ChatMessage(id={self.id}, role={self.role}, thread_id={self.thread_id})>"

src/models/schemas.py

@@ -0,0 +1,143 @@
+"""Pydantic schemas for request/response validation
+
+Provides type-safe data validation for API endpoints.
+"""
+from datetime import datetime
+from uuid import UUID
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, EmailStr, Field, field_validator
+
+
+# ============================================================================
+# User Schemas
+# ============================================================================
+
+class UserCreate(BaseModel):
+    """Schema for user registration request"""
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., min_length=8, max_length=128, description="User's password")
+
+    @field_validator("password")
+    @classmethod
+    def validate_password_strength(cls, v: str) -> str:
+        """Validate password meets strength requirements"""
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain at least one uppercase letter")
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain at least one lowercase letter")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain at least one digit")
+        if not any(c in "!@#$%^&*(),.?\":{}|<>" for c in v):
+            raise ValueError("Password must contain at least one special character")
+        return v
+
+
+class UserLogin(BaseModel):
+    """Schema for user login request"""
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., min_length=1, max_length=128, description="User's password")
+
+
+class UserResponse(BaseModel):
+    """Schema for user data in responses"""
+    id: UUID
+    email: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class AuthResponse(BaseModel):
+    """Schema for authentication response"""
+    user: UserResponse
+    message: str = "Authentication successful"
+
+
+# ============================================================================
+# Session Schemas
+# ============================================================================
+
+class SessionResponse(BaseModel):
+    """Schema for session data in responses"""
+    id: UUID
+    user_id: UUID
+    expires_at: datetime
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+# ============================================================================
+# Chat Message Schemas
+# ============================================================================
+
+class ChatMessageCreate(BaseModel):
+    """Schema for creating a new chat message"""
+    message: str = Field(..., min_length=1, max_length=10000, description="User's message content")
+    thread_id: Optional[str] = Field(None, min_length=1, max_length=255, description="OpenAI thread ID, optional for new threads")
+    query_mode: Optional[str] = Field(None, description="Query mode: 'full_book' or 'selection'")
+    selected_text: Optional[str] = Field(None, max_length=5000, description="Selected text for context queries")
+
+    @field_validator("query_mode")
+    @classmethod
+    def validate_query_mode(cls, v: Optional[str]) -> Optional[str]:
+        """Validate query mode is one of allowed values"""
+        if v is not None and v not in ["full_book", "selection"]:
+            raise ValueError("query_mode must be 'full_book' or 'selection'")
+        return v
+
+    @field_validator("selected_text")
+    @classmethod
+    def validate_selected_text(cls, v: Optional[str], info: Any) -> Optional[str]:
+        """Validate selected_text is present when query_mode is 'selection'"""
+        if info.data.get("query_mode") == "selection" and not v:
+            raise ValueError("selected_text is required when query_mode is 'selection'")
+        return v
+
+
+class ChatMessageResponse(BaseModel):
+    """Schema for chat message in responses"""
+    id: UUID
+    user_id: UUID
+    thread_id: str
+    role: str
+    content: str
+    metadata: Dict[str, Any] = Field(..., alias="message_metadata") # Use alias for Pydantic V2
+    created_at: datetime
+
+    model_config = {
+        "from_attributes": True,
+        "populate_by_name": True,
+    }
+
+
+
+class ChatResponse(BaseModel):
+    """Schema for chat response with user and assistant messages"""
+    user_message: ChatMessageResponse
+    assistant_message: ChatMessageResponse
+    thread_id: str
+
+
+class ChatHistoryResponse(BaseModel):
+    """Schema for thread history response"""
+    messages: list[ChatMessageResponse]
+    total: int
+    thread_id: str
+
+
+# ============================================================================
+# Generic Response Schemas
+# ============================================================================
+
+class MessageResponse(BaseModel):
+    """Generic message response"""
+    message: str
+
+
+class ErrorResponse(BaseModel):
+    """Error response schema"""
+    error: str
+    message: str
+    details: Optional[Dict[str, Any]] = None

src/models/session.py

@@ -0,0 +1,53 @@
+"""Session model for authentication token management
+
+Represents an active authentication session with JWT tokens and expiration.
+Aligns with data-model.md Session entity specification.
+"""
+from datetime import datetime
+from uuid import UUID, uuid4
+from sqlalchemy import Column, String, TIMESTAMP, ForeignKey
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import relationship
+
+from src.config.database import Base
+
+
+class Session(Base):
+    """Session model for JWT token management
+
+    Attributes:
+        id: Unique session identifier (UUID)
+        user_id: Foreign key to User
+        token_hash: Hashed JWT token (unique)
+        expires_at: Session expiration timestamp
+        created_at: Session creation timestamp
+    """
+
+    __tablename__ = "sessions"
+
+    id = Column(
+        PGUUID(as_uuid=True),
+        primary_key=True,
+        default=uuid4,
+        server_default="gen_random_uuid()"
+    )
+    user_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    token_hash = Column(String(255), unique=True, nullable=False, index=True)
+    expires_at = Column(TIMESTAMP, nullable=False, index=True)
+    created_at = Column(TIMESTAMP, nullable=False, default=datetime.utcnow, server_default="NOW()")
+
+    # Relationships
+    user = relationship("User", back_populates="sessions")
+
+    def __repr__(self) -> str:
+        return f"<Session(id={self.id}, user_id={self.user_id}, expires_at={self.expires_at})>"
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if session has expired"""
+        return datetime.utcnow() > self.expires_at

src/models/user.py

@@ -0,0 +1,44 @@
+"""User model for authentication and authorization
+
+Represents an authenticated reader with account credentials.
+Aligns with data-model.md User entity specification.
+"""
+from datetime import datetime
+from uuid import UUID, uuid4
+from sqlalchemy import Column, String, TIMESTAMP
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import relationship
+
+from src.config.database import Base
+
+
+class User(Base):
+    """User model for authentication
+
+    Attributes:
+        id: Unique user identifier (UUID)
+        email: User's email address (unique)
+        password_hash: Hashed password (managed by auth service)
+        created_at: Account creation timestamp
+        updated_at: Last account modification timestamp
+    """
+
+    __tablename__ = "users"
+
+    id = Column(
+        PGUUID(as_uuid=True),
+        primary_key=True,
+        default=uuid4,
+        server_default="gen_random_uuid()"
+    )
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    password_hash = Column(String(255), nullable=False)
+    created_at = Column(TIMESTAMP, nullable=False, default=datetime.utcnow, server_default="NOW()")
+    updated_at = Column(TIMESTAMP, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow, server_default="NOW()")
+
+    # Relationships
+    sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
+    chat_messages = relationship("ChatMessage", back_populates="user", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:
+        return f"<User(id={self.id}, email={self.email})>"

src/services/__init__.py

@@ -0,0 +1,6 @@
+"""Services package"""
+from src.services.auth_service import AuthService
+from src.services.vector_service import VectorService
+from src.services.chat_service import ChatService
+
+__all__ = ["AuthService", "VectorService", "ChatService"]

src/services/auth_service.py

@@ -0,0 +1,312 @@
+"""Authentication service for user management and session handling
+
+Provides user registration, authentication, password hashing,
+JWT token generation, and session management.
+"""
+from datetime import datetime, timedelta
+from typing import Optional
+from uuid import UUID
+import hashlib
+from passlib.context import CryptContext
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, delete
+
+from src.models.user import User
+from src.models.session import Session
+from src.config.settings import settings
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Password hashing configuration
+# Using Argon2 (modern, memory-hard algorithm) with bcrypt fallback for existing passwords
+pwd_context = CryptContext(schemes=["argon2", "bcrypt"], deprecated="auto")
+
+# JWT configuration
+ALGORITHM = "HS256"
+
+
+class AuthService:
+    """Authentication service for user and session management"""
+
+    @staticmethod
+    def hash_password(password: str) -> str:
+        """Hash a plain text password using Argon2
+
+        Args:
+            password: Plain text password (no length limitations with Argon2)
+
+        Returns:
+            Hashed password
+        """
+        # Argon2 is a modern, memory-hard hashing algorithm with no password length limits
+        return pwd_context.hash(password, scheme="argon2")
+
+    @staticmethod
+    def verify_password(plain_password: str, hashed_password: str) -> bool:
+        """Verify a password against its hash
+
+        Args:
+            plain_password: Plain text password to verify
+            hashed_password: Hashed password to compare against
+
+        Returns:
+            True if password matches, False otherwise
+        """
+        # Passlib automatically handles both Argon2 and bcrypt hashes
+        # Works with the hash that was used (supports password migration)
+        return pwd_context.verify(plain_password, hashed_password)
+
+    @staticmethod
+    def generate_jwt_token(user_id: UUID) -> str:
+        """Generate a JWT token for a user
+
+        Args:
+            user_id: User's UUID
+
+        Returns:
+            JWT token string
+        """
+        expires_delta = timedelta(days=settings.session_expiry_days)
+        expire = datetime.utcnow() + expires_delta
+
+        to_encode = {
+            "sub": str(user_id),
+            "exp": expire,
+            "iat": datetime.utcnow()
+        }
+
+        encoded_jwt = jwt.encode(
+            to_encode,
+            settings.better_auth_secret,
+            algorithm=ALGORITHM
+        )
+        return encoded_jwt
+
+    @staticmethod
+    def decode_jwt_token(token: str) -> Optional[dict]:
+        """Decode and validate a JWT token
+
+        Args:
+            token: JWT token string
+
+        Returns:
+            Decoded token payload or None if invalid
+        """
+        try:
+            payload = jwt.decode(
+                token,
+                settings.better_auth_secret,
+                algorithms=[ALGORITHM]
+            )
+            return payload
+        except JWTError as e:
+            logger.warning(f"JWT decode error: {e}")
+            return None
+
+    @staticmethod
+    def hash_token(token: str) -> str:
+        """Create SHA-256 hash of a token for storage
+
+        Args:
+            token: Token to hash
+
+        Returns:
+            Hex digest of token hash
+        """
+        return hashlib.sha256(token.encode()).hexdigest()
+
+    @staticmethod
+    async def create_user(
+        db: AsyncSession,
+        email: str,
+        password: str
+    ) -> User:
+        """Create a new user account
+
+        Args:
+            db: Database session
+            email: User's email address
+            password: Plain text password
+
+        Returns:
+            Created User instance
+        """
+        password_hash = AuthService.hash_password(password)
+
+        user = User(
+            email=email.lower(),  # Normalize email to lowercase
+            password_hash=password_hash
+        )
+
+        db.add(user)
+        await db.commit()
+        await db.refresh(user)
+
+        logger.info(f"User created: {user.id}")
+        return user
+
+    @staticmethod
+    async def authenticate_user(
+        db: AsyncSession,
+        email: str,
+        password: str
+    ) -> Optional[User]:
+        """Authenticate a user by email and password
+
+        Args:
+            db: Database session
+            email: User's email address
+            password: Plain text password
+
+        Returns:
+            User instance if authenticated, None otherwise
+        """
+        # Query user by email
+        result = await db.execute(
+            select(User).where(User.email == email.lower())
+        )
+        user = result.scalar_one_or_none()
+
+        if user is None:
+            logger.warning(f"Authentication failed: user not found for email {email}")
+            return None
+
+        if not AuthService.verify_password(password, user.password_hash):
+            logger.warning(f"Authentication failed: invalid password for user {user.id}")
+            return None
+
+        logger.info(f"User authenticated: {user.id}")
+        return user
+
+    @staticmethod
+    async def create_session(
+        db: AsyncSession,
+        user_id: UUID,
+        token: str
+    ) -> Session:
+        """Create a new session for a user
+
+        Args:
+            db: Database session
+            user_id: User's UUID
+            token: JWT token string
+
+        Returns:
+            Created Session instance
+        """
+        token_hash = AuthService.hash_token(token)
+        expires_at = datetime.utcnow() + timedelta(days=settings.session_expiry_days)
+
+        session = Session(
+            user_id=user_id,
+            token_hash=token_hash,
+            expires_at=expires_at
+        )
+
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+
+        logger.info(f"Session created: {session.id} for user {user_id}")
+        return session
+
+    @staticmethod
+    async def validate_session(
+        db: AsyncSession,
+        token: str
+    ) -> Optional[Session]:
+        """Validate a session token
+
+        Args:
+            db: Database session
+            token: JWT token string
+
+        Returns:
+            Session instance if valid, None otherwise
+        """
+        token_hash = AuthService.hash_token(token)
+
+        # Query session by token hash
+        result = await db.execute(
+            select(Session).where(Session.token_hash == token_hash)
+        )
+        session = result.scalar_one_or_none()
+
+        if session is None:
+            logger.warning("Session validation failed: session not found")
+            return None
+
+        if session.is_expired:
+            logger.warning(f"Session validation failed: session {session.id} expired")
+            return None
+
+        return session
+
+    @staticmethod
+    async def revoke_session(
+        db: AsyncSession,
+        token: str
+    ) -> bool:
+        """Revoke a session by token
+
+        Args:
+            db: Database session
+            token: JWT token string
+
+        Returns:
+            True if session was revoked, False otherwise
+        """
+        token_hash = AuthService.hash_token(token)
+
+        result = await db.execute(
+            delete(Session).where(Session.token_hash == token_hash)
+        )
+        await db.commit()
+
+        revoked = result.rowcount > 0
+        if revoked:
+            logger.info(f"Session revoked for token hash {token_hash[:16]}...")
+
+        return revoked
+
+    @staticmethod
+    async def cleanup_expired_sessions(db: AsyncSession) -> int:
+        """Remove all expired sessions from database
+
+        Args:
+            db: Database session
+
+        Returns:
+            Number of sessions deleted
+        """
+        result = await db.execute(
+            delete(Session).where(Session.expires_at < datetime.utcnow())
+        )
+        await db.commit()
+
+        count = result.rowcount
+        if count > 0:
+            logger.info(f"Cleaned up {count} expired sessions")
+
+        return count
+
+    @staticmethod
+    async def get_user_by_id(
+        db: AsyncSession,
+        user_id: UUID
+    ) -> Optional[User]:
+        """Get a user by ID
+
+        Args:
+            db: Database session
+            user_id: User's UUID
+
+        Returns:
+            User instance if found, None otherwise
+        """
+        result = await db.execute(
+            select(User).where(User.id == user_id)
+        )
+        return result.scalar_one_or_none()