V1

.env.example

@@ -0,0 +1,43 @@
+# SanjeevaniAI Configuration Environment Variables
+
+# Application
+APP_ENV=development
+APP_NAME=SanjeevaniAI
+APP_VERSION=1.0.0
+DEBUG=True
+HOST=0.0.0.0
+PORT=8000
+
+# Security (Generate a secure secret key for production)
+SECRET_KEY=sanjeevani-ai-secret-key-change-in-production-secure-random-2026
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+REFRESH_TOKEN_EXPIRE_DAYS=7
+
+# CORS
+CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
+
+# Database
+# Default: SQLite async database for development. For PostgreSQL use:
+# DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/sanjeevani_db
+DATABASE_URL=sqlite+aiosqlite:///./sanjeevani.db
+
+# Redis & Cache (Optional / Docker)
+REDIS_URL=redis://localhost:6379/0
+
+# Biomedical ML Models
+NER_MODEL_PATH=D:/SanjeevaniAI/models/bc5cdr-ner
+DEVICE=auto
+
+# LLM Providers (mock, gemini, openai)
+LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-gemini-api-key-here
+OPENAI_API_KEY=
+
+# Document Storage & Limits
+UPLOAD_DIR=./uploads
+MAX_UPLOAD_SIZE_MB=25
+ALLOWED_EXTENSIONS=["pdf","txt","docx"]
+
+# Rate Limiting
+RATE_LIMIT_PER_MINUTE=60

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: SanjeevaniAI CI Pipeline
+
+on:
+  push:
+    branches: [ main, master, develop ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  backend-tests:
+    name: Backend Pytest & Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install Python Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run Backend Pytest Suite
+        run: |
+          pytest backend/tests -v --durations=10
+
+  frontend-build:
+    name: Frontend Typecheck & Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: frontend/package.json
+
+      - name: Install Frontend Dependencies
+        working-directory: ./frontend
+        run: npm ci
+
+      - name: Next.js Typecheck & Production Build
+        working-directory: ./frontend
+        run: npm run build

.gitignore

@@ -0,0 +1,52 @@
+# Python & Virtual Environments
+.venv/
+venv/
+env/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.log
+
+# Sensitive Credentials
+.env
+.env.local
+.env.*.local
+
+# Database & Uploads
+*.db
+sanjeevani.db
+uploads/*
+!uploads/.gitkeep
+
+# Large Pretrained ML Model Weights (>100MB exceeds GitHub push limit)
+# Note: Cloud deployment automatically fetches 'tner/roberta-large-bc5cdr' from HuggingFace
+models/
+models/*
+!models/.gitkeep
+checkpoints/
+checkpoints/*
+datasets/
+datasets/*
+
+# Legacy Prototype Folders
+app/
+clinical_engine/
+evaluation/
+rag/
+training/
+
+# Node.js & Next.js Frontend
+frontend/node_modules/
+frontend/.next/
+frontend/.vercel/
+frontend/out/
+frontend/npm-debug.log*
+frontend/yarn-debug.log*
+frontend/yarn-error.log*
+
+# IDE & OS Files
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

README.md

@@ -1,77 +1,142 @@
-# Sanjeevani AI
-### Voice-first, multilingual polypharmacy safety companion
-**PHARMINNO QUEST 2026 — Karpagam Academy of Higher Education**
-
-## The problem
-Millions of Indians — especially elderly and chronic-disease patients — take
-medicines prescribed by multiple doctors with no single check for dangerous
-drug interactions, wrong dosing, or duplicate therapy. Existing digital
-health apps are built for literate, English-speaking, single-language users,
-which leaves out exactly the people most at risk.
-
-## The solution
-Sanjeevani AI lets a patient or caregiver add every medicine they're taking
-(by typing or by scanning the strip), cross-checks the full list against a
-curated clinical drug-interaction database, and explains any risk in plain
-language — with voice support — in **English, Hindi, and Tamil**. It also
-builds an icon-based daily schedule for low-literacy users and gives
-pharmacists/caregivers a one-screen summary for counselling.
-
-## Running it
-No install, no build step, no server required.
-
-1. Open `index.html` directly in any modern browser (Chrome, Edge, Firefox,
-   Safari) — double-click it or drag it into a browser tab.
-2. Pick a language, enter a patient name, and start adding medicines.
-3. Try adding **Ramipril** and **Spironolactone** together to see a real
-   "severe" interaction alert, or try the fuzzy search with a typo like
-   "amlong" or "dolo".
-
-Optional: serving it over a local server (e.g. `python3 -m http.server`)
-also works and additionally enables the offline service worker cache.
-
-## What's implemented
-- **Fuzzy medicine search** (Levenshtein-based) — tolerant of typos, OCR
-  noise, and partial names; matches generic names, common Indian brand
-  names, and Hindi/Tamil names.
-- **On-device OCR strip scan** via Tesseract.js (loaded from CDN when
-  online) — snap/upload a photo of a medicine strip and it's matched
-  automatically; degrades gracefully to manual search if offline.
-- **Interaction rule engine** — 16 curated, real drug-pair interactions
-  (e.g. Warfarin+Aspirin, Ramipril+Spironolactone, Sildenafil+Isosorbide)
-  across three severity levels, each with a plain-language explanation and
-  recommendation, in three languages.
-- **Icon-based daily schedule** — groups medicines into morning / afternoon
-  / night with before/after-food tags, designed to be readable without
-  fluent literacy.
-- **Voice reminders** — uses the browser's built-in Web Speech API
-  (`speechSynthesis`), no external API or cost.
-- **Pharmacist / caregiver dashboard** — a printable one-screen summary of
-  all medicines and flagged interactions for counselling.
-- **Offline-first** — a service worker caches the app shell after first
-  load; all clinical data ships as plain JS (`data/drugs.js`,
-  `data/interactions.js`), so the app works with zero connectivity and no
-  backend.
-
-## Project structure
+# SanjeevaniAI — Industry-Grade Healthcare AI Platform
+
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688?style=flat&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.2+-EE4C2C?style=flat&logo=pytorch&logoColor=white)](https://pytorch.org)
+[![HuggingFace](https://img.shields.io/badge/Model-RoBERTa--large--BC5CDR-FFD21E?style=flat&logo=huggingface&logoColor=black)](https://huggingface.co/tner/roberta-large-bc5cdr)
+[![Next.js](https://img.shields.io/badge/Next.js-14.2+-000000?style=flat&logo=next.js&logoColor=white)](https://nextjs.org)
+[![TailwindCSS](https://img.shields.io/badge/TailwindCSS-3.4+-38B2AC?style=flat&logo=tailwind-css&logoColor=white)](https://tailwindcss.com)
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat&logo=docker&logoColor=white)](https://www.docker.com)
+[![Tests](https://img.shields.io/badge/Tests-16%2F16%20Passing-brightgreen?style=flat&logo=pytest&logoColor=white)](backend/tests)
+
+> **Clinical Notice & Positioning**: SanjeevaniAI provides **AI-assisted healthcare information and clinical decision-support insights**. It is **not an autonomous diagnostic system** and is not a substitute for direct clinical examination, laboratory diagnosis, or emergency medical care.
+
+---
+
+## 🏥 Architecture Overview
+
 ```
-index.html              Main app shell (all screens)
-css/style.css            Styling (brand palette matches the pitch deck)
-js/app.js                 App logic, screen routing, rendering
-js/i18n.js                 English / Hindi / Tamil UI strings
-js/interactionEngine.js     Fuzzy search + interaction rule engine
-data/drugs.js               30-drug catalog (generic, brands, hi/ta names)
-data/interactions.js         16 curated drug-pair interaction rules
-manifest.json              PWA manifest
-sw.js                        Offline service worker
+SanjeevaniAI Platform
+├── Frontend (Next.js 14 + Tailwind CSS + Lucide Icons)
+│   ├── /                -> Landing page with medical disclaimer & capabilities
+│   ├── /dashboard       -> Clinical intelligence overview & metrics
+│   ├── /ner             -> Real-time local RoBERTa BC5CDR NER visualizer
+│   ├── /reports         -> Document upload, SHA-256 integrity & analysis
+│   ├── /reports/[id]    -> Structured clinical findings & raw text
+│   ├── /assistant       -> Conversational AI with emergency triage
+│   ├── /profile         -> Patient physiological profile & BMI
+│   ├── /history         -> Traceable medical timeline
+│   ├── /admin           -> System telemetry & security audit logs
+│   └── /demo            -> Guided 5-step mentor presentation walkthrough
+│
+├── Backend (FastAPI + Async SQLAlchemy + PyTorch)
+│   ├── Core & Security  -> JWT, bcrypt hashing, RBAC, Request ID, CSP headers
+│   ├── ML Engine        -> Local RoBERTa-large BC5CDR (355M params, CUDA/CPU)
+│   ├── Document Pipeline-> PDF/DOCX/TXT parser, chunker, entity aggregator
+│   ├── AI Assistant     -> Multi-provider LLM (Gemini + Mock) & triage engine
+│   └── Persistence      -> Async SQLite / PostgreSQL with audit trail
 ```
 
-## Important note
-This is a hackathon prototype. The drug and interaction data is a small,
-hand-curated demo set for illustration — **not** a complete or clinically
-validated database, and the app is not a substitute for a pharmacist or
-doctor. A production version would need a licensed pharmacist to maintain
-and expand the interaction database against authoritative references.
+---
+
+## ⚡ Quick Start
+
+### 1. Prerequisites
+- **Python**: 3.10+ (Recommended: Python 3.11)
+- **Node.js**: 18.x or 20+ (with npm)
+- **NVIDIA GPU (Optional)**: CUDA 11.8+ for accelerated inference (CPU fallback automatic)
+- **Pretrained NER Model**: Stored locally in `models/bc5cdr-ner`
+
+### 2. Backend Setup
+```bash
+# Activate virtual environment
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1  # Windows PowerShell
+# source .venv/bin/activate    # Linux / macOS
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run synthetic demo database seeder
+python scripts/seed_demo_data.py
+
+# Launch FastAPI backend
+uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+*API Swagger UI will be live at `http://localhost:8000/docs`.*
+
+### 3. Frontend Setup
+```bash
+cd frontend
+
+# Install npm dependencies
+npm install
+
+# Run Next.js development server
+npm run dev
+```
+*Application UI will be live at `http://localhost:3000`.*
+
+---
+
+## 🐳 Docker Deployment
+
+To launch the full containerized stack:
+```bash
+docker-compose up --build
+```
+- Frontend: `http://localhost:3000`
+- Backend API: `http://localhost:8000`
+- Health Check: `http://localhost:8000/api/v1/health`
+
+---
+
+## 🧪 Test Suite & Verification
+
+The platform includes a comprehensive automated test suite in `backend/tests/`:
+
+```bash
+pytest backend/tests -v
+```
+
+### Verified Test Results (16/16 Passing):
+- `test_auth.py`: User registration, login, JWT validation, and invalid credential handling.
+- `test_ner.py`: BC5CDR model info, entity extraction, character span alignment, and 422 validation.
+- `test_documents.py`: File upload, SHA-256 fingerprinting, raw text extraction, and entity linking.
+- `test_chat.py`: Multi-turn consultation, patient profile injection, and heuristic red-flag emergency detection.
+- `test_profile.py`: Patient profile updates, vitals calculations, and RBAC admin permission enforcement.
+- `test_health.py`: Liveness and readiness probes.
+
+---
+
+## 👨‍🏫 Mentor Demonstration Credentials
+
+Use the **"Demo Roles"** dropdown in the navigation bar or log in with these pre-seeded accounts:
+
+| Account | Email | Password | Role / Access Level |
+| :--- | :--- | :--- | :--- |
+| **Patient** | `demo.patient@sanjeevani.ai` | `DemoPatient2026!` | Health profile, documents, AI consultation |
+| **Doctor** | `demo.doctor@sanjeevani.ai` | `DemoDoctor2026!` | Clinical decision support & document review |
+| **Administrator** | `demo.admin@sanjeevani.ai` | `DemoAdmin2026!` | Platform telemetry, model status, security audit logs |
+
+---
+
+## 📚 Technical Documentation
+
+- 📐 [**System Architecture & Mermaid Diagrams**](docs/ARCHITECTURE.md)
+- 🔌 [**REST API Catalog & OpenAPI Specification**](docs/API.md)
+- 🧠 [**Machine Learning & Local RoBERTa BC5CDR Specs**](docs/ML_MODELS.md)
+- 🎯 [**10-Minute Mentor Presentation Script**](docs/MENTOR_DEMO.md)
+- 🔍 [**Initial Project Audit & Gap Analysis**](docs/PROJECT_AUDIT.md)
+
+---
+
+## 🛡️ Medical Safety & Privacy Disclaimers
+
+1. **AI-Assisted Decision Support**: SanjeevaniAI generates educational insights to assist healthcare providers and patients. It does not issue binding clinical diagnoses or prescribe treatment plans.
+2. **Emergency Triage Protocol**: If severe acute symptoms (e.g. crushing chest pain, difficulty breathing, stroke symptoms) are entered, the platform immediately presents an emergency escalation alert advising immediate contact with emergency medical services (911 / 112 / 108).
+3. **Data Security**: Uploaded files are fingerprinted with SHA-256, sensitive credentials hashed with direct bcrypt, and all administrative events logged in an immutable audit table.
+
+---
 
-## Team
-Monochrome— PHARMINNO QUEST 2026
+## 📄 License
+MIT License. Developed for healthcare AI intelligence and clinical decision-support research.

backend/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /app
+
+# Install system dependencies (build-essential, curl)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python requirements
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application source
+COPY backend /app/backend
+COPY models /app/models
+COPY uploads /app/uploads
+
+# Expose port
+EXPOSE 8000
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/api/v1/health || exit 1
+
+# Run Uvicorn
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/api/deps.py

@@ -0,0 +1,61 @@
+from typing import Generator, Optional, List
+from fastapi import Depends, HTTPException, status, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.core.security import decode_token, UserRole
+from backend.app.core.exceptions import AuthenticationError, PermissionDeniedError
+from backend.app.repositories.user_repo import UserRepository
+from backend.app.models.user import User
+
+security_scheme = HTTPBearer(auto_error=False)
+
+
+async def get_current_user(
+    token_auth: Optional[HTTPAuthorizationCredentials] = Depends(security_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    if not token_auth or not token_auth.credentials:
+        raise AuthenticationError(message="Authentication token missing.")
+
+    payload = decode_token(token_auth.credentials)
+    if not payload or payload.get("type") != "access":
+        raise AuthenticationError(message="Invalid or expired access token.")
+
+    user_id = payload.get("sub")
+    if not user_id:
+        raise AuthenticationError(message="Token missing subject identifier.")
+
+    user_repo = UserRepository(db)
+    user = await user_repo.get_by_id(user_id)
+    if not user:
+        raise AuthenticationError(message="User no longer exists.")
+
+    if not user.is_active:
+        raise AuthenticationError(message="User account is deactivated.")
+
+    return user
+
+
+def require_roles(allowed_roles: List[UserRole]):
+    async def role_checker(current_user: User = Depends(get_current_user)) -> User:
+        user_role = current_user.role
+        role_values = [r.value for r in allowed_roles]
+        if user_role not in role_values and user_role != UserRole.ADMIN.value:
+            raise PermissionDeniedError(message="You do not have permission to access this resource.")
+        return current_user
+
+    return role_checker
+
+
+async def get_current_admin(current_user: User = Depends(get_current_user)) -> User:
+    if current_user.role != UserRole.ADMIN.value:
+        raise PermissionDeniedError(message="Administrative privileges required.")
+    return current_user
+
+
+def get_client_ip(request: Request) -> Optional[str]:
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else None

backend/app/api/v1/endpoints/admin.py

@@ -0,0 +1,47 @@
+from typing import List
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.admin import AdminStatsResponse, AuditLogResponse
+from backend.app.schemas.common import BaseResponse
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.ml.manager import model_manager
+from backend.app.api.deps import get_current_admin
+from backend.app.models.user import User
+
+router = APIRouter()
+
+
+@router.get("/stats", response_model=BaseResponse[AdminStatsResponse])
+async def get_admin_stats(
+    current_admin: User = Depends(get_current_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retrieve platform usage statistics, throughput metrics, and model status."""
+    audit_repo = AuditRepository(db)
+    stats = await audit_repo.get_system_statistics()
+    model_status = model_manager.get_status()
+
+    admin_stats = AdminStatsResponse(
+        total_users=stats["total_users"],
+        active_users=stats["active_users"],
+        total_documents_processed=stats["total_documents_processed"],
+        total_ner_requests=stats["total_ner_requests"],
+        total_chat_queries=stats["total_chat_queries"],
+        model_status=model_status,
+        system_health="Operational",
+    )
+    return BaseResponse(success=True, data=admin_stats)
+
+
+@router.get("/audit-logs", response_model=BaseResponse[List[AuditLogResponse]])
+async def get_audit_logs(
+    limit: int = 100,
+    current_admin: User = Depends(get_current_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retrieve system security and access audit trail."""
+    audit_repo = AuditRepository(db)
+    logs = await audit_repo.get_admin_audit_logs(limit=limit)
+    response_list = [AuditLogResponse.model_validate(log) for log in logs]
+    return BaseResponse(success=True, data=response_list)

backend/app/api/v1/endpoints/auth.py

@@ -0,0 +1,72 @@
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.user import UserCreate, UserLogin, UserResponse
+from backend.app.schemas.token import TokenResponse, RefreshTokenRequest
+from backend.app.schemas.common import BaseResponse
+from backend.app.services.auth_service import AuthService
+from backend.app.api.deps import get_current_user, get_client_ip
+from backend.app.models.user import User
+
+router = APIRouter()
+
+
+@router.post("/register", response_model=BaseResponse[TokenResponse])
+async def register(
+    user_in: UserCreate,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+):
+    """Register a new user and receive initial access/refresh tokens."""
+    ip = get_client_ip(request)
+    auth_service = AuthService(db)
+    user, tokens = await auth_service.register(user_in, ip_address=ip)
+    return BaseResponse(
+        success=True,
+        message="User registered successfully.",
+        data=tokens,
+    )
+
+
+@router.post("/login", response_model=BaseResponse[TokenResponse])
+async def login(
+    login_in: UserLogin,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+):
+    """Authenticate with email and password to receive JWT credentials."""
+    ip = get_client_ip(request)
+    agent = request.headers.get("User-Agent")
+    auth_service = AuthService(db)
+    tokens = await auth_service.login(login_in, ip_address=ip, user_agent=agent)
+    return BaseResponse(
+        success=True,
+        message="Login successful.",
+        data=tokens,
+    )
+
+
+@router.post("/refresh", response_model=BaseResponse[TokenResponse])
+async def refresh_token(
+    refresh_in: RefreshTokenRequest,
+    db: AsyncSession = Depends(get_db),
+):
+    """Exchange a valid refresh token for a new access/refresh token pair."""
+    auth_service = AuthService(db)
+    tokens = await auth_service.refresh_tokens(refresh_in.refresh_token)
+    return BaseResponse(
+        success=True,
+        message="Token refreshed successfully.",
+        data=tokens,
+    )
+
+
+@router.get("/me", response_model=BaseResponse[UserResponse])
+async def get_me(
+    current_user: User = Depends(get_current_user),
+):
+    """Retrieve the currently authenticated user's profile metadata."""
+    return BaseResponse(
+        success=True,
+        data=UserResponse.model_validate(current_user),
+    )

backend/app/api/v1/endpoints/chat.py

@@ -0,0 +1,209 @@
+import json
+from typing import List
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.chat import (
+    ChatMessageCreate,
+    ChatMessageResponse,
+    ConversationResponse,
+    ChatCompletionResponse,
+    AIStructuredOutput,
+)
+from backend.app.schemas.common import BaseResponse, MEDICAL_DISCLAIMER
+from backend.app.models.conversation import AIConversation, AIMessage
+from backend.app.models.user import User
+from backend.app.repositories.chat_repo import ChatRepository
+from backend.app.repositories.user_repo import UserRepository
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.services.llm.service import llm_service
+from backend.app.api.deps import get_current_user
+from backend.app.core.exceptions import ResourceNotFoundError
+
+router = APIRouter()
+
+
+def _format_message(msg: AIMessage) -> ChatMessageResponse:
+    structured = None
+    if msg.structured_data:
+        try:
+            parsed = json.loads(msg.structured_data)
+            structured = AIStructuredOutput(**parsed)
+        except Exception:
+            pass
+
+    return ChatMessageResponse(
+        id=msg.id,
+        conversation_id=msg.conversation_id,
+        role=msg.role,
+        content=msg.content,
+        structured_data=structured,
+        model_provider=msg.model_provider,
+        created_at=msg.created_at,
+    )
+
+
+@router.post("/message", response_model=BaseResponse[ChatCompletionResponse])
+async def send_chat_message(
+    chat_in: ChatMessageCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    Send a medical query to the AI Assistant.
+    Generates structured healthcare decision-support insights, recommendations, and emergency triage alerts.
+    """
+    chat_repo = ChatRepository(db)
+    user_repo = UserRepository(db)
+    audit_repo = AuditRepository(db)
+
+    # 1. Resolve or Create Conversation
+    history_messages = []
+    if chat_in.conversation_id:
+        conversation = await chat_repo.get_conversation_with_messages(
+            chat_in.conversation_id, current_user.id
+        )
+        if conversation:
+            history_messages = conversation.messages or []
+        else:
+            conversation = AIConversation(
+                id=chat_in.conversation_id,
+                user_id=current_user.id,
+                title=chat_in.message[:45] + ("..." if len(chat_in.message) > 45 else ""),
+            )
+            conversation = await chat_repo.create(conversation)
+    else:
+        title_snippet = chat_in.message[:45] + ("..." if len(chat_in.message) > 45 else "")
+        conversation = AIConversation(
+            user_id=current_user.id,
+            title=title_snippet or "Medical Consultation",
+        )
+        conversation = await chat_repo.create(conversation)
+
+    # 2. Save User Message
+    user_msg = AIMessage(
+        conversation_id=conversation.id,
+        role="user",
+        content=chat_in.message,
+    )
+    await chat_repo.add_message(user_msg)
+
+    # 3. Retrieve Patient Health Profile Context
+    patient_context = {}
+    profile = await user_repo.get_profile_by_user_id(current_user.id)
+    if profile:
+        patient_context = {
+            "age": profile.age,
+            "gender": profile.gender,
+            "blood_group": profile.blood_group,
+            "known_allergies": json.loads(profile.known_allergies) if profile.known_allergies else [],
+            "chronic_conditions": json.loads(profile.chronic_conditions) if profile.chronic_conditions else [],
+            "current_medications": json.loads(profile.current_medications) if profile.current_medications else [],
+        }
+
+    # 4. Format Chat History
+    history = [
+        {"role": m.role, "content": m.content}
+        for m in history_messages[-6:]
+    ]
+
+    # 5. Execute LLM Consultation
+    structured_output, provider_name = await llm_service.consult(
+        query=chat_in.message,
+        chat_history=history,
+        patient_context=patient_context,
+    )
+
+    # 6. Save Assistant Response
+    assistant_msg = AIMessage(
+        conversation_id=conversation.id,
+        role="assistant",
+        content=structured_output.summary,
+        structured_data=json.dumps(structured_output.model_dump()),
+        model_provider=provider_name,
+    )
+    saved_assistant_msg = await chat_repo.add_message(assistant_msg)
+
+    # 7. Add Audit & Timeline
+    await audit_repo.add_history(
+        user_id=current_user.id,
+        action_type="CHAT",
+        description=f"Consulted AI Assistant: '{chat_in.message[:40]}...'",
+        reference_id=conversation.id,
+    )
+
+    return BaseResponse(
+        success=True,
+        data=ChatCompletionResponse(
+            conversation_id=conversation.id,
+            message=_format_message(saved_assistant_msg),
+            disclaimer=MEDICAL_DISCLAIMER,
+        ),
+    )
+
+
+@router.get("/conversations", response_model=BaseResponse[List[ConversationResponse]])
+async def list_conversations(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retrieve all historical AI consultation threads for the current user."""
+    chat_repo = ChatRepository(db)
+    convs = await chat_repo.get_user_conversations(current_user.id)
+    response_list = [
+        ConversationResponse(
+            id=c.id,
+            user_id=c.user_id,
+            title=c.title,
+            messages=[_format_message(m) for m in (c.messages or [])],
+            created_at=c.created_at,
+            updated_at=c.updated_at,
+        )
+        for c in convs
+    ]
+    return BaseResponse(success=True, data=response_list)
+
+
+@router.get("/conversations/{conversation_id}", response_model=BaseResponse[ConversationResponse])
+async def get_conversation(
+    conversation_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Fetch complete message history for a specific conversation."""
+    chat_repo = ChatRepository(db)
+    c = await chat_repo.get_conversation_with_messages(conversation_id, current_user.id)
+    if not c:
+        raise ResourceNotFoundError(resource="Conversation", resource_id=conversation_id)
+
+    return BaseResponse(
+        success=True,
+        data=ConversationResponse(
+            id=c.id,
+            user_id=c.user_id,
+            title=c.title,
+            messages=[_format_message(m) for m in (c.messages or [])],
+            created_at=c.created_at,
+            updated_at=c.updated_at,
+        ),
+    )
+
+
+@router.delete("/conversations/{conversation_id}", response_model=BaseResponse[dict])
+async def delete_conversation(
+    conversation_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a conversation thread and its message history."""
+    chat_repo = ChatRepository(db)
+    conv = await chat_repo.get_conversation_with_messages(conversation_id, current_user.id)
+    if not conv:
+        raise ResourceNotFoundError(resource="Conversation", resource_id=conversation_id)
+
+    await chat_repo.delete(conversation_id)
+    return BaseResponse(
+        success=True,
+        message="Conversation deleted.",
+        data={"deleted_id": conversation_id},
+    )

backend/app/api/v1/endpoints/documents.py

@@ -0,0 +1,139 @@
+import json
+from typing import List
+from fastapi import APIRouter, Depends, UploadFile, File, Request, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.document import MedicalDocumentResponse, DocumentAnalysisResponse, DocumentUploadResponse
+from backend.app.schemas.ner import NEREntity
+from backend.app.schemas.common import BaseResponse
+from backend.app.services.document_service import DocumentService
+from backend.app.repositories.document_repo import DocumentRepository
+from backend.app.api.deps import get_current_user, get_client_ip
+from backend.app.models.user import User
+from backend.app.models.document import MedicalDocument
+from backend.app.core.exceptions import ResourceNotFoundError, PermissionDeniedError
+
+router = APIRouter()
+
+
+def _format_document_response(doc: MedicalDocument) -> MedicalDocumentResponse:
+    analysis_resp = None
+    if doc.analysis:
+        analysis = doc.analysis
+        findings = json.loads(analysis.important_findings) if analysis.important_findings else []
+        conditions = json.loads(analysis.detected_conditions) if analysis.detected_conditions else []
+        medications = json.loads(analysis.detected_medications) if analysis.detected_medications else []
+
+        entities = [
+            NEREntity(
+                text=e.text,
+                label=e.label,
+                start=e.start_offset,
+                end=e.end_offset,
+                confidence=e.confidence,
+                model=e.model_name,
+            )
+            for e in (analysis.entities or [])
+        ]
+
+        analysis_resp = DocumentAnalysisResponse(
+            id=analysis.id,
+            document_id=analysis.document_id,
+            raw_text=analysis.raw_text,
+            cleaned_text=analysis.cleaned_text,
+            summary=analysis.summary,
+            important_findings=findings,
+            detected_conditions=conditions,
+            detected_medications=medications,
+            clinical_recommendations=analysis.clinical_recommendations,
+            entities=entities,
+            processed_at=analysis.processed_at,
+        )
+
+    return MedicalDocumentResponse(
+        id=doc.id,
+        user_id=doc.user_id,
+        filename=doc.filename,
+        original_filename=doc.original_filename,
+        file_type=doc.file_type,
+        file_size=doc.file_size,
+        status=doc.status,
+        error_message=doc.error_message,
+        analysis=analysis_resp,
+        created_at=doc.created_at,
+        updated_at=doc.updated_at,
+    )
+
+
+@router.post("/upload", response_model=BaseResponse[MedicalDocumentResponse])
+async def upload_medical_document(
+    request: Request,
+    file: UploadFile = File(...),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    Securely upload a medical report (PDF, DOCX, TXT), perform text extraction,
+    biomedical entity recognition, and clinical summarization.
+    """
+    ip = get_client_ip(request)
+    doc_service = DocumentService(db)
+    doc = await doc_service.process_document_upload(file=file, user_id=current_user.id, ip_address=ip)
+    formatted = _format_document_response(doc)
+    return BaseResponse(
+        success=True,
+        message="Document uploaded and analyzed successfully.",
+        data=formatted,
+    )
+
+
+@router.get("", response_model=BaseResponse[List[MedicalDocumentResponse]])
+async def list_documents(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retrieve all medical reports and document analyses uploaded by the current user."""
+    doc_repo = DocumentRepository(db)
+    docs = await doc_repo.get_user_documents(current_user.id)
+    formatted_docs = [_format_document_response(d) for d in docs]
+    return BaseResponse(
+        success=True,
+        data=formatted_docs,
+    )
+
+
+@router.get("/{document_id}", response_model=BaseResponse[MedicalDocumentResponse])
+async def get_document(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Fetch detailed analysis, extracted entities, and summary for a specific document."""
+    doc_repo = DocumentRepository(db)
+    doc = await doc_repo.get_document_details(document_id, user_id=current_user.id)
+    if not doc:
+        raise ResourceNotFoundError(resource="Medical Document", resource_id=document_id)
+    return BaseResponse(
+        success=True,
+        data=_format_document_response(doc),
+    )
+
+
+@router.delete("/{document_id}", response_model=BaseResponse[dict])
+async def delete_document(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a medical report and all associated entity analysis records."""
+    doc_repo = DocumentRepository(db)
+    doc = await doc_repo.get_document_details(document_id, user_id=current_user.id)
+    if not doc:
+        raise ResourceNotFoundError(resource="Medical Document", resource_id=document_id)
+
+    await doc_repo.delete(document_id)
+    return BaseResponse(
+        success=True,
+        message="Document deleted successfully.",
+        data={"deleted_id": document_id},
+    )

backend/app/api/v1/endpoints/health.py

@@ -0,0 +1,43 @@
+from datetime import datetime, timezone
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import text
+from backend.app.core.database import get_db
+from backend.app.core.config import settings
+from backend.app.ml.manager import model_manager
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health_check():
+    """Liveness probe: verifies basic service responsiveness."""
+    return {
+        "status": "healthy",
+        "app": settings.APP_NAME,
+        "version": settings.APP_VERSION,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+@router.get("/ready")
+async def readiness_check(db: AsyncSession = Depends(get_db)):
+    """Readiness probe: checks database connectivity and local ML model availability."""
+    db_ok = False
+    try:
+        await db.execute(text("SELECT 1"))
+        db_ok = True
+    except Exception:
+        db_ok = False
+
+    model_status = model_manager.get_status()
+    models_ok = model_status.get("initialized", False)
+
+    is_ready = db_ok
+
+    return {
+        "status": "ready" if is_ready else "degraded",
+        "database": "connected" if db_ok else "disconnected",
+        "models": model_status,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }

backend/app/api/v1/endpoints/history.py

@@ -0,0 +1,26 @@
+from typing import List
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.admin import AnalysisHistoryResponse
+from backend.app.schemas.common import BaseResponse
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.api.deps import get_current_user
+from backend.app.models.user import User
+
+router = APIRouter()
+
+
+@router.get("", response_model=BaseResponse[List[AnalysisHistoryResponse]])
+async def get_user_history(
+    limit: int = 50,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retrieve chronological medical and activity history for the current user."""
+    audit_repo = AuditRepository(db)
+    records = await audit_repo.get_user_history(current_user.id, limit=limit)
+    response_list = [
+        AnalysisHistoryResponse.model_validate(r) for r in records
+    ]
+    return BaseResponse(success=True, data=response_list)

backend/app/api/v1/endpoints/ner.py

@@ -0,0 +1,55 @@
+import uuid
+from typing import Optional
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.ner import NERRequest, NERResponse, ModelInfo
+from backend.app.schemas.common import BaseResponse
+from backend.app.ml.manager import model_manager
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.api.deps import security_scheme, get_client_ip
+from backend.app.core.security import decode_token
+
+router = APIRouter()
+
+
+@router.post("/analyze", response_model=NERResponse)
+async def analyze_biomedical_ner(
+    request_body: NERRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    Perform Named Entity Recognition using the locally loaded RoBERTa-large BC5CDR model.
+    Extracts CHEMICAL (medications/drugs) and DISEASE (medical conditions) entities with character offsets and confidence scores.
+    """
+    req_id = str(uuid.uuid4())
+    ner_service = model_manager.get_ner_service()
+    result = ner_service.analyze_text(request_body, request_id=req_id)
+
+    # If an authenticated user made the request, record in history
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        token = auth_header.split(" ")[1]
+        payload = decode_token(token)
+        if payload and payload.get("sub"):
+            audit_repo = AuditRepository(db)
+            await audit_repo.add_history(
+                user_id=payload["sub"],
+                action_type="NER",
+                description=f"Analyzed text ({len(request_body.text)} chars)",
+                entity_count=result.entity_count,
+            )
+
+    return result
+
+
+@router.get("/model-info", response_model=BaseResponse[ModelInfo])
+async def get_model_info():
+    """Retrieve metadata and runtime status of the local biomedical NER model."""
+    ner_service = model_manager.get_ner_service()
+    info = ner_service.model.get_info()
+    return BaseResponse(
+        success=True,
+        data=info,
+    )

backend/app/api/v1/endpoints/profile.py

@@ -0,0 +1,89 @@
+import json
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.core.database import get_db
+from backend.app.schemas.profile import PatientProfileUpdate, PatientProfileResponse
+from backend.app.schemas.common import BaseResponse
+from backend.app.repositories.user_repo import UserRepository
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.models.profile import PatientProfile
+from backend.app.models.user import User
+from backend.app.api.deps import get_current_user
+
+router = APIRouter()
+
+
+def _format_profile(profile: PatientProfile) -> PatientProfileResponse:
+    allergies = json.loads(profile.known_allergies) if profile.known_allergies else []
+    conditions = json.loads(profile.chronic_conditions) if profile.chronic_conditions else []
+    meds = json.loads(profile.current_medications) if profile.current_medications else []
+
+    return PatientProfileResponse(
+        id=profile.id,
+        user_id=profile.user_id,
+        age=profile.age,
+        gender=profile.gender,
+        blood_group=profile.blood_group,
+        height_cm=profile.height_cm,
+        weight_kg=profile.weight_kg,
+        known_allergies=allergies,
+        chronic_conditions=conditions,
+        current_medications=meds,
+        emergency_contact=profile.emergency_contact,
+        created_at=profile.created_at,
+        updated_at=profile.updated_at,
+    )
+
+
+@router.get("", response_model=BaseResponse[PatientProfileResponse])
+async def get_patient_profile(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Fetch the patient health profile for the current user."""
+    user_repo = UserRepository(db)
+    profile = await user_repo.get_profile_by_user_id(current_user.id)
+    if not profile:
+        profile = PatientProfile(user_id=current_user.id)
+        profile = await user_repo.save_profile(profile)
+
+    return BaseResponse(success=True, data=_format_profile(profile))
+
+
+@router.put("", response_model=BaseResponse[PatientProfileResponse])
+async def update_patient_profile(
+    profile_in: PatientProfileUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update patient health information, allergies, chronic conditions, and medications."""
+    user_repo = UserRepository(db)
+    audit_repo = AuditRepository(db)
+    profile = await user_repo.get_profile_by_user_id(current_user.id)
+
+    if not profile:
+        profile = PatientProfile(user_id=current_user.id)
+
+    profile.age = profile_in.age
+    profile.gender = profile_in.gender
+    profile.blood_group = profile_in.blood_group
+    profile.height_cm = profile_in.height_cm
+    profile.weight_kg = profile_in.weight_kg
+    profile.known_allergies = json.dumps(profile_in.known_allergies or [])
+    profile.chronic_conditions = json.dumps(profile_in.chronic_conditions or [])
+    profile.current_medications = json.dumps(profile_in.current_medications or [])
+    profile.emergency_contact = profile_in.emergency_contact
+
+    saved_profile = await user_repo.save_profile(profile)
+
+    await audit_repo.add_history(
+        user_id=current_user.id,
+        action_type="PROFILE_UPDATE",
+        description="Updated patient health profile",
+    )
+
+    return BaseResponse(
+        success=True,
+        message="Patient health profile updated successfully.",
+        data=_format_profile(saved_profile),
+    )

backend/app/api/v1/router.py

@@ -0,0 +1,22 @@
+from fastapi import APIRouter
+from backend.app.api.v1.endpoints import (
+    auth,
+    ner,
+    documents,
+    chat,
+    profile,
+    history,
+    admin,
+    health,
+)
+
+api_router = APIRouter()
+
+api_router.include_router(auth.router, prefix="/auth", tags=["Authentication"])
+api_router.include_router(ner.router, prefix="/ner", tags=["Biomedical NER"])
+api_router.include_router(documents.router, prefix="/documents", tags=["Medical Documents"])
+api_router.include_router(chat.router, prefix="/chat", tags=["AI Medical Assistant"])
+api_router.include_router(profile.router, prefix="/profile", tags=["Patient Profile"])
+api_router.include_router(history.router, prefix="/history", tags=["Medical History"])
+api_router.include_router(admin.router, prefix="/admin", tags=["Admin & Monitoring"])
+api_router.include_router(health.router, tags=["Health & Observability"])

backend/app/core/config.py

@@ -0,0 +1,68 @@
+from typing import List, Union
+from pydantic import AnyHttpUrl, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parents[3]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=str(BASE_DIR / ".env"),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    APP_ENV: str = "development"
+    APP_NAME: str = "SanjeevaniAI"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = True
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+
+    # Security
+    SECRET_KEY: str = "sanjeevani-ai-super-secret-key-change-in-production"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 120
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+
+    # CORS
+    CORS_ORIGINS: List[str] = [
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+        "http://localhost:8000",
+    ]
+
+    @field_validator("CORS_ORIGINS", mode="before")
+    def assemble_cors_origins(cls, v: Union[str, List[str]]) -> List[str]:
+        if isinstance(v, str) and not v.startswith("["):
+            return [i.strip() for i in v.split(",")]
+        elif isinstance(v, (list, str)):
+            return v
+        raise ValueError(v)
+
+    # Database
+    DATABASE_URL: str = f"sqlite+aiosqlite:///{BASE_DIR / 'sanjeevani.db'}"
+
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # ML Models
+    NER_MODEL_PATH: str = str(BASE_DIR / "models" / "bc5cdr-ner")
+    DEVICE: str = "auto"
+
+    # LLM Providers
+    LLM_PROVIDER: str = "mock"  # "gemini", "openai", "mock"
+    GEMINI_API_KEY: str = ""
+    OPENAI_API_KEY: str = ""
+
+    # Document Storage
+    UPLOAD_DIR: str = str(BASE_DIR / "uploads")
+    MAX_UPLOAD_SIZE_MB: int = 25
+    ALLOWED_EXTENSIONS: List[str] = ["pdf", "txt", "docx"]
+
+    # Rate Limiting
+    RATE_LIMIT_PER_MINUTE: int = 60
+
+
+settings = Settings()

backend/app/core/database.py

@@ -0,0 +1,53 @@
+from typing import AsyncGenerator
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+from sqlalchemy.orm import declarative_base
+from backend.app.core.config import settings
+from backend.app.core.logger import logger
+
+# Build engine with appropriate connect_args depending on SQLite or PostgreSQL
+connect_args = {}
+engine_kwargs = {"echo": False, "future": True}
+
+if settings.DATABASE_URL.startswith("sqlite"):
+    connect_args["check_same_thread"] = False
+else:
+    engine_kwargs.update({
+        "pool_size": 10,
+        "max_overflow": 20,
+        "pool_pre_ping": True,
+    })
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    connect_args=connect_args,
+    **engine_kwargs,
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autocommit=False,
+    autoflush=False,
+)
+
+Base = declarative_base()
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        except Exception as ex:
+            await session.rollback()
+            logger.error(f"Database session error: {ex}")
+            raise
+        finally:
+            await session.close()
+
+
+async def init_db() -> None:
+    """Initialize database tables for development/testing."""
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    logger.info("Database schema initialized.")

backend/app/core/exceptions.py

@@ -0,0 +1,82 @@
+from typing import Any, Optional, Dict
+from fastapi import HTTPException, status
+
+
+class SanjeevaniException(HTTPException):
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        super().__init__(
+            status_code=status_code,
+            detail={"code": code, "message": message, "details": details},
+            headers=headers,
+        )
+        self.code = code
+        self.message = message
+        self.details = details
+
+
+class AuthenticationError(SanjeevaniException):
+    def __init__(self, message: str = "Invalid credentials", details: Optional[Any] = None):
+        super().__init__(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            code="AUTHENTICATION_FAILED",
+            message=message,
+            details=details,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+class PermissionDeniedError(SanjeevaniException):
+    def __init__(self, message: str = "Access forbidden", details: Optional[Any] = None):
+        super().__init__(
+            status_code=status.HTTP_403_FORBIDDEN,
+            code="PERMISSION_DENIED",
+            message=message,
+            details=details,
+        )
+
+
+class ResourceNotFoundError(SanjeevaniException):
+    def __init__(self, resource: str, resource_id: Any = None):
+        msg = f"{resource} not found" if not resource_id else f"{resource} with ID '{resource_id}' not found"
+        super().__init__(
+            status_code=status.HTTP_404_NOT_FOUND,
+            code="RESOURCE_NOT_FOUND",
+            message=msg,
+        )
+
+
+class ValidationError(SanjeevaniException):
+    def __init__(self, message: str = "Validation failed", details: Optional[Any] = None):
+        super().__init__(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            code="VALIDATION_ERROR",
+            message=message,
+            details=details,
+        )
+
+
+class MLModelError(SanjeevaniException):
+    def __init__(self, message: str = "ML inference failed", details: Optional[Any] = None):
+        super().__init__(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            code="ML_MODEL_ERROR",
+            message=message,
+            details=details,
+        )
+
+
+class DocumentProcessingError(SanjeevaniException):
+    def __init__(self, message: str = "Failed to process document", details: Optional[Any] = None):
+        super().__init__(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            code="DOCUMENT_PROCESSING_FAILED",
+            message=message,
+            details=details,
+        )

backend/app/core/logger.py

@@ -0,0 +1,45 @@
+import logging
+import sys
+import json
+from datetime import datetime, timezone
+from backend.app.core.config import settings
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        log_obj = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "line": record.lineno,
+        }
+        if hasattr(record, "request_id"):
+            log_obj["request_id"] = record.request_id
+        if record.exc_info:
+            log_obj["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_obj)
+
+
+def setup_logger(name: str = "sanjeevani") -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG if settings.DEBUG else logging.INFO)
+
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        if settings.APP_ENV == "production":
+            handler.setFormatter(JsonFormatter())
+        else:
+            handler.setFormatter(
+                logging.Formatter(
+                    "[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
+                    datefmt="%Y-%m-%d %H:%M:%S",
+                )
+            )
+        logger.addHandler(handler)
+
+    return logger
+
+
+logger = setup_logger()

backend/app/core/security.py

@@ -0,0 +1,82 @@
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional, Union
+import bcrypt
+from jose import jwt, JWTError
+import enum
+from backend.app.core.config import settings
+
+
+class UserRole(str, enum.Enum):
+    USER = "USER"
+    PATIENT = "PATIENT"
+    DOCTOR = "DOCTOR"
+    ADMIN = "ADMIN"
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    try:
+        pwd_bytes = plain_password.encode("utf-8")[:72]
+        hash_bytes = hashed_password.encode("utf-8")
+        return bcrypt.checkpw(pwd_bytes, hash_bytes)
+    except Exception:
+        return False
+
+
+def get_password_hash(password: str) -> str:
+    pwd_bytes = password.encode("utf-8")[:72]
+    salt = bcrypt.gensalt()
+    return bcrypt.hashpw(pwd_bytes, salt).decode("utf-8")
+
+
+def create_access_token(
+    subject: Union[str, Any],
+    role: str = UserRole.PATIENT.value,
+    expires_delta: Optional[timedelta] = None,
+) -> str:
+    if expires_delta:
+        expire = datetime.now(timezone.utc) + expires_delta
+    else:
+        expire = datetime.now(timezone.utc) + timedelta(
+            minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+        )
+
+    to_encode = {
+        "sub": str(subject),
+        "role": role,
+        "type": "access",
+        "exp": expire,
+        "iat": datetime.now(timezone.utc),
+    }
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def create_refresh_token(
+    subject: Union[str, Any],
+    role: str = UserRole.PATIENT.value,
+    expires_delta: Optional[timedelta] = None,
+) -> str:
+    if expires_delta:
+        expire = datetime.now(timezone.utc) + expires_delta
+    else:
+        expire = datetime.now(timezone.utc) + timedelta(
+            days=settings.REFRESH_TOKEN_EXPIRE_DAYS
+        )
+
+    to_encode = {
+        "sub": str(subject),
+        "role": role,
+        "type": "refresh",
+        "exp": expire,
+        "iat": datetime.now(timezone.utc),
+    }
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def decode_token(token: str) -> Optional[dict]:
+    try:
+        payload = jwt.decode(
+            token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM]
+        )
+        return payload
+    except JWTError:
+        return None

backend/app/main.py

@@ -0,0 +1,130 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+
+from backend.app.core.config import settings
+from backend.app.core.database import init_db
+from backend.app.core.logger import logger
+from backend.app.core.exceptions import SanjeevaniException
+from backend.app.schemas.common import MEDICAL_DISCLAIMER
+from backend.app.ml.manager import model_manager
+from backend.app.middleware.request_id import RequestIDMiddleware
+from backend.app.middleware.security_headers import SecurityHeadersMiddleware
+from backend.app.api.v1.router import api_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info(f"Starting {settings.APP_NAME} v{settings.APP_VERSION} ({settings.APP_ENV})...")
+    # Initialize database
+    await init_db()
+    # Initialize ML Models
+    try:
+        model_manager.initialize()
+    except Exception as e:
+        logger.warning(f"ML Model initialization warning (will retry on demand): {e}")
+
+    yield
+
+    logger.info(f"Shutting down {settings.APP_NAME}...")
+
+
+def create_application() -> FastAPI:
+    app = FastAPI(
+        title=f"{settings.APP_NAME} — Healthcare Intelligence API",
+        description=(
+            "Industry-grade healthcare AI and clinical decision-support platform.\n\n"
+            f"**Medical Safety Notice**: {MEDICAL_DISCLAIMER}"
+        ),
+        version=settings.APP_VERSION,
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    # Middlewares
+    app.add_middleware(RequestIDMiddleware)
+    app.add_middleware(SecurityHeadersMiddleware)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.CORS_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Exception Handlers
+    @app.exception_handler(SanjeevaniException)
+    async def sanjeevani_exception_handler(request: Request, exc: SanjeevaniException):
+        req_id = getattr(request.state, "request_id", None)
+        logger.error(f"Domain error [{exc.code}]: {exc.message} (Request ID: {req_id})")
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "success": False,
+                "error": {
+                    "code": exc.code,
+                    "message": exc.message,
+                    "details": exc.details,
+                },
+                "request_id": req_id,
+                "disclaimer": MEDICAL_DISCLAIMER,
+            },
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError):
+        req_id = getattr(request.state, "request_id", None)
+        logger.warning(f"Validation error: {exc.errors()} (Request ID: {req_id})")
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={
+                "success": False,
+                "error": {
+                    "code": "VALIDATION_ERROR",
+                    "message": "Invalid request parameters.",
+                    "details": exc.errors(),
+                },
+                "request_id": req_id,
+                "disclaimer": MEDICAL_DISCLAIMER,
+            },
+        )
+
+    @app.exception_handler(Exception)
+    async def global_exception_handler(request: Request, exc: Exception):
+        req_id = getattr(request.state, "request_id", None)
+        logger.error(f"Unhandled exception: {str(exc)} (Request ID: {req_id})", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "success": False,
+                "error": {
+                    "code": "INTERNAL_SERVER_ERROR",
+                    "message": "An unexpected error occurred while processing the healthcare request.",
+                },
+                "request_id": req_id,
+                "disclaimer": MEDICAL_DISCLAIMER,
+            },
+        )
+
+    # Register API v1 routes
+    app.include_router(api_router, prefix="/api/v1")
+
+    # Root redirect / status
+    @app.get("/", tags=["Root"])
+    async def root():
+        return {
+            "app": settings.APP_NAME,
+            "tagline": "AI-Powered Healthcare Intelligence Platform",
+            "version": settings.APP_VERSION,
+            "docs": "/docs",
+            "disclaimer": MEDICAL_DISCLAIMER,
+        }
+
+    return app
+
+
+app = create_application()

backend/app/middleware/request_id.py

@@ -0,0 +1,13 @@
+import uuid
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        req_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
+        request.state.request_id = req_id
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = req_id
+        return response

backend/app/middleware/security_headers.py

@@ -0,0 +1,14 @@
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        return response

backend/app/ml/manager.py

@@ -0,0 +1,54 @@
+from typing import Optional, Dict, Any
+from backend.app.ml.ner.bc5cdr import BC5CDRNERModel
+from backend.app.ml.ner.service import NERService
+from backend.app.core.logger import logger
+
+
+class ModelManager:
+    _instance: Optional["ModelManager"] = None
+
+    def __init__(self):
+        self.bc5cdr_ner: Optional[BC5CDRNERModel] = None
+        self.ner_service: Optional[NERService] = None
+        self._is_initialized = False
+
+    @classmethod
+    def get_instance(cls) -> "ModelManager":
+        if cls._instance is None:
+            cls._instance = ModelManager()
+        return cls._instance
+
+    def initialize(self) -> None:
+        """Initialize and warm up all local ML models."""
+        if self._is_initialized:
+            return
+
+        logger.info("Initializing ModelManager and loading ML pipelines...")
+        try:
+            self.bc5cdr_ner = BC5CDRNERModel()
+            self.bc5cdr_ner.load()
+            self.ner_service = NERService(model=self.bc5cdr_ner)
+            self._is_initialized = True
+            logger.info("ModelManager initialized successfully.")
+        except Exception as e:
+            logger.error(f"Error during ModelManager initialization: {str(e)}", exc_info=True)
+            self._is_initialized = False
+
+    def get_ner_service(self) -> NERService:
+        if self.ner_service is None:
+            if self.bc5cdr_ner is None:
+                self.bc5cdr_ner = BC5CDRNERModel()
+            self.bc5cdr_ner.load()
+            self.ner_service = NERService(model=self.bc5cdr_ner)
+        return self.ner_service
+
+    def get_status(self) -> Dict[str, Any]:
+        return {
+            "initialized": self._is_initialized,
+            "models": {
+                "bc5cdr_ner": self.bc5cdr_ner.get_info().model_dump() if self.bc5cdr_ner else {"status": "Not Loaded"}
+            }
+        }
+
+
+model_manager = ModelManager.get_instance()

backend/app/ml/ner/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any
+from backend.app.schemas.ner import NEREntity, ModelInfo
+
+
+class BaseNERModel(ABC):
+    @abstractmethod
+    def load(self) -> None:
+        """Load model weights and tokenizer into memory."""
+        pass
+
+    @abstractmethod
+    def predict(self, text: str) -> List[NEREntity]:
+        """Perform token classification and return extracted biomedical entities."""
+        pass
+
+    @abstractmethod
+    def get_info(self) -> ModelInfo:
+        """Return model metadata."""
+        pass

backend/app/ml/ner/bc5cdr.py

@@ -0,0 +1,109 @@
+import os
+from pathlib import Path
+from typing import List, Optional
+import torch
+from transformers import AutoTokenizer, AutoModelForTokenClassification, pipeline
+from backend.app.ml.ner.base import BaseNERModel
+from backend.app.schemas.ner import NEREntity, ModelInfo
+from backend.app.core.config import settings
+from backend.app.core.logger import logger
+from backend.app.core.exceptions import MLModelError
+
+
+class BC5CDRNERModel(BaseNERModel):
+    def __init__(self, model_path: Optional[str] = None):
+        self.model_path = Path(model_path or settings.NER_MODEL_PATH)
+        self.model_name = "tner/roberta-large-bc5cdr"
+        self.tokenizer = None
+        self.model = None
+        self.pipeline = None
+        self.device = "cuda:0" if torch.cuda.is_available() else "cpu"
+        self._is_loaded = False
+
+    def load(self) -> None:
+        if self._is_loaded:
+            return
+
+        # Use local path if it exists; otherwise load directly from HuggingFace Hub (for cloud hosting)
+        if self.model_path.exists() and any(self.model_path.iterdir()):
+            model_source = str(self.model_path)
+            logger.info(f"Loading local BC5CDR NER model from disk ({model_source}) onto {self.device}...")
+        else:
+            model_source = self.model_name
+            logger.info(f"Local model path not found. Loading '{model_source}' from Hugging Face Hub onto {self.device}...")
+
+        try:
+            self.tokenizer = AutoTokenizer.from_pretrained(model_source)
+            self.model = AutoModelForTokenClassification.from_pretrained(model_source)
+
+            device_id = 0 if self.device.startswith("cuda") else -1
+            self.pipeline = pipeline(
+                "ner",
+                model=self.model,
+                tokenizer=self.tokenizer,
+                aggregation_strategy="simple",
+                device=device_id,
+            )
+
+            # Warm-up run
+            _ = self.pipeline("Metformin reduces glucose in diabetes mellitus.")
+            self._is_loaded = True
+            logger.info(f"BC5CDR NER model ({model_source}) loaded and warmed up successfully.")
+        except Exception as e:
+            logger.error(f"Failed to load BC5CDR model: {str(e)}", exc_info=True)
+            self._is_loaded = False
+            raise MLModelError(message=f"Model initialization failed: {str(e)}")
+
+    def predict(self, text: str) -> List[NEREntity]:
+        if not self._is_loaded or self.pipeline is None:
+            self.load()
+
+        if not text or not text.strip():
+            return []
+
+        try:
+            raw_entities = self.pipeline(text)
+            entities: List[NEREntity] = []
+
+            for ent in raw_entities:
+                entity_label = ent.get("entity_group") or ent.get("entity") or "UNKNOWN"
+                norm_label = entity_label.upper()
+                if "CHEM" in norm_label:
+                    norm_label = "CHEMICAL"
+                elif "DIS" in norm_label:
+                    norm_label = "DISEASE"
+
+                word = ent.get("word", "").strip()
+                start = ent.get("start", 0)
+                end = ent.get("end", 0)
+
+                if not word:
+                    continue
+
+                score = ent.get("score")
+                confidence = float(score) if score is not None else None
+
+                entities.append(
+                    NEREntity(
+                        text=word,
+                        label=norm_label,
+                        start=start,
+                        end=end,
+                        confidence=round(confidence, 4) if confidence else None,
+                        model=self.model_name,
+                    )
+                )
+
+            return entities
+        except Exception as e:
+            logger.error(f"NER inference error: {str(e)}", exc_info=True)
+            raise MLModelError(message=f"Error executing NER inference: {str(e)}")
+
+    def get_info(self) -> ModelInfo:
+        return ModelInfo(
+            name=self.model_name,
+            version="1.0.0",
+            provider="RoBERTa-large BC5CDR",
+            device=self.device,
+            status="Loaded" if self._is_loaded else "Not Loaded",
+        )

backend/app/ml/ner/service.py

@@ -0,0 +1,34 @@
+import time
+import uuid
+from typing import List, Optional
+from backend.app.ml.ner.base import BaseNERModel
+from backend.app.schemas.ner import NERRequest, NERResponse, NEREntity
+from backend.app.core.logger import logger
+
+
+class NERService:
+    def __init__(self, model: BaseNERModel):
+        self.model = model
+
+    def analyze_text(self, request: NERRequest, request_id: Optional[str] = None) -> NERResponse:
+        req_id = request_id or str(uuid.uuid4())
+        start_time = time.perf_counter()
+
+        entities: List[NEREntity] = self.model.predict(request.text)
+        processing_time_ms = round((time.perf_counter() - start_time) * 1000, 2)
+
+        model_info = self.model.get_info()
+
+        logger.info(
+            f"NER Analysis completed: req_id={req_id}, entities_found={len(entities)}, "
+            f"latency={processing_time_ms}ms"
+        )
+
+        return NERResponse(
+            request_id=req_id,
+            model=model_info,
+            entities=entities,
+            entity_count=len(entities),
+            processing_time_ms=processing_time_ms,
+            text_length=len(request.text),
+        )

backend/app/models/__init__.py

@@ -0,0 +1,21 @@
+from backend.app.models.base import BaseModel
+from backend.app.models.user import User
+from backend.app.models.profile import PatientProfile
+from backend.app.models.document import MedicalDocument, DocumentAnalysis
+from backend.app.models.entity import MedicalEntity
+from backend.app.models.conversation import AIConversation, AIMessage
+from backend.app.models.audit import AuditLog, AnalysisHistory, SystemEvent
+
+__all__ = [
+    "BaseModel",
+    "User",
+    "PatientProfile",
+    "MedicalDocument",
+    "DocumentAnalysis",
+    "MedicalEntity",
+    "AIConversation",
+    "AIMessage",
+    "AuditLog",
+    "AnalysisHistory",
+    "SystemEvent",
+]

backend/app/models/audit.py

@@ -0,0 +1,39 @@
+from sqlalchemy import Column, String, Integer, ForeignKey, Text
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel
+
+
+class AuditLog(BaseModel):
+    __tablename__ = "audit_logs"
+
+    user_id = Column(String(36), ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
+    action = Column(String(100), nullable=False, index=True)  # LOGIN, LOGOUT, NER_ANALYZE, DOCUMENT_UPLOAD, etc.
+    ip_address = Column(String(45), nullable=True)
+    user_agent = Column(String(255), nullable=True)
+    status = Column(String(20), default="SUCCESS", nullable=False)  # SUCCESS, FAILED, WARNING
+    details = Column(Text, nullable=True)  # JSON-encoded sanitized details
+
+    # Relationships
+    user = relationship("User", back_populates="audit_logs")
+
+
+class AnalysisHistory(BaseModel):
+    __tablename__ = "analysis_history"
+
+    user_id = Column(String(36), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    action_type = Column(String(50), nullable=False)  # NER, REPORT_ANALYSIS, PROFILE_UPDATE, CHAT
+    description = Column(String(255), nullable=False)
+    entity_count = Column(Integer, default=0, nullable=False)
+    reference_id = Column(String(36), nullable=True)  # document_id or conversation_id
+
+    # Relationships
+    user = relationship("User", back_populates="history")
+
+
+class SystemEvent(BaseModel):
+    __tablename__ = "system_events"
+
+    event_type = Column(String(100), nullable=False, index=True)
+    severity = Column(String(20), default="INFO", nullable=False)  # INFO, WARNING, ERROR, CRITICAL
+    message = Column(String(500), nullable=False)
+    details = Column(Text, nullable=True)

backend/app/models/base.py

@@ -0,0 +1,25 @@
+import uuid
+from datetime import datetime, timezone
+from sqlalchemy import Column, String, DateTime
+from backend.app.core.database import Base
+
+
+def generate_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class BaseModel(Base):
+    __abstract__ = True
+
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    created_at = Column(DateTime(timezone=True), default=utc_now, nullable=False)
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+        nullable=False,
+    )

backend/app/models/conversation.py

@@ -0,0 +1,33 @@
+from sqlalchemy import Column, String, ForeignKey, Text
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel
+
+
+class AIConversation(BaseModel):
+    __tablename__ = "ai_conversations"
+
+    user_id = Column(String(36), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    title = Column(String(255), default="New Medical Consultation", nullable=False)
+
+    # Relationships with selectin loading to prevent async lazy loading issues
+    user = relationship("User", back_populates="conversations", lazy="selectin")
+    messages = relationship(
+        "AIMessage",
+        back_populates="conversation",
+        cascade="all, delete-orphan",
+        order_by="AIMessage.created_at",
+        lazy="selectin",
+    )
+
+
+class AIMessage(BaseModel):
+    __tablename__ = "ai_messages"
+
+    conversation_id = Column(String(36), ForeignKey("ai_conversations.id", ondelete="CASCADE"), nullable=False, index=True)
+    role = Column(String(20), nullable=False)  # "user", "assistant", "system"
+    content = Column(Text, nullable=False)
+    structured_data = Column(Text, nullable=True)  # JSON-encoded summary, recommendations, disclaimer
+    model_provider = Column(String(50), nullable=True)
+
+    # Relationships
+    conversation = relationship("AIConversation", back_populates="messages", lazy="selectin")

backend/app/models/document.py

@@ -0,0 +1,39 @@
+from sqlalchemy import Column, String, Integer, ForeignKey, Text, DateTime
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel, utc_now
+
+
+class MedicalDocument(BaseModel):
+    __tablename__ = "medical_documents"
+
+    user_id = Column(String(36), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    filename = Column(String(255), nullable=False)
+    original_filename = Column(String(255), nullable=False)
+    file_path = Column(String(500), nullable=False)
+    file_type = Column(String(50), nullable=False)
+    file_size = Column(Integer, nullable=False)
+    file_hash = Column(String(64), nullable=False)
+    status = Column(String(50), default="PENDING", nullable=False)  # PENDING, PROCESSING, COMPLETED, FAILED
+    error_message = Column(Text, nullable=True)
+
+    # Relationships
+    user = relationship("User", back_populates="documents", lazy="selectin")
+    analysis = relationship("DocumentAnalysis", back_populates="document", uselist=False, cascade="all, delete-orphan", lazy="selectin")
+
+
+class DocumentAnalysis(BaseModel):
+    __tablename__ = "document_analyses"
+
+    document_id = Column(String(36), ForeignKey("medical_documents.id", ondelete="CASCADE"), unique=True, nullable=False, index=True)
+    raw_text = Column(Text, nullable=False)
+    cleaned_text = Column(Text, nullable=True)
+    summary = Column(Text, nullable=True)
+    important_findings = Column(Text, nullable=True)  # JSON-encoded array or text
+    detected_conditions = Column(Text, nullable=True)  # JSON-encoded array
+    detected_medications = Column(Text, nullable=True)  # JSON-encoded array
+    clinical_recommendations = Column(Text, nullable=True)
+    processed_at = Column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    # Relationships
+    document = relationship("MedicalDocument", back_populates="analysis", lazy="selectin")
+    entities = relationship("MedicalEntity", back_populates="analysis", cascade="all, delete-orphan", lazy="selectin")

backend/app/models/entity.py

@@ -0,0 +1,18 @@
+from sqlalchemy import Column, String, Integer, Float, ForeignKey
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel
+
+
+class MedicalEntity(BaseModel):
+    __tablename__ = "medical_entities"
+
+    analysis_id = Column(String(36), ForeignKey("document_analyses.id", ondelete="CASCADE"), nullable=False, index=True)
+    text = Column(String(255), nullable=False)
+    label = Column(String(50), nullable=False)  # CHEMICAL, DISEASE, MEDICINE, etc.
+    start_offset = Column(Integer, nullable=False)
+    end_offset = Column(Integer, nullable=False)
+    confidence = Column(Float, nullable=True)
+    model_name = Column(String(100), default="tner/roberta-large-bc5cdr", nullable=False)
+
+    # Relationships
+    analysis = relationship("DocumentAnalysis", back_populates="entities")

backend/app/models/profile.py

@@ -0,0 +1,21 @@
+from sqlalchemy import Column, String, Integer, Float, ForeignKey, Text
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel
+
+
+class PatientProfile(BaseModel):
+    __tablename__ = "patient_profiles"
+
+    user_id = Column(String(36), ForeignKey("users.id", ondelete="CASCADE"), unique=True, nullable=False, index=True)
+    age = Column(Integer, nullable=True)
+    gender = Column(String(20), nullable=True)
+    blood_group = Column(String(10), nullable=True)
+    height_cm = Column(Float, nullable=True)
+    weight_kg = Column(Float, nullable=True)
+    known_allergies = Column(Text, nullable=True)  # JSON or comma-separated string
+    chronic_conditions = Column(Text, nullable=True)  # JSON or comma-separated string
+    current_medications = Column(Text, nullable=True)  # JSON or comma-separated string
+    emergency_contact = Column(String(255), nullable=True)
+
+    # Relationships
+    user = relationship("User", back_populates="profile")

backend/app/models/user.py

@@ -0,0 +1,22 @@
+from sqlalchemy import Column, String, Boolean
+from sqlalchemy.orm import relationship
+from backend.app.models.base import BaseModel
+from backend.app.core.security import UserRole
+
+
+class User(BaseModel):
+    __tablename__ = "users"
+
+    email = Column(String(255), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    full_name = Column(String(255), nullable=False)
+    role = Column(String(50), default=UserRole.PATIENT.value, nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    is_verified = Column(Boolean, default=False, nullable=False)
+
+    # Relationships
+    profile = relationship("PatientProfile", back_populates="user", uselist=False, cascade="all, delete-orphan", lazy="selectin")
+    documents = relationship("MedicalDocument", back_populates="user", cascade="all, delete-orphan", lazy="selectin")
+    conversations = relationship("AIConversation", back_populates="user", cascade="all, delete-orphan", lazy="selectin")
+    audit_logs = relationship("AuditLog", back_populates="user", lazy="selectin")
+    history = relationship("AnalysisHistory", back_populates="user", cascade="all, delete-orphan", lazy="selectin")

backend/app/repositories/audit_repo.py

@@ -0,0 +1,85 @@
+from typing import List, Optional, Dict, Any
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc, func
+from backend.app.models.audit import AuditLog, AnalysisHistory, SystemEvent
+from backend.app.models.user import User
+from backend.app.models.document import MedicalDocument
+from backend.app.models.conversation import AIConversation
+from backend.app.repositories.base import BaseRepository
+
+
+class AuditRepository(BaseRepository[AuditLog]):
+    def __init__(self, db: AsyncSession):
+        super().__init__(AuditLog, db)
+
+    async def log_event(
+        self,
+        action: str,
+        user_id: Optional[str] = None,
+        ip_address: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        status: str = "SUCCESS",
+        details: Optional[str] = None,
+    ) -> AuditLog:
+        audit = AuditLog(
+            user_id=user_id,
+            action=action,
+            ip_address=ip_address,
+            user_agent=user_agent[:255] if user_agent else None,
+            status=status,
+            details=details,
+        )
+        self.db.add(audit)
+        await self.db.commit()
+        await self.db.refresh(audit)
+        return audit
+
+    async def add_history(
+        self,
+        user_id: str,
+        action_type: str,
+        description: str,
+        entity_count: int = 0,
+        reference_id: Optional[str] = None,
+    ) -> AnalysisHistory:
+        history = AnalysisHistory(
+            user_id=user_id,
+            action_type=action_type,
+            description=description,
+            entity_count=entity_count,
+            reference_id=reference_id,
+        )
+        self.db.add(history)
+        await self.db.commit()
+        await self.db.refresh(history)
+        return history
+
+    async def get_user_history(self, user_id: str, limit: int = 50) -> List[AnalysisHistory]:
+        result = await self.db.execute(
+            select(AnalysisHistory)
+            .where(AnalysisHistory.user_id == user_id)
+            .order_by(desc(AnalysisHistory.created_at))
+            .limit(limit)
+        )
+        return list(result.scalars().all())
+
+    async def get_admin_audit_logs(self, limit: int = 100) -> List[AuditLog]:
+        result = await self.db.execute(
+            select(AuditLog).order_by(desc(AuditLog.created_at)).limit(limit)
+        )
+        return list(result.scalars().all())
+
+    async def get_system_statistics(self) -> Dict[str, int]:
+        total_users = (await self.db.execute(select(func.count(User.id)))).scalar_one() or 0
+        active_users = (await self.db.execute(select(func.count(User.id)).where(User.is_active == True))).scalar_one() or 0
+        total_docs = (await self.db.execute(select(func.count(MedicalDocument.id)))).scalar_one() or 0
+        total_chats = (await self.db.execute(select(func.count(AIConversation.id)))).scalar_one() or 0
+        total_ner = (await self.db.execute(select(func.count(AnalysisHistory.id)).where(AnalysisHistory.action_type == "NER"))).scalar_one() or 0
+
+        return {
+            "total_users": total_users,
+            "active_users": active_users,
+            "total_documents_processed": total_docs,
+            "total_chat_queries": total_chats,
+            "total_ner_requests": total_ner,
+        }

backend/app/repositories/base.py

@@ -0,0 +1,36 @@
+from typing import Generic, TypeVar, Type, Optional, List, Any
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, delete
+from backend.app.models.base import BaseModel
+
+ModelType = TypeVar("ModelType", bound=BaseModel)
+
+
+class BaseRepository(Generic[ModelType]):
+    def __init__(self, model: Type[ModelType], db: AsyncSession):
+        self.model = model
+        self.db = db
+
+    async def get_by_id(self, id: str) -> Optional[ModelType]:
+        result = await self.db.execute(select(self.model).where(self.model.id == id))
+        return result.scalars().first()
+
+    async def get_all(self, skip: int = 0, limit: int = 100) -> List[ModelType]:
+        result = await self.db.execute(select(self.model).offset(skip).limit(limit))
+        return list(result.scalars().all())
+
+    async def create(self, entity: ModelType) -> ModelType:
+        self.db.add(entity)
+        await self.db.commit()
+        await self.db.refresh(entity)
+        return entity
+
+    async def update(self, entity: ModelType) -> ModelType:
+        await self.db.commit()
+        await self.db.refresh(entity)
+        return entity
+
+    async def delete(self, id: str) -> bool:
+        result = await self.db.execute(delete(self.model).where(self.model.id == id))
+        await self.db.commit()
+        return result.rowcount > 0

backend/app/repositories/chat_repo.py

@@ -0,0 +1,34 @@
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from sqlalchemy.orm import selectinload
+from backend.app.models.conversation import AIConversation, AIMessage
+from backend.app.repositories.base import BaseRepository
+
+
+class ChatRepository(BaseRepository[AIConversation]):
+    def __init__(self, db: AsyncSession):
+        super().__init__(AIConversation, db)
+
+    async def get_user_conversations(self, user_id: str) -> List[AIConversation]:
+        result = await self.db.execute(
+            select(AIConversation)
+            .options(selectinload(AIConversation.messages))
+            .where(AIConversation.user_id == user_id)
+            .order_by(desc(AIConversation.updated_at))
+        )
+        return list(result.scalars().all())
+
+    async def get_conversation_with_messages(self, conversation_id: str, user_id: str) -> Optional[AIConversation]:
+        result = await self.db.execute(
+            select(AIConversation)
+            .options(selectinload(AIConversation.messages))
+            .where(AIConversation.id == conversation_id, AIConversation.user_id == user_id)
+        )
+        return result.scalars().first()
+
+    async def add_message(self, message: AIMessage) -> AIMessage:
+        self.db.add(message)
+        await self.db.commit()
+        await self.db.refresh(message)
+        return message

backend/app/repositories/document_repo.py

@@ -0,0 +1,48 @@
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from sqlalchemy.orm import selectinload
+from backend.app.models.document import MedicalDocument, DocumentAnalysis
+from backend.app.models.entity import MedicalEntity
+from backend.app.repositories.base import BaseRepository
+
+
+class DocumentRepository(BaseRepository[MedicalDocument]):
+    def __init__(self, db: AsyncSession):
+        super().__init__(MedicalDocument, db)
+
+    async def get_user_documents(self, user_id: str) -> List[MedicalDocument]:
+        result = await self.db.execute(
+            select(MedicalDocument)
+            .options(
+                selectinload(MedicalDocument.analysis).selectinload(DocumentAnalysis.entities)
+            )
+            .where(MedicalDocument.user_id == user_id)
+            .order_by(desc(MedicalDocument.created_at))
+        )
+        return list(result.scalars().all())
+
+    async def get_document_details(self, document_id: str, user_id: Optional[str] = None) -> Optional[MedicalDocument]:
+        query = (
+            select(MedicalDocument)
+            .options(
+                selectinload(MedicalDocument.analysis).selectinload(DocumentAnalysis.entities)
+            )
+            .where(MedicalDocument.id == document_id)
+        )
+        if user_id:
+            query = query.where(MedicalDocument.user_id == user_id)
+
+        result = await self.db.execute(query)
+        return result.scalars().first()
+
+    async def save_analysis(self, analysis: DocumentAnalysis) -> DocumentAnalysis:
+        self.db.add(analysis)
+        await self.db.commit()
+        await self.db.refresh(analysis)
+        return analysis
+
+    async def save_entities(self, entities: List[MedicalEntity]) -> List[MedicalEntity]:
+        self.db.add_all(entities)
+        await self.db.commit()
+        return entities

backend/app/repositories/user_repo.py

@@ -0,0 +1,36 @@
+from typing import Optional, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+from backend.app.models.user import User
+from backend.app.models.profile import PatientProfile
+from backend.app.repositories.base import BaseRepository
+
+
+class UserRepository(BaseRepository[User]):
+    def __init__(self, db: AsyncSession):
+        super().__init__(User, db)
+
+    async def get_by_email(self, email: str) -> Optional[User]:
+        result = await self.db.execute(
+            select(User).options(selectinload(User.profile)).where(User.email == email.lower())
+        )
+        return result.scalars().first()
+
+    async def get_with_profile(self, user_id: str) -> Optional[User]:
+        result = await self.db.execute(
+            select(User).options(selectinload(User.profile)).where(User.id == user_id)
+        )
+        return result.scalars().first()
+
+    async def get_profile_by_user_id(self, user_id: str) -> Optional[PatientProfile]:
+        result = await self.db.execute(
+            select(PatientProfile).where(PatientProfile.user_id == user_id)
+        )
+        return result.scalars().first()
+
+    async def save_profile(self, profile: PatientProfile) -> PatientProfile:
+        self.db.add(profile)
+        await self.db.commit()
+        await self.db.refresh(profile)
+        return profile

backend/app/schemas/__init__.py

@@ -0,0 +1,40 @@
+from backend.app.schemas.common import BaseResponse, ErrorResponse, HealthCheck, MEDICAL_DISCLAIMER
+from backend.app.schemas.user import UserCreate, UserLogin, UserUpdate, UserResponse
+from backend.app.schemas.token import TokenResponse, TokenPayload, RefreshTokenRequest
+from backend.app.schemas.profile import PatientProfileCreate, PatientProfileUpdate, PatientProfileResponse
+from backend.app.schemas.ner import NERRequest, NEREntity, NERResponse, ModelInfo
+from backend.app.schemas.document import MedicalDocumentResponse, DocumentAnalysisResponse, DocumentUploadResponse
+from backend.app.schemas.chat import ChatMessageCreate, ChatMessageResponse, ConversationResponse, AIStructuredOutput, ChatCompletionResponse
+from backend.app.schemas.admin import AdminStatsResponse, AuditLogResponse, AnalysisHistoryResponse
+
+__all__ = [
+    "BaseResponse",
+    "ErrorResponse",
+    "HealthCheck",
+    "MEDICAL_DISCLAIMER",
+    "UserCreate",
+    "UserLogin",
+    "UserUpdate",
+    "UserResponse",
+    "TokenResponse",
+    "TokenPayload",
+    "RefreshTokenRequest",
+    "PatientProfileCreate",
+    "PatientProfileUpdate",
+    "PatientProfileResponse",
+    "NERRequest",
+    "NEREntity",
+    "NERResponse",
+    "ModelInfo",
+    "MedicalDocumentResponse",
+    "DocumentAnalysisResponse",
+    "DocumentUploadResponse",
+    "ChatMessageCreate",
+    "ChatMessageResponse",
+    "ConversationResponse",
+    "AIStructuredOutput",
+    "ChatCompletionResponse",
+    "AdminStatsResponse",
+    "AuditLogResponse",
+    "AnalysisHistoryResponse",
+]

backend/app/schemas/admin.py

@@ -0,0 +1,38 @@
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, ConfigDict
+from datetime import datetime
+
+
+class AuditLogResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: Optional[str] = None
+    action: str
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+    status: str
+    details: Optional[str] = None
+    created_at: datetime
+
+
+class AnalysisHistoryResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: str
+    action_type: str
+    description: str
+    entity_count: int
+    reference_id: Optional[str] = None
+    created_at: datetime
+
+
+class AdminStatsResponse(BaseModel):
+    total_users: int
+    active_users: int
+    total_documents_processed: int
+    total_ner_requests: int
+    total_chat_queries: int
+    model_status: Dict[str, Any]
+    system_health: str

backend/app/schemas/chat.py

@@ -0,0 +1,48 @@
+from typing import List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+from datetime import datetime
+from backend.app.schemas.common import MEDICAL_DISCLAIMER
+
+
+class AIStructuredOutput(BaseModel):
+    summary: str
+    possible_considerations: List[str] = []
+    relevant_medical_info: List[str] = []
+    questions_for_doctor: List[str] = []
+    safety_warning: str = MEDICAL_DISCLAIMER
+    is_emergency: bool = False
+    emergency_instructions: Optional[str] = None
+
+
+class ChatMessageCreate(BaseModel):
+    conversation_id: Optional[str] = None
+    message: str = Field(..., min_length=1, max_length=5000)
+
+
+class ChatMessageResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    conversation_id: str
+    role: str
+    content: str
+    structured_data: Optional[AIStructuredOutput] = None
+    model_provider: Optional[str] = None
+    created_at: datetime
+
+
+class ConversationResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: str
+    title: str
+    messages: List[ChatMessageResponse] = []
+    created_at: datetime
+    updated_at: datetime
+
+
+class ChatCompletionResponse(BaseModel):
+    conversation_id: str
+    message: ChatMessageResponse
+    disclaimer: str = MEDICAL_DISCLAIMER

backend/app/schemas/common.py

@@ -0,0 +1,40 @@
+from typing import Generic, TypeVar, Optional, Any, List
+from pydantic import BaseModel, ConfigDict
+from datetime import datetime
+
+T = TypeVar("T")
+
+MEDICAL_DISCLAIMER = (
+    "SanjeevaniAI provides AI-assisted healthcare information and decision-support insights. "
+    "It is not a substitute for professional medical diagnosis, treatment, or emergency care."
+)
+
+
+class BaseResponse(BaseModel, Generic[T]):
+    model_config = ConfigDict(from_attributes=True)
+
+    success: bool = True
+    message: Optional[str] = None
+    data: Optional[T] = None
+    disclaimer: str = MEDICAL_DISCLAIMER
+
+
+class ErrorDetail(BaseModel):
+    code: str
+    message: str
+    details: Optional[Any] = None
+
+
+class ErrorResponse(BaseModel):
+    success: bool = False
+    error: ErrorDetail
+    request_id: Optional[str] = None
+    disclaimer: str = MEDICAL_DISCLAIMER
+
+
+class HealthCheck(BaseModel):
+    status: str = "healthy"
+    version: str
+    environment: str
+    timestamp: datetime
+    services: dict

backend/app/schemas/document.py

@@ -0,0 +1,43 @@
+from typing import List, Optional
+from pydantic import BaseModel, ConfigDict
+from datetime import datetime
+from backend.app.schemas.ner import NEREntity
+from backend.app.schemas.common import MEDICAL_DISCLAIMER
+
+
+class DocumentAnalysisResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    document_id: str
+    raw_text: str
+    cleaned_text: Optional[str] = None
+    summary: Optional[str] = None
+    important_findings: List[str] = []
+    detected_conditions: List[str] = []
+    detected_medications: List[str] = []
+    clinical_recommendations: Optional[str] = None
+    entities: List[NEREntity] = []
+    processed_at: datetime
+
+
+class MedicalDocumentResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: str
+    filename: str
+    original_filename: str
+    file_type: str
+    file_size: int
+    status: str
+    error_message: Optional[str] = None
+    analysis: Optional[DocumentAnalysisResponse] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class DocumentUploadResponse(BaseModel):
+    document: MedicalDocumentResponse
+    message: str = "Document uploaded and processed successfully"
+    disclaimer: str = MEDICAL_DISCLAIMER

backend/app/schemas/ner.py

@@ -0,0 +1,34 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from backend.app.schemas.common import MEDICAL_DISCLAIMER
+
+
+class NERRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=10000, description="Clinical or biomedical text to analyze")
+
+
+class NEREntity(BaseModel):
+    text: str
+    label: str  # CHEMICAL, DISEASE
+    start: int
+    end: int
+    confidence: Optional[float] = None
+    model: str = "tner/roberta-large-bc5cdr"
+
+
+class ModelInfo(BaseModel):
+    name: str = "tner/roberta-large-bc5cdr"
+    version: str = "local"
+    provider: str = "Local PyTorch / Transformers"
+    device: str = "cuda:0"
+    status: str = "Loaded"
+
+
+class NERResponse(BaseModel):
+    request_id: str
+    model: ModelInfo
+    entities: List[NEREntity]
+    entity_count: int
+    processing_time_ms: float
+    text_length: int
+    disclaimer: str = MEDICAL_DISCLAIMER

backend/app/schemas/profile.py

@@ -0,0 +1,32 @@
+from typing import Optional, List
+from pydantic import BaseModel, Field, ConfigDict
+from datetime import datetime
+
+
+class PatientProfileBase(BaseModel):
+    age: Optional[int] = Field(None, ge=0, le=130)
+    gender: Optional[str] = Field(None, max_length=20)
+    blood_group: Optional[str] = Field(None, max_length=10)
+    height_cm: Optional[float] = Field(None, ge=20, le=300)
+    weight_kg: Optional[float] = Field(None, ge=1, le=500)
+    known_allergies: Optional[List[str]] = Field(default_factory=list)
+    chronic_conditions: Optional[List[str]] = Field(default_factory=list)
+    current_medications: Optional[List[str]] = Field(default_factory=list)
+    emergency_contact: Optional[str] = Field(None, max_length=255)
+
+
+class PatientProfileCreate(PatientProfileBase):
+    pass
+
+
+class PatientProfileUpdate(PatientProfileBase):
+    pass
+
+
+class PatientProfileResponse(PatientProfileBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: str
+    created_at: datetime
+    updated_at: datetime

backend/app/schemas/token.py

@@ -0,0 +1,22 @@
+from typing import Optional
+from pydantic import BaseModel
+from backend.app.schemas.user import UserResponse
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    expires_in: int
+    user: UserResponse
+
+
+class RefreshTokenRequest(BaseModel):
+    refresh_token: str
+
+
+class TokenPayload(BaseModel):
+    sub: Optional[str] = None
+    role: Optional[str] = None
+    type: Optional[str] = None
+    exp: Optional[int] = None

backend/app/schemas/user.py

@@ -0,0 +1,35 @@
+from typing import Optional
+from pydantic import BaseModel, EmailStr, Field, ConfigDict
+from datetime import datetime
+from backend.app.core.security import UserRole
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    full_name: str = Field(..., min_length=2, max_length=255)
+    role: UserRole = UserRole.PATIENT
+
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8, max_length=128)
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserUpdate(BaseModel):
+    full_name: Optional[str] = Field(None, min_length=2, max_length=255)
+    email: Optional[EmailStr] = None
+    password: Optional[str] = Field(None, min_length=8, max_length=128)
+
+
+class UserResponse(UserBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    is_active: bool
+    is_verified: bool
+    created_at: datetime
+    updated_at: datetime

backend/app/services/auth_service.py

@@ -0,0 +1,105 @@
+from typing import Optional, Tuple
+from sqlalchemy.ext.asyncio import AsyncSession
+from backend.app.models.user import User
+from backend.app.models.profile import PatientProfile
+from backend.app.schemas.user import UserCreate, UserLogin, UserResponse
+from backend.app.schemas.token import TokenResponse
+from backend.app.core.security import (
+    verify_password,
+    get_password_hash,
+    create_access_token,
+    create_refresh_token,
+    decode_token,
+    UserRole,
+)
+from backend.app.core.exceptions import AuthenticationError, ValidationError, ResourceNotFoundError
+from backend.app.repositories.user_repo import UserRepository
+from backend.app.repositories.audit_repo import AuditRepository
+from backend.app.core.config import settings
+
+
+class AuthService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+        self.user_repo = UserRepository(db)
+        self.audit_repo = AuditRepository(db)
+
+    async def register(self, user_in: UserCreate, ip_address: Optional[str] = None) -> Tuple[User, TokenResponse]:
+        existing = await self.user_repo.get_by_email(user_in.email)
+        if existing:
+            raise ValidationError(message="A user with this email already exists.")
+
+        hashed_pwd = get_password_hash(user_in.password)
+        user = User(
+            email=user_in.email.lower(),
+            hashed_password=hashed_pwd,
+            full_name=user_in.full_name,
+            role=user_in.role.value if isinstance(user_in.role, UserRole) else str(user_in.role),
+            is_active=True,
+            is_verified=True,
+        )
+        created_user = await self.user_repo.create(user)
+
+        # Create blank patient profile
+        profile = PatientProfile(user_id=created_user.id)
+        await self.user_repo.save_profile(profile)
+
+        # Log audit event
+        await self.audit_repo.log_event(
+            action="USER_REGISTER",
+            user_id=created_user.id,
+            ip_address=ip_address,
+            details=f"User registered with role {created_user.role}",
+        )
+
+        tokens = self._generate_tokens(created_user)
+        return created_user, tokens
+
+    async def login(self, login_in: UserLogin, ip_address: Optional[str] = None, user_agent: Optional[str] = None) -> TokenResponse:
+        user = await self.user_repo.get_by_email(login_in.email)
+        if not user or not verify_password(login_in.password, user.hashed_password):
+            await self.audit_repo.log_event(
+                action="LOGIN_FAILED",
+                ip_address=ip_address,
+                user_agent=user_agent,
+                status="FAILED",
+                details=f"Failed login attempt for email: {login_in.email}",
+            )
+            raise AuthenticationError(message="Incorrect email or password.")
+
+        if not user.is_active:
+            raise AuthenticationError(message="User account is inactive.")
+
+        await self.audit_repo.log_event(
+            action="USER_LOGIN",
+            user_id=user.id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+            status="SUCCESS",
+        )
+
+        return self._generate_tokens(user)
+
+    async def refresh_tokens(self, refresh_token: str) -> TokenResponse:
+        payload = decode_token(refresh_token)
+        if not payload or payload.get("type") != "refresh":
+            raise AuthenticationError(message="Invalid or expired refresh token.")
+
+        user_id = payload.get("sub")
+        user = await self.user_repo.get_by_id(user_id)
+        if not user or not user.is_active:
+            raise AuthenticationError(message="User not found or inactive.")
+
+        return self._generate_tokens(user)
+
+    def _generate_tokens(self, user: User) -> TokenResponse:
+        access_token = create_access_token(subject=user.id, role=user.role)
+        refresh_token = create_refresh_token(subject=user.id, role=user.role)
+
+        return TokenResponse(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_type="bearer",
+            expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+            user=UserResponse.model_validate(user),
+        )