PreRelease v2

2026-03-28 23:46:45 +01:00
parent 6bf998a52a
commit 9993bd232f
39 changed files with 3964 additions and 1469 deletions
--- a/AI_FEATURES_DOCUMENTATION.md
+++ b/AI_FEATURES_DOCUMENTATION.md
@@ -0,0 +1,578 @@
+# AI Features Documentation
+
+## 1. Overview
+
+This document explains all AI-powered capabilities currently implemented in the BFSI contract analysis application, how data flows through the system, what resilience mechanisms are in place, and how explainability is surfaced to users.
+
+### 1.1 AI Flow for Juniors (Start Here)
+
+If you are new to the codebase, this is the exact AI lifecycle from upload to UI proof:
+
+1. User uploads a document and opens it in dashboard details.
+2. Analyze action validates ownership and marks status as PROCESSING.
+3. AI prevalidation checks if the file is a real contract.
+4. Main extraction runs with primary model; fallback model is used if needed.
+5. Output is parsed, repaired when malformed, normalized to strict shape, and validated.
+6. Results are persisted in DB (title, dates, premium, summary, key points, explainability evidence, extracted text).
+7. Continuous learning metadata (aiMeta) is stored in keyPoints for future adaptive prompts.
+8. UI shows extracted fields and proof icons next to each critical field.
+9. Clicking a proof icon opens Field Proof modal:
+
+- tries to map evidence snippet to exact line(s) in extracted text using normalized fuzzy matching,
+- runs deterministic field-aware checks first (exact snippet/date/value line) before fuzzy scoring,
+- falls back to snippet evidence when precise line mapping is not possible.
+
+11. Premium amount keeps source currency semantics:
+
+- AI is instructed to return numeric premium without conversion,
+- AI also returns premiumCurrency (for example TND, USD, EUR),
+- UI displays premium using detected source currency (no forced EUR formatting).
+
+10. Q&A and reminders reuse the persisted AI output.
+
+### 1.2 Where to Read in Code
+
+- Orchestration: `lib/actions/contract.action.ts`
+- AI core + retries + validation: `lib/services/ai.service.ts`
+- Prompt contracts: `lib/services/ai/analysis.prompt.ts`
+- Parser + normalizer: `lib/services/ai/analysis.parser.ts`, `lib/services/ai/analysis.normalizer.ts`
+- UI proof rendering: `components/views/dashboard/contracts-list.tsx`
+
+The AI subsystem is centered on:
+
+- Contract prevalidation (contract vs non-contract detection)
+- Contract analysis and structured field extraction
+- Multi-model fallback and JSON repair
+- Normalization and validation hardening
+- Explainability evidence for extracted fields
+- Multilingual contract Q&A
+- AI-derived deadline reminders
+- Field-level proof modal with line-context evidence mapping
+- Snippet text search inside extracted snippets
+- Continuous learning context from previous analyses (without schema migration)
+
+## 2. Tech and Configuration
+
+### 2.1 Core Components
+
+- Next.js server actions for orchestration
+- Gemini via @google/generative-ai for extraction and Q&A
+- Prisma for persistence
+- Clerk for authenticated user context
+- React client UI for details modal, field-proof modal, and chat
+
+### 2.2 Models
+
+- Primary model: gemini-2.5-flash
+- Fallback model: gemini-2.0-flash
+- Model list is de-duplicated and iterated in order
+
+### 2.3 Environment Variables
+
+- AI_API_KEY (or AI_API_KEY2 / AI_API_KEY3 fallback)
+- AI_MODEL_PRIMARY (optional override)
+- AI_MODEL_FALLBACK (optional override)
+
+## 3. AI Capability Matrix
+
+| Capability                    | Trigger                           | Output                                                             | Main File                                                                                                                   |
+| ----------------------------- | --------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| Prevalidation                 | Analyze action                    | isValidContract, confidence, reason                                | lib/services/ai.service.ts                                                                                                  |
+| Structured extraction         | Analyze action                    | title/type/provider/policy/dates/premium/summary/key points        | lib/services/ai.service.ts                                                                                                  |
+| Premium currency preservation | Analyze + normalize + UI display  | premium + premiumCurrency with no currency conversion              | lib/services/ai/analysis.prompt.ts + lib/services/ai/analysis.normalizer.ts + components/views/dashboard/contracts-list.tsx |
+| Explainability extraction     | Structured extraction prompt      | field-level why + snippet + hints                                  | lib/services/ai/analysis.prompt.ts                                                                                          |
+| JSON repair                   | Parse failure                     | corrected JSON                                                     | lib/services/ai.service.ts                                                                                                  |
+| Emergency extraction          | Repair failure                    | minimal valid analysis JSON                                        | lib/services/ai.service.ts                                                                                                  |
+| Normalization                 | Post-parse                        | canonical, bounded, safe analysis object                           | lib/services/ai/analysis.normalizer.ts                                                                                      |
+| Contract validity assertion   | Post-normalization                | pass/fail with invalid-contract reason                             | lib/services/ai.service.ts                                                                                                  |
+| Contract Q&A                  | Ask action                        | multilingual business/legal-oriented answer                        | lib/services/ai.service.ts                                                                                                  |
+| Deadline reminders            | Contract save after AI completion | DEADLINE notifications at 30/15/7 days                             | lib/services/notification.service.ts                                                                                        |
+| Explainability UI             | Details modal                     | field-level proof icon, line-context modal, fuzzy evidence mapping | components/views/dashboard/contracts-list.tsx                                                                               |
+| Evidence quick copy           | Details modal                     | one-click clipboard copy of compliance evidence bundle             | components/views/dashboard/contracts-list.tsx                                                                               |
+| Snippet search                | Details modal                     | text/field search inside extracted snippets                        | components/views/dashboard/contracts-list.tsx                                                                               |
+| Continuous learning context   | Every completed analysis          | adaptive context enriched from historical aiMeta/evidence          | lib/actions/contract.action.ts + lib/services/ai.service.ts                                                                 |
+
+## 4. Feature Details and Sequence Diagrams
+
+---
+
+## 4.1 AI Contract Analysis End-to-End
+
+### What it does
+
+When a user clicks Analyze, the system validates ownership, marks contract as PROCESSING, performs AI prevalidation and extraction, validates results, saves structured output, and returns success or failure.
+
+### Key resilience points
+
+- Ownership checks before all sensitive operations
+- Invalid-contract short-circuit based on AI confidence and heuristics
+- Multi-pass retry with correction hints
+- Multi-model fallback
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant U as User
+  participant UI as Contracts UI
+  participant SA as contract.action analyzeContractAction
+  participant CS as ContractService
+  participant NS as NotificationService
+  participant AIS as AIService
+  participant G as Gemini
+  participant DB as Prisma DB
+
+  U->>UI: Click Analyze
+  UI->>SA: analyzeContractAction(contractId)
+  SA->>CS: getById + ownership check
+  SA->>CS: updateStatus(PROCESSING)
+  SA->>NS: create ANALYSIS_STARTED notification
+  SA->>AIS: analyzeContract(fileUrl, userId, fileName)
+  AIS->>G: prevalidation prompt + file
+  G-->>AIS: {isValidContract, confidence, reason}
+  AIS->>G: analysis prompt + file
+  G-->>AIS: analysis JSON/raw text
+  AIS->>AIS: parse, repair if needed, normalize, assert validity
+  AIS-->>SA: NormalizedAnalysis
+  SA->>CS: updateWithAIResults(COMPLETED)
+  CS->>DB: Persist extracted fields + keyPoints + extractedText
+  CS->>NS: checkUpcomingDeadlines(userId)
+  SA->>NS: create ANALYSIS_SUCCESS notification
+  SA-->>UI: success + analyzed contract payload
+```
+
+---
+
+## 4.2 Contract Prevalidation Gate
+
+### What it does
+
+Before expensive extraction, AI classifies whether the uploaded document is actually a contract in any language.
+
+### Decision rules
+
+- Rejects obvious non-contract files (invoices, IDs, blank pages, random images)
+- If parse of prevalidation JSON fails, system defaults to permissive moderate confidence to avoid false negatives due malformed precheck output
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant AIS as AIService
+  participant G1 as Gemini Primary
+  participant G2 as Gemini Fallback
+
+  AIS->>G1: buildPrevalidationPrompt + inline file
+  alt Primary succeeds
+    G1-->>AIS: JSON precheck
+  else Primary fails
+    AIS->>G2: same precheck request
+    G2-->>AIS: JSON precheck
+  end
+  AIS->>AIS: parse precheck JSON
+  alt parse failed
+    AIS-->>AIS: Assume valid with moderate confidence
+  else parsed
+    AIS-->>AIS: Return isValidContract/confidence/reason
+  end
+```
+
+---
+
+## 4.3 Multi-Model Extraction + JSON Repair + Emergency Fallback
+
+### What it does
+
+If extraction output is malformed or incomplete, the service tries progressively stronger recovery paths.
+
+### Recovery layers
+
+1. Primary/Fallback model extraction with strict JSON mime type
+2. Lenient generation (no forced responseMimeType JSON)
+3. JSON repair pass with schema guidance
+4. Emergency field extraction from raw text patterns
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant AIS as AIService
+  participant GP as Gemini Primary
+  participant GF as Gemini Fallback
+
+  AIS->>GP: generate analysis (strict JSON)
+  alt GP success with usable output
+    GP-->>AIS: text
+  else GP fails
+    AIS->>GF: generate analysis (strict JSON)
+    alt GF success
+      GF-->>AIS: text
+    else GF fails
+      AIS->>GP: lenient generation attempt
+      GP-->>AIS: raw text
+    end
+  end
+
+  AIS->>AIS: parseJsonResponse
+  alt parse failed
+    AIS->>GF: repairMalformedJson(originalText, parseError)
+    alt repair success
+      GF-->>AIS: repaired JSON text
+      AIS->>AIS: parse repaired JSON
+    else repair failed
+      AIS->>AIS: emergencyExtractFields(rawText)
+      AIS->>AIS: parse emergency JSON
+    end
+  end
+```
+
+---
+
+## 4.4 Normalization, Validation, and Persistence
+
+### What it does
+
+Raw model output is converted into a strict normalized contract object and validated before DB write.
+
+### Normalization highlights
+
+- Contract type alias mapping into supported enum
+- Date coercion to YYYY-MM-DD
+- Safe string truncation and null handling
+- Premium normalization and bounds
+- Explainability normalization with bounded field lengths and confidence clamping
+- Extracted text cap at 12000 chars
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant AIS as AIService
+  participant N as analysis.normalizer
+  participant V as assertValidContract
+  participant SA as contract.action
+  participant CS as ContractService
+  participant DB as Prisma DB
+
+  AIS->>N: normalizeAnalysis(parsed)
+  N-->>AIS: NormalizedAnalysis
+  AIS->>V: assertValidContract(raw, normalized)
+  alt valid
+    AIS-->>SA: normalized analysis
+    SA->>CS: updateWithAIResults
+    CS->>DB: update contract to COMPLETED
+  else invalid
+    V-->>SA: INVALID_CONTRACT error
+    SA->>CS: markFailed
+  end
+```
+
+---
+
+## 4.5 Explainability Pipeline and UI Interaction
+
+### What it does
+
+The model is instructed to provide extraction evidence per field. The UI renders a compact proof icon near each extracted field and opens a dedicated Field Proof modal with source snippet, metadata, and line-context evidence.
+
+### Explainability object shape
+
+- field
+- why
+- sourceSnippet
+- sourceHints.page
+- sourceHints.section
+- sourceHints.confidence
+
+### UI enhancements implemented
+
+- Field-level proof icon beside core extracted fields (title/provider/policy/dates/premium)
+- Field Proof modal with fixed professional layout (stable regardless of content size)
+- Normalized fuzzy line matching for snippet-to-line mapping in extracted text
+- Fallback to extracted field value when explicit explainability snippet is absent
+- Confidence/page/section metadata surfaced in proof summary chips
+- Line-context panel with explicit quality state (resolved vs fallback evidence)
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant AI as Gemini Extraction
+  participant N as analysis.normalizer
+  participant DB as Prisma DB
+  participant UI as Contracts Details Modal
+  participant User as User
+
+  AI-->>N: keyPoints.explainability[]
+  N->>N: validate/sanitize/trim explainability items
+  N->>DB: persist explainability in keyPoints JSON
+  UI->>DB: fetch contract details (includes keyPoints)
+  DB-->>UI: explainability array
+  User->>UI: Click field proof icon
+  UI->>UI: map field to explainability evidence
+  UI->>UI: normalized fuzzy search in extracted text lines/windows
+  alt line mapping found
+    UI->>UI: show line number + context window
+  else mapping unavailable
+    UI->>UI: show fallback snippet evidence with quality badge
+  end
+```
+
+---
+
+## 4.8 Continuous Learning Pipeline (Safe, No Schema Migration)
+
+### What it does
+
+The system now gets smarter after each completed analysis by persisting learned metadata into `keyPoints.aiMeta`, then reusing it in `buildAdaptiveContext` for future analyses.
+
+### Why this design is safe
+
+- No Prisma schema changes required
+- Uses existing JSON storage (`keyPoints`)
+- Backward compatible with older records
+- If aiMeta is missing, system gracefully falls back to previous behavior
+
+### Learning signals currently used
+
+- Dominant learned languages
+- Frequent key roles (from extracted key people)
+- Most evidenced extracted fields (from explainability)
+- Average explainability confidence score
+- Existing prior signals already used: top contract types/providers/policy patterns/summary length
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant SA as analyzeContractAction
+  participant AIS as AIService
+  participant CS as ContractService
+  participant DB as Prisma DB
+
+  SA->>AIS: analyzeContract(...)
+  AIS-->>SA: normalized analysis + explainability + language/people/contacts
+  SA->>SA: merge aiMeta into keyPoints
+  SA->>CS: updateWithAIResults(keyPoints.aiMeta)
+  CS->>DB: persist COMPLETED contract
+
+  Note over AIS,DB: Next analysis for same user
+  AIS->>DB: fetch last completed examples with keyPoints
+  AIS->>AIS: derive adaptive learning signals from aiMeta + explainability
+  AIS->>AIS: inject enriched adaptive context into next analysis prompt
+```
+
+---
+
+## 4.6 Multilingual Contract Q&A
+
+### What it does
+
+Users ask follow-up questions about a selected contract. The AI answers in the contract language using extracted fields, key points, and extracted text context.
+
+### Behavior highlights
+
+- Language-aware response instruction (en, fr, de, es, it, pt, nl, pl, ja, zh, ar)
+- Contract-type-specific guidance for domain emphasis
+- Output sanitization strips markdown artifacts
+- Fallback across configured model list
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant U as User
+  participant UI as Ask Modal
+  participant SA as askContractQuestionAction
+  participant CS as ContractService
+  participant AIS as AIService
+  participant G as Gemini
+
+  U->>UI: Ask question
+  UI->>SA: askContractQuestionAction(contractId, question)
+  SA->>CS: getById + ownership check
+  SA->>AIS: askAboutContract(question, contractContext)
+  AIS->>AIS: determine language + type guidance
+  AIS->>G: Q&A prompt with metadata, summary, keyPoints, extracted text
+  G-->>AIS: answer text
+  AIS->>AIS: sanitize formatting artifacts
+  AIS-->>SA: final answer
+  SA-->>UI: answer
+```
+
+---
+
+## 4.7 AI-Derived Deadline Notifications
+
+### What it does
+
+After successful AI extraction and save, reminder notifications are generated from extracted contract end date.
+
+### Reminder policy
+
+- 30 days: CRITICAL
+- 15 days: WARNING
+- 7 days: URGENT
+- Duplicate prevention based on recent existing reminder action type
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant SA as analyzeContractAction
+  participant CS as ContractService
+  participant NS as NotificationService
+  participant DB as Prisma DB
+
+  SA->>CS: updateWithAIResults(COMPLETED)
+  CS->>NS: checkUpcomingDeadlines(userId)
+  NS->>DB: find COMPLETED contracts with endDate
+  loop each contract
+    NS->>NS: compute daysUntilExpiration
+    alt day is 30/15/7 and no duplicate today
+      NS->>DB: create DEADLINE notification
+    end
+  end
+  NS-->>CS: created count summary
+```
+
+## 5. Data Contracts
+
+### 5.1 Normalized Analysis (core)
+
+- title
+- type
+- provider
+- policyNumber
+- startDate
+- endDate
+- premium
+- summary
+- extractedText
+- keyPoints (guarantees, exclusions, franchise, importantDates, explainability)
+- language
+- keyPeople
+- contactInfo
+- importantContacts
+- relevantDates
+
+### 5.2 Explainability Item
+
+- field: extracted field identifier
+- why: concise reasoning sentence
+- sourceSnippet: quoted support from document
+- sourceHints: page/section/confidence for audit context
+
+## 6. Security and Guardrails
+
+- Ownership validation before analyze and ask operations
+- Contract validity checks to reject unrelated uploads
+- Bounded extracted text and structured truncation to reduce prompt and storage risk
+- Retry and fallback paths to reduce failure rate without unsafe assumptions
+- Missing-notification-table safe handling in notification service
+
+## 7. Failure Modes and Handling
+
+### 7.1 Non-contract file
+
+- Outcome: analysis fails with INVALID_CONTRACT code
+- User feedback: explicit invalid contract reason
+
+### 7.2 Malformed AI JSON
+
+- Outcome: repair pass, then emergency extraction fallback
+- User impact: improved completion rate with bounded quality fallback
+
+### 7.3 Model/API/key issues
+
+- Outcome: explicit error messages for API key/model configuration
+
+### 7.4 Notification table missing
+
+- Outcome: notification operations degrade gracefully without blocking core contract workflow
+
+## 8. UX Features for Explainability and Compliance
+
+- Proof icon per extracted field for one-click transparency
+- Professional Field Proof modal with fixed sections and stable dimensions
+- Fuzzy snippet-to-line mapping to reduce unresolved line cases
+- Deterministic field-specific matching before fuzzy mode (especially for dates)
+- Fallback evidence mode when OCR/formatting prevents exact line resolution
+- Confidence/page/section metadata chips for compliance readability
+- Extracted snippets section with search and field reference tags
+
+## 9. Test Plan (Step-by-Step)
+
+### 9.1 Field Proof Resolution
+
+1. Upload and analyze a contract with clear dates/amounts.
+2. Open Details modal.
+3. Click proof icon next to `Title`, `End Date`, or `Premium`.
+4. Verify Field Proof modal opens with line/page/section/confidence chips.
+5. Verify line context appears with numbered rows and a marker on matched line.
+
+### 9.2 Snippet Search Box
+
+1. In the `Extracted Text Snippets` section, type a keyword (for example `premium`, `TND`, `2044`, `endDate`).
+2. Verify only matching snippets remain visible.
+3. Clear the search and verify all snippets return.
+
+### 9.3 Fallback Evidence Mode
+
+1. Test with a contract where OCR quality is noisy or formatting is table-heavy.
+2. Click field proof icon for a difficult field.
+3. Verify modal still shows exact source snippet with a fallback quality badge.
+4. Verify user still receives proof even when exact line number is unavailable.
+
+### 9.4 Layout Consistency
+
+1. Open field proof for short and very long snippets.
+2. Verify modal section heights remain visually consistent.
+3. Verify metadata chips keep a stable grid layout across content lengths.
+
+### 9.5 Continuous Learning (AI Gets Smarter Over Time)
+
+1. Analyze at least 3 contracts from the same provider or domain.
+2. Analyze a 4th similar contract.
+3. Verify extraction quality improves in consistency for:
+
+- provider naming style
+- policy number patterns
+- detected language and role patterns
+- evidence confidence on common fields
+
+4. In server logs, confirm adaptive context includes learned indicators (languages/evidenced fields/roles/confidence).
+
+### 9.6 Multilingual Q&A Consistency
+
+1. Analyze a non-English contract (for example French).
+2. Ask a question in Ask modal.
+3. Verify answer is in contract language and aligned to extracted context.
+
+## 10. Suggested Operational Checks
+
+- Run build after AI prompt or normalizer changes
+- Spot-check at least one document per supported major language
+- Verify explainability has non-empty source snippets for key fields
+- Verify deadline notifications for synthetic end dates at 30/15/7 days
+- Validate ask flow stays in detected contract language
+
+## 11. File Index
+
+- lib/actions/contract.action.ts
+- lib/services/ai.service.ts
+- lib/services/ai/analysis.prompt.ts
+- lib/services/ai/analysis.normalizer.ts
+- lib/services/ai/analysis.types.ts
+- lib/services/contract.service.ts
+- lib/services/notification.service.ts
+- components/views/dashboard/contracts-list.tsx
+- types/contract.types.ts
--- a/SOLID_REFACTOR_REPORT.md
+++ b/SOLID_REFACTOR_REPORT.md
@@ -0,0 +1,33 @@
+# FSD & SOLID Refactoring Report
+
+## 1. What I Did (Project-Wide Structural Migration)
+
+1. **Abolished Global "Bucket" Folders:** I completely migrated all files out of generic structural folders (`/components/views` and `/lib/actions`).
+2. **Designed a Domain-Driven Architecture (FSD):** Created an entire structural blueprint separating components by their core business area into a new `/features/` directory architecture.
+3. **Decentralized Backend Logistics:** I took top-level database `server_actions` (`contract.action.ts`, `notification.action.ts`, etc.) and relocated them entirely under the purview of their specific domain (e.g., `/features/contracts/api/contract.action.ts`).
+4. **Abstracted Shared Layouts:** I isolated global UI architecture (Sidebars & Top Navigations) into a dedicated generic `/components/layout/` directory.
+5. **Applied the Single Responsibility Principle:** Eliminated massive chunks of code from the "God File" (`contracts-list.tsx`). Abstracted over 300+ lines of monolithic JSX code defining the complicated **Chatbot Assessment Modal** and **Field Proof Verification Modal**.
+6. **Encapsulated Complex State:** Stripped out isolated React states (`question`, `isAsking`, `messages`) from `contracts-list.tsx`'s scope into `ContractChatModal`.
+
+## 2. Why I Did It
+
+The project was structured by technological type (`views`, `actions`, `pages`) instead of business domains (Contracts, Notifications, Analytics). 
+
+**The consequence of tech-centric folders:**
+- When a developer wanted to change how a single chart works, they had to hop between `/app/dashboard/page.tsx` (Route), `/components/views/dashboard/charts.tsx` (UI), and `/lib/actions/stats.action.ts` (Database logic). 
+- Changing `contracts-list.tsx` was incredibly dangerous; it had ballooned to 2,000 lines because all database actions, list management, and distinct heavy UI Modals were bundled recursively. This caused excessive Time To Interactive (TTI) Virtual DOM lag, where opening the chatbot inside the list triggered state updates scaling to all 100 rendered table rows repeatedly.
+
+## 3. The Developer Benefits
+
+### 1. Immense Performance Gains (Virtual DOM Efficiency)
+Because internal UI state (like typing inside the chat) is isolated strictly to the new `ContractChatModal` component wrapper, keystrokes no longer force the virtual DOM to evaluate data bound to the contracts table. TTI is radically lower.
+
+### 2. High Cohesion & Loose Coupling
+Under the new `/features/` domains, every business unit is entirely self-sufficient. 
+If an engineer needs to overhaul the Analytics feature to use a different database provider, they perform 100% of their coding inside `/features/analytics`. They will never accidentally break routing on `/features/contracts`, because they physically aren't interacting with shared central files.
+
+### 3. Maximum Reusability (Open/Closed Principle)
+Since Modals and Actions are now completely unchained from specific parent hierarchies, you can reuse the complex UI flows anywhere natively. If a Mobile App route needs access to `Contract Status charts`, it imports them from `/features/analytics/components/charts.tsx` with zero duplication.
+
+### 4. Zero Merge Conflicts
+Multiple developers can reliably build completely different modules simultaneously without fighting over massive shared state stores in generic global files.
--- a/app/(dashboard)/contacts/layout.tsx
+++ b/app/(dashboard)/contacts/layout.tsx
@@ -1,5 +1,11 @@
 import { redirect } from "next/navigation";
 import { auth } from "@clerk/nextjs/server";
+import { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Contracts | LexiChain",
+  description: "Upload, manage, and analyze your financial contracts with LexiChain's AI.",
+};

 export default async function ContactsLayout({
  children,
--- a/app/(dashboard)/contacts/page.tsx
+++ b/app/(dashboard)/contacts/page.tsx
@@ -1,11 +1,11 @@
 "use client";

-import { ContractUploadForm } from "@/components/views/dashboard/contract-upload-form";
-import { EmptyContractsState } from "@/components/views/dashboard/empty-contracts-state";
-import { ContractsList } from "@/components/views/dashboard/contracts-list";
-import { ContactsHeader } from "@/components/views/dashboard/contacts-header";
+import { ContractUploadForm } from "@/features/contracts/components/forms/contract-upload-form";
+import { EmptyContractsState } from "@/features/contracts/components/list/empty-contracts-state";
+import { ContractsList } from "@/features/contracts/components/list/contracts-list";
+import { ContactsHeader } from "@/components/layout/contacts-header";
 import { useState, useEffect } from "react";
-import { getContracts } from "@/lib/actions/contract.action";
+import { getContracts } from "@/features/contracts/api/contract.action";
 import { Card } from "@/components/ui/card";

 export default function ContactsPage() {
--- a/app/(dashboard)/dashboard/page.tsx
+++ b/app/(dashboard)/dashboard/page.tsx
@@ -19,13 +19,14 @@ import {
 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Card } from "@/components/ui/card";
-import { getStatsAction } from "@/lib/actions/stats.action";
-import { checkDeadlineNotifications } from "@/lib/actions/notification.action";
-import {
-  ContractStatusChart,
-  ContractTypeChart,
-  TrendChart,
-} from "@/components/views/dashboard/charts";
+import { getStatsAction } from "@/features/analytics/api/stats.action";
+import { checkDeadlineNotifications } from "@/features/notifications/api/notification.action";
+import dynamic from "next/dynamic";
+
+// Dynamically import heavy charting libraries to dramatically improve initial load and rendering time
+const ContractStatusChart = dynamic(() => import("@/features/analytics/components/charts").then(mod => mod.ContractStatusChart), { ssr: false, loading: () => <div className="h-full w-full animate-pulse bg-muted/30 rounded-lg"></div> });
+const ContractTypeChart = dynamic(() => import("@/features/analytics/components/charts").then(mod => mod.ContractTypeChart), { ssr: false, loading: () => <div className="h-full w-full animate-pulse bg-muted/30 rounded-lg"></div> });
+const TrendChart = dynamic(() => import("@/features/analytics/components/charts").then(mod => mod.TrendChart), { ssr: false, loading: () => <div className="h-full w-full animate-pulse bg-muted/30 rounded-lg"></div> });

 interface DashboardStats {
  totalContracts: number;
--- a/app/(dashboard)/layout.tsx
+++ b/app/(dashboard)/layout.tsx
@@ -1,6 +1,12 @@
 import { auth } from "@clerk/nextjs/server";
 import { redirect } from "next/navigation";
-import { DashboardNavigation } from "@/components/views/dashboard/navigation";
+import { DashboardNavigation } from "@/components/layout/navigation";
+import { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Dashboard | LexiChain Contract Intelligence",
+  description: "View and manage your AI-processed financial contracts, analytics, and metrics in real time.",
+};

 export default async function DashboardLayout({
  children,
--- a/app/globals.css
+++ b/app/globals.css
@@ -123,6 +123,60 @@
  :focus-visible {
    @apply outline-none ring-2 ring-primary ring-offset-2;
  }
+
+  /* Global branded scrollbar */
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: hsl(var(--primary) / 0.65) hsl(var(--muted));
+  }
+
+  *::-webkit-scrollbar {
+    width: 11px;
+    height: 11px;
+  }
+
+  *::-webkit-scrollbar-track {
+    background: linear-gradient(
+      180deg,
+      hsl(var(--muted)) 0%,
+      hsl(var(--background)) 100%
+    );
+    border-radius: 999px;
+  }
+
+  *::-webkit-scrollbar-thumb {
+    background: linear-gradient(
+      180deg,
+      hsl(var(--primary) / 0.85) 0%,
+      hsl(var(--secondary) / 0.8) 100%
+    );
+    border: 2px solid hsl(var(--background));
+    border-radius: 999px;
+  }
+
+  *::-webkit-scrollbar-thumb:hover {
+    background: linear-gradient(
+      180deg,
+      hsl(var(--primary)) 0%,
+      hsl(var(--accent) / 0.95) 100%
+    );
+  }
+
+  .dark * {
+    scrollbar-color: hsl(var(--primary) / 0.8) hsl(var(--muted));
+  }
+
+  .dark *::-webkit-scrollbar-track {
+    background: linear-gradient(
+      180deg,
+      hsl(var(--muted)) 0%,
+      hsl(var(--background) / 0.92) 100%
+    );
+  }
+
+  .dark *::-webkit-scrollbar-thumb {
+    border-color: hsl(var(--background));
+  }
 }

@layer utilities {
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,4 +1,14 @@
-import { HomePage } from "@/components/views/Home/HomePage";
+import { Metadata } from "next";
+import { HomePage } from "@/features/home/components/HomePage";
+
+export const metadata: Metadata = {
+  title: "LexiChain | AI-Powered Fast Contract Management",
+  description: "Accelerate your BFSI contract management with AI. LexiChain is the premier blockchain-verified platform for smart contracts, loans, and insurance.",
+  openGraph: {
+    title: "LexiChain | AI-Powered Fast Contract Management",
+    description: "Accelerate your BFSI contract management with AI. LexiChain is the premier blockchain-verified platform for smart contracts, loans, and insurance.",
+  }
+};

 export default function Home() {
  return <HomePage />;
--- a/components/views/dashboard/contacts-header.tsx
+++ b/components/views/dashboard/contacts-header.tsx
@@ -8,7 +8,7 @@ import { BackgroundBeams } from "@/components/ui/background-beams";
 export function ContactsHeader() {
  return (
    <div className="border-b border-border/50 bg-background/80 backdrop-blur-sm">
-      <BackgroundBeams className="opacity-70" />
+      <BackgroundBeams className="opacity-80" />
      <div className="max-w-7xl mx-auto px-6 py-8 space-y-6">
        <Link
          href="/dashboard"
--- a/components/views/dashboard/navigation.tsx
+++ b/components/views/dashboard/navigation.tsx
@@ -9,7 +9,7 @@ import { SignOutButton, UserButton } from "@clerk/nextjs";
 import { motion } from "motion/react";
 import Image from "next/image";
 import { ModeToggle } from "@/components/ui/mode-toggle";
-import NotificationBar from "./notification-bar";
+import NotificationBar from "@/features/notifications/components/notification-bar";

 interface NavItem {
  href: string;
--- a/components/views/dashboard/contracts-list.tsx
+++ b/components/views/dashboard/contracts-list.tsx
--- a/features/analytics/api/stats.action.ts
+++ b/features/analytics/api/stats.action.ts
--- a/features/analytics/components/charts.tsx
+++ b/features/analytics/components/charts.tsx
--- a/features/auth/api/user.action.ts
+++ b/features/auth/api/user.action.ts
--- a/features/contracts/api/contract.action.ts
+++ b/features/contracts/api/contract.action.ts
@@ -134,6 +134,7 @@ export async function getContracts(filters?: Record<string, unknown>) {
        : null,
      summary: contract.summary || null,
      keyPoints: contract.keyPoints || null,
+      extractedText: contract.extractedText || null,
    }));

    return { success: true, contracts: serializedContracts };
@@ -358,9 +359,25 @@ export async function analyzeContractAction(id: string) {
      };
    }

+    // Persist AI learning metadata inside keyPoints JSON so future analyses can adapt
+    // without requiring DB schema changes.
+    const keyPointsWithLearning = {
+      ...(aiResults.keyPoints ?? {}),
+      aiMeta: {
+        language: (aiResults as any).language ?? null,
+        keyPeople: (aiResults as any).keyPeople ?? [],
+        contactInfo: (aiResults as any).contactInfo ?? null,
+        importantContacts: (aiResults as any).importantContacts ?? [],
+        relevantDates: (aiResults as any).relevantDates ?? [],
+        premiumCurrency: (aiResults as any).premiumCurrency ?? null,
+        learnedAt: new Date().toISOString(),
+      },
+    };
+
    // Save AI results to database (convert nulls to undefined for optional fields)
    await ContractService.updateWithAIResults(id, {
      ...aiResults,
+      keyPoints: keyPointsWithLearning,
      provider: aiResults.provider ?? undefined,
      policyNumber: aiResults.policyNumber ?? undefined,
      startDate: aiResults.startDate ?? undefined,
@@ -516,6 +533,7 @@ export async function askContractQuestionAction(id: string, question: string) {
        keyPoints:
          (contract.keyPoints as Record<string, unknown> | null) ?? null,
        extractedText: contract.extractedText,
+        language: (contract.keyPoints as any)?.aiMeta?.language ?? null,
      },
    });

--- a/features/contracts/components/forms/contract-upload-form.tsx
+++ b/features/contracts/components/forms/contract-upload-form.tsx
@@ -3,7 +3,7 @@
 import { UploadDropzone } from "@uploadthing/react";
 import { AlertCircle, Sparkles, Wand2, ShieldCheck } from "lucide-react";
 import { Card } from "@/components/ui/card";
-import { saveContract } from "@/lib/actions/contract.action";
+import { saveContract } from "@/features/contracts/api/contract.action";
 import { toast } from "sonner";
 import type { OurFileRouter } from "@/lib/upload";
 import { useRouter } from "next/navigation";
--- a/features/contracts/components/list/contracts-list.tsx
+++ b/features/contracts/components/list/contracts-list.tsx
--- a/features/contracts/components/list/empty-contracts-state.tsx
+++ b/features/contracts/components/list/empty-contracts-state.tsx
--- a/features/contracts/components/modals/contract-chat-modal.tsx
+++ b/features/contracts/components/modals/contract-chat-modal.tsx
@@ -0,0 +1,215 @@
+"use client";
+
+import { useState } from "react";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { MessageSquare, Briefcase, Scale, Bot, User, Loader2, Send } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { askContractQuestionAction } from "@/features/contracts/api/contract.action";
+
+interface Contract {
+  id: string;
+  fileName: string;
+}
+
+interface ChatMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+interface ContractChatModalProps {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  contract: Contract | null;
+  renderRichParagraphs: (text: string, prefix: string) => React.ReactNode[];
+}
+
+export function ContractChatModal({
+  isOpen,
+  onOpenChange,
+  contract,
+  renderRichParagraphs,
+}: ContractChatModalProps) {
+  const [question, setQuestion] = useState("");
+  const [isAsking, setIsAsking] = useState(false);
+  const [messages, setMessages] = useState<ChatMessage[]>([
+    {
+      role: "assistant",
+      content: "Ask me anything about this contract. I will answer based on the file analysis.",
+    },
+  ]);
+
+  const quickQuestions = [
+    "What are the main obligations and deadlines?",
+    "What are the non-compliance risks under general EU/US principles?",
+    "What are the most important exclusions and liabilities?",
+  ];
+
+  const handleAskQuestion = async () => {
+    if (!contract) return;
+
+    const trimmedQuestion = question.trim();
+    if (!trimmedQuestion) return;
+
+    setMessages((prev) => [...prev, { role: "user", content: trimmedQuestion }]);
+    setQuestion("");
+    setIsAsking(true);
+
+    try {
+      const result = await askContractQuestionAction(contract.id, trimmedQuestion);
+
+      if (result.success && result.answer) {
+        setMessages((prev) => [...prev, { role: "assistant", content: result.answer as string }]);
+      } else {
+        const errorMessage = result.error || "Failed to get AI response";
+        setMessages((prev) => [...prev, { role: "assistant", content: `Error: ${errorMessage}` }]);
+      }
+    } catch (error) {
+      const fallbackMessage = error instanceof Error ? error.message : "Unknown error occurred";
+      setMessages((prev) => [...prev, { role: "assistant", content: `Error: ${fallbackMessage}` }]);
+    } finally {
+      setIsAsking(false);
+    }
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[90vh] max-w-2xl overflow-y-auto border-border/60 bg-[radial-gradient(circle_at_top_right,hsl(var(--primary)/0.18),transparent_40%),radial-gradient(circle_at_bottom_left,hsl(var(--secondary)/0.12),transparent_45%)]">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <MessageSquare className="w-5 h-5" />
+            Ask About This File
+          </DialogTitle>
+        </DialogHeader>
+
+        {contract && (
+          <div className="space-y-4">
+            <div className="rounded-2xl border border-white/20 dark:border-white/10 bg-background/40 p-4 shadow-xl backdrop-blur-xl ring-1 ring-black/5 dark:ring-white/5 transition-all duration-500 hover:shadow-primary/5 hover:border-primary/20">
+              <div className="flex items-start justify-between gap-4">
+                <div className="min-w-0">
+                  <p className="text-xs uppercase tracking-[0.14em] text-muted-foreground">
+                    Contract Intelligence Assistant
+                  </p>
+                  <p className="text-sm font-medium truncate mt-1">{contract.fileName}</p>
+                </div>
+                <div className="flex items-center gap-2 text-xs">
+                  <span className="inline-flex items-center gap-1 rounded-full border border-border/70 bg-muted/30 px-2 py-1">
+                    <Briefcase className="w-3.5 h-3.5" />
+                    Business
+                  </span>
+                  <span className="inline-flex items-center gap-1 rounded-full border border-border/70 bg-muted/30 px-2 py-1">
+                    <Scale className="w-3.5 h-3.5" />
+                    Legal Context
+                  </span>
+                </div>
+              </div>
+            </div>
+
+            <div className="space-y-2">
+              <p className="text-xs text-muted-foreground">Quick prompts</p>
+              <div className="flex flex-wrap gap-2">
+                {quickQuestions.map((quickQuestion) => (
+                  <Button
+                    key={quickQuestion}
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    disabled={isAsking}
+                    onClick={() => setQuestion(quickQuestion)}
+                    className="border-primary/25 bg-background/80 text-xs hover:border-primary/50 hover:bg-primary/10"
+                  >
+                    {quickQuestion}
+                  </Button>
+                ))}
+              </div>
+            </div>
+
+            <div className="h-80 space-y-3 overflow-y-auto rounded-2xl border border-white/10 bg-black/5 dark:bg-white/5 p-4 shadow-inner backdrop-blur-md">
+              {messages.map((message, index) => (
+                <div
+                  key={index}
+                  className={`flex ${message.role === "user" ? "justify-end" : "justify-start"}`}
+                >
+                  <div className="flex max-w-[88%] items-start gap-2">
+                    {message.role === "assistant" && (
+                      <span className="mt-1 inline-flex h-7 w-7 items-center justify-center rounded-full border border-border/60 bg-muted/40 text-muted-foreground">
+                        <Bot className="h-4 w-4" />
+                      </span>
+                    )}
+                    <div
+                      className={`rounded-2xl px-3 py-2 text-sm whitespace-pre-wrap break-words shadow-sm transition-all duration-300 hover:shadow-md ${
+                        message.role === "user"
+                          ? "bg-gradient-to-r from-primary to-accent text-primary-foreground shadow-primary/25"
+                          : "border border-white/20 dark:border-white/10 bg-white/50 dark:bg-black/50 backdrop-blur-md shadow-[0_4px_30px_rgba(0,0,0,0.05)]"
+                      }`}
+                    >
+                      {message.role === "assistant"
+                        ? renderRichParagraphs(message.content, `chat-assistant-${index}`)
+                        : message.content}
+                    </div>
+                    {message.role === "user" && (
+                      <span className="mt-1 inline-flex h-7 w-7 items-center justify-center rounded-full border border-primary/25 bg-primary/10 text-primary">
+                        <User className="h-4 w-4" />
+                      </span>
+                    )}
+                  </div>
+                </div>
+              ))}
+              {isAsking && (
+                <div className="flex justify-start">
+                  <div className="flex items-center gap-2 rounded-2xl border border-border/70 bg-background px-3 py-2 text-sm shadow-sm">
+                    <span className="inline-flex h-6 w-6 items-center justify-center rounded-full border border-border/60 bg-muted/30 text-muted-foreground">
+                      <Bot className="h-3.5 w-3.5" />
+                    </span>
+                    <Loader2 className="w-4 h-4 animate-spin" />
+                    Preparing a professional legal-business answer...
+                  </div>
+                </div>
+              )}
+            </div>
+
+            <div className="space-y-2">
+              <Textarea
+                value={question}
+                onChange={(event) => setQuestion(event.target.value)}
+                placeholder="Ask about obligations, liabilities, legal exposure, compliance risks, or business impact..."
+                rows={3}
+                disabled={isAsking}
+                className="rounded-2xl border-white/20 dark:border-white/10 bg-background/50 backdrop-blur-md focus:bg-background/80 transition-all duration-300 shadow-inner"
+                onKeyDown={(event) => {
+                  if (event.key === "Enter" && !event.shiftKey && !isAsking && question.trim()) {
+                    event.preventDefault();
+                    void handleAskQuestion();
+                  }
+                }}
+              />
+              <div className="flex justify-end">
+                <Button
+                  onClick={handleAskQuestion}
+                  disabled={isAsking || !question.trim()}
+                  className="gap-2 bg-gradient-to-r from-primary to-accent text-white shadow-md hover:from-primary/90 hover:to-accent/90"
+                >
+                  {isAsking ? (
+                    <>
+                      <Loader2 className="w-4 h-4 animate-spin" />
+                      Sending...
+                    </>
+                  ) : (
+                    <>
+                      <Send className="w-4 h-4" />
+                      Send
+                    </>
+                  )}
+                </Button>
+              </div>
+            </div>
+
+            <p className="text-[11px] text-muted-foreground">
+              Tip: press Enter to send, Shift+Enter for a new line.
+            </p>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
--- a/features/contracts/components/modals/contract-proof-modal.tsx
+++ b/features/contracts/components/modals/contract-proof-modal.tsx
@@ -0,0 +1,157 @@
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Info } from "lucide-react";
+
+interface ProofData {
+  fieldKey: string;
+  field: string;
+  sourceSnippet: string;
+  confidence: number | null;
+  page: string | null;
+  section: string | null;
+  lineNumber: number | null;
+  contextStartLine: number | null;
+  context: string[];
+  resolutionMode: "exact" | "fuzzy" | "fallback";
+}
+
+interface ContractProofModalProps {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  proofData: ProofData | null;
+}
+
+export function ContractProofModal({
+  isOpen,
+  onOpenChange,
+  proofData,
+}: ContractProofModalProps) {
+  return (
+    <Dialog open={isOpen} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[92vh] max-w-5xl overflow-y-auto border-border/60 bg-[radial-gradient(circle_at_top_right,hsl(var(--primary)/0.16),transparent_38%),radial-gradient(circle_at_bottom_left,hsl(var(--secondary)/0.12),transparent_42%)]">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Info className="h-5 w-5 text-primary" />
+            Field Proof
+          </DialogTitle>
+        </DialogHeader>
+
+        {proofData && (
+          <div className="space-y-4">
+            <div className="rounded-3xl border border-white/20 dark:border-white/10 bg-background/40 p-5 shadow-2xl backdrop-blur-2xl ring-1 ring-black/5 dark:ring-white/5 md:p-6 transition-all duration-500 hover:shadow-primary/5 hover:border-primary/20">
+              <div className="grid auto-rows-fr gap-2 sm:grid-cols-2 xl:grid-cols-5">
+                <div className="rounded-xl border border-primary/25 bg-primary/10 px-2.5 py-2">
+                  <p className="text-[10px] uppercase tracking-wide text-primary/80">
+                    Field
+                  </p>
+                  <p className="mt-1 text-xs font-semibold text-primary truncate">
+                    {proofData.field}
+                  </p>
+                </div>
+                <div className="rounded-xl border border-border/60 bg-muted/30 px-2.5 py-2">
+                  <p className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                    Line
+                  </p>
+                  <p className="mt-1 text-xs font-semibold text-foreground">
+                    {proofData.lineNumber ?? "Not found"}
+                  </p>
+                </div>
+                <div className="rounded-xl border border-border/60 bg-muted/30 px-2.5 py-2">
+                  <p className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                    Page
+                  </p>
+                  <p className="mt-1 text-xs font-semibold text-foreground truncate">
+                    {proofData.page ?? "N/A"}
+                  </p>
+                </div>
+                <div className="rounded-xl border border-border/60 bg-muted/30 px-2.5 py-2">
+                  <p className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                    Section
+                  </p>
+                  <p className="mt-1 text-xs font-semibold text-foreground truncate">
+                    {proofData.section ?? "N/A"}
+                  </p>
+                </div>
+                <div className="rounded-xl border border-border/60 bg-muted/30 px-2.5 py-2">
+                  <p className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                    Confidence
+                  </p>
+                  <p className="mt-1 text-xs font-semibold text-foreground">
+                    {proofData.confidence ?? "N/A"}
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            <div className="rounded-3xl border border-white/20 dark:border-white/10 bg-background/40 p-5 shadow-2xl backdrop-blur-2xl ring-1 ring-black/5 dark:ring-white/5 md:p-6 transition-all duration-500 hover:shadow-primary/5 hover:border-primary/20">
+              <p className="text-xs font-semibold uppercase tracking-[0.12em] text-muted-foreground">
+                Exact Source Snippet
+              </p>
+              <div className="mt-2 min-h-[92px] rounded-xl border border-border/60 bg-muted/20 px-3 py-2 text-sm italic text-muted-foreground whitespace-pre-wrap break-words">
+                “{proofData.sourceSnippet}”
+              </div>
+            </div>
+
+            <div className="rounded-3xl border border-white/20 dark:border-white/10 bg-background/40 p-5 shadow-2xl backdrop-blur-2xl ring-1 ring-black/5 dark:ring-white/5 md:p-6 transition-all duration-500 hover:shadow-primary/5 hover:border-primary/20">
+              <div className="flex items-center justify-between gap-2">
+                <p className="text-xs font-semibold uppercase tracking-[0.12em] text-muted-foreground">
+                  Contract Lines Context
+                </p>
+                <span
+                  className={`rounded-md border px-2 py-1 text-[10px] font-medium ${
+                    proofData.context.length > 0 && proofData.lineNumber
+                      ? "border-emerald-500/25 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300"
+                      : "border-amber-500/25 bg-amber-500/10 text-amber-700 dark:text-amber-300"
+                  }`}
+                >
+                  {proofData.context.length > 0 && proofData.lineNumber
+                    ? "Resolved from extracted text"
+                    : "Fallback snippet evidence"}
+                </span>
+              </div>
+
+              {proofData.context.length > 0 && proofData.contextStartLine ? (
+                <div className="mt-2 h-[320px] overflow-auto rounded-xl border border-border/60 bg-muted/20">
+                  <pre className="p-3 text-xs leading-6 text-muted-foreground whitespace-pre-wrap break-words">
+                    {proofData.context.map((line, idx) => {
+                      const currentLineNumber =
+                        proofData.contextStartLine! + idx;
+                      const isMatch =
+                        proofData.lineNumber === currentLineNumber;
+                      return (
+                        <span
+                          key={idx}
+                          className={
+                            isMatch ? "font-bold text-primary block" : "block"
+                          }
+                        >
+                          {String(currentLineNumber).padStart(4, " ")} | {line}
+                        </span>
+                      );
+                    })}
+                  </pre>
+                </div>
+              ) : (
+                <div className="mt-2 h-[320px] rounded-xl border border-border/60 bg-muted/20 px-4 py-3 text-sm text-muted-foreground">
+                  <p>
+                    Precise line mapping is unavailable for this field. The
+                    quoted snippet remains the verified AI evidence.
+                  </p>
+                  <p className="mt-2 text-xs text-muted-foreground/80">
+                    This usually happens when OCR compressed multiple lines,
+                    formatting changed, or the source value appears in a
+                    table-like structure.
+                  </p>
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
--- a/features/home/components/Features.tsx
+++ b/features/home/components/Features.tsx
--- a/features/home/components/Footer.tsx
+++ b/features/home/components/Footer.tsx
--- a/features/home/components/Hero.tsx
+++ b/features/home/components/Hero.tsx
--- a/features/home/components/HomePage.tsx
+++ b/features/home/components/HomePage.tsx
@@ -1,15 +1,18 @@
 "use client";

 import { useEffect, useState } from "react";
-import { Navbar } from "@/components/views/Home/Navbar";
-import { Hero } from "@/components/views/Home/Hero";
-import { Features } from "@/components/views/Home/Features";
-import { HowItWorks } from "@/components/views/Home/HowItWorks";
-import { Stats } from "@/components/views/Home/Stats";
-import { Footer } from "@/components/views/Home/Footer";
+import { Navbar } from "@/features/home/components/Navbar";
+import { Hero } from "@/features/home/components/Hero";
+import dynamic from "next/dynamic";
 import { Button } from "@/components/ui/button";
 import { Sparkles } from "lucide-react";

+// Dynamically load below-the-fold components to improve initial response time and rendering speed
+const Features = dynamic(() => import("@/features/home/components/Features").then(mod => mod.Features), { ssr: true });
+const HowItWorks = dynamic(() => import("@/features/home/components/HowItWorks").then(mod => mod.HowItWorks), { ssr: true });
+const Stats = dynamic(() => import("@/features/home/components/Stats").then(mod => mod.Stats), { ssr: true });
+const Footer = dynamic(() => import("@/features/home/components/Footer").then(mod => mod.Footer), { ssr: true });
+
 function LoadingScreen({ onComplete }: { onComplete: () => void }) {
  const [progress, setProgress] = useState(0);

@@ -130,12 +133,9 @@ export function HomePage() {
    setIsLoading(false);
  };

-  if (isLoading) {
-    return <LoadingScreen onComplete={handleLoadingComplete} />;
-  }
-
  return (
    <div className="relative min-h-screen bg-background text-foreground overflow-x-hidden">
+      {isLoading && <LoadingScreen onComplete={handleLoadingComplete} />}
      <ScrollProgressBar />

      <Navbar />
--- a/features/home/components/HowItWorks.tsx
+++ b/features/home/components/HowItWorks.tsx
--- a/features/home/components/Navbar.tsx
+++ b/features/home/components/Navbar.tsx
--- a/features/home/components/Stats.tsx
+++ b/features/home/components/Stats.tsx
--- a/features/notifications/api/notification.action.ts
+++ b/features/notifications/api/notification.action.ts
@@ -80,7 +80,10 @@ export async function getNotifications(limit: number = 10) {
      };
    }

-    // Step 3: Fetch unread notifications
+    // Step 3: Enforce cleanup policy for seen non-deadline notifications
+    await NotificationService.cleanupReadNonDeadline(user.id);
+
+    // Step 4: Fetch unread notifications
    const result = await NotificationService.getUnread(user.id, limit);

    return result;
@@ -128,6 +131,8 @@ export async function getAllNotifications(limit: number = 50) {
      };
    }

+    await NotificationService.cleanupReadNonDeadline(user.id);
+
    const result = await NotificationService.getAll(user.id, limit);

    return result;
@@ -180,6 +185,8 @@ export async function getUnreadNotificationCount() {
      };
    }

+    await NotificationService.cleanupReadNonDeadline(user.id);
+
    const result = await NotificationService.getUnreadCount(user.id);

    return result;
@@ -301,6 +308,47 @@ export async function markAllNotificationsAsRead() {
  }
 }

+/**
+ * Force cleanup of seen non-deadline notifications for current user.
+ * Useful as a maintenance endpoint from UI hooks.
+ */
+export async function cleanupSeenNotifications() {
+  try {
+    const { userId: clerkId } = await auth();
+
+    if (!clerkId) {
+      return {
+        success: false,
+        error: "Unauthorized",
+      };
+    }
+
+    const user = await ContractService.getUserByClerkId(clerkId);
+
+    if (!user) {
+      return {
+        success: false,
+        error: "User not found",
+      };
+    }
+
+    return await NotificationService.cleanupReadNonDeadline(user.id);
+  } catch (error: unknown) {
+    if (isNotificationTableMissingError(error)) {
+      return {
+        success: true,
+        data: { count: 0 },
+      };
+    }
+
+    console.error("Cleanup seen notifications error:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
 /**
 * Deletes a notification
 *
--- a/features/notifications/components/notification-bar.tsx
+++ b/features/notifications/components/notification-bar.tsx
@@ -40,7 +40,7 @@ import {
  markAllNotificationsAsRead,
  deleteNotification,
  checkDeadlineNotifications,
-} from "@/lib/actions/notification.action";
+} from "@/features/notifications/api/notification.action";
 import { cn } from "@/lib/utils";

 /**
@@ -236,7 +236,7 @@ export default function NotificationBar() {

    const rect = triggerRef.current.getBoundingClientRect();
    const panelWidth = 420;
-    const panelHeightEstimate = panelRef.current?.offsetHeight ?? 240;
+    const panelHeightEstimate = panelRef.current?.offsetHeight ?? 340;
    const viewportPadding = 12;

    const preferredLeft = rect.right + 14;
@@ -475,10 +475,29 @@ export default function NotificationBar() {
    if (!isOpen) return;

    updatePanelPosition();
+
+    // Reposition after paint so empty-state and populated-state heights are both measured correctly.
+    const rafId = window.requestAnimationFrame(() => {
+      updatePanelPosition();
+    });
+
+    // Track panel content height changes in real time.
+    let resizeObserver: ResizeObserver | null = null;
+    if (panelRef.current && typeof ResizeObserver !== "undefined") {
+      resizeObserver = new ResizeObserver(() => {
+        updatePanelPosition();
+      });
+      resizeObserver.observe(panelRef.current);
+    }
+
    const handleResize = () => updatePanelPosition();
    window.addEventListener("resize", handleResize);
-    return () => window.removeEventListener("resize", handleResize);
-  }, [isMounted, isOpen, updatePanelPosition]);
+    return () => {
+      window.cancelAnimationFrame(rafId);
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", handleResize);
+    };
+  }, [isMounted, isOpen, updatePanelPosition, notifications.length, isLoading]);

  if (!isMounted) {
    return (
--- a/lib/services/ai.service.ts
+++ b/lib/services/ai.service.ts
@@ -1,9 +1,21 @@
 // src/lib/services/ai.service.ts
 import { GoogleGenerativeAI } from "@google/generative-ai";
 import { prisma } from "@/lib/db/prisma";
+import {
+  AnalyzeOptions,
+  ContractPrecheckResult,
+  NormalizedAnalysis,
+} from "@/lib/services/ai/analysis.types";
+import {
+  buildAnalysisPrompt,
+  buildPrevalidationPrompt,
+} from "@/lib/services/ai/analysis.prompt";
+import { parseJsonResponse as parseAiJsonResponse } from "@/lib/services/ai/analysis.parser";
+import { normalizeAnalysis as normalizeAiAnalysis } from "@/lib/services/ai/analysis.normalizer";

 // Read API key from environment once at module load.
-const API_KEY = process.env.AI_API_KEY;
+const API_KEY =
+  process.env.AI_API_KEY || process.env.AI_API_KEY2 || process.env.AI_API_KEY3;

 if (!API_KEY) {
  console.error("❌ AI_API_KEY is missing from environment variables");
@@ -14,45 +26,14 @@ if (!API_KEY) {
 // Initialize Gemini
 const genAI = new GoogleGenerativeAI(API_KEY);

-// Runtime options used by analysis.
-type AnalyzeOptions = {
-  userId?: string;
-  fileName?: string;
-  maxRetries?: number;
-};
+const PRIMARY_ANALYSIS_MODEL =
+  process.env.AI_MODEL_PRIMARY || "gemini-2.5-flash";
+const FALLBACK_ANALYSIS_MODEL =
+  process.env.AI_MODEL_FALLBACK || "gemini-2.0-flash";

-// Canonical shape returned by this service after normalization and validation.
-type NormalizedAnalysis = {
-  title: string;
-  type:
-    | "INSURANCE_AUTO"
-    | "INSURANCE_HOME"
-    | "INSURANCE_HEALTH"
-    | "INSURANCE_LIFE"
-    | "LOAN"
-    | "CREDIT_CARD"
-    | "INVESTMENT"
-    | "OTHER";
-  provider: string | null;
-  policyNumber: string | null;
-  startDate: string | null;
-  endDate: string | null;
-  premium: number | null;
-  summary: string;
-  keyPoints: {
-    guarantees: string[];
-    exclusions: string[];
-    franchise: string | null;
-    importantDates: string[];
-  };
-  extractedText: string;
-};
-
-type ContractPrecheckResult = {
-  isValidContract: boolean;
-  confidence: number;
-  reason: string | null;
-};
+const ANALYSIS_MODELS = Array.from(
+  new Set([PRIMARY_ANALYSIS_MODEL, FALLBACK_ANALYSIS_MODEL]),
+);

 export class AIService {
  /**
@@ -127,21 +108,9 @@ export class AIService {
        );
      }

-      // Step 3: Configure model for deterministic, JSON-centric extraction.
-      const model = genAI.getGenerativeModel({
-        model: "gemini-2.5-flash",
-        generationConfig: {
-          temperature: 0.1, // Low for consistency
-          topP: 0.95,
-          topK: 40,
-          maxOutputTokens: 8192,
-          responseMimeType: "application/json",
-        },
-      });
-
      // Step 4: Build adaptive extraction context from previously analyzed contracts.
      const adaptiveContext = await this.buildAdaptiveContext(options?.userId);
-      const basePrompt = this.buildPrompt({
+      const basePrompt = buildAnalysisPrompt({
        adaptiveContext,
        fileName: options?.fileName,
      });
@@ -158,17 +127,12 @@ export class AIService {
            : `\n\nCORRECTION MODE:\nYour previous response was invalid.\nReason: ${lastValidationError || "Invalid structure"}.\nReturn JSON only and keep every required field.\nPrevious invalid response:\n${previousRawResponse.slice(0, 2000)}`;

        // Step 5: Ask model to extract strict JSON from the uploaded file.
-        const result = await model.generateContent([
-          `${basePrompt}${correctionHint}`,
-          {
-            inlineData: {
-              data: base64,
-              mimeType: mimeType,
-            },
-          },
-        ]);
+        const text = await this.generateAnalysisWithFallback({
+          prompt: `${basePrompt}${correctionHint}`,
+          base64,
+          mimeType,
+        });

-        const text = result.response.text();
        if (!text) {
          lastValidationError = "No content in AI response";
          continue;
@@ -178,7 +142,38 @@ export class AIService {

        try {
          // Step 6: Parse and normalize output into canonical structure.
-          const parsed = this.parseJsonResponse(text);
+          let parsed: unknown;
+
+          try {
+            parsed = this.parseJsonResponse(text);
+          } catch (parseError) {
+            console.warn(
+              "Initial JSON parse failed. Attempting repair with fallback model...",
+            );
+            const repaired = await this.repairMalformedJson(
+              text,
+              parseError instanceof Error
+                ? parseError.message
+                : "Invalid JSON response",
+            );
+
+            if (!repaired) {
+              // Emergency fallback: try to extract key fields from raw text
+              console.warn(
+                "Repair model failed. Attempting emergency field extraction...",
+              );
+              const emergency = this.emergencyExtractFields(text);
+              if (emergency) {
+                console.log("✅ Emergency extraction succeeded");
+                parsed = this.parseJsonResponse(emergency);
+              } else {
+                throw parseError;
+              }
+            } else {
+              parsed = this.parseJsonResponse(repaired);
+            }
+          }
+
          const normalized = this.normalizeAnalysis(parsed);

          // Step 7: Reject non-contract uploads with explicit error.
@@ -225,7 +220,7 @@ export class AIService {
        error.message?.includes("404")
      ) {
        throw new Error(
-          "Invalid Gemini model. Ensure 'gemini-2.5-flash' is available in your Google Cloud project.",
+          `Invalid Gemini model configuration. Current models: ${ANALYSIS_MODELS.join(", ")}. Check model availability in your Gemini account.`,
        );
      } else if (
        error.message?.includes("fetch") &&
@@ -234,7 +229,11 @@ export class AIService {
        throw new Error(
          "Download failed. Check if the file URL is correct and accessible.",
        );
-      } else if (error.message?.includes("JSON")) {
+      } else if (
+        error.message?.includes("JSON") ||
+        error.message?.includes("No complete JSON object") ||
+        error.message?.includes("parse failed")
+      ) {
        console.error("❌ Raw response that failed to parse:", error);
        console.error("Full error message:", error.message);

@@ -253,7 +252,7 @@ export class AIService {
          );
        } else {
          throw new Error(
-            "Error parsing AI response. The response may not be valid JSON. Check console for details.",
+            "AI returned a malformed response format. Please retry analysis; if it fails again, the file may require OCR cleanup.",
          );
        }
      } else if (error.message?.includes("quota")) {
@@ -267,88 +266,13 @@ export class AIService {
  }

  /**
-   * Build extraction prompt with strict schema + anti-hallucination instructions.
+   * Prompt generation has been moved to lib/services/ai/analysis.prompt.ts.
   */
  private static buildPrompt(input?: {
    adaptiveContext?: string;
    fileName?: string;
  }): string {
-    return `You are an expert in BFSI contract analysis (Banking, Financial Services, Insurance).
-
-Document name: ${input?.fileName ?? "Unknown"}
-
-${input?.adaptiveContext ?? ""}
-
-Analyze this contract document and extract ALL important information in the EXACT JSON format below:
-
-{
-  "title": "Descriptive contract title (e.g., Allianz Car Insurance)",
-  "type": "INSURANCE_AUTO",
-  "provider": "Name of the company or financial institution",
-  "policyNumber": "Policy number or contract number",
-  "startDate": "2024-01-01",
-  "endDate": "2024-12-31",
-  "premium": 1200.50,
-  "summary": "Clear and concise summary of the contract in a maximum of 3–4 sentences, covering the main guarantees and conditions",
-  "keyPoints": {
-    "guarantees": ["List of main guarantees or coverages provided"],
-    "exclusions": ["List of important exclusions to be aware of"],
-    "franchise": "Deductible amount or description (e.g., €500)",
-    "importantDates": ["Key dates and important deadlines"]
-  },
-  "contractValidation": {
-    "isValidContract": true,
-    "confidence": 88,
-    "reason": "Short reason if invalid, otherwise null"
-  },
-  "extractedText": "Full text extracted from the document with all details"
-}
-
-CRITICAL INSTRUCTIONS:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-TYPE — Must be EXACTLY one of the following values:
-
-INSURANCE_AUTO (car insurance)
-
-INSURANCE_HOME (home insurance)
-
-INSURANCE_HEALTH (health insurance/mutual)
-
-INSURANCE_LIFE (life insurance)
-
-LOAN (bank loan)
-
-CREDIT_CARD (credit card)
-
-INVESTMENT (investment account)
-
-OTHER (other type)
-
-DATES — Strict format YYYY-MM-DD (e.g., 2024-01-15)
-
-PREMIUM — Decimal number only (e.g., 1200.50, no text)
-
-NULL — If information does not exist, use null (not an empty string "")
-
-CONTRACT VALIDATION — Determine whether this document is truly a contract/policy/loan agreement.
- contractValidation.isValidContract must be false for invoices, receipts, ID cards, blank scans, random photos, marketing flyers, or unrelated files.
- confidence must be an integer from 0 to 100.
- reason must explain why invalid when isValidContract is false.
-
-EXTRACTED TEXT — Must contain ALL visible text from the document
-
-SUMMARY — Maximum 4 sentences, clear and informative
-
-RESPONSE — Respond ONLY with valid JSON, no text before or after, no markdown
-
-QUALITY GUARDRAILS:
- Never invent provider names, policy numbers, dates, or premium values.
- If uncertain, use null for that field.
- Keep extractedText raw and faithful to the visible document content.
- For summary and key points, prioritize practical legal and business implications.
-
-NOW ANALYZE THE DOCUMENT:`;
+    return buildAnalysisPrompt(input);
  }

  /**
@@ -382,86 +306,232 @@ NOW ANALYZE THE DOCUMENT:`;
  }

  private static parseJsonResponse(text: string): unknown {
-    if (!text || typeof text !== "string" || text.trim().length === 0) {
-      throw new Error("AI response is empty or invalid.");
+    return parseAiJsonResponse(text);
  }

-    // Remove potential markdown wrappers, comments, and extra whitespace
-    let cleanJson = text
-      .replace(/```json[\s\n]*/, "") // Remove opening markdown
-      .replace(/```[\s\n]*$/, "") // Remove closing markdown
-      .replace(/\/\/.*$/gm, "") // Remove JavaScript comments
-      .trim();
+  private static async generateAnalysisWithFallback(input: {
+    prompt: string;
+    base64: string;
+    mimeType: string;
+  }): Promise<string> {
+    let lastError: unknown = null;

-    // Check for common issues that indicate incomplete/corrupted response
-    const responsePreview = cleanJson.substring(0, 200);
-    console.log("🔍 AI Response preview:", responsePreview);
-
-    // Try direct parse first
+    for (const modelName of ANALYSIS_MODELS) {
      try {
-      const result = JSON.parse(cleanJson);
-      console.log("✅ JSON parsed successfully on first attempt");
-      return result;
-    } catch (firstError) {
+        const model = genAI.getGenerativeModel({
+          model: modelName,
+          generationConfig: {
+            temperature: 0.1,
+            topP: 0.95,
+            topK: 40,
+            maxOutputTokens: 16384,
+            responseMimeType: "application/json",
+          },
+        });
+
+        const result = await model.generateContent([
+          input.prompt,
+          {
+            inlineData: {
+              data: input.base64,
+              mimeType: input.mimeType,
+            },
+          },
+        ]);
+
+        const text = result.response.text();
+        if (text && text.trim().length > 0) {
+          console.log(`✅ Analysis with model ${modelName} succeeded`);
+          return text;
+        }
+      } catch (error) {
+        lastError = error;
        console.warn(
-        "⚠️ First JSON parse failed:",
-        (firstError as Error).message,
+          `Analysis with model ${modelName} failed. Trying next model.`,
+          error instanceof Error ? error.message : String(error),
        );
      }
+    }

-    // Fallback 1: Try removing non-JSON text (explanations before/after JSON)
+    // All primary models failed. Try with more lenient generation settings as last resort
+    console.warn(
+      "All standard models failed. Trying with lenient generation config...",
+    );
    try {
-      const firstCurly = cleanJson.indexOf("{");
-      const lastCurly = cleanJson.lastIndexOf("}");
+      const fallbackModel = genAI.getGenerativeModel({
+        model: PRIMARY_ANALYSIS_MODEL,
+        generationConfig: {
+          temperature: 0,
+          topP: 0.9,
+          topK: 20,
+          maxOutputTokens: 16384,
+          // Don't enforce JSON format; let model produce raw output
+        },
+      });

-      if (firstCurly === -1 || lastCurly === -1 || firstCurly >= lastCurly) {
-        throw new Error(
-          "No JSON object wrapper found (missing { or }). Response may be incomplete.",
-        );
+      const result = await fallbackModel.generateContent([
+        input.prompt,
+        {
+          inlineData: {
+            data: input.base64,
+            mimeType: input.mimeType,
+          },
+        },
+      ]);
+
+      const text = result.response.text();
+      if (text && text.trim().length > 0) {
+        console.log("✅ Lenient generation succeeded");
+        return text;
+      }
+    } catch (error) {
+      console.warn("Lenient generation also failed:", error);
    }

-      // Ensure we get complete closing braces for nested objects
-      let braceCount = 0;
-      let endIndex = firstCurly;
+    throw lastError instanceof Error
+      ? lastError
+      : new Error("All analysis models failed to generate content.");
+  }

-      for (let i = firstCurly; i < cleanJson.length; i++) {
-        if (cleanJson[i] === "{") braceCount++;
-        if (cleanJson[i] === "}") braceCount--;
-        if (braceCount === 0) {
-          endIndex = i;
-          break;
+  private static async repairMalformedJson(
+    malformedResponse: string,
+    parseError: string,
+  ): Promise<string | null> {
+    try {
+      const repairModelName = FALLBACK_ANALYSIS_MODEL;
+      const model = genAI.getGenerativeModel({
+        model: repairModelName,
+        generationConfig: {
+          temperature: 0,
+          topP: 0.9,
+          topK: 20,
+          maxOutputTokens: 16384,
+          responseMimeType: "application/json",
+        },
+      });
+
+      const expectedSchema = {
+        language: "string|null",
+        title: "string",
+        type: "enum: INSURANCE_AUTO|INSURANCE_HOME|INSURANCE_HEALTH|INSURANCE_LIFE|LOAN|CREDIT_CARD|INVESTMENT|OTHER",
+        provider: "string|null",
+        policyNumber: "string|null",
+        startDate: "YYYY-MM-DD|null",
+        endDate: "YYYY-MM-DD|null",
+        premium: "number|null",
+        premiumCurrency: "string|null (ISO code like EUR/USD/TND or symbol)",
+        summary: "string (min 10 chars)",
+        extractedText: "string (min 30 chars)",
+        keyPoints: {
+          guarantees: "string[]",
+          exclusions: "string[]",
+          franchise: "string|null",
+          importantDates: "string[]",
+          explainability:
+            "[{ field, why, sourceSnippet, sourceHints:{ page|null, section|null, confidence|null } }]",
+        },
+        keyPeople: "[{ name, role|null, email|null, phone|null }]",
+        contactInfo:
+          "{ name|null, email|null, phone|null, address|null, role|null }",
+        importantContacts:
+          "[{ name|null, email|null, phone|null, address|null, role|null }]",
+        relevantDates:
+          "[{ date:'YYYY-MM-DD', description, type:'EXPIRATION|RENEWAL|PAYMENT|REVIEW|OTHER' }]",
+        contractValidation: {
+          isValidContract: "boolean",
+          confidence: "number (0-100)",
+          reason: "string|null",
+        },
+      };
+
+      const repairPrompt = `You are a JSON repair engine for contract analysis.
+Fix the malformed JSON response below and return ONLY valid, parseable JSON conforming to this schema:
+
+${JSON.stringify(expectedSchema, null, 2)}
+
+Rules:
+1. Return ONLY the JSON object, no markdown, no explanations.
+2. Preserve all values from the original response as accurately as possible.
+3. Fix structural issues: missing braces, unescaped quotes, trailing commas, unmatched brackets.
+4. For null/missing fields, use null value or empty array [] as appropriate.
+5. Ensure all required text fields (title, summary, extractedText) have content.
+6. All numeric values must be valid numbers.
+7. All dates must be in YYYY-MM-DD format.
+8. If type is unclear, use "OTHER".
+9. Preserve explainability and evidence snippets when present.
+
+Original parse error: ${parseError}
+
+Malformed response to fix:
+${malformedResponse.slice(0, 14000)}`;
+
+      const repaired = await model.generateContent(repairPrompt);
+      const repairedText = repaired.response.text()?.trim() || "";
+
+      if (repairedText.length === 0) {
+        return null;
+      }
+
+      // Verify the repaired text is at least JSON-like before returning
+      if (!repairedText.includes("{")) {
+        return null;
+      }
+
+      return repairedText;
+    } catch (error) {
+      console.warn("JSON repair step failed:", error);
+      return null;
    }
  }

-      const jsonSlice = cleanJson.slice(firstCurly, endIndex + 1);
-      console.log("📝 Extracted JSON slice length:", jsonSlice.length);
-
-      const result = JSON.parse(jsonSlice);
-      console.log("✅ JSON parsed successfully after text removal");
-      return result;
-    } catch (fallbackError) {
-      console.error(
-        "❌ JSON fallback parsing failed:",
-        (fallbackError as Error).message,
+  /**
+   * Emergency fallback: Extract key contract fields from raw text when JSON is completely malformed.
+   * Builds a minimal but valid JSON structure from pattern-matched fields.
+   */
+  private static emergencyExtractFields(rawText: string): string | null {
+    try {
+      const titleMatch = rawText.match(
+        /["']?title["']?\s*:\s*["']([^"']{5,200})/i,
      );
-      console.error("Full raw response:", cleanJson.substring(0, 500));
-
-      // Last resort: Check for common formatting issues
-      if (cleanJson.includes('\\n"') || cleanJson.includes('\\"')) {
-        throw new Error(
-          "Response contains escaped quotes or newlines that couldn't be parsed. The contract may have corrupted text.",
+      const summaryMatch = rawText.match(
+        /summary["']?\s*:\s*["']([^"']{10,500})/i,
      );
+      const extractedMatch = rawText.match(
+        /extractedText["']?\s*:\s*["']([^"']{30,})/i,
+      );
+
+      if (!titleMatch || !summaryMatch) {
+        return null;
      }

-      if (!cleanJson.includes('"type"') && !cleanJson.includes('"title"')) {
-        throw new Error(
-          "Response is missing expected contract fields. It may not be a valid contract document.",
-        );
-      }
+      const emergency = {
+        title: titleMatch[1]?.slice(0, 200) || "Contract",
+        type: "OTHER",
+        provider: null,
+        policyNumber: null,
+        startDate: null,
+        endDate: null,
+        premium: null,
+        premiumCurrency: null,
+        summary: summaryMatch[1]?.slice(0, 500) || "Contract analysis",
+        extractedText:
+          extractedMatch?.[1]?.slice(0, 12000) || rawText.slice(0, 12000),
+        keyPoints: {
+          guarantees: [],
+          exclusions: [],
+          franchise: null,
+          importantDates: [],
+        },
+        contractValidation: {
+          isValidContract: true,
+          confidence: 50,
+          reason: "Emergency partial extraction due to response malformation",
+        },
+      };

-      throw new Error(
-        `Failed to parse AI response as JSON: ${(fallbackError as Error).message}`,
-      );
+      return JSON.stringify(emergency);
+    } catch {
+      return null;
    }
  }

@@ -476,44 +546,24 @@ NOW ANALYZE THE DOCUMENT:`;
    mimeType: string;
    fileName?: string;
  }): Promise<ContractPrecheckResult> {
-    const model = genAI.getGenerativeModel({
-      model: "gemini-2.5-flash",
-      generationConfig: {
-        temperature: 0,
-        topP: 0.9,
-        topK: 20,
-        maxOutputTokens: 350,
-        responseMimeType: "application/json",
-      },
-    });
+    const rawText = await this.generatePrevalidationWithFallback(input);

-    const result = await model.generateContent([
-      `You are validating whether an uploaded document is a legal/financial contract.
+    let raw: any;
+    try {
+      raw = this.parseJsonResponse(rawText || "{}");
+    } catch (error) {
+      // If prevalidation JSON is malformed, assume it's a contract with moderate confidence
+      console.warn(
+        "Prevalidation JSON parse failed, assuming contract with moderate confidence",
+      );
+      return {
+        isValidContract: true,
+        confidence: 60,
+        reason:
+          "Prevalidation response was malformed, but document appears contract-like",
+      };
+    }

-File name: ${input.fileName ?? "Unknown"}
-
-Return ONLY JSON:
-{
-  "isValidContract": true,
-  "confidence": 0,
-  "reason": null
-}
-
-Rules:
- isValidContract=false for invoices, receipts, identity cards, random photos/screenshots, blank pages, flyers, or unrelated files.
- confidence is an integer from 0 to 100.
- reason must be concise and user-friendly when invalid.
- If valid, reason can be null.
-`,
-      {
-        inlineData: {
-          data: input.base64,
-          mimeType: input.mimeType,
-        },
-      },
-    ]);
-
-    const raw = this.parseJsonResponse(result.response.text() || "{}");
    const maybe = raw as Partial<ContractPrecheckResult>;

    const isValidContract = Boolean(maybe.isValidContract);
@@ -532,95 +582,55 @@ Rules:
    };
  }

-  private static normalizeAnalysis(input: any): NormalizedAnalysis {
-    // Ensure contract type belongs to supported enum.
-    const validTypes = new Set([
-      "INSURANCE_AUTO",
-      "INSURANCE_HOME",
-      "INSURANCE_HEALTH",
-      "INSURANCE_LIFE",
-      "LOAN",
-      "CREDIT_CARD",
-      "INVESTMENT",
-      "OTHER",
+  private static async generatePrevalidationWithFallback(input: {
+    base64: string;
+    mimeType: string;
+    fileName?: string;
+  }): Promise<string> {
+    let lastError: unknown = null;
+
+    for (const modelName of ANALYSIS_MODELS) {
+      try {
+        const model = genAI.getGenerativeModel({
+          model: modelName,
+          generationConfig: {
+            temperature: 0,
+            topP: 0.9,
+            topK: 20,
+            maxOutputTokens: 350,
+            responseMimeType: "application/json",
+          },
+        });
+
+        const result = await model.generateContent([
+          buildPrevalidationPrompt(input.fileName),
+          {
+            inlineData: {
+              data: input.base64,
+              mimeType: input.mimeType,
+            },
+          },
        ]);

-    const type =
-      typeof input?.type === "string" && validTypes.has(input.type)
-        ? input.type
-        : null;
-
-    if (!type) {
-      throw new Error("Contract type is missing or invalid.");
+        const text = result.response.text();
+        if (text && text.trim().length > 0) {
+          return text;
+        }
+      } catch (error) {
+        lastError = error;
+        console.warn(
+          `Pre-validation with model ${modelName} failed. Trying next model.`,
+        );
+      }
    }

-    const title = String(input?.title || "").trim();
-    const summary = String(input?.summary || "").trim();
-    const extractedText = String(input?.extractedText || "").trim();
-
-    if (title.length < 3) {
-      throw new Error("Title is missing or too short.");
-    }
-    if (summary.length < 10) {
-      throw new Error("Summary is missing or too short.");
-    }
-    if (extractedText.length < 50) {
-      throw new Error("Extracted text is missing or too short.");
+    throw lastError instanceof Error
+      ? lastError
+      : new Error("All pre-validation models failed to generate content.");
  }

-    // Helper: normalize unknown primitive into string|null.
-    const toStringOrNull = (value: unknown): string | null => {
-      const normalized = String(value ?? "").trim();
-      return normalized.length > 0 ? normalized : null;
-    };
-
-    // Helper: accept only strict ISO date values.
-    const toDateOrNull = (value: unknown): string | null => {
-      const candidate = String(value ?? "").trim();
-      if (!candidate) return null;
-
-      const isIsoDate = /^\d{4}-\d{2}-\d{2}$/.test(candidate);
-      return isIsoDate ? candidate : null;
-    };
-
-    // Helper: sanitize array values into non-empty text list.
-    const toStringList = (value: unknown): string[] => {
-      if (!Array.isArray(value)) return [];
-      return value
-        .map((item) => String(item ?? "").trim())
-        .filter((item) => item.length > 0);
-    };
-
-    // Premium must be numeric and non-negative.
-    const premiumValue =
-      input?.premium === null || input?.premium === undefined
-        ? null
-        : Number(input.premium);
-
-    const premium =
-      premiumValue !== null &&
-      Number.isFinite(premiumValue) &&
-      premiumValue >= 0
-        ? Number(premiumValue.toFixed(2))
-        : null;
-
-    return {
-      title,
-      type,
-      provider: toStringOrNull(input?.provider),
-      policyNumber: toStringOrNull(input?.policyNumber),
-      startDate: toDateOrNull(input?.startDate),
-      endDate: toDateOrNull(input?.endDate),
-      premium,
-      summary,
-      keyPoints: {
-        guarantees: toStringList(input?.keyPoints?.guarantees),
-        exclusions: toStringList(input?.keyPoints?.exclusions),
-        franchise: toStringOrNull(input?.keyPoints?.franchise),
-        importantDates: toStringList(input?.keyPoints?.importantDates),
-      },
-      extractedText,
-    };
+  private static normalizeAnalysis(input: any): NormalizedAnalysis {
+    return normalizeAiAnalysis(input);
  }

  private static async buildAdaptiveContext(userId?: string): Promise<string> {
@@ -643,6 +653,7 @@ Rules:
        provider: true,
        policyNumber: true,
        summary: true,
+        keyPoints: true,
      },
    });

@@ -680,6 +691,49 @@ Rules:
      .slice(0, 4)
      .map((value) => value.replace(/[A-Za-z0-9]/g, "X"));

+    const allExplainability = examples
+      .flatMap((item) => {
+        const maybeExplainability = (item.keyPoints as any)?.explainability;
+        return Array.isArray(maybeExplainability) ? maybeExplainability : [];
+      })
+      .slice(0, 120);
+
+    const explainabilityByField = count(
+      allExplainability
+        .map((entry: any) => String(entry?.field ?? "").trim())
+        .filter((value: string) => value.length > 0),
+    );
+
+    const confidenceValues = allExplainability
+      .map((entry: any) => Number(entry?.sourceHints?.confidence))
+      .filter((value: number) => Number.isFinite(value));
+
+    const avgEvidenceConfidence = confidenceValues.length
+      ? Math.round(
+          confidenceValues.reduce(
+            (sum: number, value: number) => sum + value,
+            0,
+          ) / confidenceValues.length,
+        )
+      : null;
+
+    const learnedLanguages = count(
+      examples
+        .map((item) => (item.keyPoints as any)?.aiMeta?.language)
+        .map((value) => String(value ?? "").trim())
+        .filter((value: string) => value.length > 0),
+    );
+
+    const learnedKeyRoles = count(
+      examples
+        .flatMap((item) => {
+          const people = (item.keyPoints as any)?.aiMeta?.keyPeople;
+          return Array.isArray(people) ? people : [];
+        })
+        .map((person: any) => String(person?.role ?? "").trim())
+        .filter((value: string) => value.length > 0),
+    );
+
    const avgSummaryLength =
      examples
        .map((item) => item.summary?.length ?? 0)
@@ -690,6 +744,10 @@ Rules:
 - Frequent provider naming patterns: ${topProviders.join(", ") || "N/A"}
 - Example policy number shape patterns: ${policyPatterns.join(", ") || "N/A"}
 - Typical summary length target: around ${Math.round(avgSummaryLength)} characters.
+- Dominant learned languages: ${learnedLanguages.join(", ") || "N/A"}
+- Most evidenced fields: ${explainabilityByField.join(", ") || "N/A"}
+- Average evidence confidence: ${avgEvidenceConfidence ?? "N/A"}
+- Frequent key roles identified: ${learnedKeyRoles.join(", ") || "N/A"}

 Use this context only as formatting guidance. Do not force it if current document content differs.`;
  }
@@ -711,7 +769,7 @@ Use this context only as formatting guidance. Do not force it if current documen
    const modelReason = String(raw?.contractValidation?.reason ?? "").trim();

    const legalSignalRegex =
-      /contract|agreement|policy|terms|clause|premium|coverage|insured|insurer|loan|borrower|credit|beneficiary|liability/i;
+      /contract|agreement|policy|terms|clause|premium|coverage|insured|insurer|loan|borrower|credit|beneficiary|liability|lease|service|supplier|client|vendor|annex|appendix|signature|party|contrat|assurance|banque|credit|emprunteur|garantie|echeance|duree|clause/i;
    const hasLegalSignals = legalSignalRegex.test(normalized.extractedText);
    const hasStructuredSignal =
      Boolean(normalized.provider) ||
@@ -732,6 +790,16 @@ Use this context only as formatting guidance. Do not force it if current documen
      );
    }

+    // For generic contracts mapped to OTHER, keep a lighter heuristic so valid non-BFSI contracts pass.
+    if (normalized.type === "OTHER") {
+      if (!hasLegalSignals && normalized.extractedText.length < 120) {
+        throw new Error(
+          "INVALID_CONTRACT:Uploaded file does not contain enough contract-specific signals.",
+        );
+      }
+      return;
+    }
+
    if (!hasLegalSignals && !hasStructuredSignal) {
      throw new Error(
        "INVALID_CONTRACT:Uploaded file does not contain enough contract-specific signals.",
@@ -794,20 +862,10 @@ Use this context only as formatting guidance. Do not force it if current documen
      summary?: string | null;
      keyPoints?: Record<string, unknown> | null;
      extractedText?: string | null;
+      language?: string | null; // NEW: contract's detected language
    };
  }) {
    try {
-      // Configure fast Q&A model tuned for concise answers.
-      const model = genAI.getGenerativeModel({
-        model: "gemini-2.5-flash",
-        generationConfig: {
-          temperature: 0.2,
-          topP: 0.95,
-          topK: 40,
-          maxOutputTokens: 2048,
-        },
-      });
-
      // Keep context bounded to avoid overlong prompts and token waste.
      const extractedTextSnippet = (input.contract.extractedText || "")
        .slice(0, 12000)
@@ -816,10 +874,28 @@ Use this context only as formatting guidance. Do not force it if current documen
        input.contract.type,
      );

-      const prompt = `You are a senior BFSI contract advisor.
+      // Detect contract language for multilingual response
+      const contractLanguage = input.contract.language || "en";
+      const languageName =
+        {
+          en: "English",
+          fr: "French",
+          de: "German",
+          es: "Spanish",
+          it: "Italian",
+          pt: "Portuguese",
+          nl: "Dutch",
+          pl: "Polish",
+          ja: "Japanese",
+          zh: "Chinese",
+          ar: "Arabic",
+        }[contractLanguage] || "English";
+
+      const prompt = `You are a senior BFSI contract advisor. IMPORTANT: Respond entirely in ${languageName} to match the contract language.

 Contract metadata:
 - File: ${input.contract.fileName}
+- Language: ${languageName}
 - Title: ${input.contract.title ?? "N/A"}
 - Type: ${input.contract.type ?? "N/A"}
 - Provider: ${input.contract.provider ?? "N/A"}
@@ -837,12 +913,13 @@ ${JSON.stringify(input.contract.keyPoints ?? {}, null, 2)}
 Extracted Text:
 ${extractedTextSnippet || "N/A"}

-User question:
+User question (${languageName}):
 ${input.question}

 Instructions:
+- RESPOND ENTIRELY IN ${languageName}. This is critical.
 - Write in clear, professional, business-oriented plain text.
- Do NOT use markdown or special formatting symbols, including: **, __, #, *, -, backticks.
+- Do NOT use markdown or special formatting symbols, including: **, __, #, *, -, backticks with one exception: you can use | for separators if needed for clarity
 - Do NOT quote large raw excerpts from extracted text unless strictly necessary.
 - Synthesize and explain the implications in practical terms instead of copying file content.
 - Base your answer ONLY on the provided contract content.
@@ -852,21 +929,54 @@ Instructions:
 - For legal context, use wording like: "Under general EU/US legal principles..." and avoid citing specific article numbers unless explicitly present in the contract content.
 - Never claim certainty where the contract text is ambiguous.
 - Keep the answer concise, executive, and decision-oriented.
+- Use the same language preference throughout (${languageName}).

-Response structure:
+Response structure (in ${languageName}):
 1) Direct answer in one sentence.
 2) Business impact in one to two sentences (risk, cost, operational effect).
 3) General legal context in one to two sentences when relevant.
 4) Recommended next step in one sentence.

-Compliance note:
+Compliance note (in ${languageName}):
 Include one short disclaimer only when legal context is discussed: "This is general information, not formal legal advice."`;

-      // Execute completion and sanitize styling artifacts from response.
+      // Execute completion with model fallback and sanitize styling artifacts.
+      let rawAnswer = "";
+      let lastError: unknown = null;
+
+      for (const modelName of ANALYSIS_MODELS) {
+        try {
+          const model = genAI.getGenerativeModel({
+            model: modelName,
+            generationConfig: {
+              temperature: 0.2,
+              topP: 0.95,
+              topK: 40,
+              maxOutputTokens: 2048,
+            },
+          });
+
          const result = await model.generateContent(prompt);
-      const rawAnswer = result.response.text()?.trim();
+          rawAnswer = result.response.text()?.trim() || "";
+
+          if (rawAnswer) {
+            console.log(
+              `✅ Q&A with model ${modelName} succeeded in ${languageName}`,
+            );
+            break;
+          }
+        } catch (error) {
+          lastError = error;
+          console.warn(
+            `Q&A with model ${modelName} failed. Trying next model.`,
+          );
+        }
+      }

      if (!rawAnswer) {
+        if (lastError instanceof Error) {
+          throw lastError;
+        }
        throw new Error("No response generated");
      }

--- a/lib/services/ai/analysis.normalizer.ts
+++ b/lib/services/ai/analysis.normalizer.ts
@@ -0,0 +1,222 @@
+import {
+  NormalizedAnalysis,
+  SUPPORTED_CONTRACT_TYPES,
+  SupportedContractType,
+  ContactInfo,
+  KeyPerson,
+  ExplainabilityItem,
+} from "./analysis.types";
+
+function mapContractType(rawType: unknown): SupportedContractType {
+  const value = String(rawType ?? "")
+    .trim()
+    .toUpperCase()
+    .replace(/\s+/g, "_");
+
+  if (SUPPORTED_CONTRACT_TYPES.includes(value as SupportedContractType)) {
+    return value as SupportedContractType;
+  }
+
+  const aliases: Record<string, SupportedContractType> = {
+    AUTO_INSURANCE: "INSURANCE_AUTO",
+    HOME_INSURANCE: "INSURANCE_HOME",
+    HEALTH_INSURANCE: "INSURANCE_HEALTH",
+    LIFE_INSURANCE: "INSURANCE_LIFE",
+    MORTGAGE: "LOAN",
+    CREDIT: "LOAN",
+    CARD_CREDIT: "CREDIT_CARD",
+  };
+
+  return aliases[value] ?? "OTHER";
+}
+
+function toStringOrNull(value: unknown): string | null {
+  const normalized = String(value ?? "").trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeCurrency(value: unknown): string | null {
+  const raw = String(value ?? "")
+    .trim()
+    .toUpperCase();
+  if (!raw) return null;
+
+  const symbolMap: Record<string, string> = {
+    "€": "EUR",
+    $: "USD",
+    "£": "GBP",
+  };
+
+  if (symbolMap[raw]) {
+    return symbolMap[raw];
+  }
+
+  // Accept ISO-like 3-letter currencies and common BFSI currencies.
+  if (/^[A-Z]{3}$/.test(raw)) {
+    return raw;
+  }
+
+  return null;
+}
+
+function toDateOrNull(value: unknown): string | null {
+  const candidate = String(value ?? "").trim();
+  if (!candidate) return null;
+
+  if (/^\d{4}-\d{2}-\d{2}$/.test(candidate)) {
+    return candidate;
+  }
+
+  const parsed = new Date(candidate);
+  if (Number.isNaN(parsed.getTime())) return null;
+
+  return parsed.toISOString().slice(0, 10);
+}
+
+function toStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => String(item ?? "").trim())
+    .filter((item) => item.length > 0)
+    .slice(0, 25);
+}
+
+function parseContactInfo(input: any): ContactInfo {
+  return {
+    name: toStringOrNull(input?.name),
+    email: toStringOrNull(input?.email),
+    phone: toStringOrNull(input?.phone),
+    address: toStringOrNull(input?.address),
+    role: toStringOrNull(input?.role),
+  };
+}
+
+function parseKeyPeople(input: any): KeyPerson[] {
+  if (!Array.isArray(input)) return [];
+  return input.slice(0, 10).map((person) => ({
+    name: String(person?.name ?? "").trim() || "Unknown",
+    role: toStringOrNull(person?.role),
+    email: toStringOrNull(person?.email),
+    phone: toStringOrNull(person?.phone),
+  }));
+}
+
+function parseRelevantDates(input: any): Array<{
+  date: string;
+  description: string;
+  type: "EXPIRATION" | "RENEWAL" | "PAYMENT" | "REVIEW" | "OTHER";
+}> {
+  if (!Array.isArray(input)) return [];
+
+  return input.slice(0, 15).map((dateObj) => {
+    const dateStr = toDateOrNull(dateObj?.date);
+    const type = String(dateObj?.type ?? "OTHER").toUpperCase();
+    const isValidType = [
+      "EXPIRATION",
+      "RENEWAL",
+      "PAYMENT",
+      "REVIEW",
+      "OTHER",
+    ].includes(type);
+
+    return {
+      date: dateStr || "0000-01-01",
+      description:
+        String(dateObj?.description ?? "")
+          .trim()
+          .slice(0, 200) || "Important date",
+      type: (isValidType ? type : "OTHER") as
+        | "EXPIRATION"
+        | "RENEWAL"
+        | "PAYMENT"
+        | "REVIEW"
+        | "OTHER",
+    };
+  });
+}
+
+function parseExplainability(input: any): ExplainabilityItem[] {
+  if (!Array.isArray(input)) return [];
+
+  return input
+    .slice(0, 30)
+    .map((item) => {
+      const field = String(item?.field ?? "").trim();
+      const why = String(item?.why ?? "").trim();
+      const sourceSnippet = String(item?.sourceSnippet ?? "").trim();
+
+      if (!field || !why || !sourceSnippet) return null;
+
+      const confidenceRaw = Number(item?.sourceHints?.confidence);
+      const confidence = Number.isFinite(confidenceRaw)
+        ? Math.max(0, Math.min(100, Math.round(confidenceRaw)))
+        : null;
+
+      return {
+        field: field.slice(0, 80),
+        why: why.slice(0, 260),
+        sourceSnippet: sourceSnippet.slice(0, 480),
+        sourceHints: {
+          page: toStringOrNull(item?.sourceHints?.page),
+          section: toStringOrNull(item?.sourceHints?.section),
+          confidence,
+        },
+      } as ExplainabilityItem;
+    })
+    .filter((value): value is ExplainabilityItem => value !== null);
+}
+
+export function normalizeAnalysis(input: any): NormalizedAnalysis {
+  const title = String(input?.title || "").trim() || "Untitled Contract";
+  const summary = String(input?.summary || "").trim();
+  const extractedText = String(input?.extractedText || "").trim();
+
+  if (summary.length < 10) {
+    throw new Error("Summary is missing or too short.");
+  }
+
+  if (extractedText.length < 30) {
+    throw new Error("Extracted text is missing or too short.");
+  }
+
+  const premiumValue =
+    input?.premium === null || input?.premium === undefined
+      ? null
+      : Number(input.premium);
+
+  const premium =
+    premiumValue !== null && Number.isFinite(premiumValue) && premiumValue >= 0
+      ? Number(premiumValue.toFixed(2))
+      : null;
+
+  const language = toStringOrNull(input?.language) || "en";
+
+  return {
+    title,
+    type: mapContractType(input?.type),
+    provider: toStringOrNull(input?.provider),
+    policyNumber: toStringOrNull(input?.policyNumber),
+    startDate: toDateOrNull(input?.startDate),
+    endDate: toDateOrNull(input?.endDate),
+    premium,
+    premiumCurrency: normalizeCurrency(input?.premiumCurrency),
+    summary,
+    keyPoints: {
+      guarantees: toStringList(input?.keyPoints?.guarantees),
+      exclusions: toStringList(input?.keyPoints?.exclusions),
+      franchise: toStringOrNull(input?.keyPoints?.franchise),
+      importantDates: toStringList(input?.keyPoints?.importantDates),
+      explainability: parseExplainability(input?.keyPoints?.explainability),
+    },
+    extractedText: extractedText.slice(0, 12000),
+    language,
+    keyPeople: parseKeyPeople(input?.keyPeople),
+    contactInfo: parseContactInfo(input?.contactInfo),
+    importantContacts: Array.isArray(input?.importantContacts)
+      ? input.importantContacts
+          .slice(0, 10)
+          .map((c: any) => parseContactInfo(c))
+      : [],
+    relevantDates: parseRelevantDates(input?.relevantDates),
+  };
+}
--- a/lib/services/ai/analysis.parser.ts
+++ b/lib/services/ai/analysis.parser.ts
@@ -0,0 +1,110 @@
+function stripMarkdownFences(value: string): string {
+  return value
+    .replace(/^```json\s*/i, "")
+    .replace(/^```\s*/i, "")
+    .replace(/\s*```$/, "")
+    .trim();
+}
+
+function extractBalancedJson(text: string): string | null {
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  const stack: string[] = [];
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+
+    if (start === -1) {
+      if (char === "{" || char === "[") {
+        start = i;
+        stack.push(char);
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (!escaped && char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (!escaped && char === '"') {
+        inString = false;
+      }
+      escaped = false;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      stack.push(char);
+      continue;
+    }
+
+    if (char === "}" || char === "]") {
+      const last = stack[stack.length - 1];
+      const isMatch =
+        (last === "{" && char === "}") || (last === "[" && char === "]");
+
+      if (!isMatch) {
+        return null;
+      }
+
+      stack.pop();
+
+      if (stack.length === 0 && start !== -1) {
+        return text.slice(start, i + 1);
+      }
+    }
+  }
+
+  return null;
+}
+
+function sanitizeLooseJson(value: string): string {
+  return value
+    .replace(/[\u201C\u201D]/g, '"')
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/,\s*([}\]])/g, "$1")
+    .trim();
+}
+
+export function parseJsonResponse(text: string): unknown {
+  if (!text || typeof text !== "string" || text.trim().length === 0) {
+    throw new Error("AI response is empty.");
+  }
+
+  const cleaned = stripMarkdownFences(text);
+
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    // continue to robust fallback
+  }
+
+  const extracted = extractBalancedJson(cleaned);
+  if (!extracted) {
+    throw new Error(
+      `No complete JSON object found in AI response. Preview: ${cleaned.slice(0, 220)}`,
+    );
+  }
+
+  try {
+    return JSON.parse(extracted);
+  } catch {
+    const sanitized = sanitizeLooseJson(extracted);
+    try {
+      return JSON.parse(sanitized);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "unknown parse error";
+      throw new Error(
+        `JSON parse failed after recovery attempts: ${message}. Preview: ${sanitized.slice(0, 220)}`,
+      );
+    }
+  }
+}
--- a/lib/services/ai/analysis.prompt.ts
+++ b/lib/services/ai/analysis.prompt.ts
@@ -0,0 +1,165 @@
+export function buildAnalysisPrompt(input?: {
+  adaptiveContext?: string;
+  fileName?: string;
+}): string {
+  return `You are an expert in contract analysis for BFSI and general legal/business contracts. 
+You support multi-language analysis and will automatically detect the contract language.
+
+Document name: ${input?.fileName ?? "Unknown"}
+
+${input?.adaptiveContext ?? ""}
+
+Analyze this contract document completely and return JSON in the EXACT structure below. 
+CRITICAL: Your response must be VALID, PARSEABLE JSON only. Do not include markdown, backticks, or explanations.
+
+{
+  "language": "en",
+  "title": "Descriptive contract title",
+  "type": "INSURANCE_AUTO",
+  "provider": "Company or institution name",
+  "policyNumber": "Policy/contract/reference number",
+  "startDate": "2024-01-01",
+  "endDate": "2025-12-31",
+  "premium": 1200.50,
+  "premiumCurrency": "TND",
+  "summary": "Professional, comprehensive 4-6 sentence summary in the contract's language. Include: main parties, key obligations, coverage/benefits, exclusions, important deadlines, key contacts. Use **bold** for: names, numbers, dates, amounts, important terms.",
+  "keyPoints": {
+    "guarantees": ["**Main Benefit 1**: Description", "**Main Benefit 2**: Description"],
+    "exclusions": ["**Exclusion 1**: Description with impact", "**Exclusion 2**: Description"],
+    "franchise": "**Deductible/Penalty**: €150 per claim or equivalent",
+    "importantDates": ["**Renewal Date**: 31 December annually", "**Payment Deadline**: 15th of each month"],
+    "explainability": [
+      {
+        "field": "endDate",
+        "why": "Extracted as contract expiration because the clause explicitly sets validity end.",
+        "sourceSnippet": "Durée du prêt: échéance finale fixée au 10 avril 2044.",
+        "sourceHints": { "page": "1", "section": "Durée/Échéancier", "confidence": 92 }
+      },
+      {
+        "field": "premium",
+        "why": "Detected monetary obligation from insurance/fee clause.",
+        "sourceSnippet": "Coût total estimé de 18 240,00 TND.",
+        "sourceHints": { "page": "2", "section": "Coût / Prime", "confidence": 88 }
+      }
+    ]
+  },
+  "keyPeople": [
+    {"name": "**John Smith**", "role": "Policy Holder", "email": "john@example.com", "phone": "+33612345678"},
+    {"name": "**Jane Doe**", "role": "Insurance Agent", "email": "jane@insurer.com", "phone": "+33987654321"}
+  ],
+  "contactInfo": {
+    "name": "**Policy Holder Name**",
+    "email": "holder@email.com",
+    "phone": "+33612345678",
+    "address": "123 Main Street, City, Postal Code",
+    "role": "Insured Person"
+  },
+  "importantContacts": [
+    {"name": "**Claims Department**", "email": "claims@insurer.com", "phone": "+33800000000"},
+    {"name": "**Customer Service**", "email": "support@insurer.com", "phone": "+33800111111"}
+  ],
+  "relevantDates": [
+    {"date": "2025-12-31", "description": "**Policy Expiration Date**", "type": "EXPIRATION"},
+    {"date": "2025-10-31", "description": "**Renewal Notice Deadline** (60 days before expiration)", "type": "RENEWAL"},
+    {"date": "1970-01-15", "description": "**Monthly Payment Due Date**", "type": "PAYMENT"}
+  ],
+  "extractedText": "Most relevant extracted text, preserving original structure and keywords. Include key clauses, definitions, obligations. Max 12000 chars.",
+  "contractValidation": {
+    "isValidContract": true,
+    "confidence": 88,
+    "reason": null
+  }
+}
+
+TYPE must be one of:
+INSURANCE_AUTO, INSURANCE_HOME, INSURANCE_HEALTH, INSURANCE_LIFE, LOAN, CREDIT_CARD, INVESTMENT, OTHER
+
+CRITICAL FIELD EXTRACTION RULES:
+
+1. **Language Detection**: Detect and return the contract's primary language (en, fr, de, es, it, pt, etc.). If mixed, return dominant language.
+
+2. **Summary (VERY IMPORTANT)**:
+   - Write 4-6 comprehensive sentences covering: parties involved, contract scope, key obligations, main coverage/benefits, critical exclusions, important deadlines
+   - Use **Party Name** for persons/entities mentioned
+   - Use **number** for all quantities, dates, amounts, percentages
+   - Use **YYYY-MM-DD** format for dates with **bold**
+   - Language: Professional business French, English, or contract's native language
+   - MUST be detailed enough that reader understands contract without opening PDF
+
+3. **Key People Extraction**:
+   - Extract all named individuals: policy holders, insured parties, beneficiaries, signatories, agents, brokers
+   - Include roles, contact methods when visible in contract
+   - Use **bold** for names: {"name": "**John Smith**", ...}
+
+4. **Contact Information**:
+   - contactInfo: Details of PRIMARY policy holder or contract party
+   - importantContacts: Agent, broker, support teams, claims department with **bold** for names
+
+5. **Relevant Dates**:
+   - Extract ALL dates with business meaning: expiration, renewal, payment due dates, review dates
+   - For recurring dates (monthly, annually): show pattern like "1970-01-15" for "15th of each month"
+   - Include type: EXPIRATION, RENEWAL, PAYMENT, REVIEW, or OTHER
+   - Each date must have clear **bold** description explaining its significance
+
+6. **Key Points**:
+   - Use **bold** for: benefit names, exclusion types, monetary amounts, coverage limits
+   - Example: "**Motor Coverage**: Collision and theft protection up to **€50,000**"
+   - Make exclusions explicit and impactful
+   - Include franchise/deductible with bold currency and amount
+
+7. **Guarantees & Exclusions**:
+   - Be specific: "**Theft Coverage** includes keys, GPS, and aftermarket electronics"
+   - For exclusions, explain impact: "**Mechanical wear excluded** - means breakdowns in years 3+ not covered"
+
+8. **Email/Phone Extraction**: If present in contract, extract:
+   - Email addresses in format: contact@domain.com
+   - Phone numbers with country code: +33 for France, +44 for UK, etc.
+
+9. **Explainability (MANDATORY)**:
+   - In keyPoints.explainability, include at least 6 items for critical fields when available:
+     title, provider, policyNumber, startDate, endDate, premium, key obligations, key exclusions.
+   - Each item MUST contain:
+     - field: exact extracted field name
+     - why: one sentence explaining extraction logic
+     - sourceSnippet: short verbatim quote from document supporting the field
+     - sourceHints.page: page number if inferable, otherwise null
+     - sourceHints.section: section title/heading when inferable, otherwise null
+     - sourceHints.confidence: 0..100 confidence for that field extraction
+   - Keep sourceSnippet short (max 280 chars) but sufficiently specific to audit.
+   - Never invent snippet text not present in document.
+
+Field Type Rules:
+- dates: ISO format YYYY-MM-DD or null. For recurring patterns, use canonical date (e.g., "0000-01-15" for "15th each month")
+- premium: Positive number or null. NO currency symbols and NO currency conversion.
+- premiumCurrency: Use the exact currency mentioned in contract (e.g., TND, EUR, USD, MAD, DZD, GBP, CHF). Never convert currency.
+- keyPeople, contactInfo arrays: Can include null values for missing fields
+- type: MUST be one of the 8 contract types. Default to OTHER if unsure.
+- confidence: 1-100, higher for clear data, lower for ambiguous/partial info
+
+Validation:
+- isValidContract: true for all actual contracts (even type=OTHER), false only for non-contract files
+- reason: null if valid, brief explanation if invalid
+
+MUST return VALID JSON parseable with JSON.parse() in ONE line of pure JSON.`;
+}
+
+export function buildPrevalidationPrompt(fileName?: string): string {
+  return `You are validating whether an uploaded document is a legal/financial contract in any language.
+
+File name: ${fileName ?? "Unknown"}
+
+Return ONLY JSON (no markdown, no backticks, no explanations):
+{
+  "isValidContract": true,
+  "confidence": 0,
+  "reason": null
+}
+
+Rules:
+- isValidContract=false for invoices, receipts, identity cards, random photos/screenshots, blank pages, flyers, or unrelated files
+- confidence is an integer from 0 to 100
+- reason must be concise and user-friendly when invalid
+- If valid, reason can be null
+- This must be valid JSON parseable with JSON.parse()
+- Return ONLY the JSON object, nothing else`;
+}
--- a/lib/services/ai/analysis.types.ts
+++ b/lib/services/ai/analysis.types.ts
@@ -0,0 +1,80 @@
+export const SUPPORTED_CONTRACT_TYPES = [
+  "INSURANCE_AUTO",
+  "INSURANCE_HOME",
+  "INSURANCE_HEALTH",
+  "INSURANCE_LIFE",
+  "LOAN",
+  "CREDIT_CARD",
+  "INVESTMENT",
+  "OTHER",
+] as const;
+
+export type SupportedContractType = (typeof SUPPORTED_CONTRACT_TYPES)[number];
+
+export type AnalyzeOptions = {
+  userId?: string;
+  fileName?: string;
+  maxRetries?: number;
+};
+
+export type ContactInfo = {
+  name?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  address?: string | null;
+  role?: string | null;
+};
+
+export type KeyPerson = {
+  name: string;
+  role?: string | null;
+  email?: string | null;
+  phone?: string | null;
+};
+
+export type ExplainabilityItem = {
+  field: string;
+  why: string;
+  sourceSnippet: string;
+  sourceHints?: {
+    page?: string | null;
+    section?: string | null;
+    confidence?: number | null;
+  };
+};
+
+export type NormalizedAnalysis = {
+  title: string;
+  type: SupportedContractType;
+  provider: string | null;
+  policyNumber: string | null;
+  startDate: string | null;
+  endDate: string | null;
+  premium: number | null;
+  premiumCurrency?: string | null;
+  summary: string;
+  keyPoints: {
+    guarantees: string[];
+    exclusions: string[];
+    franchise: string | null;
+    importantDates: string[];
+    explainability?: ExplainabilityItem[];
+  };
+  extractedText: string;
+  // New enhanced fields
+  language?: string | null;
+  keyPeople: KeyPerson[];
+  contactInfo: ContactInfo;
+  importantContacts: ContactInfo[];
+  relevantDates: Array<{
+    date: string;
+    description: string;
+    type: "EXPIRATION" | "RENEWAL" | "PAYMENT" | "REVIEW" | "OTHER";
+  }>;
+};
+
+export type ContractPrecheckResult = {
+  isValidContract: boolean;
+  confidence: number;
+  reason: string | null;
+};
--- a/lib/services/contract.service.ts
+++ b/lib/services/contract.service.ts
@@ -10,6 +10,7 @@ import type {
  ContractType,
 } from "@/types/contract.types";
 import { revalidatePath } from "next/cache";
+import { NotificationService } from "@/lib/services/notification.service";

 const utapi = new UTApi();

@@ -124,7 +125,7 @@ export class ContractService {
      return null;
    };

-    return await prisma.contract.update({
+    const contract = await prisma.contract.update({
      where: { id },
      data: {
        title: aiResults.title,
@@ -140,6 +141,23 @@ export class ContractService {
        status: "COMPLETED",
      },
    });
+
+    // Check for upcoming deadlines after contract is completed
+    try {
+      const user = await prisma.user.findUnique({
+        where: { id: contract.userId },
+        select: { id: true },
+      });
+
+      if (user) {
+        await NotificationService.checkUpcomingDeadlines(user.id);
+      }
+    } catch (error) {
+      console.warn("Failed to check upcoming deadlines:", error);
+      // Don't fail the contract update if deadline check fails
+    }
+
+    return contract;
  }

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
--- a/lib/services/notification.service.ts
+++ b/lib/services/notification.service.ts
@@ -70,6 +70,46 @@ interface NotificationResponse {
 }

 export class NotificationService {
+  static async cleanupReadNonDeadline(
+    userId: string,
+  ): Promise<NotificationResponse> {
+    try {
+      const result = await prisma.notification.deleteMany({
+        where: {
+          userId,
+          read: true,
+          NOT: {
+            type: "DEADLINE",
+          },
+        },
+      });
+
+      return {
+        success: true,
+        message: `Cleaned ${result.count} seen non-deadline notifications`,
+        data: { count: result.count },
+      };
+    } catch (error) {
+      if (isNotificationTableMissingError(error)) {
+        warnMissingNotificationTableOnce();
+        return {
+          success: true,
+          message: "Notification table missing. Read cleanup skipped.",
+          data: { count: 0 },
+        };
+      }
+
+      console.error("Error cleaning read non-deadline notifications:", error);
+      return {
+        success: false,
+        error:
+          error instanceof Error
+            ? error.message
+            : "Failed to cleanup seen notifications",
+      };
+    }
+  }
+
  /**
   * Creates a new notification for a user
   *
@@ -162,6 +202,9 @@ export class NotificationService {
    limit: number = 10,
  ): Promise<NotificationResponse> {
    try {
+      // Enforce retention policy on each read path.
+      await this.cleanupReadNonDeadline(userId);
+
      const notifications = await prisma.notification.findMany({
        where: {
          userId,
@@ -220,6 +263,9 @@ export class NotificationService {
    limit: number = 50,
  ): Promise<NotificationResponse> {
    try {
+      // Enforce retention policy on each read path.
+      await this.cleanupReadNonDeadline(userId);
+
      const notifications = await prisma.notification.findMany({
        where: {
          userId,
@@ -282,6 +328,21 @@ export class NotificationService {
        data: { read: true },
      });

+      if (notification.type !== "DEADLINE") {
+        await prisma.notification.delete({
+          where: { id: notificationId },
+        });
+
+        return {
+          success: true,
+          message: "Notification marked as read and auto-deleted",
+          data: {
+            id: notificationId,
+            deleted: true,
+          },
+        };
+      }
+
      return {
        success: true,
        data: notification,
@@ -322,10 +383,13 @@ export class NotificationService {
        data: { read: true },
      });

+      const cleanup = await this.cleanupReadNonDeadline(userId);
+      const cleanupCount = cleanup.success ? cleanup.data?.count || 0 : 0;
+
      return {
        success: true,
-        message: `Marked ${result.count} notifications as read`,
-        data: { count: result.count },
+        message: `Marked ${result.count} notifications as read and auto-deleted ${cleanupCount} non-deadline items`,
+        data: { count: result.count, deletedCount: cleanupCount },
      };
    } catch (error) {
      if (isNotificationTableMissingError(error)) {
@@ -446,6 +510,9 @@ export class NotificationService {
   */
  static async getUnreadCount(userId: string): Promise<NotificationResponse> {
    try {
+      // Enforce retention policy on count path as well.
+      await this.cleanupReadNonDeadline(userId);
+
      const count = await prisma.notification.count({
        where: {
          userId,
--- a/public/Contrat_Credit_Immobilier_BTE.pdf
+++ b/public/Contrat_Credit_Immobilier_BTE.pdf
--- a/tailwind.config.ts
+++ b/tailwind.config.ts
@@ -82,11 +82,16 @@ const config: Config = {
          "0%,70%,100%": { opacity: "1" },
          "20%,50%": { opacity: "0" },
        },
+        "progress-loading": {
+          "0%": { transform: "translateX(-100%)" },
+          "100%": { transform: "translateX(100%)" },
+        },
      },
      animation: {
        "accordion-down": "accordion-down 0.2s ease-out",
        "accordion-up": "accordion-up 0.2s ease-out",
        "caret-blink": "caret-blink 1.25s ease-out infinite",
+        "progress-loading": "progress-loading 1.5s infinite linear",
      },
    },
  },
--- a/types/contract.types.ts
+++ b/types/contract.types.ts
@@ -38,6 +38,16 @@ export interface Contract {
    exclusions?: string[];
    franchise?: string;
    importantDates?: string[];
+    explainability?: Array<{
+      field: string;
+      why: string;
+      sourceSnippet: string;
+      sourceHints?: {
+        page?: string | null;
+        section?: string | null;
+        confidence?: number | null;
+      };
+    }>;
  } | null;

  documentHash: string | null;
@@ -79,5 +89,15 @@ export interface AIAnalysisResult {
    exclusions?: string[];
    franchise?: string;
    importantDates?: string[];
+    explainability?: Array<{
+      field: string;
+      why: string;
+      sourceSnippet: string;
+      sourceHints?: {
+        page?: string | null;
+        section?: string | null;
+        confidence?: number | null;
+      };
+    }>;
  };
 }