docs/IMPLEMENTATION_PLAN.md

SanjeevaniAI — Implementation Plan

Phase Overview

The construction of SanjeevaniAI follows a disciplined 15-phase engineering roadmap designed to deliver a robust, modular, testable, and presentation-ready healthcare AI platform.

---

Roadmap

Phase 1: Architecture & Project Audit (Completed)

• Complete directory scan and asset inventory
• Model verification for models/bc5cdr-ner (RoBERTa-large BC5CDR Token Classification)
• Create docs/PROJECT_AUDIT.md and docs/IMPLEMENTATION_PLAN.md
• Establish architecture diagrams and technical specifications

Phase 2: Environment Configuration & Dependencies

• Update requirements.txt with FastAPI, Pydantic v2, SQLAlchemy 2.0, Alembic, python-jose, passlib, pypdf, httpx, uvicorn, redis, etc.
• Create .env.example and default .env configuration
• Install missing backend packages into D:\SanjeevaniAI\.venv

Phase 3: Backend Foundation & Modular Architecture

• Scaffold backend/ directory structure:
  • app/main.py: Application factory with lifespan event handling, CORS, rate limiting, and exception handlers
  • app/core/: Settings (config.py), security (security.py), logging (logger.py), exceptions (exceptions.py)
  • app/api/v1/: API Routers for auth, users, ner, documents, chat, history, profile, and admin
  • app/models/: SQLAlchemy ORM models (users, profiles, documents, entities, conversations, audit_logs)
  • app/schemas/: Pydantic validation schemas
  • app/repositories/: Data access layer
  • app/services/: Business logic layer
  • app/ml/: Model manager & local NER adapter
  • app/middleware/: Request ID, audit logging, security headers

Phase 4: Local Biomedical NER Model Integration

• Implement app/ml/ner/base.py (Abstract NER interface)
• Implement app/ml/ner/bc5cdr.py (Local RoBERTa-large BC5CDR inference engine)
• Implement app/ml/ner/service.py & app/ml/manager.py (Lifecycle, warmup, error isolation, batch inference)
• Expose POST /api/v1/ner/analyze with confidence scores, offsets, entity types (CHEMICAL, DISEASE), and model metadata
• Unit & integration tests for NER pipeline

Phase 5: Database Schema & Migrations

• Configure SQLAlchemy async engine (supporting PostgreSQL with SQLite dev fallback)
• Define normalized models: User, Role, PatientProfile, MedicalDocument, DocumentAnalysis, MedicalEntity, AIConversation, AIMessage, AuditLog
• Setup Alembic migration environment (alembic/)
• Generate and apply baseline database migration

Phase 6: Authentication & Authorization (RBAC)

• Secure JWT authentication (Access & Refresh tokens)
• Password hashing via Argon2 / Bcrypt
• RBAC for USER, PATIENT, DOCTOR, ADMIN
• Endpoints: POST /api/v1/auth/register, POST /api/v1/auth/login, POST /api/v1/auth/refresh, GET /api/v1/auth/me

Phase 7: Medical Document Analysis Pipeline

• Secure multi-format text extraction (PDF, TXT, DOCX)
• Filename sanitization, SHA256 integrity hashing, size limits
• Pipeline: Upload -> Text Extraction -> Normalization -> BC5CDR NER -> Clinical Summarization -> Structured Storage
• Endpoints: POST /api/v1/documents/upload, GET /api/v1/documents, GET /api/v1/documents/{id}, DELETE /api/v1/documents/{id}

Phase 8: AI Medical Assistant & Multi-Provider Abstraction

• Implement BaseLLMProvider, GeminiProvider (Google GenAI API), and MockLLMProvider (offline fallback)
• Strict clinical safety guardrails (extracted facts vs. AI considerations, emergency disclaimers, no speculative diagnoses)
• Endpoints: POST /api/v1/chat/completions, GET /api/v1/chat/conversations, DELETE /api/v1/chat/conversations/{id}

Phase 9: Patient Profile, Medical History & Audit Logging

• Patient profile management (GET/PUT /api/v1/profile)
• Chronological medical timeline (GET /api/v1/history)
• Structured security audit logger for sensitive events (LOGIN, DOCUMENT_UPLOAD, AI_ANALYSIS, ADMIN_ACTION)

Phase 10: Frontend Foundation (Next.js 14+ / React / Tailwind)

• Initialize Next.js TypeScript project in frontend/
• Configure Tailwind CSS, Lucide React icons, and accessible component library
• Create layout architecture: Sidebar navigation, Header, Breadcrumbs, Dark/Light theme, Clinical Disclaimer Banner
• Setup API Client with Axios/TanStack Query and JWT authentication context

Phase 11: Frontend Pages & Features

• Landing Page (/): Hero, product capabilities, architecture overview, medical safety disclaimer
• Auth Pages (/login, /register): Accessible forms with Zod validation
• Dashboard (/dashboard): Summary metric cards, recent document analyses, detected conditions, activity timeline
• Biomedical NER Visualizer (/ner): Dedicated mentor demo page with live entity highlighting (CHEMICAL / DISEASE), confidence metrics, and execution latency
• Medical Document Manager (/reports, /reports/[id]): Drag-and-drop file upload, progress bar, clinical entity viewer, summary export
• AI Assistant Interface (/assistant): Conversational UI, structured medical guidance, chat history, emergency alerts
• Patient Profile & Timeline (/profile, /history): Editable vitals/allergies/medications and chronological action history
• Admin & System Health (/admin): User statistics, model usage metrics, system logs, audit trails
• Mentor Demonstration Mode (/demo): Synthetic patient flow for 10-minute presentation

Phase 12: Seed Data & Testing Suites

• Synthetic seed generator: scripts/seed_demo_data.py (No real patient data)
• Backend test suite: pytest covering auth, NER, document analysis, RBAC, error handlers
• Frontend validation: Lint, TypeScript build verification

Phase 13: Containerization & Docker Setup

• backend/Dockerfile and frontend/Dockerfile
• docker-compose.yml (Backend, Frontend, PostgreSQL, Redis)
• Model volume mounting configuration

Phase 14: CI/CD & Security Auditing

• GitHub Actions workflows: .github/workflows/test.yml, .github/workflows/lint.yml
• Security hardening: Rate limiting, CORS policies, XSS/CSRF headers, path traversal protection

Phase 15: Documentation & Presentation Package

• Root README.md
• docs/ARCHITECTURE.md (with Mermaid diagrams)
• docs/API.md (OpenAPI specification & curl examples)
• docs/ML_MODELS.md (BC5CDR NER specs & performance metrics)
• docs/MENTOR_DEMO.md (Step-by-step 10-15 minute demonstration script)