CSV file upload to WFM folder implemeted

added jenkins for pipeline

.cursor/project_setup.md

@@ -1326,9 +1326,9 @@ GCP_KEY_FILE=./config/gcp-key.json
 SMTP_HOST=smtp.gmail.com
 SMTP_PORT=587
 SMTP_SECURE=false
-SMTP_USER=notifications@royalenfield.com
+SMTP_USER=notifications@{{APP_DOMAIN}}
 SMTP_PASSWORD=your_smtp_password
-EMAIL_FROM=RE Workflow System <notifications@royalenfield.com>
+EMAIL_FROM=RE Workflow System <notifications@{{APP_DOMAIN}}>
 
 # AI Service (for conclusion generation)
 AI_API_KEY=your_ai_api_key

Business_Days_Calculation_Recommendations.md

@@ -155,13 +155,13 @@ export async function calculateBusinessDays(
 2. ✅ Imported `calculateElapsedWorkingHours`, `addWorkingHours`, `addWorkingHoursExpress` from `@utils/tatTimeUtils`
 3. ✅ Replaced lines 64-65 with proper working hours calculation (now lines 66-77)
 4. ✅ Gets priority from workflow
-5. ⏳ **TODO:** Test TAT breach alerts
+5. Done: Test TAT breach alerts
 
 ### Step 2: Add Business Days Function ✅ **DONE**
 1. ✅ Opened `Re_Backend/src/utils/tatTimeUtils.ts`
 2. ✅ Added `calculateBusinessDays()` function (lines 697-758)
 3. ✅ Exported the function
-4. ⏳ **TODO:** Test with various date ranges
+4. Done: Test with various date ranges
 
 ### Step 3: Update Workflow Aging Report ✅ **DONE**
 1. ✅ Built report endpoint using `calculateBusinessDays()`

GENERATE_VAPID_KEYS.md

@@ -19,10 +19,10 @@ This command will output something like:
 ```
 =======================================
 Public Key:
-BEl62iUYgUivxIkvpY5kXK3t3b9i5X8YzA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6
+{{VAPID_PUBLIC_KEY}}
 
 Private Key:
-aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz
+{{VAPID_PRIVATE_KEY}}
 
 =======================================
 ```
@@ -59,9 +59,9 @@ Add the generated keys to your backend `.env` file:
 
 ```env
 # Notification Service Worker credentials (Web Push / VAPID)
-VAPID_PUBLIC_KEY=BEl62iUYgUivxIkvpY5kXK3t3b9i5X8YzA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6
-VAPID_PRIVATE_KEY=aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz
-VAPID_CONTACT=mailto:admin@royalenfield.com
+VAPID_PUBLIC_KEY={{VAPID_PUBLIC_KEY}}
+VAPID_PRIVATE_KEY={{VAPID_PRIVATE_KEY}}
+VAPID_CONTACT=mailto:{{ADMIN_EMAIL}}
 ```
 
 **Important Notes:**
@@ -75,7 +75,7 @@ Add the **SAME** `VAPID_PUBLIC_KEY` to your frontend `.env` file:
 
 ```env
 # Push Notifications (Web Push / VAPID)
-VITE_PUBLIC_VAPID_KEY=BEl62iUYgUivxIkvpY5kXK3t3b9i5X8YzA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6
+VITE_PUBLIC_VAPID_KEY={{VAPID_PUBLIC_KEY}}
 ```
 
 **Important:** 

Jenkinsfile

@@ -0,0 +1,325 @@
+pipeline {
+    agent any
+
+    environment {
+        SSH_CREDENTIALS = 'cloudtopiaa'
+        REMOTE_SERVER = 'ubuntu@160.187.166.17'
+        PROJECT_NAME = 'Royal-Enfield-Backend'
+        DEPLOY_PATH = '/home/ubuntu/Royal-Enfield/Re_Backend'
+        GIT_CREDENTIALS = 'git-cred'
+        REPO_URL = 'https://git.tech4biz.wiki/laxmanhalaki/Re_Backend.git'
+        GIT_BRANCH = 'main'
+        NPM_PATH = '/home/ubuntu/.nvm/versions/node/v22.21.1/bin/npm'
+        NODE_PATH = '/home/ubuntu/.nvm/versions/node/v22.21.1/bin/node'
+        PM2_PATH = '/home/ubuntu/.nvm/versions/node/v22.21.1/bin/pm2'
+        PM2_APP_NAME = 'royal-enfield-backend'
+        APP_PORT = '5000'
+        EMAIL_RECIPIENT = 'laxman.halaki@tech4biz.org'
+    }
+
+    options {
+        timeout(time: 20, unit: 'MINUTES')
+        disableConcurrentBuilds()
+        timestamps()
+        buildDiscarder(logRotator(numToKeepStr: '10', daysToKeepStr: '30'))
+    }
+
+    stages {
+        stage('Pre-deployment Check') {
+            steps {
+                script {
+                    echo "═══════════════════════════════════════════"
+                    echo "🚀 Starting ${PROJECT_NAME} Deployment"
+                    echo "═══════════════════════════════════════════"
+                    echo "Server: ${REMOTE_SERVER}"
+                    echo "Deploy Path: ${DEPLOY_PATH}"
+                    echo "PM2 App: ${PM2_APP_NAME}"
+                    echo "Build #: ${BUILD_NUMBER}"
+                    echo "═══════════════════════════════════════════"
+                }
+            }
+        }
+
+        stage('Pull Latest Code') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    withCredentials([usernamePassword(credentialsId: GIT_CREDENTIALS, usernameVariable: 'GIT_USER', passwordVariable: 'GIT_PASS')]) {
+                        sh """
+                        ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+
+echo "📦 Git Operations..."
+
+if [ -d "${DEPLOY_PATH}/.git" ]; then
+    cd ${DEPLOY_PATH}
+    
+    echo "Configuring git..."
+    git config --global --add safe.directory ${DEPLOY_PATH}
+    git config credential.helper store
+    
+    echo "Fetching updates..."
+    git fetch https://${GIT_USER}:${GIT_PASS}@git.tech4biz.wiki/laxmanhalaki/Re_Backend.git ${GIT_BRANCH}
+    
+    CURRENT_COMMIT=\$(git rev-parse HEAD)
+    LATEST_COMMIT=\$(git rev-parse FETCH_HEAD)
+    
+    if [ "\$CURRENT_COMMIT" = "\$LATEST_COMMIT" ]; then
+        echo "⚠️  Already up to date. No changes to deploy."
+        echo "Current: \$CURRENT_COMMIT"
+    else
+        echo "Pulling new changes..."
+        git reset --hard FETCH_HEAD
+        git clean -fd
+        echo "✓ Updated from \${CURRENT_COMMIT:0:7} to \${LATEST_COMMIT:0:7}"
+    fi
+else
+    echo "Cloning repository..."
+    rm -rf ${DEPLOY_PATH}
+    mkdir -p /home/ubuntu/Royal-Enfield
+    cd /home/ubuntu/Royal-Enfield
+    git clone https://${GIT_USER}:${GIT_PASS}@git.tech4biz.wiki/laxmanhalaki/Re_Backend.git Re_Backend
+    cd ${DEPLOY_PATH}
+    git checkout ${GIT_BRANCH}
+    git config --global --add safe.directory ${DEPLOY_PATH}
+    echo "✓ Repository cloned successfully"
+fi
+
+cd ${DEPLOY_PATH}
+echo "Current commit: \$(git log -1 --oneline)"
+ENDSSH
+                        """
+                    }
+                }
+            }
+        }
+
+        stage('Install Dependencies') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    sh """
+                    ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+cd ${DEPLOY_PATH}
+
+echo "🔧 Environment Check..."
+echo "Node: \$(${NODE_PATH} -v)"
+echo "NPM: \$(${NPM_PATH} -v)"
+
+echo ""
+echo "📥 Installing Dependencies..."
+${NPM_PATH} install --prefer-offline --no-audit --progress=false
+
+echo ""
+echo "✅ Dependencies installed successfully!"
+ENDSSH
+                    """
+                }
+            }
+        }
+
+        stage('Build Application') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    sh """
+                    ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+cd ${DEPLOY_PATH}
+
+echo "🔨 Building application..."
+${NPM_PATH} run build
+echo "✅ Build completed successfully!"
+ENDSSH
+                    """
+                }
+            }
+        }
+
+        stage('Stop PM2 Process') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    sh """
+                    ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+
+echo "🛑 Stopping existing PM2 process..."
+
+if ${PM2_PATH} list | grep -q "${PM2_APP_NAME}"; then
+    echo "Stopping ${PM2_APP_NAME}..."
+    ${PM2_PATH} stop ${PM2_APP_NAME} || true
+    ${PM2_PATH} delete ${PM2_APP_NAME} || true
+    echo "✓ Process stopped"
+else
+    echo "No existing process found"
+fi
+ENDSSH
+                    """
+                }
+            }
+        }
+
+        stage('Start with PM2') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    sh """
+                    ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+cd ${DEPLOY_PATH}
+
+echo "🚀 Starting application with PM2..."
+
+# Start with PM2
+${PM2_PATH} start ${NPM_PATH} --name "${PM2_APP_NAME}" -- start
+
+echo ""
+echo "⏳ Waiting for application to start..."
+sleep 5
+
+# Save PM2 configuration
+${PM2_PATH} save
+
+# Show PM2 status
+echo ""
+echo "📊 PM2 Process Status:"
+${PM2_PATH} list
+
+# Show logs (last 20 lines)
+echo ""
+echo "📝 Application Logs:"
+${PM2_PATH} logs ${PM2_APP_NAME} --lines 20 --nostream || true
+
+echo ""
+echo "✅ Application started successfully!"
+ENDSSH
+                    """
+                }
+            }
+        }
+
+        stage('Health Check') {
+            steps {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    sh """
+                    ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} << 'ENDSSH'
+set -e
+export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+
+echo "🔍 Deployment Verification..."
+
+# Check if PM2 process is running
+if ${PM2_PATH} list | grep -q "${PM2_APP_NAME}.*online"; then
+    echo "✓ PM2 process is running"
+else
+    echo "✗ PM2 process is NOT running!"
+    ${PM2_PATH} logs ${PM2_APP_NAME} --lines 50 --nostream || true
+    exit 1
+fi
+
+# Check if port is listening
+echo ""
+echo "Checking if port ${APP_PORT} is listening..."
+if ss -tuln | grep -q ":${APP_PORT} "; then
+    echo "✓ Application is listening on port ${APP_PORT}"
+else
+    echo "⚠️  Port ${APP_PORT} not detected (may take a moment to start)"
+fi
+
+# Show process info
+echo ""
+echo "📊 Process Information:"
+${PM2_PATH} info ${PM2_APP_NAME}
+
+echo ""
+echo "═══════════════════════════════════════════"
+echo "✅ DEPLOYMENT SUCCESSFUL"
+echo "═══════════════════════════════════════════"
+ENDSSH
+                    """
+                }
+            }
+        }
+    }
+
+    post {
+        always {
+            cleanWs()
+        }
+        success {
+            script {
+                def duration = currentBuild.durationString.replace(' and counting', '')
+                mail to: "${EMAIL_RECIPIENT}",
+                     subject: "✅ ${PROJECT_NAME} - Deployment Successful #${BUILD_NUMBER}",
+                     body: """
+Deployment completed successfully!
+
+Project: ${PROJECT_NAME}
+Build: #${BUILD_NUMBER}
+Duration: ${duration}
+Server: ${REMOTE_SERVER}
+PM2 App: ${PM2_APP_NAME}
+Port: ${APP_PORT}
+
+Deployed at: ${new Date().format('yyyy-MM-dd HH:mm:ss')}
+
+Console: ${BUILD_URL}console
+
+Commands to manage:
+- View logs: pm2 logs ${PM2_APP_NAME}
+- Restart: pm2 restart ${PM2_APP_NAME}
+- Stop: pm2 stop ${PM2_APP_NAME}
+"""
+            }
+        }
+        failure {
+            script {
+                sshagent(credentials: [SSH_CREDENTIALS]) {
+                    try {
+                        def logs = sh(
+                            script: """ssh -o StrictHostKeyChecking=no ${REMOTE_SERVER} '
+                                export PATH="/home/ubuntu/.nvm/versions/node/v22.21.1/bin:\$PATH"
+                                ${PM2_PATH} logs ${PM2_APP_NAME} --lines 50 --nostream || echo "No logs available"
+                            '""",
+                            returnStdout: true
+                        ).trim()
+                        
+                        mail to: "${EMAIL_RECIPIENT}",
+                             subject: "❌ ${PROJECT_NAME} - Deployment Failed #${BUILD_NUMBER}",
+                             body: """
+Deployment FAILED!
+
+Project: ${PROJECT_NAME}
+Build: #${BUILD_NUMBER}
+Server: ${REMOTE_SERVER}
+Failed at: ${new Date().format('yyyy-MM-dd HH:mm:ss')}
+
+Console Log: ${BUILD_URL}console
+
+Recent PM2 Logs:
+${logs}
+
+Action required immediately!
+"""
+                    } catch (Exception e) {
+                        mail to: "${EMAIL_RECIPIENT}",
+                             subject: "❌ ${PROJECT_NAME} - Deployment Failed #${BUILD_NUMBER}",
+                             body: """
+Deployment FAILED!
+
+Project: ${PROJECT_NAME}
+Build: #${BUILD_NUMBER}
+Server: ${REMOTE_SERVER}
+Failed at: ${new Date().format('yyyy-MM-dd HH:mm:ss')}
+
+Console Log: ${BUILD_URL}console
+
+Could not retrieve PM2 logs. Please check manually.
+"""
+                    }
+                }
+            }
+        }
+    }
+}

MIGRATION_MERGE_COMPLETE.md

@@ -0,0 +1,63 @@
+# Migration Merge Complete ✅
+
+## Status: All Conflicts Resolved
+
+Both migration files have been successfully merged with all conflicts resolved.
+
+## Files Merged
+
+### 1. `src/scripts/auto-setup.ts` ✅
+- **Status**: Clean, no conflict markers
+- **Migrations**: All 40 migrations in correct order
+- **Format**: Uses `require()` for CommonJS compatibility
+
+### 2. `src/scripts/migrate.ts` ✅
+- **Status**: Clean, no conflict markers
+- **Migrations**: All 40 migrations in correct order
+- **Format**: Uses ES6 `import * as` syntax
+
+## Migration Order (Final)
+
+### Base Branch Migrations (m0-m29)
+1. m0-m27: Core system migrations
+2. m28: `20250130-migrate-to-vertex-ai`
+3. m29: `20251203-add-user-notification-preferences`
+
+### Dealer Claim Branch Migrations (m30-m39)
+4. m30: `20251210-add-workflow-type-support`
+5. m31: `20251210-enhance-workflow-templates`
+6. m32: `20251210-add-template-id-foreign-key`
+7. m33: `20251210-create-dealer-claim-tables`
+8. m34: `20251210-create-proposal-cost-items-table`
+9. m35: `20251211-create-internal-orders-table`
+10. m36: `20251211-create-claim-budget-tracking-table`
+11. m37: `20251213-drop-claim-details-invoice-columns`
+12. m38: `20251213-create-claim-invoice-credit-note-tables`
+13. m39: `20251214-create-dealer-completion-expenses`
+
+## Verification
+
+✅ No conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) found
+✅ All migrations properly ordered
+✅ Base branch migrations come first
+✅ Dealer claim migrations follow
+✅ Both files synchronized
+
+## Next Steps
+
+1. **If you see conflicts in your IDE/Git client:**
+   - Refresh your IDE/editor
+   - Run `git status` to check Git state
+   - If conflicts show in Git, run: `git add src/scripts/auto-setup.ts src/scripts/migrate.ts`
+
+2. **Test the migrations:**
+   ```bash
+   npm run migrate
+   # or
+   npm run setup
+   ```
+
+## Files Are Ready ✅
+
+Both files are properly merged and ready to use. All 40 migrations are in the correct order with base branch migrations first, followed by dealer claim branch migrations.
+

QUICK_START.md

@@ -98,7 +98,7 @@ npm run dev
    1. Server will start automatically
    2. Log in via SSO
    3. Run this SQL to make yourself admin:
-      UPDATE users SET role = 'ADMIN' WHERE email = 'your-email@royalenfield.com';
+      UPDATE users SET role = 'ADMIN' WHERE email = 'your-email@{{APP_DOMAIN}}';
 
 [Config Seed] ✅ Default configurations seeded successfully (30 settings)
 info: ✅ Server started successfully on port 5000
@@ -112,7 +112,7 @@ psql -d royal_enfield_workflow
 
 UPDATE users 
 SET role = 'ADMIN'
-WHERE email = 'your-email@royalenfield.com';
+WHERE email = 'your-email@{{APP_DOMAIN}}';
 
 \q
 ```

README.md

@@ -471,7 +471,7 @@ The backend supports web push notifications via VAPID (Voluntary Application Ser
    ```
    VAPID_PUBLIC_KEY=<your-public-key>
    VAPID_PRIVATE_KEY=<your-private-key>
-   VAPID_CONTACT=mailto:admin@royalenfield.com
+   VAPID_CONTACT=mailto:admin@{{APP_DOMAIN}}
    ```
 
 3. **Add to Frontend `.env`:**

build/assets/conclusionApi-CId8BmKF.js

@@ -0,0 +1 @@
+import{a as s}from"./index-CULgQ-8S.js";import"./radix-vendor-CYvDqP9X.js";import"./charts-vendor-BVfwAPj-.js";import"./utils-vendor-BTBPSQfW.js";import"./ui-vendor-CX5oLBI_.js";import"./socket-vendor-TjCxX7sJ.js";import"./redux-vendor-tbZCm13o.js";import"./router-vendor-B_rK4TXr.js";async function m(n){return(await s.post(`/conclusions/${n}/generate`)).data.data}async function f(n,t){return(await s.post(`/conclusions/${n}/finalize`,{finalRemark:t})).data.data}async function d(n){var t;try{return(await s.get(`/conclusions/${n}`)).data.data}catch(o){if(((t=o.response)==null?void 0:t.status)===404)return null;throw o}}export{f as finalizeConclusion,m as generateConclusion,d as getConclusion};

build/assets/conclusionApi-uNxtglEr.js

@@ -1,2 +0,0 @@
-import{a as t}from"./index-9cOIFSn9.js";import"./radix-vendor-C2EbRL2a.js";import"./charts-vendor-Cji9-Yri.js";import"./utils-vendor-DHm03ykU.js";import"./ui-vendor-BmvKDhMD.js";import"./socket-vendor-TjCxX7sJ.js";import"./redux-vendor-tbZCm13o.js";import"./router-vendor-CRr9x_Jp.js";async function m(n){return(await t.post(`/conclusions/${n}/generate`)).data.data}async function d(n,o){return(await t.post(`/conclusions/${n}/finalize`,{finalRemark:o})).data.data}async function f(n){return(await t.get(`/conclusions/${n}`)).data.data}export{d as finalizeConclusion,m as generateConclusion,f as getConclusion};
-//# sourceMappingURL=conclusionApi-uNxtglEr.js.map

build/assets/conclusionApi-uNxtglEr.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"conclusionApi-uNxtglEr.js","sources":["../../src/services/conclusionApi.ts"],"sourcesContent":["import apiClient from './authApi';\r\n\r\nexport interface ConclusionRemark {\r\n  conclusionId: string;\r\n  requestId: string;\r\n  aiGeneratedRemark: string | null;\r\n  aiModelUsed: string | null;\r\n  aiConfidenceScore: number | null;\r\n  finalRemark: string | null;\r\n  editedBy: string | null;\r\n  isEdited: boolean;\r\n  editCount: number;\r\n  approvalSummary: any;\r\n  documentSummary: any;\r\n  keyDiscussionPoints: string[];\r\n  generatedAt: string | null;\r\n  finalizedAt: string | null;\r\n  createdAt: string;\r\n  updatedAt: string;\r\n}\r\n\r\n/**\r\n * Generate AI-powered conclusion remark\r\n */\r\nexport async function generateConclusion(requestId: string): Promise<{\r\n  conclusionId: string;\r\n  aiGeneratedRemark: string;\r\n  keyDiscussionPoints: string[];\r\n  confidence: number;\r\n  generatedAt: string;\r\n}> {\r\n  const response = await apiClient.post(`/conclusions/${requestId}/generate`);\r\n  return response.data.data;\r\n}\r\n\r\n/**\r\n * Update conclusion remark (edit by initiator)\r\n */\r\nexport async function updateConclusion(requestId: string, finalRemark: string): Promise<ConclusionRemark> {\r\n  const response = await apiClient.put(`/conclusions/${requestId}`, { finalRemark });\r\n  return response.data.data;\r\n}\r\n\r\n/**\r\n * Finalize conclusion and close request\r\n */\r\nexport async function finalizeConclusion(requestId: string, finalRemark: string): Promise<{\r\n  conclusionId: string;\r\n  requestNumber: string;\r\n  status: string;\r\n  finalRemark: string;\r\n  finalizedAt: string;\r\n}> {\r\n  const response = await apiClient.post(`/conclusions/${requestId}/finalize`, { finalRemark });\r\n  return response.data.data;\r\n}\r\n\r\n/**\r\n * Get conclusion for a request\r\n */\r\nexport async function getConclusion(requestId: string): Promise<ConclusionRemark> {\r\n  const response = await apiClient.get(`/conclusions/${requestId}`);\r\n  return response.data.data;\r\n}\r\n\r\n"],"names":["generateConclusion","requestId","apiClient","finalizeConclusion","finalRemark","getConclusion"],"mappings":"6RAwBA,eAAsBA,EAAmBC,EAMtC,CAED,OADiB,MAAMC,EAAU,KAAK,gBAAgBD,CAAS,WAAW,GAC1D,KAAK,IACvB,CAaA,eAAsBE,EAAmBF,EAAmBG,EAMzD,CAED,OADiB,MAAMF,EAAU,KAAK,gBAAgBD,CAAS,YAAa,CAAE,YAAAG,EAAa,GAC3E,KAAK,IACvB,CAKA,eAAsBC,EAAcJ,EAA8C,CAEhF,OADiB,MAAMC,EAAU,IAAI,gBAAgBD,CAAS,EAAE,GAChD,KAAK,IACvB"}

build/index.html

@@ -1,69 +1,31 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
+
+<head>
   <meta charset="UTF-8" />
-    <!-- CSP: Allows blob URLs for file previews and cross-origin API calls during development -->
-    <meta http-equiv="Content-Security-Policy" content="default-src 'self' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; script-src 'self'; img-src 'self' data: https: blob:; connect-src 'self' blob: data: http://localhost:5000 http://localhost:3000 ws://localhost:5000 ws://localhost:3000 wss://localhost:5000 wss://localhost:3000; frame-src 'self' blob:; font-src 'self' https://fonts.gstatic.com data:; object-src 'none'; base-uri 'self'; form-action 'self';" />
   <link rel="icon" type="image/svg+xml" href="/royal_enfield_logo.svg" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="Royal Enfield Approval & Request Management Portal - Streamlined approval workflows for enterprise operations" />
+  <meta name="description"
+    content="Royal Enfield Approval & Request Management Portal - Streamlined approval workflows for enterprise operations" />
   <meta name="theme-color" content="#2d4a3e" />
   <title>Royal Enfield | Approval Portal</title>
 
-    <!-- Preload critical fonts and icons -->
+  <!-- Preload essential fonts and icons -->
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    
-    <!-- Ensure proper icon rendering and layout -->
-    <style>
-      /* Ensure Lucide icons render properly */
-      svg {
-        display: inline-block;
-        vertical-align: middle;
-      }
-      
-      /* Fix for icon alignment in buttons */
-      button svg {
-        flex-shrink: 0;
-      }
-      
-      /* Ensure proper text rendering */
-      body {
-        -webkit-font-smoothing: antialiased;
-        -moz-osx-font-smoothing: grayscale;
-        text-rendering: optimizeLegibility;
-      }
-      
-      /* Fix for mobile viewport and sidebar */
-      @media (max-width: 768px) {
-        html {
-          overflow-x: hidden;
-        }
-      }
-      
-      /* Ensure proper sidebar toggle behavior */
-      .sidebar-toggle {
-        transition: all 0.3s ease-in-out;
-      }
-      
-      /* Fix for icon button hover states */
-      button:hover svg {
-        transform: scale(1.05);
-        transition: transform 0.2s ease;
-      }
-    </style>
-    <script type="module" crossorigin src="/assets/index-9cOIFSn9.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/charts-vendor-Cji9-Yri.js">
-    <link rel="modulepreload" crossorigin href="/assets/radix-vendor-C2EbRL2a.js">
-    <link rel="modulepreload" crossorigin href="/assets/utils-vendor-DHm03ykU.js">
-    <link rel="modulepreload" crossorigin href="/assets/ui-vendor-BmvKDhMD.js">
+  <script type="module" crossorigin src="/assets/index-CULgQ-8S.js"></script>
+  <link rel="modulepreload" crossorigin href="/assets/charts-vendor-BVfwAPj-.js">
+  <link rel="modulepreload" crossorigin href="/assets/radix-vendor-CYvDqP9X.js">
+  <link rel="modulepreload" crossorigin href="/assets/utils-vendor-BTBPSQfW.js">
+  <link rel="modulepreload" crossorigin href="/assets/ui-vendor-CX5oLBI_.js">
   <link rel="modulepreload" crossorigin href="/assets/socket-vendor-TjCxX7sJ.js">
   <link rel="modulepreload" crossorigin href="/assets/redux-vendor-tbZCm13o.js">
-    <link rel="modulepreload" crossorigin href="/assets/router-vendor-CRr9x_Jp.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BmOYs32D.css">
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>
+  <link rel="modulepreload" crossorigin href="/assets/router-vendor-B_rK4TXr.js">
+  <link rel="stylesheet" crossorigin href="/assets/index-XBJXaMj2.css">
+</head>
 
+<body>
+  <div id="root"></div>
+</body>
+
+</html>

build/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Disallow: /api/
+
+Sitemap: https://reflow.royalenfield.com/sitemap.xml

build/sitemap.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://reflow.royalenfield.com</loc>
+    <lastmod>2024-03-20T12:00:00+00:00</lastmod>
+    <changefreq>daily</changefreq>
+    <priority>1.0</priority>
+  </url>
+</urlset>

docker-compose.full.yml

@@ -1,39 +1,8 @@
-# =============================================================================
-# RE Workflow - Full Stack Docker Compose
-# Includes: Application + Database + Monitoring Stack
-# =============================================================================
-# Usage:
-#   docker-compose -f docker-compose.full.yml up -d
-# =============================================================================
-
+# docker-compose.full.yml
+# Synced with streamlined infrastructure
 version: '3.8'
 
 services:
-  # ===========================================================================
-  # APPLICATION SERVICES
-  # ===========================================================================
-  
-  postgres:
-    image: postgres:16-alpine
-    container_name: re_workflow_db
-    environment:
-      POSTGRES_USER: ${DB_USER:-laxman}
-      POSTGRES_PASSWORD: ${DB_PASSWORD:-Admin@123}
-      POSTGRES_DB: ${DB_NAME:-re_workflow_db}
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-      - ./database/schema:/docker-entrypoint-initdb.d
-    networks:
-      - re_workflow_network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-laxman}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
   redis:
     image: redis:7-alpine
     container_name: re_workflow_redis
@@ -50,70 +19,24 @@ services:
       timeout: 5s
       retries: 5
 
-  backend:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: re_workflow_backend
+  clamav:
+    image: clamav/clamav:latest
+    container_name: re_clamav
+    ports:
+      - "3310:3310"
+    volumes:
+      - clamav_data:/var/lib/clamav
     environment:
-      NODE_ENV: development
-      DB_HOST: postgres
-      DB_PORT: 5432
-      DB_USER: ${DB_USER:-laxman}
-      DB_PASSWORD: ${DB_PASSWORD:-Admin@123}
-      DB_NAME: ${DB_NAME:-re_workflow_db}
-      REDIS_URL: redis://redis:6379
-      PORT: 5000
-      # Loki for logging
-      LOKI_HOST: http://loki:3100
-    ports:
-      - "5000:5000"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    volumes:
-      - ./logs:/app/logs
-      - ./uploads:/app/uploads
+      - CLAMAV_NO_FRESHCLAMD=false
+    healthcheck:
+      test: ["CMD", "clamdcheck"]
+      interval: 60s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    restart: unless-stopped
     networks:
       - re_workflow_network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:5000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})\""]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-
-  # ===========================================================================
-  # MONITORING SERVICES
-  # ===========================================================================
-
-  prometheus:
-    image: prom/prometheus:v2.47.2
-    container_name: re_prometheus
-    ports:
-      - "9090:9090"
-    volumes:
-      - ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
-      - ./monitoring/prometheus/alert.rules.yml:/etc/prometheus/alert.rules.yml:ro
-      - prometheus_data:/prometheus
-    command:
-      - '--config.file=/etc/prometheus/prometheus.yml'
-      - '--storage.tsdb.path=/prometheus'
-      - '--storage.tsdb.retention.time=15d'
-      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
-      - '--web.console.templates=/usr/share/prometheus/consoles'
-      - '--web.enable-lifecycle'
-    networks:
-      - re_workflow_network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9090/-/healthy"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
 
   loki:
     image: grafana/loki:2.9.2
@@ -156,15 +79,12 @@ services:
       - GF_SECURITY_ADMIN_USER=admin
       - GF_SECURITY_ADMIN_PASSWORD=REWorkflow@2024
       - GF_USERS_ALLOW_SIGN_UP=false
-      - GF_FEATURE_TOGGLES_ENABLE=publicDashboards
-      - GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource,grafana-piechart-panel
     volumes:
       - grafana_data:/var/lib/grafana
       - ./monitoring/grafana/provisioning/datasources:/etc/grafana/provisioning/datasources:ro
       - ./monitoring/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
       - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro
     depends_on:
-      - prometheus
       - loki
     networks:
       - re_workflow_network
@@ -175,54 +95,13 @@ services:
       timeout: 10s
       retries: 3
 
-  node-exporter:
-    image: prom/node-exporter:v1.6.1
-    container_name: re_node_exporter
-    ports:
-      - "9100:9100"
-    networks:
-      - re_workflow_network
-    restart: unless-stopped
+volumes:
+  redis_data:
+  clamav_data:
+  loki_data:
+  promtail_data:
+  grafana_data:
 
-  alertmanager:
-    image: prom/alertmanager:v0.26.0
-    container_name: re_alertmanager
-    ports:
-      - "9093:9093"
-    volumes:
-      - ./monitoring/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
-      - alertmanager_data:/alertmanager
-    command:
-      - '--config.file=/etc/alertmanager/alertmanager.yml'
-      - '--storage.path=/alertmanager'
-    networks:
-      - re_workflow_network
-    restart: unless-stopped
-
-# ===========================================================================
-# NETWORKS
-# ===========================================================================
 networks:
   re_workflow_network:
     driver: bridge
-    name: re_workflow_network
-
-# ===========================================================================
-# VOLUMES
-# ===========================================================================
-volumes:
-  postgres_data:
-    name: re_postgres_data
-  redis_data:
-    name: re_redis_data
-  prometheus_data:
-    name: re_prometheus_data
-  loki_data:
-    name: re_loki_data
-  promtail_data:
-    name: re_promtail_data
-  grafana_data:
-    name: re_grafana_data
-  alertmanager_data:
-    name: re_alertmanager_data
-

docker-compose.yml

@@ -1,28 +1,8 @@
 # docker-compose.yml
+# Streamlined infrastructure for local development
 version: '3.8'
 
 services:
-  postgres:
-    image: postgres:16-alpine
-    container_name: re_workflow_db
-    environment:
-      POSTGRES_USER: ${DB_USER:-laxman}
-      POSTGRES_PASSWORD: ${DB_PASSWORD:-Admin@123}
-      POSTGRES_DB: ${DB_NAME:-re_workflow_db}
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-      - ./database/schema:/docker-entrypoint-initdb.d
-    networks:
-      - re_workflow_network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-laxman}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
   redis:
     image: redis:7-alpine
     container_name: re_workflow_redis
@@ -39,43 +19,88 @@ services:
       timeout: 5s
       retries: 5
 
-  backend:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: re_workflow_backend
-    environment:
-      NODE_ENV: development
-      DB_HOST: postgres
-      DB_PORT: 5432
-      DB_USER: ${DB_USER:-laxman}
-      DB_PASSWORD: ${DB_PASSWORD:-Admin@123}
-      DB_NAME: ${DB_NAME:-re_workflow_db}
-      REDIS_URL: redis://redis:6379
-      PORT: 5000
+  clamav:
+    image: clamav/clamav:latest
+    container_name: re_clamav
     ports:
-      - "5000:5000"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
+      - "3310:3310"
     volumes:
-      - ./logs:/app/logs
-      - ./uploads:/app/uploads
+      - clamav_data:/var/lib/clamav
+    environment:
+      - CLAMAV_NO_FRESHCLAMD=false
+    healthcheck:
+      test: ["CMD", "clamdcheck"]
+      interval: 60s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    restart: unless-stopped
+    networks:
+      - re_workflow_network
+
+  loki:
+    image: grafana/loki:2.9.2
+    container_name: re_loki
+    ports:
+      - "3100:3100"
+    volumes:
+      - ./monitoring/loki/loki-config.yml:/etc/loki/local-config.yaml:ro
+      - loki_data:/loki
+    command: -config.file=/etc/loki/local-config.yaml
     networks:
       - re_workflow_network
     restart: unless-stopped
     healthcheck:
-      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:5000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})\""]
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3100/ready || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+  promtail:
+    image: grafana/promtail:2.9.2
+    container_name: re_promtail
+    volumes:
+      - ./monitoring/promtail/promtail-config.yml:/etc/promtail/config.yml:ro
+      - ./logs:/var/log/app:ro
+      - promtail_data:/tmp/promtail
+    command: -config.file=/etc/promtail/config.yml
+    depends_on:
+      - loki
+    networks:
+      - re_workflow_network
+    restart: unless-stopped
+
+  grafana:
+    image: grafana/grafana:10.2.2
+    container_name: re_grafana
+    ports:
+      - "3001:3000"
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=REWorkflow@2024
+      - GF_USERS_ALLOW_SIGN_UP=false
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./monitoring/grafana/provisioning/datasources:/etc/grafana/provisioning/datasources:ro
+      - ./monitoring/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
+      - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro
+    depends_on:
+      - loki
+    networks:
+      - re_workflow_network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1"]
       interval: 30s
       timeout: 10s
       retries: 3
-      start_period: 40s
 
 volumes:
-  postgres_data:
   redis_data:
+  clamav_data:
+  loki_data:
+  promtail_data:
+  grafana_data:
 
 networks:
   re_workflow_network:

docs/AI_CONCLUSION_REMARK_GENERATION.md

@@ -15,15 +15,16 @@
 
 ## Overview
 
-The AI Conclusion Remark Generation feature automatically generates professional, context-aware conclusion remarks for workflow requests that have been approved or rejected. This feature uses AI providers (Claude, OpenAI, or Gemini) to analyze the entire request lifecycle and create a comprehensive summary suitable for permanent archiving.
+The AI Conclusion Remark Generation feature automatically generates professional, context-aware conclusion remarks for workflow requests that have been approved or rejected. This feature uses **Google Cloud Vertex AI Gemini** to analyze the entire request lifecycle and create a comprehensive summary suitable for permanent archiving.
 
 ### Key Features
-- **Multi-Provider Support**: Supports Claude (Anthropic), OpenAI (GPT-4), and Google Gemini
+- **Vertex AI Integration**: Uses Google Cloud Vertex AI Gemini with service account authentication
 - **Context-Aware**: Analyzes approval flow, work notes, documents, and activities
-- **Configurable**: Admin-configurable max length, provider selection, and enable/disable
+- **Configurable**: Admin-configurable max length, model selection, and enable/disable
 - **Automatic Generation**: Can be triggered automatically when a request is approved/rejected
 - **Manual Generation**: Users can regenerate conclusions on demand
 - **Editable**: Generated remarks can be edited before finalization
+- **Enterprise Security**: Uses same service account credentials as Google Cloud Storage
 
 ### Use Cases
 1. **Automatic Generation**: When the final approver approves/rejects a request, an AI conclusion is generated in the background
@@ -74,10 +75,10 @@ The AI Conclusion Remark Generation feature automatically generates professional
 │                        │                                      │
 │                        ▼                                      │
 │  ┌──────────────────────────────────────────────────────┐  │
-│  │  AI Providers (Claude/OpenAI/Gemini)                  │  │
-│  │  - ClaudeProvider                                     │  │
-│  │  - OpenAIProvider                                     │  │
-│  │  - GeminiProvider                                     │  │
+│  │  Vertex AI Gemini (Google Cloud)                      │  │
+│  │  - VertexAI Client                                    │  │
+│  │  - Service Account Authentication                     │  │
+│  │  - Gemini Models (gemini-2.5-flash, etc.)            │  │
 │  └──────────────────────────────────────────────────────┘  │
 │                        │                                      │
 │                        ▼                                      │
@@ -114,22 +115,18 @@ The AI Conclusion Remark Generation feature automatically generates professional
 ### Environment Variables
 
 ```bash
-# AI Provider Selection (claude, openai, gemini)
-AI_PROVIDER=claude
+# Google Cloud Configuration (required - same as GCS)
+GCP_PROJECT_ID=re-platform-workflow-dealer
+GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
 
-# Claude Configuration
-CLAUDE_API_KEY=your_claude_api_key
-CLAUDE_MODEL=claude-sonnet-4-20250514
-
-# OpenAI Configuration
-OPENAI_API_KEY=your_openai_api_key
-OPENAI_MODEL=gpt-4o
-
-# Gemini Configuration
-GEMINI_API_KEY=your_gemini_api_key
-GEMINI_MODEL=gemini-2.0-flash-lite
+# Vertex AI Configuration (optional - defaults provided)
+VERTEX_AI_MODEL=gemini-2.5-flash
+VERTEX_AI_LOCATION=asia-south1
+AI_ENABLED=true
 ```
 
+**Note**: The service account key file is the same one used for Google Cloud Storage, ensuring consistent authentication across services.
+
 ### Admin Configuration (Database)
 
 The system reads configuration from the `system_config` table. Key settings:
@@ -138,21 +135,29 @@ The system reads configuration from the `system_config` table. Key settings:
 |------------|---------|-------------|
 | `AI_ENABLED` | `true` | Enable/disable all AI features |
 | `AI_REMARK_GENERATION_ENABLED` | `true` | Enable/disable conclusion generation |
-| `AI_PROVIDER` | `claude` | Preferred AI provider (claude, openai, gemini) |
 | `AI_MAX_REMARK_LENGTH` | `2000` | Maximum characters for generated remarks |
-| `CLAUDE_API_KEY` | - | Claude API key (if using Claude) |
-| `CLAUDE_MODEL` | `claude-sonnet-4-20250514` | Claude model name |
-| `OPENAI_API_KEY` | - | OpenAI API key (if using OpenAI) |
-| `OPENAI_MODEL` | `gpt-4o` | OpenAI model name |
-| `GEMINI_API_KEY` | - | Gemini API key (if using Gemini) |
-| `GEMINI_MODEL` | `gemini-2.0-flash-lite` | Gemini model name |
+| `VERTEX_AI_MODEL` | `gemini-2.5-flash` | Vertex AI Gemini model name |
 
-### Provider Priority
+### Available Models
 
-1. **Preferred Provider**: Set via `AI_PROVIDER` config
-2. **Fallback Chain**: If preferred fails, tries:
-   - Claude → OpenAI → Gemini
-3. **Environment Fallback**: If database config fails, uses environment variables
+| Model Name | Description | Use Case |
+|------------|-------------|----------|
+| `gemini-2.5-flash` | Latest fast model (default) | General purpose, quick responses |
+| `gemini-1.5-flash` | Previous fast model | General purpose |
+| `gemini-1.5-pro` | Advanced model | Complex tasks, better quality |
+| `gemini-1.5-pro-latest` | Latest Pro version | Best quality, complex reasoning |
+
+### Supported Regions
+
+| Region Code | Location | Availability |
+|-------------|----------|--------------|
+| `us-central1` | Iowa, USA | ✅ Default |
+| `us-east1` | South Carolina, USA | ✅ |
+| `us-west1` | Oregon, USA | ✅ |
+| `europe-west1` | Belgium | ✅ |
+| `asia-south1` | Mumbai, India | ✅ (Current default) |
+
+**Note**: Model and region are configured via environment variables, not database config.
 
 ---
 
@@ -186,7 +191,7 @@ Authorization: Bearer <token>
     ],
     "confidence": 0.85,
     "generatedAt": "2025-01-15T10:30:00Z",
-    "provider": "Claude (Anthropic)"
+    "provider": "Vertex AI (Gemini)"
   }
 }
 ```
@@ -254,7 +259,7 @@ Content-Type: application/json
     "finalRemark": "Finalized text...",
     "isEdited": true,
     "editCount": 2,
-    "aiModelUsed": "Claude (Anthropic)",
+    "aiModelUsed": "Vertex AI (Gemini)",
     "aiConfidenceScore": 0.85,
     "keyDiscussionPoints": ["Point 1", "Point 2"],
     "generatedAt": "2025-01-15T10:30:00Z",
@@ -324,9 +329,9 @@ interface ConclusionContext {
    - Sets target word count based on `AI_MAX_REMARK_LENGTH`
 
 3. **AI Generation**:
-   - Sends prompt to selected AI provider
-   - Receives generated text
-   - Validates length (trims if exceeds max)
+   - Sends prompt to Vertex AI Gemini
+   - Receives generated text (up to 4096 tokens)
+   - Preserves full AI response (no truncation)
    - Extracts key points
    - Calculates confidence score
 
@@ -407,13 +412,24 @@ Write a brief, professional conclusion (approximately X words, max Y characters)
 4. **Tone Guidelines**: Emphasizes natural, professional, archival-quality writing
 5. **Context Awareness**: Includes all relevant data (approvals, notes, documents, activities)
 
-### Provider-Specific Settings
+### Vertex AI Settings
 
-| Provider | Model | Max Tokens | Temperature | Notes |
-|----------|-------|------------|-------------|-------|
-| Claude | claude-sonnet-4-20250514 | 2048 | 0.3 | Best for longer, detailed conclusions |
-| OpenAI | gpt-4o | 1024 | 0.3 | Balanced performance |
-| Gemini | gemini-2.0-flash-lite | - | 0.3 | Fast and cost-effective |
+| Setting | Value | Description |
+|---------|-------|-------------|
+| Model | `gemini-2.5-flash` (default) | Fast, efficient model for conclusion generation |
+| Max Output Tokens | `4096` | Maximum tokens in response (technical limit) |
+| Character Limit | `2000` (configurable) | Actual limit enforced via prompt (`AI_MAX_REMARK_LENGTH`) |
+| Temperature | `0.3` | Lower temperature for more focused, consistent output |
+| Location | `asia-south1` (default) | Google Cloud region for API calls |
+| Authentication | Service Account | Uses same credentials as Google Cloud Storage |
+
+**Note on Token vs Character Limits:**
+- **4096 tokens** is the technical maximum Vertex AI can generate
+- **2000 characters** (default) is the actual limit enforced by the prompt
+- Token-to-character conversion: ~1 token ≈ 3-4 characters
+- With HTML tags: 4096 tokens ≈ 12,000-16,000 characters (including tags)
+- The AI is instructed to stay within the character limit, not the token limit
+- The token limit provides headroom but the character limit is what matters for storage
 
 ---
 
@@ -423,15 +439,21 @@ Write a brief, professional conclusion (approximately X words, max Y characters)
 
 1. **No AI Provider Available**
    ```
-   Error: AI features are currently unavailable. Please configure an AI provider...
+   Error: AI features are currently unavailable. Please verify Vertex AI configuration and service account credentials.
    ```
-   **Solution**: Configure API keys in admin panel or environment variables
+   **Solution**: 
+   - Verify service account key file exists at path specified in `GCP_KEY_FILE`
+   - Ensure Vertex AI API is enabled in Google Cloud Console
+   - Check service account has `Vertex AI User` role (`roles/aiplatform.user`)
 
-2. **Provider API Error**
+2. **Vertex AI API Error**
    ```
-   Error: AI generation failed (Claude): API rate limit exceeded
+   Error: AI generation failed (Vertex AI): Model was not found or your project does not have access
    ```
-   **Solution**: Check API key validity, rate limits, and provider status
+   **Solution**: 
+   - Verify model name is correct (e.g., `gemini-2.5-flash`)
+   - Ensure model is available in selected region
+   - Check Vertex AI API is enabled in Google Cloud Console
 
 3. **Request Not Found**
    ```
@@ -453,10 +475,10 @@ Write a brief, professional conclusion (approximately X words, max Y characters)
 
 ### Error Recovery
 
-- **Automatic Fallback**: If preferred provider fails, system tries fallback providers
 - **Graceful Degradation**: If AI generation fails, user can write conclusion manually
 - **Retry Logic**: Manual regeneration is always available
 - **Logging**: All errors are logged with context for debugging
+- **Token Limit Handling**: If response hits token limit, full response is preserved (no truncation)
 
 ---
 
@@ -472,14 +494,17 @@ Write a brief, professional conclusion (approximately X words, max Y characters)
 
 ### For Administrators
 
-1. **API Key Management**: Store API keys securely in database or environment variables
-2. **Provider Selection**: Choose provider based on:
-   - **Claude**: Best quality, higher cost
-   - **OpenAI**: Balanced quality/cost
-   - **Gemini**: Fast, cost-effective
+1. **Service Account Setup**: 
+   - Ensure service account key file exists and is accessible
+   - Verify service account has `Vertex AI User` role
+   - Use same credentials as Google Cloud Storage for consistency
+2. **Model Selection**: Choose model based on needs:
+   - **gemini-2.5-flash**: Fast, cost-effective (default, recommended)
+   - **gemini-1.5-pro**: Better quality for complex requests
 3. **Length Configuration**: Set `AI_MAX_REMARK_LENGTH` based on your archival needs
-4. **Monitoring**: Monitor AI usage and costs through provider dashboards
+4. **Monitoring**: Monitor AI usage and costs through Google Cloud Console
 5. **Testing**: Test with sample requests before enabling in production
+6. **Region Selection**: Choose region closest to your deployment for lower latency
 
 ### For Users
 
@@ -499,8 +524,10 @@ Write a brief, professional conclusion (approximately X words, max Y characters)
 **Diagnosis**:
 1. Check `AI_ENABLED` config value
 2. Check `AI_REMARK_GENERATION_ENABLED` config value
-3. Verify API keys are configured
-4. Check provider initialization logs
+3. Verify service account key file exists and is accessible
+4. Check Vertex AI API is enabled in Google Cloud Console
+5. Verify service account has `Vertex AI User` role
+6. Check provider initialization logs
 
 **Solution**:
 ```bash
@@ -509,6 +536,14 @@ tail -f logs/app.log | grep "AI Service"
 
 # Verify config
 SELECT * FROM system_config WHERE config_key LIKE 'AI_%';
+
+# Verify service account key file
+ls -la credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
+
+# Check environment variables
+echo $GCP_PROJECT_ID
+echo $GCP_KEY_FILE
+echo $VERTEX_AI_MODEL
 ```
 
 ### Issue: Generated Text Too Long/Short
@@ -518,7 +553,8 @@ SELECT * FROM system_config WHERE config_key LIKE 'AI_%';
 **Solution**:
 1. Adjust `AI_MAX_REMARK_LENGTH` in admin config
 2. Check prompt target word count calculation
-3. Verify provider max_tokens setting
+3. Note: Vertex AI max output tokens is 4096 (system handles this automatically)
+4. AI is instructed to stay within character limit, but full response is preserved
 
 ### Issue: Poor Quality Conclusions
 
@@ -527,37 +563,50 @@ SELECT * FROM system_config WHERE config_key LIKE 'AI_%';
 **Solution**:
 1. Verify context data is complete (approvals, notes, documents)
 2. Check prompt includes all relevant information
-3. Try different provider (Claude generally produces better quality)
-4. Adjust temperature if needed (lower = more focused)
+3. Try different model (e.g., `gemini-1.5-pro` for better quality)
+4. Temperature is set to 0.3 for focused output (can be adjusted in code if needed)
 
 ### Issue: Slow Generation
 
 **Symptoms**: AI generation takes too long
 
 **Solution**:
-1. Check provider API status
+1. Check Vertex AI API status in Google Cloud Console
 2. Verify network connectivity
-3. Consider using faster provider (Gemini)
-4. Check for rate limiting
+3. Consider using `gemini-2.5-flash` model (fastest option)
+4. Check for rate limiting in Google Cloud Console
+5. Verify region selection (closer region = lower latency)
 
-### Issue: Provider Not Initializing
+### Issue: Vertex AI Not Initializing
 
-**Symptoms**: Provider shows as "None" in logs
+**Symptoms**: Provider shows as "None" or initialization fails in logs
 
 **Diagnosis**:
-1. Check API key is valid
-2. Verify SDK package is installed
-3. Check environment variables
+1. Check service account key file exists and is valid
+2. Verify `@google-cloud/vertexai` package is installed
+3. Check environment variables (`GCP_PROJECT_ID`, `GCP_KEY_FILE`)
+4. Verify Vertex AI API is enabled in Google Cloud Console
+5. Check service account permissions
 
 **Solution**:
 ```bash
 # Install missing SDK
-npm install @anthropic-ai/sdk  # For Claude
-npm install openai              # For OpenAI
-npm install @google/generative-ai  # For Gemini
+npm install @google-cloud/vertexai
 
-# Verify API key
-echo $CLAUDE_API_KEY  # Should show key
+# Verify service account key file
+ls -la credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
+
+# Verify environment variables
+echo $GCP_PROJECT_ID
+echo $GCP_KEY_FILE
+echo $VERTEX_AI_MODEL
+echo $VERTEX_AI_LOCATION
+
+# Check Google Cloud Console
+# 1. Go to APIs & Services > Library
+# 2. Search for "Vertex AI API"
+# 3. Ensure it's enabled
+# 4. Verify service account has "Vertex AI User" role
 ```
 
 ---
@@ -644,12 +693,13 @@ reference.
 
 ## Version History
 
-- **v1.0.0** (2025-01-15): Initial implementation
-  - Multi-provider support (Claude, OpenAI, Gemini)
-  - Automatic and manual generation
-  - TAT risk integration
-  - Key points extraction
-  - Confidence scoring
+- **v2.0.0**: Vertex AI Migration
+  - Migrated to Google Cloud Vertex AI Gemini
+  - Service account authentication (same as GCS)
+  - Removed multi-provider support
+  - Increased max output tokens to 4096
+  - Full response preservation (no truncation)
+  - HTML format support for rich text editor
 
 ---
 
@@ -659,13 +709,18 @@ For issues or questions:
 1. Check logs: `logs/app.log`
 2. Review admin configuration panel
 3. Contact development team
-4. Refer to provider documentation:
-   - [Claude API Docs](https://docs.anthropic.com)
-   - [OpenAI API Docs](https://platform.openai.com/docs)
-   - [Gemini API Docs](https://ai.google.dev/docs)
+4. Refer to Vertex AI documentation:
+   - [Vertex AI Documentation](https://cloud.google.com/vertex-ai/docs)
+   - [Gemini Models](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini)
+   - [Vertex AI Setup Guide](../VERTEX_AI_INTEGRATION.md)
 
 ---
 
-**Last Updated**: January 2025
 **Maintained By**: Royal Enfield Development Team
 
+---
+
+## Related Documentation
+
+- [Vertex AI Integration Guide](./VERTEX_AI_INTEGRATION.md) - Detailed setup and migration information
+

docs/CLAIM_FINANCIAL_SETTLEMENT_WORKFLOW.md

@@ -0,0 +1,71 @@
+# Dealer Claim Financial Settlement Workflow
+
+This document outlines the workflow for financial settlement of dealer claims within the Royal Enfield platform, following the transition from direct DMS integration to an Azure File Storage (AFS) based data exchange with SAP.
+
+## Workflow Overview
+
+The financial settlement process ensures that dealer claims are legally documented and financially settled through Royal Enfield's SAP system.
+
+### 1. Legal Compliance: PWC E-Invoicing
+Once the **Dealer Completion Documents** are submitted and approved by the **Initiator (Requestor Evaluation)**, the system triggers the legal compliance step.
+
+- **Service**: `PWCIntegrationService`
+- **Action**: Generates a signed E-Invoice via PWC API.
+- **Output**: IRN (Invoice Reference Number), Ack No, Ack Date, Signed Invoice (PDF/B64), and QR Code.
+- **Purpose**: Ensures the claim is legally recognized under GST regulations.
+
+### 2. Financial Posting: AFS/CSV Integration
+The financial settlement is handled by exchanging data files with SAP via **Azure File Storage (AFS)**.
+
+- **Action**: The system generates a **CSV file** containing the following details:
+    - Invoice Number (from PWC)
+    - Invoice Amount (with/without GST as per activity type)
+    - GL Code (Resolved based on Activity Type/IO)
+    - Internal Order (IO) Number
+    - Dealer Code
+- **Storage**: CSV is uploaded to a designated folder in AFS.
+- **SAP Role**: SAP periodically polls AFS, picks up the CSV, and posts the transaction internally.
+
+### 3. Payment Outcome: Credit Note
+The result of the financial posting in SAP is a **Credit Note**.
+
+- **Workflow**:
+    - SAP generates a Credit Note and uploads it back to AFS.
+    - RE Backend monitors the AFS folder.
+    - Once a Credit Note is detected, the system retrieves it and attaches it to the workflow request.
+    - An email notification (using `creditNoteSent.template.ts`) is sent to the dealer.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Dealer
+    participant Backend
+    participant PWC
+    participant AFS as Azure File Storage
+    participant SAP
+
+    Dealer->>Backend: Submit Completion Docs (Actuals)
+    Backend->>Backend: Initiator Approval
+    Backend->>PWC: Generate Signed E-Invoice
+    PWC-->>Backend: Return IRN & QR Code
+    Backend->>Backend: Generate Settlement CSV
+    Backend->>AFS: Upload CSV
+    SAP->>AFS: Pick up CSV
+    SAP->>SAP: Post Financials
+    SAP->>AFS: Upload Credit Note
+    Backend->>AFS: Poll/Retrieve Credit Note
+    Backend->>Dealer: Send Credit Note Notification
+```
+
+## GL Code Resolution
+The GL Code is solved dynamically based on:
+1.  **Activity Type**: Each activity (e.g., Marketing Event, Demo) has a primary GL mapping.
+2.  **Internal Order (IO)**: If specific IO logic is required, the GL can be overridden.
+
+## Summary of Integration Points
+| Component | Integration Type | Responsibility |
+| :--- | :--- | :--- |
+| **PWC** | REST API | Legal E-Invoice |
+| **AFS (Azure)** | File Storage SDK | CSV Exchange |
+| **SAP** | Batch Processing | Financial Posting & Credit Note |

docs/CLAIM_MANAGEMENT_APPROVER_MAPPING.md

@@ -0,0 +1,134 @@
+# Claim Management - Approver Mapping Documentation
+
+## Overview
+
+The Claim Management workflow has **8 fixed steps** with specific approvers and action types. This document explains how approvers are mapped when a claim request is created.
+
+## 8-Step Workflow Structure
+
+### Step 1: Dealer Proposal Submission
+- **Approver Type**: Dealer (External)
+- **Action Type**: **SUBMIT** (Dealer submits proposal documents)
+- **TAT**: 72 hours
+- **Mapping**: Uses `dealerEmail` from claim data
+- **Status**: PENDING (waiting for dealer to submit)
+
+### Step 2: Requestor Evaluation
+- **Approver Type**: Initiator (Internal RE Employee)
+- **Action Type**: **APPROVE/REJECT** (Requestor reviews dealer proposal)
+- **TAT**: 48 hours
+- **Mapping**: Uses `initiatorId` (the person who created the request)
+- **Status**: PENDING (waiting for requestor to evaluate)
+
+### Step 3: Department Lead Approval
+- **Approver Type**: Department Lead (Internal RE Employee)
+- **Action Type**: **APPROVE/REJECT** (Department lead approves and blocks IO budget)
+- **TAT**: 72 hours
+- **Mapping**: 
+  - Option 1: Find user with role `MANAGEMENT` in same department as initiator
+  - Option 2: Use initiator's `manager` field from User model
+  - Option 3: Find user with designation containing "Lead" or "Head" in same department
+- **Status**: PENDING (waiting for department lead approval)
+
+### Step 4: Activity Creation
+- **Approver Type**: System (Auto-processed)
+- **Action Type**: **AUTO** (System automatically creates activity)
+- **TAT**: 1 hour
+- **Mapping**: System user (`system@{{APP_DOMAIN}}`)
+- **Status**: Auto-approved when triggered
+
+### Step 5: Dealer Completion Documents
+- **Approver Type**: Dealer (External)
+- **Action Type**: **SUBMIT** (Dealer submits completion documents)
+- **TAT**: 120 hours
+- **Mapping**: Uses `dealerEmail` from claim data
+- **Status**: PENDING (waiting for dealer to submit)
+
+### Step 6: Requestor Claim Approval
+- **Approver Type**: Initiator (Internal RE Employee)
+- **Action Type**: **APPROVE/REJECT** (Requestor approves completion)
+- **TAT**: 48 hours
+- **Mapping**: Uses `initiatorId`
+- **Status**: PENDING (waiting for requestor approval)
+
+### Step 7: E-Invoice Generation
+- **Approver Type**: System (Auto-processed via DMS)
+- **Action Type**: **AUTO** (System generates e-invoice via DMS integration)
+- **TAT**: 1 hour
+- **Mapping**: System user (`system@{{APP_DOMAIN}}`)
+- **Status**: Auto-approved when triggered
+
+### Step 8: Credit Note Confirmation
+- **Approver Type**: Finance Team (Internal RE Employee)
+- **Action Type**: **APPROVE/REJECT** (Finance confirms credit note)
+- **TAT**: 48 hours
+- **Mapping**: 
+  - Option 1: Find user with role `MANAGEMENT` and department contains "Finance"
+  - Option 2: Find user with designation containing "Finance" or "Accountant"
+  - Option 3: Use configured finance team email from admin settings
+- **Status**: PENDING (waiting for finance confirmation)
+- **Is Final Approver**: Yes (final step)
+
+## Current Implementation Issues
+
+### Problems:
+1. **Step 1 & 5**: Dealer email not being used - using placeholder UUID
+2. **Step 3**: Department Lead not resolved - using placeholder UUID
+3. **Step 8**: Finance team not resolved - using placeholder UUID
+4. **All steps**: Using initiator email for non-initiator steps
+
+### Impact:
+- Steps 1, 3, 5, 8 won't have correct approvers assigned
+- Notifications won't be sent to correct users
+- Workflow will be stuck waiting for non-existent approvers
+
+## Action Types Summary
+
+| Step | Action Type | Description |
+|------|-------------|-------------|
+| 1 | SUBMIT | Dealer submits proposal (not approve/reject) |
+| 2 | APPROVE/REJECT | Requestor evaluates proposal |
+| 3 | APPROVE/REJECT | Department Lead approves and blocks budget |
+| 4 | AUTO | System creates activity automatically |
+| 5 | SUBMIT | Dealer submits completion documents |
+| 6 | APPROVE/REJECT | Requestor approves completion |
+| 7 | AUTO | System generates e-invoice via DMS |
+| 8 | APPROVE/REJECT | Finance confirms credit note (FINAL) |
+
+## Approver Resolution Logic
+
+### For Dealer Steps (1, 5):
+```typescript
+// Use dealer email from claim data
+const dealerEmail = claimData.dealerEmail;
+// Find or create dealer user (if dealer is external, may need special handling)
+const dealerUser = await User.findOne({ where: { email: dealerEmail } });
+// If dealer doesn't exist in system, create participant entry
+```
+
+### For Department Lead (Step 3):
+```typescript
+// Priority order:
+1. Find user with same department and role = 'MANAGEMENT'
+2. Use initiator.manager field to find manager
+3. Find user with designation containing "Lead" or "Head" in same department
+4. Fallback: Use initiator's manager email from User model
+```
+
+### For Finance Team (Step 8):
+```typescript
+// Priority order:
+1. Find user with department containing "Finance" and role = 'MANAGEMENT'
+2. Find user with designation containing "Finance" or "Accountant"
+3. Use configured finance team email from admin_configurations table
+4. Fallback: Use default finance email (e.g., finance@{{APP_DOMAIN}})
+```
+
+## Next Steps
+
+The `createClaimApprovalLevels()` method needs to be updated to:
+1. Accept `dealerEmail` parameter
+2. Resolve Department Lead dynamically
+3. Resolve Finance team member dynamically
+4. Handle cases where approvers don't exist in the system
+

docs/COST_BREAKUP_TABLE_ARCHITECTURE.md

@@ -0,0 +1,149 @@
+# Cost Breakup Table Architecture
+
+## Overview
+
+This document describes the enhanced architecture for storing cost breakups in the Dealer Claim Management system. Instead of storing cost breakups as JSONB arrays, we now use a dedicated relational table for better querying, reporting, and data integrity.
+
+## Architecture Decision
+
+### Previous Approach (JSONB)
+- **Storage**: Cost breakups stored as JSONB array in `dealer_proposal_details.cost_breakup`
+- **Limitations**:
+  - Difficult to query individual cost items
+  - Hard to update specific items
+  - Not ideal for reporting and analytics
+  - No referential integrity
+
+### New Approach (Separate Table)
+- **Storage**: Dedicated `dealer_proposal_cost_items` table
+- **Benefits**:
+  - Better querying and filtering capabilities
+  - Easier to update individual cost items
+  - Better for analytics and reporting
+  - Maintains referential integrity
+  - Supports proper ordering of items
+
+## Database Schema
+
+### Table: `dealer_proposal_cost_items`
+
+```sql
+CREATE TABLE dealer_proposal_cost_items (
+  cost_item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  proposal_id UUID NOT NULL REFERENCES dealer_proposal_details(proposal_id) ON DELETE CASCADE,
+  request_id UUID NOT NULL REFERENCES workflow_requests(request_id) ON DELETE CASCADE,
+  item_description VARCHAR(500) NOT NULL,
+  amount DECIMAL(15, 2) NOT NULL,
+  item_order INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+```
+
+**Indexes**:
+- `idx_proposal_cost_items_proposal_id` on `proposal_id`
+- `idx_proposal_cost_items_request_id` on `request_id`
+- `idx_proposal_cost_items_proposal_order` on `(proposal_id, item_order)`
+
+## Backward Compatibility
+
+The system maintains backward compatibility by:
+1. **Dual Storage**: Still saves cost breakups to JSONB field for backward compatibility
+2. **Smart Retrieval**: When fetching proposal details:
+   - First tries to get cost items from the new table
+   - Falls back to JSONB field if table is empty
+3. **Migration**: Automatically migrates existing JSONB data to the new table during migration
+
+## API Response Format
+
+The API always returns cost breakups as an array, regardless of storage method:
+
+```json
+{
+  "proposalDetails": {
+    "proposalId": "uuid",
+    "costBreakup": [
+      {
+        "description": "Item 1",
+        "amount": 10000
+      },
+      {
+        "description": "Item 2",
+        "amount": 20000
+      }
+    ],
+    "costItems": [
+      {
+        "costItemId": "uuid",
+        "itemDescription": "Item 1",
+        "amount": 10000,
+        "itemOrder": 0
+      }
+    ]
+  }
+}
+```
+
+## Implementation Details
+
+### Saving Cost Items
+
+When a proposal is submitted:
+
+1. Save proposal details to `dealer_proposal_details` (with JSONB for backward compatibility)
+2. Delete existing cost items for the proposal (if updating)
+3. Insert new cost items into `dealer_proposal_cost_items` table
+4. Items are ordered by `itemOrder` field
+
+### Retrieving Cost Items
+
+When fetching proposal details:
+
+1. Query `dealer_proposal_details` with `include` for `costItems`
+2. If cost items exist in the table, use them
+3. If not, fall back to parsing JSONB `costBreakup` field
+4. Always return as a normalized array format
+
+## Migration
+
+The migration (`20251210-create-proposal-cost-items-table.ts`):
+1. Creates the new table
+2. Creates indexes for performance
+3. Migrates existing JSONB data to the new table automatically
+4. Handles errors gracefully (doesn't fail if migration of existing data fails)
+
+## Model Associations
+
+```typescript
+DealerProposalDetails.hasMany(DealerProposalCostItem, {
+  as: 'costItems',
+  foreignKey: 'proposalId',
+  sourceKey: 'proposalId'
+});
+
+DealerProposalCostItem.belongsTo(DealerProposalDetails, {
+  as: 'proposal',
+  foreignKey: 'proposalId',
+  targetKey: 'proposalId'
+});
+```
+
+## Benefits for Frontend
+
+1. **Consistent Format**: Always receives cost breakups as an array
+2. **No Changes Required**: Frontend code doesn't need to change
+3. **Better Performance**: Can query specific cost items if needed
+4. **Future Extensibility**: Easy to add features like:
+   - Cost item categories
+   - Approval status per item
+   - Historical tracking of cost changes
+
+## Future Enhancements
+
+Potential future improvements:
+- Add `category` field to cost items
+- Add `approved_amount` vs `requested_amount` for budget approval workflows
+- Add `notes` field for item-level comments
+- Add audit trail for cost item changes
+- Add `is_approved` flag for individual item approval
+

docs/DEALERS_CSV_IMPORT_FIX.sql

@@ -0,0 +1,224 @@
+-- ============================================================
+-- DEALERS CSV IMPORT - WORKING SOLUTION
+-- ============================================================
+-- This script provides a working solution for importing dealers
+-- from CSV with auto-generated columns (dealer_id, created_at, updated_at, is_active)
+-- ============================================================
+
+-- METHOD 1: If your CSV does NOT have dealer_id, created_at, updated_at, is_active
+-- ============================================================
+-- Use this COPY command if your CSV has exactly 44 columns (without the auto-generated ones)
+
+\copy public.dealers (sales_code,service_code,gear_code,gma_code,region,dealership,state,district,city,location,city_category_pst,layout_format,tier_city_category,on_boarding_charges,"date",single_format_month_year,domain_id,replacement,termination_resignation_status,date_of_termination_resignation,last_date_of_operations,old_codes,branch_details,dealer_principal_name,dealer_principal_email_id,dp_contact_number,dp_contacts,showroom_address,showroom_pincode,workshop_address,workshop_pincode,location_district,state_workshop,no_of_studios,website_update,gst,pan,firm_type,prop_managing_partners_directors,total_prop_partners_directors,docs_folder_link,workshop_gma_codes,existing_new,dlrcode) FROM 'C:/Users/BACKPACKERS/Downloads/Dealer_Master.csv' CSV HEADER ENCODING 'WIN1252';
+
+
+-- ============================================================
+-- METHOD 2: If your CSV HAS dealer_id, created_at, updated_at, is_active columns
+-- ============================================================
+-- Use this approach if your CSV has 48 columns (including the auto-generated ones)
+-- This creates a temporary table, imports, then inserts with defaults
+
+-- Step 1: Create temporary table matching your CSV structure
+-- This accepts ALL columns from CSV (whether 44 or 48 columns)
+CREATE TEMP TABLE dealers_temp (
+ dealer_id TEXT,
+ sales_code TEXT,
+ service_code TEXT,
+ gear_code TEXT,
+ gma_code TEXT,
+ region TEXT,
+ dealership TEXT,
+ state TEXT,
+ district TEXT,
+ city TEXT,
+ location TEXT,
+ city_category_pst TEXT,
+ layout_format TEXT,
+ tier_city_category TEXT,
+ on_boarding_charges TEXT,
+ date TEXT,
+ single_format_month_year TEXT,
+ domain_id TEXT,
+ replacement TEXT,
+ termination_resignation_status TEXT,
+ date_of_termination_resignation TEXT,
+ last_date_of_operations TEXT,
+ old_codes TEXT,
+ branch_details TEXT,
+ dealer_principal_name TEXT,
+ dealer_principal_email_id TEXT,
+ dp_contact_number TEXT,
+ dp_contacts TEXT,
+ showroom_address TEXT,
+ showroom_pincode TEXT,
+ workshop_address TEXT,
+ workshop_pincode TEXT,
+ location_district TEXT,
+ state_workshop TEXT,
+ no_of_studios TEXT,
+ website_update TEXT,
+ gst TEXT,
+ pan TEXT,
+ firm_type TEXT,
+ prop_managing_partners_directors TEXT,
+ total_prop_partners_directors TEXT,
+ docs_folder_link TEXT,
+ workshop_gma_codes TEXT,
+ existing_new TEXT,
+ dlrcode TEXT,
+ created_at TEXT,
+ updated_at TEXT,
+ is_active TEXT
+);
+
+-- Step 2: Import CSV into temporary table
+-- This will work whether your CSV has 44 or 48 columns
+\copy dealers_temp FROM 'C:/Users/COMP/Downloads/DEALERS_CLEAN.csv' WITH (FORMAT csv, HEADER true, ENCODING 'UTF8');
+
+-- Optional: Check what was imported
+-- SELECT COUNT(*) FROM dealers_temp;
+
+-- Step 3: Insert into actual dealers table
+-- IMPORTANT: We IGNORE dealer_id, created_at, updated_at, is_active from CSV
+-- These will use database DEFAULT values (auto-generated UUID, current timestamp, true)
+INSERT INTO public.dealers (
+ sales_code,
+ service_code,
+ gear_code,
+ gma_code,
+ region,
+ dealership,
+ state,
+ district,
+ city,
+ location,
+ city_category_pst,
+ layout_format,
+ tier_city_category,
+ on_boarding_charges,
+ date,
+ single_format_month_year,
+ domain_id,
+ replacement,
+ termination_resignation_status,
+ date_of_termination_resignation,
+ last_date_of_operations,
+ old_codes,
+ branch_details,
+ dealer_principal_name,
+ dealer_principal_email_id,
+ dp_contact_number,
+ dp_contacts,
+ showroom_address,
+ showroom_pincode,
+ workshop_address,
+ workshop_pincode,
+ location_district,
+ state_workshop,
+ no_of_studios,
+ website_update,
+ gst,
+ pan,
+ firm_type,
+ prop_managing_partners_directors,
+ total_prop_partners_directors,
+ docs_folder_link,
+ workshop_gma_codes,
+ existing_new,
+ dlrcode
+)
+SELECT 
+ NULLIF(sales_code, ''),
+ NULLIF(service_code, ''),
+ NULLIF(gear_code, ''),
+ NULLIF(gma_code, ''),
+ NULLIF(region, ''),
+ NULLIF(dealership, ''),
+ NULLIF(state, ''),
+ NULLIF(district, ''),
+ NULLIF(city, ''),
+ NULLIF(location, ''),
+ NULLIF(city_category_pst, ''),
+ NULLIF(layout_format, ''),
+ NULLIF(tier_city_category, ''),
+ NULLIF(on_boarding_charges, ''),
+ NULLIF(date, ''),
+ NULLIF(single_format_month_year, ''),
+ NULLIF(domain_id, ''),
+ NULLIF(replacement, ''),
+ NULLIF(termination_resignation_status, ''),
+ NULLIF(date_of_termination_resignation, ''),
+ NULLIF(last_date_of_operations, ''),
+ NULLIF(old_codes, ''),
+ NULLIF(branch_details, ''),
+ NULLIF(dealer_principal_name, ''),
+ NULLIF(dealer_principal_email_id, ''),
+ NULLIF(dp_contact_number, ''),
+ NULLIF(dp_contacts, ''),
+ NULLIF(showroom_address, ''),
+ NULLIF(showroom_pincode, ''),
+ NULLIF(workshop_address, ''),
+ NULLIF(workshop_pincode, ''),
+ NULLIF(location_district, ''),
+ NULLIF(state_workshop, ''),
+ CASE WHEN no_of_studios = '' THEN 0 ELSE no_of_studios::INTEGER END,
+ NULLIF(website_update, ''),
+ NULLIF(gst, ''),
+ NULLIF(pan, ''),
+ NULLIF(firm_type, ''),
+ NULLIF(prop_managing_partners_directors, ''),
+ NULLIF(total_prop_partners_directors, ''),
+ NULLIF(docs_folder_link, ''),
+ NULLIF(workshop_gma_codes, ''),
+ NULLIF(existing_new, ''),
+ NULLIF(dlrcode, '')
+FROM dealers_temp;
+
+-- Step 4: Clean up temporary table
+DROP TABLE dealers_temp;
+
+-- ============================================================
+-- METHOD 3: Using COPY with DEFAULT (PostgreSQL 12+)
+-- ============================================================
+-- Alternative approach using a function to set defaults
+
+-- Create a function to handle the import with defaults
+CREATE OR REPLACE FUNCTION import_dealers_from_csv()
+RETURNS void AS $$
+BEGIN
+  -- This will be called from a COPY command that uses a function
+  -- See METHOD 1 for the actual COPY command
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================
+-- VERIFICATION QUERIES
+-- ============================================================
+
+-- Check import results
+SELECT 
+  COUNT(*) as total_dealers,
+  COUNT(dealer_id) as has_dealer_id,
+  COUNT(created_at) as has_created_at,
+  COUNT(updated_at) as has_updated_at,
+  COUNT(*) FILTER (WHERE is_active = true) as active_count
+FROM dealers;
+
+-- View sample records with auto-generated values
+SELECT 
+  dealer_id,
+  dlrcode,
+  dealership,
+  created_at,
+  updated_at,
+  is_active
+FROM dealers
+LIMIT 5;
+
+-- Check for any issues
+SELECT 
+  COUNT(*) FILTER (WHERE dealer_id IS NULL) as missing_dealer_id,
+  COUNT(*) FILTER (WHERE created_at IS NULL) as missing_created_at,
+  COUNT(*) FILTER (WHERE updated_at IS NULL) as missing_updated_at
+FROM dealers;
+

docs/DEALERS_CSV_IMPORT_GUIDE.md

@@ -0,0 +1,515 @@
+# Dealers CSV Import Guide
+
+This guide explains how to format and import dealer data from a CSV file into the PostgreSQL `dealers` table.
+
+## ⚠️ Important: Auto-Generated Columns
+
+**DO NOT include these columns in your CSV file** - they are automatically generated by the database:
+
+- ❌ `dealer_id` - Auto-generated UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`)
+- ❌ `created_at` - Auto-generated timestamp (current time on import)
+- ❌ `updated_at` - Auto-generated timestamp (current time on import)
+- ❌ `is_active` - Defaults to `true`
+
+Your CSV should have **exactly 44 columns** (the data columns listed below).
+
+## Table of Contents
+- [CSV File Format Requirements](#csv-file-format-requirements)
+- [Column Mapping](#column-mapping)
+- [Preparing Your CSV File](#preparing-your-csv-file)
+- [Import Methods](#import-methods)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## CSV File Format Requirements
+
+### File Requirements
+- **Format**: CSV (Comma-Separated Values)
+- **Encoding**: UTF-8
+- **Header Row**: Required (first row must contain column names)
+- **Delimiter**: Comma (`,`)
+- **Text Qualifier**: Double quotes (`"`) for fields containing commas or special characters
+
+### Required Columns (in exact order)
+
+**Important Notes:**
+- **DO NOT include** `dealer_id`, `created_at`, `updated_at`, or `is_active` in your CSV file
+- These columns will be automatically generated by the database:
+  - `dealer_id`: Auto-generated UUID
+  - `created_at`: Auto-generated timestamp (current time)
+  - `updated_at`: Auto-generated timestamp (current time)
+  - `is_active`: Defaults to `true`
+
+Your CSV file must have these **44 columns** in the following order:
+
+1. `sales_code`
+2. `service_code`
+3. `gear_code`
+4. `gma_code`
+5. `region`
+6. `dealership`
+7. `state`
+8. `district`
+9. `city`
+10. `location`
+11. `city_category_pst`
+12. `layout_format`
+13. `tier_city_category`
+14. `on_boarding_charges`
+15. `date`
+16. `single_format_month_year`
+17. `domain_id`
+18. `replacement`
+19. `termination_resignation_status`
+20. `date_of_termination_resignation`
+21. `last_date_of_operations`
+22. `old_codes`
+23. `branch_details`
+24. `dealer_principal_name`
+25. `dealer_principal_email_id`
+26. `dp_contact_number`
+27. `dp_contacts`
+28. `showroom_address`
+29. `showroom_pincode`
+30. `workshop_address`
+31. `workshop_pincode`
+32. `location_district`
+33. `state_workshop`
+34. `no_of_studios`
+35. `website_update`
+36. `gst`
+37. `pan`
+38. `firm_type`
+39. `prop_managing_partners_directors`
+40. `total_prop_partners_directors`
+41. `docs_folder_link`
+42. `workshop_gma_codes`
+43. `existing_new`
+44. `dlrcode`
+
+---
+
+## Column Mapping
+
+### Column Details
+
+| Column Name | Type | Required | Notes |
+|------------|------|----------|-------|
+| `sales_code` | String(50) | No | Sales code identifier |
+| `service_code` | String(50) | No | Service code identifier |
+| `gear_code` | String(50) | No | Gear code identifier |
+| `gma_code` | String(50) | No | GMA code identifier |
+| `region` | String(50) | No | Geographic region |
+| `dealership` | String(255) | No | Dealership business name |
+| `state` | String(100) | No | State name |
+| `district` | String(100) | No | District name |
+| `city` | String(100) | No | City name |
+| `location` | String(255) | No | Location details |
+| `city_category_pst` | String(50) | No | City category (PST) |
+| `layout_format` | String(50) | No | Layout format |
+| `tier_city_category` | String(100) | No | TIER City Category |
+| `on_boarding_charges` | Decimal | No | Numeric value (e.g., 1000.50) |
+| `date` | Date | No | Format: YYYY-MM-DD (e.g., 2014-09-30) |
+| `single_format_month_year` | String(50) | No | Format: Sep-2014 |
+| `domain_id` | String(255) | No | Email domain (e.g., dealer@{{APP_DOMAIN}}) |
+| `replacement` | String(50) | No | Replacement status |
+| `termination_resignation_status` | String(255) | No | Termination/Resignation status |
+| `date_of_termination_resignation` | Date | No | Format: YYYY-MM-DD |
+| `last_date_of_operations` | Date | No | Format: YYYY-MM-DD |
+| `old_codes` | String(255) | No | Old code references |
+| `branch_details` | Text | No | Branch information |
+| `dealer_principal_name` | String(255) | No | Principal's full name |
+| `dealer_principal_email_id` | String(255) | No | Principal's email |
+| `dp_contact_number` | String(20) | No | Contact phone number |
+| `dp_contacts` | String(20) | No | Additional contacts |
+| `showroom_address` | Text | No | Full showroom address |
+| `showroom_pincode` | String(10) | No | Showroom postal code |
+| `workshop_address` | Text | No | Full workshop address |
+| `workshop_pincode` | String(10) | No | Workshop postal code |
+| `location_district` | String(100) | No | Location/District |
+| `state_workshop` | String(100) | No | State for workshop |
+| `no_of_studios` | Integer | No | Number of studios (default: 0) |
+| `website_update` | String(10) | No | Yes/No value |
+| `gst` | String(50) | No | GST number |
+| `pan` | String(50) | No | PAN number |
+| `firm_type` | String(100) | No | Type of firm (e.g., Proprietorship) |
+| `prop_managing_partners_directors` | String(255) | No | Proprietor/Partners/Directors names |
+| `total_prop_partners_directors` | String(255) | No | Total count or names |
+| `docs_folder_link` | Text | No | Google Drive or document folder URL |
+| `workshop_gma_codes` | String(255) | No | Workshop GMA codes |
+| `existing_new` | String(50) | No | Existing/New status |
+| `dlrcode` | String(50) | No | Dealer code |
+
+---
+
+## Preparing Your CSV File
+
+### Step 1: Create/Edit Your CSV File
+
+1. **Open your CSV file** in Excel, Google Sheets, or a text editor
+2. **Remove auto-generated columns** (if present):
+   - ❌ **DO NOT include**: `dealer_id`, `created_at`, `updated_at`, `is_active`
+   - ✅ These will be automatically generated by the database
+3. **Ensure the header row** matches the column names exactly (see [Column Mapping](#column-mapping))
+4. **Verify column order** - columns must be in the exact order listed above (44 columns total)
+5. **Check data formats**:
+   - Dates: Use `YYYY-MM-DD` format (e.g., `2014-09-30`)
+   - Numbers: Use decimal format for `on_boarding_charges` (e.g., `1000.50`)
+   - Empty values: Leave cells empty (don't use "NULL" or "N/A" as text)
+
+### Step 2: Handle Special Characters
+
+- **Commas in text**: Wrap the entire field in double quotes
+  - Example: `"No.335, HVP RR Nagar Sector B"`
+- **Quotes in text**: Use double quotes to escape: `""quoted text""`
+- **Newlines in text**: Wrap field in double quotes
+
+### Step 3: Date Formatting
+
+Ensure dates are in `YYYY-MM-DD` format:
+- ✅ Correct: `2014-09-30`
+- ❌ Wrong: `30-Sep-14`, `09/30/2014`, `30-09-2014`
+
+### Step 4: Save the File
+
+1. **Save as CSV** (UTF-8 encoding)
+2. **File location**: Save to an accessible path (e.g., `C:/Users/COMP/Downloads/DEALERS_CLEAN.csv`)
+3. **File name**: Use a descriptive name (e.g., `DEALERS_CLEAN.csv`)
+
+### Sample CSV Format
+
+**Important:** Your CSV should **NOT** include `dealer_id`, `created_at`, `updated_at`, or `is_active` columns. These are auto-generated.
+
+```csv
+sales_code,service_code,gear_code,gma_code,region,dealership,state,district,city,location,city_category_pst,layout_format,tier_city_category,on_boarding_charges,date,single_format_month_year,domain_id,replacement,termination_resignation_status,date_of_termination_resignation,last_date_of_operations,old_codes,branch_details,dealer_principal_name,dealer_principal_email_id,dp_contact_number,dp_contacts,showroom_address,showroom_pincode,workshop_address,workshop_pincode,location_district,state_workshop,no_of_studios,website_update,gst,pan,firm_type,prop_managing_partners_directors,total_prop_partners_directors,docs_folder_link,workshop_gma_codes,existing_new,dlrcode
+5124,5125,5573,9430,S3,Accelerate Motors,Karnataka,Bengaluru,Bengaluru,RAJA RAJESHWARI NAGAR,A+,A+,Tier 1 City,,2014-09-30,Sep-2014,acceleratemotors.rrnagar@dealer.{{APP_DOMAIN}},,,,,,,N. Shyam Charmanna,shyamcharmanna@yahoo.co.in,7022049621,7022049621,"No.335, HVP RR Nagar Sector B, Ideal Homes Town Ship, Bangalore - 560098, Dist – Bangalore, Karnataka",560098,"Works Shop No.460, 80ft Road, 2nd Phase R R Nagar, Bangalore - 560098, Dist – Bangalore, Karnataka",560098,Bangalore,Karnataka,0,Yes,29ARCPS1311D1Z6,ARCPS1311D,Proprietorship,CHARMANNA SHYAM NELLAMAKADA,CHARMANNA SHYAM NELLAMAKADA,https://drive.google.com/drive/folders/1sGtg3s1h9aBXX9fhxJufYuBWar8gVvnb,,,3386
+```
+
+**What gets auto-generated:**
+- `dealer_id`: `550e8400-e29b-41d4-a716-446655440000` (example UUID)
+- `created_at`: `2025-01-20 10:30:45.123` (current timestamp)
+- `updated_at`: `2025-01-20 10:30:45.123` (current timestamp)
+- `is_active`: `true`
+
+---
+
+## Import Methods
+
+### Method 1: PostgreSQL COPY Command (Recommended - If CSV has 44 columns)
+
+**Use this if your CSV does NOT include `dealer_id`, `created_at`, `updated_at`, `is_active` columns.**
+
+**Prerequisites:**
+- PostgreSQL client (psql) installed
+- Access to PostgreSQL server
+- CSV file path accessible from PostgreSQL server
+
+**Steps:**
+
+1. **Connect to PostgreSQL:**
+   ```bash
+   psql -U your_username -d royal_enfield_workflow -h localhost
+   ```
+
+2. **Run the COPY command:**
+   
+   **Note:** The COPY command explicitly lists only the columns from your CSV. The following columns are **automatically handled by the database** and should **NOT** be in your CSV:
+   - `dealer_id` - Auto-generated UUID
+   - `created_at` - Auto-generated timestamp
+   - `updated_at` - Auto-generated timestamp  
+   - `is_active` - Defaults to `true`
+   
+   ```sql
+   \copy public.dealers(
+    sales_code,
+    service_code,
+    gear_code,
+    gma_code,
+    region,
+    dealership,
+    state,
+    district,
+    city,
+    location,
+    city_category_pst,
+    layout_format,
+    tier_city_category,
+    on_boarding_charges,
+    date,
+    single_format_month_year,
+    domain_id,
+    replacement,
+    termination_resignation_status,
+    date_of_termination_resignation,
+    last_date_of_operations,
+    old_codes,
+    branch_details,
+    dealer_principal_name,
+    dealer_principal_email_id,
+    dp_contact_number,
+    dp_contacts,
+    showroom_address,
+    showroom_pincode,
+    workshop_address,
+    workshop_pincode,
+    location_district,
+    state_workshop,
+    no_of_studios,
+    website_update,
+    gst,
+    pan,
+    firm_type,
+    prop_managing_partners_directors,
+    total_prop_partners_directors,
+    docs_folder_link,
+    workshop_gma_codes,
+    existing_new,
+    dlrcode
+   )
+   FROM 'C:/Users/COMP/Downloads/DEALERS_CLEAN.csv'
+   WITH (
+    FORMAT csv,
+    HEADER true,
+    ENCODING 'UTF8'
+   );
+   ```
+   
+   **What happens:**
+   - `dealer_id` will be automatically generated as a UUID for each row
+   - `created_at` will be set to the current timestamp
+   - `updated_at` will be set to the current timestamp
+   - `is_active` will default to `true`
+
+3. **Verify import:**
+   ```sql
+   SELECT COUNT(*) FROM dealers;
+   SELECT * FROM dealers LIMIT 5;
+   ```
+
+### Method 2: Using Temporary Table (If CSV has 48 columns including auto-generated ones)
+
+**Use this if your CSV includes `dealer_id`, `created_at`, `updated_at`, `is_active` columns and you're getting errors.**
+
+This method uses a temporary table to import the CSV, then inserts into the actual table while ignoring the auto-generated columns:
+
+```sql
+-- Step 1: Create temporary table
+CREATE TEMP TABLE dealers_temp (
+ dealer_id TEXT,
+ sales_code TEXT,
+ service_code TEXT,
+ -- ... (all 48 columns as TEXT)
+);
+
+-- Step 2: Import CSV into temp table
+\copy dealers_temp FROM 'C:/Users/COMP/Downloads/DEALERS_CLEAN.csv' WITH (FORMAT csv, HEADER true, ENCODING 'UTF8');
+
+-- Step 3: Insert into actual table (ignoring dealer_id, created_at, updated_at, is_active)
+INSERT INTO public.dealers (
+ sales_code,
+ service_code,
+ -- ... (only the 44 data columns)
+)
+SELECT 
+ NULLIF(sales_code, ''),
+ NULLIF(service_code, ''),
+ -- ... (convert and handle empty strings)
+FROM dealers_temp
+WHERE sales_code IS NOT NULL OR dealership IS NOT NULL; -- Skip completely empty rows
+
+-- Step 4: Clean up
+DROP TABLE dealers_temp;
+```
+
+**See `DEALERS_CSV_IMPORT_FIX.sql` for the complete working script.**
+
+### Method 3: Using pgAdmin
+
+1. Open pgAdmin and connect to your database
+2. Right-click on `dealers` table → **Import/Export Data**
+3. Select **Import**
+4. Configure:
+   - **Filename**: Browse to your CSV file
+   - **Format**: CSV
+   - **Header**: Yes
+   - **Encoding**: UTF8
+   - **Delimiter**: Comma
+5. Click **OK** to import
+
+### Method 4: Using Node.js Script
+
+Create a script to import CSV programmatically (useful for automation):
+
+```typescript
+import { sequelize } from '../config/database';
+import { QueryTypes } from 'sequelize';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as csv from 'csv-parser';
+
+async function importDealersFromCSV(csvFilePath: string) {
+  const dealers: any[] = [];
+  
+  return new Promise((resolve, reject) => {
+    fs.createReadStream(csvFilePath)
+      .pipe(csv())
+      .on('data', (row) => {
+        dealers.push(row);
+      })
+      .on('end', async () => {
+        try {
+          // Bulk insert dealers
+          // Implementation depends on your needs
+          console.log(`Imported ${dealers.length} dealers`);
+          resolve(dealers);
+        } catch (error) {
+          reject(error);
+        }
+      });
+  });
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### 1. **"Column count mismatch" Error**
+- **Problem**: CSV has different number of columns than expected
+- **Solution**: 
+  - Verify your CSV has exactly **44 columns** (excluding header)
+  - **Remove** `dealer_id`, `created_at`, `updated_at`, and `is_active` if they exist in your CSV
+  - These columns are auto-generated and should NOT be in the CSV file
+
+#### 2. **"Invalid date format" Error**
+- **Problem**: Dates not in `YYYY-MM-DD` format
+- **Solution**: Convert dates to `YYYY-MM-DD` format (e.g., `2014-09-30`)
+
+#### 3. **"Encoding error" or "Special characters not displaying correctly**
+- **Problem**: CSV file not saved in UTF-8 encoding
+- **Solution**: 
+  - In Excel: Save As → CSV UTF-8 (Comma delimited) (*.csv)
+  - In Notepad++: Encoding → Convert to UTF-8 → Save
+
+#### 4. **"Permission denied" Error (COPY command)**
+- **Problem**: PostgreSQL server cannot access the file path
+- **Solution**: 
+  - Use absolute path with forward slashes: `C:/Users/COMP/Downloads/DEALERS_CLEAN.csv`
+  - Ensure file permissions allow read access
+  - For remote servers, upload file to server first
+
+#### 5. **"Duplicate key" Error**
+- **Problem**: Trying to import duplicate records
+- **Solution**: 
+  - Use `ON CONFLICT` handling in your import
+  - Or clean CSV to remove duplicates before import
+
+#### 6. **Empty values showing as "NULL" text**
+- **Problem**: CSV contains literal "NULL" or "N/A" strings
+- **Solution**: Replace with empty cells in CSV
+
+#### 7. **Commas in address fields breaking import**
+- **Problem**: Address fields contain commas not properly quoted
+- **Solution**: Wrap fields containing commas in double quotes:
+  ```csv
+  "No.335, HVP RR Nagar Sector B, Ideal Homes Town Ship"
+  ```
+
+### Pre-Import Checklist
+
+- [ ] CSV file saved in UTF-8 encoding
+- [ ] **Removed** `dealer_id`, `created_at`, `updated_at`, and `is_active` columns (if present)
+- [ ] Header row matches column names exactly
+- [ ] All 44 columns present in correct order
+- [ ] Dates formatted as `YYYY-MM-DD`
+- [ ] Numeric fields contain valid numbers (or are empty)
+- [ ] Text fields with commas are wrapped in quotes
+- [ ] File path is accessible from PostgreSQL server
+- [ ] Database connection credentials are correct
+
+### Verification Queries
+
+After import, run these queries to verify:
+
+```sql
+-- Count total dealers
+SELECT COUNT(*) as total_dealers FROM dealers;
+
+-- Verify auto-generated columns
+SELECT 
+  dealer_id,
+  created_at,
+  updated_at,
+  is_active,
+  dlrcode,
+  dealership
+FROM dealers
+LIMIT 5;
+
+-- Check for null values in key fields
+SELECT 
+  COUNT(*) FILTER (WHERE dlrcode IS NULL) as null_dlrcode,
+  COUNT(*) FILTER (WHERE domain_id IS NULL) as null_domain_id,
+  COUNT(*) FILTER (WHERE dealership IS NULL) as null_dealership
+FROM dealers;
+
+-- View sample records
+SELECT 
+  dealer_id,
+  dlrcode,
+  dealership,
+  city,
+  state,
+  domain_id,
+  created_at,
+  is_active
+FROM dealers
+LIMIT 10;
+
+-- Check date formats
+SELECT 
+  dlrcode,
+  date,
+  date_of_termination_resignation,
+  last_date_of_operations
+FROM dealers
+WHERE date IS NOT NULL
+LIMIT 5;
+
+-- Verify all dealers have dealer_id and timestamps
+SELECT 
+  COUNT(*) as total,
+  COUNT(dealer_id) as has_dealer_id,
+  COUNT(created_at) as has_created_at,
+  COUNT(updated_at) as has_updated_at,
+  COUNT(*) FILTER (WHERE is_active = true) as active_count
+FROM dealers;
+```
+
+---
+
+## Additional Notes
+
+- **Backup**: Always backup your database before bulk imports
+- **Testing**: Test import with a small sample (5-10 rows) first
+- **Validation**: Validate data quality before import
+- **Updates**: Use `UPSERT` logic if you need to update existing records
+
+---
+
+## Support
+
+For issues or questions:
+1. Check the troubleshooting section above
+2. Review PostgreSQL COPY documentation
+3. Verify CSV format matches the sample provided
+4. Check database logs for detailed error messages
+
+---
+
+**Last Updated**: December 2025  
+**Version**: 1.0
+

docs/DEALER_CLAIM_FRESH_START.md

@@ -0,0 +1,181 @@
+# Dealer Claim Management - Fresh Start Guide
+
+## Overview
+
+This guide helps you start fresh with the dealer claim management system by cleaning up all existing data and ensuring the database structure is ready for new requests.
+
+## Prerequisites
+
+1. **Database Migrations**: Ensure all migrations are up to date, including the new tables:
+   - `internal_orders` (for IO details)
+   - `claim_budget_tracking` (for comprehensive budget tracking)
+
+2. **Backup** (Optional but Recommended): 
+   - If you have important data, backup your database before running cleanup
+
+## Fresh Start Steps
+
+### Step 1: Run Database Migrations
+
+Ensure all new tables are created:
+
+```bash
+cd Re_Backend
+npm run migrate
+```
+
+This will create:
+- ✅ `internal_orders` table (for IO details with `ioRemark`)
+- ✅ `claim_budget_tracking` table (for comprehensive budget tracking)
+- ✅ All other dealer claim related tables
+
+### Step 2: Clean Up All Existing Dealer Claims
+
+Run the cleanup script to remove all existing CLAIM_MANAGEMENT requests:
+
+```bash
+npm run cleanup:dealer-claims
+```
+
+**What this script does:**
+- Finds all workflow requests with `workflow_type = 'CLAIM_MANAGEMENT'`
+- Deletes all related data from:
+  - `claim_budget_tracking`
+  - `internal_orders`
+  - `dealer_proposal_cost_items`
+  - `dealer_completion_details`
+  - `dealer_proposal_details`
+  - `dealer_claim_details`
+  - `activities`
+  - `work_notes`
+  - `documents`
+  - `participants`
+  - `approval_levels`
+  - `subscriptions`
+  - `notifications`
+  - `request_summaries`
+  - `shared_summaries`
+  - `conclusion_remarks`
+  - `tat_alerts`
+  - `workflow_requests` (finally)
+
+**Note:** This script uses a database transaction, so if any step fails, all changes will be rolled back.
+
+### Step 3: Verify Cleanup
+
+After running the cleanup script, verify that no CLAIM_MANAGEMENT requests remain:
+
+```sql
+SELECT COUNT(*) FROM workflow_requests WHERE workflow_type = 'CLAIM_MANAGEMENT';
+-- Should return 0
+```
+
+### Step 4: Seed Dealers (If Needed)
+
+If you need to seed dealer users:
+
+```bash
+npm run seed:dealers
+```
+
+## Database Structure Summary
+
+### New Tables Created
+
+1. **`internal_orders`** - Dedicated table for IO (Internal Order) details
+   - `io_id` (PK)
+   - `request_id` (FK, unique)
+   - `io_number`
+   - `io_remark` ✅ (dedicated field, not in comments)
+   - `io_available_balance`
+   - `io_blocked_amount`
+   - `io_remaining_balance`
+   - `organized_by` (FK to users)
+   - `organized_at`
+   - `status` (PENDING, BLOCKED, RELEASED, CANCELLED)
+
+2. **`claim_budget_tracking`** - Comprehensive budget tracking
+   - `budget_id` (PK)
+   - `request_id` (FK, unique)
+   - `initial_estimated_budget`
+   - `proposal_estimated_budget`
+   - `approved_budget`
+   - `io_blocked_amount`
+   - `closed_expenses`
+   - `final_claim_amount`
+   - `credit_note_amount`
+   - `budget_status` (DRAFT, PROPOSED, APPROVED, BLOCKED, CLOSED, SETTLED)
+   - `variance_amount` & `variance_percentage`
+   - Audit fields (last_modified_by, last_modified_at, modification_reason)
+
+### Existing Tables (Enhanced)
+
+- `dealer_claim_details` - Main claim information
+- `dealer_proposal_details` - Step 1: Dealer proposal
+- `dealer_proposal_cost_items` - Cost breakdown items
+- `dealer_completion_details` - Step 5: Completion documents
+
+## What's New
+
+### 1. IO Details in Separate Table
+- ✅ IO remark is now stored in `internal_orders.io_remark` (not parsed from comments)
+- ✅ Tracks who organized the IO (`organized_by`, `organized_at`)
+- ✅ Better data integrity and querying
+
+### 2. Comprehensive Budget Tracking
+- ✅ All budget-related values in one place
+- ✅ Tracks budget lifecycle (DRAFT → PROPOSED → APPROVED → BLOCKED → CLOSED → SETTLED)
+- ✅ Calculates variance automatically
+- ✅ Audit trail for budget modifications
+
+### 3. Proper Data Structure
+- ✅ Estimated budget: `claimDetails.estimatedBudget` or `proposalDetails.totalEstimatedBudget`
+- ✅ Claim amount: `completionDetails.totalClosedExpenses` or `budgetTracking.finalClaimAmount`
+- ✅ IO details: `internalOrder` table (separate, dedicated)
+- ✅ E-Invoice: `claimDetails.eInvoiceNumber`, `claimDetails.eInvoiceDate`
+- ✅ Credit Note: `claimDetails.creditNoteNumber`, `claimDetails.creditNoteAmount`
+
+## Next Steps After Cleanup
+
+1. **Create New Claim Requests**: Use the API or frontend to create fresh dealer claim requests
+2. **Test Workflow**: Go through the 8-step workflow to ensure everything works correctly
+3. **Verify Data Storage**: Check that IO details and budget tracking are properly stored
+
+## Troubleshooting
+
+### If Cleanup Fails
+
+1. Check database connection
+2. Verify foreign key constraints are not blocking deletion
+3. Check logs for specific error messages
+4. The script uses transactions, so partial deletions won't occur
+
+### If Tables Don't Exist
+
+Run migrations again:
+```bash
+npm run migrate
+```
+
+### If You Need to Restore Data
+
+If you backed up before cleanup, restore from your backup. The cleanup script does not create backups automatically.
+
+## API Endpoints Ready
+
+After cleanup, you can use these endpoints:
+
+- `POST /api/v1/dealer-claims` - Create new claim request
+- `POST /api/v1/dealer-claims/:requestId/proposal` - Submit proposal (Step 1)
+- `PUT /api/v1/dealer-claims/:requestId/io` - Update IO details (Step 3)
+- `POST /api/v1/dealer-claims/:requestId/completion` - Submit completion (Step 5)
+- `PUT /api/v1/dealer-claims/:requestId/e-invoice` - Update e-invoice (Step 7)
+- `PUT /api/v1/dealer-claims/:requestId/credit-note` - Update credit note (Step 8)
+
+## Summary
+
+✅ **Cleanup Script**: `npm run cleanup:dealer-claims`  
+✅ **Migrations**: `npm run migrate`  
+✅ **Fresh Start**: Database is ready for new dealer claim requests  
+✅ **Proper Structure**: IO details and budget tracking in dedicated tables
+

docs/DEALER_INTEGRATION_STATUS.md

@@ -0,0 +1,29 @@
+# Dealer Integration Implementation Status
+
+This document summarizes the changes made to integrate the external Royal Enfield Dealer API and implement the dealer validation logic during request creation.
+
+## Completed Work
+
+### 1. External Dealer API Integration
+- **Service**: `DealerExternalService` in `src/services/dealerExternal.service.ts`
+    - Implemented `getDealerByCode` to fetch data from `https://api-uat2.royalenfield.com/DealerMaster`.
+    - Returns real-time GSTIN, Address, and location details.
+- **Controller & Routes**: Integrated under `/api/v1/dealers-external/search/:dealerCode`.
+- **Enrichment**: `DealerService.getDealerByCode` now automatically merges this external data into the system's `DealerInfo`, benefiting PWC and PDF generation services.
+
+### 2. Dealer Validation & Field Mapping Fix
+- **Strategic Mapping**: Based on requirement, all dealer codes are now mapped against the `employeeNumber` field (HR ID) in the `User` model, not `employeeId`.
+- **User Enrichment Service**: `validateDealerUser(dealerCode)` now searches by `employeeNumber`.
+- **SSO Alignment**: `AuthService.ts` now extracts `dealer_code` from the authentication response and persists it to `employeeNumber`.
+- **Dealer Service**: `getDealerByCode` uses jobTitle-based validation against the `User` table as the primary lookup.
+
+### 3. Claim Workflow Integration
+- **Dealer Claim Service**: `createClaimRequest` validates the dealer immediately and overrides approver steps 1 and 4 with the validated user.
+- **Workflow Controller**: Enforces dealer validation for all `DEALER CLAIM` templates and any request containing a `dealerCode`.
+
+### 4. E-Invoice & PDF Alignment
+- **PWC Integration**: `generateSignedInvoice` now uses the enriched `DealerInfo` containing the correct external GSTIN and state code.
+- **Invoice PDF**: `PdfService` correctly displays the external dealer name, GSTIN, and POS from the source of truth.
+
+## Conclusion
+All integrated components have been verified via test scripts and end-to-end flow analysis. The dependency on the local `dealers` table has been successfully minimized, and the system now relies on the `User` table and External API as the primary sources of dealer information.

docs/DEALER_USER_ARCHITECTURE.md

@@ -0,0 +1,134 @@
+# Dealer User Architecture
+
+## Overview
+
+**Dealers and regular users are stored in the SAME `users` table.** This is the correct approach because dealers ARE users in the system - they login via SSO, participate in workflows, receive notifications, etc.
+
+## Why Single Table?
+
+### ✅ Advantages:
+1. **Unified Authentication**: Dealers login via the same Okta SSO as regular users
+2. **Shared Functionality**: Dealers need all user features (notifications, workflow participation, etc.)
+3. **Simpler Architecture**: No need for joins or complex queries
+4. **Data Consistency**: Single source of truth for all users
+5. **Workflow Integration**: Dealers can be approvers, participants, or action takers seamlessly
+
+### ❌ Why NOT Separate Table:
+- Would require complex joins for every query
+- Data duplication (email, name, etc. in both tables)
+- Dealers still need user authentication and permissions
+- More complex to maintain
+
+## How Dealers Are Identified
+
+Dealers are identified using **three criteria** (any one matches):
+
+1. **`employeeId` field starts with `'RE-'`** (e.g., `RE-MH-001`, `RE-DL-002`)
+   - This is the **primary identifier** for dealers
+   - Dealer code is stored in `employeeId` field
+
+2. **`designation` contains `'dealer'`** (case-insensitive)
+   - Example: `"Dealer"`, `"Senior Dealer"`, etc.
+
+3. **`department` contains `'dealer'`** (case-insensitive)
+   - Example: `"Dealer Operations"`, `"Dealer Management"`, etc.
+
+## Database Schema
+
+```sql
+users {
+    user_id UUID PK
+    email VARCHAR(255) UNIQUE
+    okta_sub VARCHAR(100) UNIQUE  -- From Okta SSO
+    employee_id VARCHAR(50)        -- For dealers: stores dealer code (RE-MH-001)
+    display_name VARCHAR(255)
+    designation VARCHAR(255)       -- For dealers: "Dealer"
+    department VARCHAR(255)        -- For dealers: "Dealer Operations"
+    role ENUM('USER', 'MANAGEMENT', 'ADMIN')
+    is_active BOOLEAN
+    -- ... other user fields
+}
+```
+
+## Example Data
+
+### Regular User:
+```json
+{
+  "userId": "uuid-1",
+  "email": "john.doe@{{APP_DOMAIN}}",
+  "employeeId": "E12345",  // Regular employee ID
+  "designation": "Software Engineer",
+  "department": "IT",
+  "role": "USER"
+}
+```
+
+### Dealer User:
+```json
+{
+  "userId": "uuid-2",
+  "email": "test.2@{{APP_DOMAIN}}",
+  "employeeId": "RE-MH-001",  // Dealer code stored here
+  "designation": "Dealer",
+  "department": "Dealer Operations",
+  "role": "USER"
+}
+```
+
+## Querying Dealers
+
+The `dealer.service.ts` uses these filters to find dealers:
+
+```typescript
+User.findAll({
+  where: {
+    [Op.or]: [
+      { designation: { [Op.iLike]: '%dealer%' } },
+      { employeeId: { [Op.like]: 'RE-%' } },
+      { department: { [Op.iLike]: '%dealer%' } },
+    ],
+    isActive: true,
+  }
+});
+```
+
+## Seed Script Behavior
+
+When running `npm run seed:dealers`:
+
+1. **If user exists (from Okta SSO)**:
+   - ✅ Preserves `oktaSub` (real Okta subject ID)
+   - ✅ Preserves `role` (from Okta)
+   - ✅ Updates `employeeId` with dealer code
+   - ✅ Updates `designation` to "Dealer" (if not already)
+   - ✅ Updates `department` to "Dealer Operations" (if not already)
+
+2. **If user doesn't exist**:
+   - Creates placeholder user
+   - Sets `oktaSub` to `dealer-{code}-pending-sso`
+   - When dealer logs in via SSO, `oktaSub` gets updated automatically
+
+## Workflow Integration
+
+Dealers participate in workflows just like regular users:
+
+- **As Approvers**: In Steps 1 & 5 of claim management workflow
+- **As Participants**: Can be added to any workflow
+- **As Action Takers**: Can submit proposals, completion documents, etc.
+
+The system identifies them as dealers by checking `employeeId` starting with `'RE-'` or `designation` containing `'dealer'`.
+
+## API Endpoints
+
+- `GET /api/v1/dealers` - Get all dealers (filters users table)
+- `GET /api/v1/dealers/code/:dealerCode` - Get dealer by code
+- `GET /api/v1/dealers/email/:email` - Get dealer by email
+- `GET /api/v1/dealers/search?q=term` - Search dealers
+
+All endpoints query the same `users` table with dealer-specific filters.
+
+## Conclusion
+
+**✅ Single `users` table is the correct approach.** No separate dealer table needed. Dealers are users with special identification markers (dealer code in `employeeId`, dealer designation, etc.).
+

docs/DMS_INTEGRATION_API.md

@@ -0,0 +1,695 @@
+# DMS Integration API Documentation
+
+## Overview
+
+This document describes the data exchange between the Royal Enfield Workflow System (RE-Flow) and the DMS (Document Management System) for:
+1. **E-Invoice Generation** - Submitting claim data to DMS for e-invoice creation
+2. **Credit Note Generation** - Fetching/Generating credit note from DMS
+
+## Data Flow Overview
+
+### Inputs from RE-Flow System
+
+The following data is sent **FROM** RE-Flow System **TO** DMS:
+
+1. **Dealer Code** - Unique dealer identifier
+2. **Dealer Name** - Dealer business name
+3. **Activity Name** - Name of the activity/claim type (see Activity Types below)
+4. **Activity Description** - Detailed description of the activity
+5. **Claim Amount** - Total claim amount (before taxes)
+6. **Request Number** - Unique request identifier from RE-Flow (e.g., "REQ-2025-12-0001")
+7. **IO Number** - Internal Order number (if available)
+
+### Inputs from DMS Team
+
+The following data is **PROVIDED BY** DMS Team **TO** RE-Flow System (via webhook):
+
+3. **Document No** - Generated invoice/credit note number
+4. **Document Type** - Type of document ("E-INVOICE", "INVOICE", or "CREDIT_NOTE")
+10. **Item Code No** - Item code number (same as provided in request, used for GST calculation)
+11. **HSN/SAC Code** - HSN/SAC code for tax calculation (determined by DMS based on Item Code No)
+12. **CGST %** - CGST percentage (e.g., 9.0 for 9%) - calculated by DMS based on Item Code No and dealer location
+13. **SGST %** - SGST percentage (e.g., 9.0 for 9%) - calculated by DMS based on Item Code No and dealer location
+14. **IGST %** - IGST percentage (0.0 for intra-state, >0 for inter-state) - calculated by DMS based on Item Code No and dealer location
+15. **CGST Amount** - CGST amount in INR - calculated by DMS
+16. **SGST Amount** - SGST amount in INR - calculated by DMS
+17. **IGST Amount** - IGST amount in INR - calculated by DMS
+18. **Credit Type** - Type of credit: "GST" or "Commercial Credit" (for credit notes only)
+19. **IRN No** - Invoice Reference Number from GST portal (response from GST system)
+20. **SAP Credit Note No** - SAP Credit Note Number (response from SAP system, for credit notes only)
+
+**Important:** Item Code No is used by DMS for GST calculation. DMS determines HSN/SAC code, tax percentages, and tax amounts based on the Item Code No and dealer location.
+
+### Predefined Activity Types
+
+The following is the complete list of predefined Activity Types that RE-Flow System uses. DMS Team must provide **Item Code No** mapping for each Activity Type:
+
+- **Riders Mania Claims**
+- **Marketing Cost – Bike to Vendor**
+- **Media Bike Service**
+- **ARAI Motorcycle Liquidation**
+- **ARAI Certification – STA Approval CNR**
+- **Procurement of Spares/Apparel/GMA for Events**
+- **Fuel for Media Bike Used for Event**
+- **Motorcycle Buyback and Goodwill Support**
+- **Liquidation of Used Motorcycle**
+- **Motorcycle Registration CNR (Owned or Gifted by RE)**
+- **Legal Claims Reimbursement**
+- **Service Camp Claims**
+- **Corporate Claims – Institutional Sales PDI**
+
+**Item Code No Lookup Process:**
+1. RE-Flow sends `activity_name` to DMS
+2. DMS responds with corresponding `item_code_no` based on activity type mapping
+3. RE-Flow includes the `item_code_no` in invoice/credit note generation payload
+4. DMS uses `item_code_no` to determine HSN/SAC code and calculate GST (CGST/SGST/IGST percentages and amounts)
+
+**Note:** DMS Team must configure the Activity Type → Item Code No mapping in their system. This mapping is used for GST calculation.
+
+---
+
+## 1. E-Invoice Generation (DMS Push)
+
+### When It's Called
+
+This API is called when:
+- **Step 6** of the claim management workflow is approved (Requestor approves the claim)
+- User manually pushes claim data to DMS via the "Push to DMS" action
+- System auto-generates e-invoice after claim approval
+
+### Request Details
+
+**Endpoint:** `POST {DMS_BASE_URL}/api/invoices/generate`
+
+**Headers:**
+```http
+Authorization: Bearer {DMS_API_KEY}
+Content-Type: application/json
+```
+
+**Request Body (Complete Payload):**
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001"
+}
+```
+
+**Complete Webhook Response Payload (from DMS to RE-Flow):**
+
+After processing, DMS will send the following complete payload to RE-Flow webhook endpoint `POST /api/v1/webhooks/dms/invoice`:
+
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "document_no": "EINV-2025-001234",
+  "document_type": "E-INVOICE",
+  "document_date": "2025-12-17T10:30:00.000Z",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001",
+  "hsn_sac_code": "998314",
+  "cgst_percentage": 9.0,
+  "sgst_percentage": 9.0,
+  "igst_percentage": 0.0,
+  "cgst_amount": 13500.00,
+  "sgst_amount": 13500.00,
+  "igst_amount": 0.00,
+  "total_amount": 177000.00,
+  "irn_no": "IRN123456789012345678901234567890123456789012345678901234567890",
+  "invoice_file_path": "https://dms.example.com/invoices/EINV-2025-001234.pdf",
+  "error_message": null,
+  "timestamp": "2025-12-17T10:30:00.000Z"
+}
+```
+
+**Important Notes:**
+- RE-Flow sends all required details including `item_code_no` (determined by DMS based on `activity_name` mapping)
+- DMS processes the invoice generation **asynchronously**
+- DMS responds with acknowledgment only
+- **Status Verification (Primary Method):** DMS sends webhook to RE-Flow webhook URL `POST /api/v1/webhooks/dms/invoice` (see DMS_WEBHOOK_API.md) to notify when invoice is generated with complete details
+- `item_code_no` is used by DMS for GST calculation (HSN/SAC code, tax percentages, tax amounts)
+- **Status Verification (Backup Method):** If webhook fails, RE-Flow can use backup status check API (see section "Backup: Status Check API" below)
+
+### Request Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `request_number` | string | ✅ Yes | Unique request number from RE-Flow System (e.g., "REQ-2025-12-0001") |
+| `dealer_code` | string | ✅ Yes | Dealer's unique code/identifier |
+| `dealer_name` | string | ✅ Yes | Dealer's business name |
+| `activity_name` | string | ✅ Yes | Activity type name (must match one of the predefined Activity Types) |
+| `activity_description` | string | ✅ Yes | Detailed description of the activity/claim |
+| `claim_amount` | number | ✅ Yes | Total claim amount before taxes (in INR, decimal format) |
+| `io_number` | string | No | Internal Order (IO) number if available |
+| `item_code_no` | string | ✅ Yes | Item code number determined by DMS based on `activity_name` mapping. RE-Flow includes this in the request. Used by DMS for GST calculation. |
+
+### Expected Response
+
+**Success Response (200 OK):**
+
+**Note:** DMS should respond with a simple acknowledgment. The actual invoice details (document number, tax calculations, IRN, etc.) will be sent back to RE-Flow via **webhook** (see DMS_WEBHOOK_API.md).
+
+```json
+{
+  "success": true,
+  "message": "Invoice generation request received and queued for processing",
+  "request_number": "REQ-2025-12-0001"
+}
+```
+
+### Response Field Descriptions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Indicates if the request was accepted |
+| `message` | string | Status message |
+| `request_number` | string | Echo of the request number for reference |
+
+**Important:** 
+- The actual invoice generation happens **asynchronously**
+- DMS will send the complete invoice details (including document number, tax calculations, IRN, file path, `item_code_no`, etc.) via **webhook** to RE-Flow System once processing is complete
+- Webhook endpoint: `POST /api/v1/webhooks/dms/invoice` (see DMS_WEBHOOK_API.md for details)
+- If webhook delivery fails, RE-Flow can use the backup status check API (see section "Backup: Status Check API" below)
+
+### Error Response
+
+**Error Response (400/500):**
+```json
+{
+  "success": false,
+  "error": "Error message describing what went wrong",
+  "error_code": "INVALID_DEALER_CODE"
+}
+```
+
+### Error Scenarios
+
+| Error Code | Description | Possible Causes |
+|------------|-------------|-----------------|
+| `INVALID_DEALER_CODE` | Dealer code not found in DMS | Dealer not registered in DMS |
+| `INVALID_AMOUNT` | Amount validation failed | Negative amount or invalid format |
+| `IO_NOT_FOUND` | IO number not found | Invalid or non-existent IO number |
+| `DMS_SERVICE_ERROR` | DMS internal error | DMS system unavailable or processing error |
+
+### Example cURL Request
+
+```bash
+curl -X POST "https://dms.example.com/api/invoices/generate" \
+  -H "Authorization: Bearer YOUR_DMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "request_number": "REQ-2025-12-0001",
+    "dealer_code": "DLR001",
+    "dealer_name": "ABC Motors",
+    "activity_name": "Marketing Cost – Bike to Vendor",
+    "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+    "claim_amount": 150000.00,
+    "io_number": "IO-2025-001",
+    "item_code_no": "ITEM-001"
+  }'
+```
+
+---
+
+## 2. Credit Note Generation (DMS Fetch)
+
+### When It's Called
+
+This API is called when:
+- **Step 8** of the claim management workflow is initiated (Credit Note Confirmation)
+- User requests to generate/fetch credit note from DMS
+- System auto-generates credit note after e-invoice is confirmed
+
+### Request Details
+
+**Endpoint:** `POST {DMS_BASE_URL}/api/credit-notes/generate`
+
+**Headers:**
+```http
+Authorization: Bearer {DMS_API_KEY}
+Content-Type: application/json
+```
+
+**Request Body (Complete Payload):**
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "e_invoice_number": "EINV-2025-001234",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001"
+}
+```
+
+**Complete Webhook Response Payload (from DMS to RE-Flow):**
+
+After processing, DMS will send the following complete payload to RE-Flow webhook endpoint `POST /api/v1/webhooks/dms/credit-note`:
+
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "document_no": "CN-2025-001234",
+  "document_type": "CREDIT_NOTE",
+  "document_date": "2025-12-17T11:00:00.000Z",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001",
+  "hsn_sac_code": "998314",
+  "cgst_percentage": 9.0,
+  "sgst_percentage": 9.0,
+  "igst_percentage": 0.0,
+  "cgst_amount": 13500.00,
+  "sgst_amount": 13500.00,
+  "igst_amount": 0.00,
+  "total_amount": 177000.00,
+  "credit_type": "GST",
+  "irn_no": "IRN987654321098765432109876543210987654321098765432109876543210",
+  "sap_credit_note_no": "SAP-CN-2025-001234",
+  "credit_note_file_path": "https://dms.example.com/credit-notes/CN-2025-001234.pdf",
+  "error_message": null,
+  "timestamp": "2025-12-17T11:00:00.000Z"
+}
+```
+
+**Important Notes:** 
+- RE-Flow sends `activity_name` in the request
+- DMS should use the same Item Code No from the original invoice (determined by `activity_name`)
+- DMS returns `item_code_no` in the webhook response (see DMS_WEBHOOK_API.md)
+- `item_code_no` is used by DMS for GST calculation (HSN/SAC code, tax percentages, tax amounts)
+
+### Request Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `request_number` | string | ✅ Yes | Original request number from RE-Flow System |
+| `e_invoice_number` | string | ✅ Yes | E-invoice number that was generated earlier (must exist in DMS) |
+| `dealer_code` | string | ✅ Yes | Dealer's unique code/identifier (must match invoice) |
+| `dealer_name` | string | ✅ Yes | Dealer's business name |
+| `activity_name` | string | ✅ Yes | Activity type name (must match original invoice) |
+| `activity_description` | string | ✅ Yes | Activity description (must match original invoice) |
+| `claim_amount` | number | ✅ Yes | Credit note amount (in INR, decimal format) - typically matches invoice amount |
+| `io_number` | string | No | Internal Order (IO) number if available |
+| `item_code_no` | string | ✅ Yes | Item code number (same as original invoice, determined by `activity_name` mapping). RE-Flow includes this in the request. Used by DMS for GST calculation. |
+
+### Expected Response
+
+**Success Response (200 OK):**
+
+**Note:** DMS should respond with a simple acknowledgment. The actual credit note details (document number, tax calculations, SAP credit note number, IRN, etc.) will be sent back to RE-Flow via **webhook** (see DMS_WEBHOOK_API.md).
+
+```json
+{
+  "success": true,
+  "message": "Credit note generation request received and queued for processing",
+  "request_number": "REQ-2025-12-0001"
+}
+```
+
+### Response Field Descriptions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Indicates if the request was accepted |
+| `message` | string | Status message |
+| `request_number` | string | Echo of the request number for reference |
+
+**Important:** The actual credit note generation happens asynchronously. DMS will send the complete credit note details (including document number, tax calculations, SAP credit note number, IRN, file path, etc.) via webhook to RE-Flow System once processing is complete.
+
+### Error Response
+
+**Error Response (400/500):**
+```json
+{
+  "success": false,
+  "error": "Error message describing what went wrong",
+  "error_code": "INVOICE_NOT_FOUND"
+}
+```
+
+### Error Scenarios
+
+| Error Code | Description | Possible Causes |
+|------------|-------------|-----------------|
+| `INVOICE_NOT_FOUND` | E-invoice number not found in DMS | Invoice was not generated or invalid invoice number |
+| `INVALID_AMOUNT` | Amount validation failed | Amount mismatch with invoice or invalid format |
+| `DEALER_MISMATCH` | Dealer code/name doesn't match invoice | Different dealer code than original invoice |
+| `CREDIT_NOTE_EXISTS` | Credit note already generated for this invoice | Duplicate request for same invoice |
+| `DMS_SERVICE_ERROR` | DMS internal error | DMS system unavailable or processing error |
+
+### Example cURL Request
+
+```bash
+curl -X POST "https://dms.example.com/api/credit-notes/generate" \
+  -H "Authorization: Bearer YOUR_DMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "request_number": "REQ-2025-12-0001",
+    "e_invoice_number": "EINV-2025-001234",
+    "dealer_code": "DLR001",
+    "dealer_name": "ABC Motors",
+    "activity_name": "Marketing Cost – Bike to Vendor",
+    "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+    "claim_amount": 150000.00,
+    "io_number": "IO-2025-001",
+    "item_code_no": "ITEM-001"
+  }'
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+The following environment variables need to be configured in the RE Workflow System:
+
+```env
+# DMS Integration Configuration
+DMS_BASE_URL=https://dms.example.com
+DMS_API_KEY=your_dms_api_key_here
+
+# Alternative: Username/Password Authentication
+DMS_USERNAME=your_dms_username
+DMS_PASSWORD=your_dms_password
+```
+
+### Authentication Methods
+
+DMS supports two authentication methods:
+
+1. **API Key Authentication** (Recommended)
+   - Set `DMS_API_KEY` in environment variables
+   - Header: `Authorization: Bearer {DMS_API_KEY}`
+
+2. **Username/Password Authentication**
+   - Set `DMS_USERNAME` and `DMS_PASSWORD` in environment variables
+   - Use Basic Auth or custom authentication as per DMS requirements
+
+---
+
+## Integration Flow
+
+### E-Invoice Generation Flow
+
+```
+┌─────────────────┐
+│ RE-Flow System  │
+│ (Step 6)        │
+└────────┬────────┘
+         │
+         │ POST /api/invoices/generate
+         │ { request_number, dealer_code, activity_name,
+         │   claim_amount, item_code_no, ... }
+         │
+         ▼
+┌─────────────────┐
+│ DMS System      │
+│                 │
+│ - Validates     │
+│ - Queues for    │
+│   processing    │
+│                 │
+│ Response:       │
+│ { success: true }│
+└────────┬────────┘
+         │
+         │ (Asynchronous Processing)
+         │
+         │ - Determines Item Code No
+         │ - Calculates GST
+         │ - Generates E-Invoice
+         │ - Gets IRN from GST
+         │
+         │ POST /api/v1/webhooks/dms/invoice
+         │ { document_no, item_code_no, 
+         │   hsn_sac_code, tax details,
+         │   irn_no, invoice_file_path, ... }
+         │
+         ▼
+┌─────────────────┐
+│ RE-Flow System  │
+│                 │
+│ - Receives      │
+│   webhook       │
+│ - Stores        │
+│   invoice data  │
+│ - Updates       │
+│   workflow      │
+│ - Moves to      │
+│   Step 8        │
+└─────────────────┘
+
+Backup (if webhook fails):
+┌─────────────────┐
+│ RE-Flow System  │
+│                 │
+│ GET /api/invoices/status/{request_number}
+│                 │
+         ▼
+┌─────────────────┐
+│ DMS System      │
+│                 │
+│ Returns current │
+│ invoice status  │
+│ and details     │
+└─────────────────┘
+```
+
+### Credit Note Generation Flow
+
+```
+┌─────────────────┐
+│ RE-Flow System  │
+│ (Step 8)        │
+└────────┬────────┘
+         │
+         │ POST /api/credit-notes/generate
+         │ { e_invoice_number, request_number, 
+         │   activity_name, claim_amount,
+         │   item_code_no, ... }
+         │
+         ▼
+┌─────────────────┐
+│ DMS System      │
+│                 │
+│ - Validates     │
+│   invoice       │
+│ - Queues for    │
+│   processing    │
+│                 │
+│ Response:       │
+│ { success: true }│
+└────────┬────────┘
+         │
+         │ (Asynchronous Processing)
+         │
+         │ - Uses Item Code No from invoice
+         │ - Calculates GST
+         │ - Generates Credit Note
+         │ - Gets IRN from GST
+         │ - Gets SAP Credit Note No
+         │
+         │ POST /api/v1/webhooks/dms/credit-note
+         │ { document_no, item_code_no,
+         │   hsn_sac_code, tax details,
+         │   irn_no, sap_credit_note_no,
+         │   credit_note_file_path, ... }
+         │
+         ▼
+┌─────────────────┐
+│ RE-Flow System  │
+│                 │
+│ - Receives      │
+│   webhook       │
+│ - Stores        │
+│   credit note   │
+│ - Updates       │
+│   workflow      │
+│ - Completes     │
+│   request       │
+└─────────────────┘
+
+Backup (if webhook fails):
+┌─────────────────┐
+│ RE-Flow System  │
+│                 │
+│ GET /api/credit-notes/status/{request_number}
+│                 │
+         ▼
+┌─────────────────┐
+│ DMS System      │
+│                 │
+│ Returns current │
+│ credit note     │
+│ status and      │
+│ details         │
+└─────────────────┘
+```
+
+---
+
+## Data Mapping
+
+### RE-Flow System → DMS (API Request)
+
+| RE-Flow Field | DMS Request Field | Notes |
+|----------------|-------------------|-------|
+| `request.requestNumber` | `request_number` | Direct mapping |
+| `claimDetails.dealerCode` | `dealer_code` | Direct mapping |
+| `claimDetails.dealerName` | `dealer_name` | Direct mapping |
+| `claimDetails.activityName` | `activity_name` | Must match predefined Activity Types |
+| `claimDetails.activityDescription` | `activity_description` | Direct mapping |
+| `budgetTracking.closedExpenses` | `claim_amount` | Total claim amount (before taxes) |
+| `internalOrder.ioNumber` | `io_number` | Optional, if available |
+| `itemCodeNo` (determined by DMS) | `item_code_no` | Included in payload. DMS determines this based on `activity_name` mapping. Used by DMS for GST calculation. |
+| `claimInvoice.invoiceNumber` | `e_invoice_number` | For credit note request only |
+
+### DMS → RE-Flow System (Webhook Response)
+
+**Note:** All invoice and credit note details are sent via webhook (see DMS_WEBHOOK_API.md), not in the API response.
+
+| DMS Webhook Field | RE-Flow Database Field | Table | Notes |
+|-------------------|------------------------|-------|-------|
+| `document_no` | `invoice_number` / `credit_note_number` | `claim_invoices` / `claim_credit_notes` | Generated by DMS |
+| `document_date` | `invoice_date` / `credit_note_date` | `claim_invoices` / `claim_credit_notes` | Converted to Date object |
+| `total_amount` | `invoice_amount` / `credit_amount` | `claim_invoices` / `claim_credit_notes` | Includes taxes |
+| `invoice_file_path` | `invoice_file_path` | `claim_invoices` | URL/path to PDF |
+| `credit_note_file_path` | `credit_note_file_path` | `claim_credit_notes` | URL/path to PDF |
+| `irn_no` | Stored in `description` field | Both tables | From GST portal |
+| `sap_credit_note_no` | `sap_document_number` | `claim_credit_notes` | From SAP system |
+| `item_code_no` | Stored in `description` field | Both tables | Provided by DMS based on activity |
+| `hsn_sac_code` | Stored in `description` field | Both tables | Provided by DMS |
+| `cgst_amount`, `sgst_amount`, `igst_amount` | Stored in `description` field | Both tables | Tax breakdown |
+| `credit_type` | Stored in `description` field | `claim_credit_notes` | "GST" or "Commercial Credit" |
+
+---
+
+## Testing
+
+### Mock Mode
+
+When DMS is not configured, the system operates in **mock mode**:
+- Returns mock invoice/credit note numbers
+- Logs warnings instead of making actual API calls
+- Useful for development and testing
+
+### Test Data
+
+**E-Invoice Test Request:**
+```json
+{
+  "request_number": "REQ-TEST-001",
+  "dealer_code": "TEST-DLR-001",
+  "dealer_name": "Test Dealer",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Test invoice generation for marketing activity",
+  "claim_amount": 10000.00,
+  "io_number": "IO-TEST-001",
+  "item_code_no": "ITEM-001"
+}
+```
+
+**Credit Note Test Request:**
+```json
+{
+  "request_number": "REQ-TEST-001",
+  "e_invoice_number": "EINV-TEST-001",
+  "dealer_code": "TEST-DLR-001",
+  "dealer_name": "Test Dealer",
+  "activity_name": "Marketing Cost – Bike to Vendor",
+  "activity_description": "Test credit note generation for marketing activity",
+  "claim_amount": 10000.00,
+  "io_number": "IO-TEST-001",
+  "item_code_no": "ITEM-001"
+}
+```
+
+---
+
+## Notes
+
+1. **Asynchronous Processing**: Invoice and credit note generation happens asynchronously. DMS should:
+   - Accept the request immediately and return a success acknowledgment
+   - Process the invoice/credit note in the background
+   - Send complete details via webhook once processing is complete
+
+2. **Activity Type to Item Code No Mapping**: 
+   - DMS Team must provide **Item Code No** mapping for each predefined Activity Type
+   - This mapping should be configured in DMS system
+   - RE-Flow includes `item_code_no` in the request payload (determined by DMS based on `activity_name` mapping)
+   - DMS uses Item Code No to determine HSN/SAC code and calculate GST (CGST/SGST/IGST percentages and amounts)
+   - DMS returns `item_code_no` in the webhook response for verification
+
+3. **Tax Calculation**: DMS is responsible for:
+   - Determining CGST/SGST/IGST percentages based on dealer location and activity type
+   - Calculating tax amounts
+   - Providing HSN/SAC codes
+
+4. **Amount Validation**: DMS should validate that credit note amount matches or is less than the original invoice amount.
+
+5. **Invoice Dependency**: Credit note generation requires a valid e-invoice to exist in DMS first.
+
+6. **Error Handling**: RE-Flow System handles DMS errors gracefully and allows manual entry if DMS is unavailable.
+
+7. **Retry Logic**: Consider implementing retry logic for transient DMS failures.
+
+8. **Webhooks (Primary Method)**: DMS **MUST** send webhooks to notify RE-Flow System when invoice/credit note processing is complete. See DMS_WEBHOOK_API.md for webhook specifications. This is the **primary method** for status verification.
+
+9. **Status Check API (Backup Method)**: If webhook delivery fails, RE-Flow can use the backup status check API to verify invoice/credit note generation status. See section "Backup: Status Check API" above.
+
+10. **IRN Generation**: DMS should generate IRN (Invoice Reference Number) from GST portal and include it in the webhook response.
+
+11. **SAP Integration**: For credit notes, DMS should generate SAP Credit Note Number and include it in the webhook response.
+
+12. **Webhook URL Configuration**: DMS must be configured with RE-Flow webhook URLs:
+    - Invoice Webhook: `POST /api/v1/webhooks/dms/invoice`
+    - Credit Note Webhook: `POST /api/v1/webhooks/dms/credit-note`
+    - See DMS_WEBHOOK_API.md for complete webhook specifications
+
+---
+
+## Support
+
+For issues or questions regarding DMS integration:
+- **Backend Team**: Check logs in `Re_Backend/src/services/dmsIntegration.service.ts`
+- **DMS Team**: Contact DMS support for API-related issues
+- **Documentation**: Refer to DMS API documentation for latest updates
+
+---
+
+**Last Updated:** December 19, 2025  
+**Version:** 2.0
+
+## Changelog
+
+### Version 2.0 (December 19, 2025)
+- Added clear breakdown of inputs from RE-Flow vs DMS Team
+- Added predefined Activity Types list
+- Updated request/response structure to reflect asynchronous processing
+- Clarified that detailed responses come via webhook, not API response
+- Updated field names to match actual implementation (`claim_amount` instead of `amount`, `activity_name`, `activity_description`)
+- Added notes about Item Code No mapping requirement for DMS Team
+- Updated data mapping section with webhook fields
+
+### Version 1.0 (December 17, 2025)
+- Initial documentation
+

docs/DMS_WEBHOOK_API.md

@@ -0,0 +1,574 @@
+# DMS Webhook API Documentation
+
+## Overview
+
+This document describes the webhook endpoints that DMS (Document Management System) will call to notify the RE Workflow System after processing invoice and credit note generation requests.
+
+---
+
+## Table of Contents
+
+1. [Webhook Overview](#1-webhook-overview)
+2. [Authentication](#2-authentication)
+3. [Invoice Webhook](#3-invoice-webhook)
+4. [Credit Note Webhook](#4-credit-note-webhook)
+5. [Payload Specifications](#5-payload-specifications)
+6. [Error Handling](#6-error-handling)
+7. [Testing](#7-testing)
+
+---
+
+## 1. Webhook Overview
+
+### 1.1 Purpose
+
+After RE Workflow System pushes invoice/credit note generation requests to DMS, DMS processes them and sends webhook callbacks with the generated document details, tax information, and other metadata.
+
+### 1.2 Webhook Flow
+
+```
+┌─────────────────┐                    ┌─────────────────┐
+│ RE Workflow     │                    │ DMS System      │
+│ System          │                    │                 │
+└────────┬────────┘                    └────────┬────────┘
+         │                                      │
+         │ POST /api/invoices/generate          │
+         │ { request_number, dealer_code, ... }│
+         ├─────────────────────────────────────►│
+         │                                      │
+         │                                      │ Process Invoice
+         │                                      │ Generate Document
+         │                                      │ Calculate GST
+         │                                      │
+         │                                      │ POST /api/v1/webhooks/dms/invoice
+         │                                      │ { document_no, irn_no, ... }
+         │◄─────────────────────────────────────┤
+         │                                      │
+         │ Update Invoice Record                │
+         │ Store IRN, GST Details, etc.         │
+         │                                      │
+```
+
+---
+
+## 2. Authentication
+
+### 2.1 Webhook Signature
+
+DMS must include a signature in the request header for security validation:
+
+**Header:**
+```
+X-DMS-Signature: <HMAC-SHA256-signature>
+```
+
+**Signature Generation:**
+1. Create HMAC-SHA256 hash of the request body (JSON string)
+2. Use the shared secret key (`DMS_WEBHOOK_SECRET`)
+3. Send the hex-encoded signature in the `X-DMS-Signature` header
+
+**Example:**
+```javascript
+const crypto = require('crypto');
+const body = JSON.stringify(payload);
+const signature = crypto
+  .createHmac('sha256', DMS_WEBHOOK_SECRET)
+  .update(body)
+  .digest('hex');
+// Send in header: X-DMS-Signature: <signature>
+```
+
+### 2.2 Environment Variable
+
+Configure the webhook secret in RE Workflow System:
+
+```env
+DMS_WEBHOOK_SECRET=your_shared_secret_key_here
+```
+
+**Note:** If `DMS_WEBHOOK_SECRET` is not configured, signature validation is skipped (development mode only).
+
+---
+
+## 3. Invoice Webhook
+
+### 3.1 Endpoint
+
+**URL:** `POST /api/v1/webhooks/dms/invoice`
+
+**Base URL Examples:**
+- Development: `http://localhost:5000/api/v1/webhooks/dms/invoice`
+- UAT: `https://reflow-uat.{{APP_DOMAIN}}/api/v1/webhooks/dms/invoice`
+- Production: `https://reflow.{{APP_DOMAIN}}/api/v1/webhooks/dms/invoice`
+
+### 3.2 Request Headers
+
+```http
+Content-Type: application/json
+X-DMS-Signature: <HMAC-SHA256-signature>
+User-Agent: DMS-Webhook-Client/1.0
+```
+
+### 3.3 Request Payload
+
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "document_no": "EINV-2025-001234",
+  "document_type": "E-INVOICE",
+  "document_date": "2025-12-17T10:30:00.000Z",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Campaign",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001",
+  "hsn_sac_code": "998314",
+  "cgst_percentage": 9.0,
+  "sgst_percentage": 9.0,
+  "igst_percentage": 0.0,
+  "cgst_amount": 13500.00,
+  "sgst_amount": 13500.00,
+  "igst_amount": 0.00,
+  "total_amount": 177000.00,
+  "irn_no": "IRN123456789012345678901234567890123456789012345678901234567890",
+  "invoice_file_path": "https://dms.example.com/invoices/EINV-2025-001234.pdf",
+  "error_message": null,
+  "timestamp": "2025-12-17T10:30:00.000Z"
+}
+```
+
+### 3.4 Payload Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `request_number` | string | ✅ Yes | Original request number from RE Workflow System (e.g., "REQ-2025-12-0001") |
+| `document_no` | string | ✅ Yes | Generated invoice/document number from DMS |
+| `document_type` | string | ✅ Yes | Type of document: "E-INVOICE" or "INVOICE" |
+| `document_date` | string (ISO 8601) | ✅ Yes | Date when invoice was generated |
+| `dealer_code` | string | ✅ Yes | Dealer code (should match original request) |
+| `dealer_name` | string | ✅ Yes | Dealer name (should match original request) |
+| `activity_name` | string | ✅ Yes | Activity name from original request |
+| `activity_description` | string | ✅ Yes | Activity description from original request |
+| `claim_amount` | number | ✅ Yes | Original claim amount (before tax) |
+| `io_number` | string | No | Internal Order number (if provided in original request) |
+| `item_code_no` | string | ✅ Yes | Item code number (provided by DMS team based on activity list) |
+| `hsn_sac_code` | string | ✅ Yes | HSN/SAC code for the invoice |
+| `cgst_percentage` | number | ✅ Yes | CGST percentage (e.g., 9.0 for 9%) |
+| `sgst_percentage` | number | ✅ Yes | SGST percentage (e.g., 9.0 for 9%) |
+| `igst_percentage` | number | ✅ Yes | IGST percentage (0.0 for intra-state, >0 for inter-state) |
+| `cgst_amount` | number | ✅ Yes | CGST amount in INR |
+| `sgst_amount` | number | ✅ Yes | SGST amount in INR |
+| `igst_amount` | number | ✅ Yes | IGST amount in INR |
+| `total_amount` | number | ✅ Yes | Total invoice amount (claim_amount + all taxes) |
+| `irn_no` | string | No | Invoice Reference Number (IRN) from GST portal (if generated) |
+| `invoice_file_path` | string | ✅ Yes | URL or path to the generated invoice PDF/document file |
+| `error_message` | string | No | Error message if invoice generation failed |
+| `timestamp` | string (ISO 8601) | ✅ Yes | Timestamp when webhook is sent |
+
+### 3.5 Success Response
+
+**Status Code:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Invoice webhook processed successfully",
+  "data": {
+    "message": "Invoice webhook processed successfully",
+    "invoiceNumber": "EINV-2025-001234",
+    "requestNumber": "REQ-2025-12-0001"
+  }
+}
+```
+
+### 3.6 Error Response
+
+**Status Code:** `400 Bad Request` or `500 Internal Server Error`
+
+```json
+{
+  "success": false,
+  "message": "Failed to process invoice webhook",
+  "error": "Request not found: REQ-2025-12-0001"
+}
+```
+
+---
+
+## 4. Credit Note Webhook
+
+### 4.1 Endpoint
+
+**URL:** `POST /api/v1/webhooks/dms/credit-note`
+
+**Base URL Examples:**
+- Development: `http://localhost:5000/api/v1/webhooks/dms/credit-note`
+- UAT: `https://reflow-uat.{{APP_DOMAIN}}/api/v1/webhooks/dms/credit-note`
+- Production: `https://reflow.{{APP_DOMAIN}}/api/v1/webhooks/dms/credit-note`
+
+### 4.2 Request Headers
+
+```http
+Content-Type: application/json
+X-DMS-Signature: <HMAC-SHA256-signature>
+User-Agent: DMS-Webhook-Client/1.0
+```
+
+### 4.3 Request Payload
+
+```json
+{
+  "request_number": "REQ-2025-12-0001",
+  "document_no": "CN-2025-001234",
+  "document_type": "CREDIT_NOTE",
+  "document_date": "2025-12-17T11:00:00.000Z",
+  "dealer_code": "DLR001",
+  "dealer_name": "ABC Motors",
+  "activity_name": "Marketing Campaign",
+  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
+  "claim_amount": 150000.00,
+  "io_number": "IO-2025-001",
+  "item_code_no": "ITEM-001",
+  "hsn_sac_code": "998314",
+  "cgst_percentage": 9.0,
+  "sgst_percentage": 9.0,
+  "igst_percentage": 0.0,
+  "cgst_amount": 13500.00,
+  "sgst_amount": 13500.00,
+  "igst_amount": 0.00,
+  "total_amount": 177000.00,
+  "credit_type": "GST",
+  "irn_no": "IRN987654321098765432109876543210987654321098765432109876543210",
+  "sap_credit_note_no": "SAP-CN-2025-001234",
+  "credit_note_file_path": "https://dms.example.com/credit-notes/CN-2025-001234.pdf",
+  "error_message": null,
+  "timestamp": "2025-12-17T11:00:00.000Z"
+}
+```
+
+### 4.4 Payload Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `request_number` | string | ✅ Yes | Original request number from RE Workflow System |
+| `document_no` | string | ✅ Yes | Generated credit note number from DMS |
+| `document_type` | string | ✅ Yes | Type of document: "CREDIT_NOTE" |
+| `document_date` | string (ISO 8601) | ✅ Yes | Date when credit note was generated |
+| `dealer_code` | string | ✅ Yes | Dealer code (should match original request) |
+| `dealer_name` | string | ✅ Yes | Dealer name (should match original request) |
+| `activity_name` | string | ✅ Yes | Activity name from original request |
+| `activity_description` | string | ✅ Yes | Activity description from original request |
+| `claim_amount` | string | ✅ Yes | Original claim amount (before tax) |
+| `io_number` | string | No | Internal Order number (if provided) |
+| `item_code_no` | string | ✅ Yes | Item code number (provided by DMS team) |
+| `hsn_sac_code` | string | ✅ Yes | HSN/SAC code for the credit note |
+| `cgst_percentage` | number | ✅ Yes | CGST percentage |
+| `sgst_percentage` | number | ✅ Yes | SGST percentage |
+| `igst_percentage` | number | ✅ Yes | IGST percentage |
+| `cgst_amount` | number | ✅ Yes | CGST amount in INR |
+| `sgst_amount` | number | ✅ Yes | SGST amount in INR |
+| `igst_amount` | number | ✅ Yes | IGST amount in INR |
+| `total_amount` | number | ✅ Yes | Total credit note amount (claim_amount + all taxes) |
+| `credit_type` | string | ✅ Yes | Type of credit: "GST" or "Commercial Credit" |
+| `irn_no` | string | No | Invoice Reference Number (IRN) for credit note (if generated) |
+| `sap_credit_note_no` | string | ✅ Yes | SAP Credit Note Number (generated by SAP system) |
+| `credit_note_file_path` | string | ✅ Yes | URL or path to the generated credit note PDF/document file |
+| `error_message` | string | No | Error message if credit note generation failed |
+| `timestamp` | string (ISO 8601) | ✅ Yes | Timestamp when webhook is sent |
+
+### 4.5 Success Response
+
+**Status Code:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Credit note webhook processed successfully",
+  "data": {
+    "message": "Credit note webhook processed successfully",
+    "creditNoteNumber": "CN-2025-001234",
+    "requestNumber": "REQ-2025-12-0001"
+  }
+}
+```
+
+### 4.6 Error Response
+
+**Status Code:** `400 Bad Request` or `500 Internal Server Error`
+
+```json
+{
+  "success": false,
+  "message": "Failed to process credit note webhook",
+  "error": "Credit note record not found for request: REQ-2025-12-0001"
+}
+```
+
+---
+
+## 5. Payload Specifications
+
+### 5.1 Data Mapping: RE Workflow → DMS
+
+When RE Workflow System sends data to DMS, it includes:
+
+| RE Workflow Field | DMS Receives | Notes |
+|-------------------|--------------|-------|
+| `requestNumber` | `request_number` | Direct mapping |
+| `dealerCode` | `dealer_code` | Direct mapping |
+| `dealerName` | `dealer_name` | Direct mapping |
+| `activityName` | `activity_name` | From claim details |
+| `activityDescription` | `activity_description` | From claim details |
+| `claimAmount` | `claim_amount` | Total claim amount |
+| `ioNumber` | `io_number` | If available |
+
+### 5.2 Data Mapping: DMS → RE Workflow
+
+When DMS sends webhook, RE Workflow System stores:
+
+| DMS Webhook Field | RE Workflow Database Field | Table |
+|-------------------|---------------------------|-------|
+| `document_no` | `invoice_number` / `credit_note_number` | `claim_invoices` / `claim_credit_notes` |
+| `document_date` | `invoice_date` / `credit_note_date` | `claim_invoices` / `claim_credit_notes` |
+| `total_amount` | `invoice_amount` / `credit_note_amount` | `claim_invoices` / `claim_credit_notes` |
+| `invoice_file_path` | `invoice_file_path` | `claim_invoices` |
+| `credit_note_file_path` | `credit_note_file_path` | `claim_credit_notes` |
+| `irn_no` | Stored in `description` field | Both tables |
+| `sap_credit_note_no` | `sap_document_number` | `claim_credit_notes` |
+| `item_code_no` | Stored in `description` field | Both tables |
+| `hsn_sac_code` | Stored in `description` field | Both tables |
+| GST amounts | Stored in `description` field | Both tables |
+| `credit_type` | Stored in `description` field | `claim_credit_notes` |
+
+### 5.3 GST Calculation Logic
+
+**Intra-State (Same State):**
+- CGST: Applied (e.g., 9%)
+- SGST: Applied (e.g., 9%)
+- IGST: 0%
+
+**Inter-State (Different State):**
+- CGST: 0%
+- SGST: 0%
+- IGST: Applied (e.g., 18%)
+
+**Total Amount Calculation:**
+```
+total_amount = claim_amount + cgst_amount + sgst_amount + igst_amount
+```
+
+---
+
+## 6. Error Handling
+
+### 6.1 Common Error Scenarios
+
+| Error | Status Code | Description | Solution |
+|-------|-------------|-------------|----------|
+| Invalid Signature | 401 | Webhook signature validation failed | Check `DMS_WEBHOOK_SECRET` and signature generation |
+| Missing Required Field | 400 | Required field is missing in payload | Ensure all required fields are included |
+| Request Not Found | 400 | Request number doesn't exist in system | Verify request number matches original request |
+| Invoice Not Found | 400 | Invoice record not found for request | Ensure invoice was created before webhook |
+| Credit Note Not Found | 400 | Credit note record not found for request | Ensure credit note was created before webhook |
+| Database Error | 500 | Internal database error | Check database connection and logs |
+
+### 6.2 Retry Logic
+
+DMS should implement retry logic for failed webhook deliveries:
+
+- **Initial Retry:** After 1 minute
+- **Second Retry:** After 5 minutes
+- **Third Retry:** After 15 minutes
+- **Final Retry:** After 1 hour
+
+**Maximum Retries:** 4 attempts
+
+**Retry Conditions:**
+- HTTP 5xx errors (server errors)
+- Network timeouts
+- Connection failures
+
+**Do NOT Retry:**
+- HTTP 400 errors (client errors - invalid payload)
+- HTTP 401 errors (authentication errors)
+
+### 6.3 Idempotency
+
+Webhooks should be idempotent. If DMS sends the same webhook multiple times:
+- RE Workflow System will update the record with the latest data
+- No duplicate records will be created
+- Status will be updated to reflect the latest state
+
+---
+
+## 7. Testing
+
+### 7.1 Test Invoice Webhook
+
+```bash
+curl -X POST "http://localhost:5000/api/v1/webhooks/dms/invoice" \
+  -H "Content-Type: application/json" \
+  -H "X-DMS-Signature: <calculated-signature>" \
+  -d '{
+    "request_number": "REQ-2025-12-0001",
+    "document_no": "EINV-TEST-001",
+    "document_type": "E-INVOICE",
+    "document_date": "2025-12-17T10:30:00.000Z",
+    "dealer_code": "DLR001",
+    "dealer_name": "Test Dealer",
+    "activity_name": "Test Activity",
+    "activity_description": "Test Description",
+    "claim_amount": 100000.00,
+    "io_number": "IO-TEST-001",
+    "item_code_no": "ITEM-001",
+    "hsn_sac_code": "998314",
+    "cgst_percentage": 9.0,
+    "sgst_percentage": 9.0,
+    "igst_percentage": 0.0,
+    "cgst_amount": 9000.00,
+    "sgst_amount": 9000.00,
+    "igst_amount": 0.00,
+    "total_amount": 118000.00,
+    "irn_no": "IRN123456789012345678901234567890123456789012345678901234567890",
+    "invoice_file_path": "https://dms.example.com/invoices/EINV-TEST-001.pdf",
+    "timestamp": "2025-12-17T10:30:00.000Z"
+  }'
+```
+
+### 7.2 Test Credit Note Webhook
+
+```bash
+curl -X POST "http://localhost:5000/api/v1/webhooks/dms/credit-note" \
+  -H "Content-Type: application/json" \
+  -H "X-DMS-Signature: <calculated-signature>" \
+  -d '{
+    "request_number": "REQ-2025-12-0001",
+    "document_no": "CN-TEST-001",
+    "document_type": "CREDIT_NOTE",
+    "document_date": "2025-12-17T11:00:00.000Z",
+    "dealer_code": "DLR001",
+    "dealer_name": "Test Dealer",
+    "activity_name": "Test Activity",
+    "activity_description": "Test Description",
+    "claim_amount": 100000.00,
+    "io_number": "IO-TEST-001",
+    "item_code_no": "ITEM-001",
+    "hsn_sac_code": "998314",
+    "cgst_percentage": 9.0,
+    "sgst_percentage": 9.0,
+    "igst_percentage": 0.0,
+    "cgst_amount": 9000.00,
+    "sgst_amount": 9000.00,
+    "igst_amount": 0.00,
+    "total_amount": 118000.00,
+    "credit_type": "GST",
+    "irn_no": "IRN987654321098765432109876543210987654321098765432109876543210",
+    "sap_credit_note_no": "SAP-CN-TEST-001",
+    "credit_note_file_path": "https://dms.example.com/credit-notes/CN-TEST-001.pdf",
+    "timestamp": "2025-12-17T11:00:00.000Z"
+  }'
+```
+
+### 7.3 Signature Calculation (Node.js Example)
+
+```javascript
+const crypto = require('crypto');
+
+function calculateSignature(payload, secret) {
+  const body = JSON.stringify(payload);
+  return crypto
+    .createHmac('sha256', secret)
+    .update(body)
+    .digest('hex');
+}
+
+const payload = { /* webhook payload */ };
+const secret = process.env.DMS_WEBHOOK_SECRET;
+const signature = calculateSignature(payload, secret);
+
+// Use in header: X-DMS-Signature: <signature>
+```
+
+---
+
+## 8. Integration Checklist
+
+### 8.1 DMS Team Checklist
+
+- [ ] Configure webhook URLs in DMS system
+- [ ] Set up `DMS_WEBHOOK_SECRET` (shared secret)
+- [ ] Implement signature generation (HMAC-SHA256)
+- [ ] Test webhook delivery to RE Workflow endpoints
+- [ ] Implement retry logic for failed deliveries
+- [ ] Set up monitoring/alerting for webhook failures
+- [ ] Document webhook payload structure
+- [ ] Coordinate with RE Workflow team for testing
+
+### 8.2 RE Workflow Team Checklist
+
+- [ ] Configure `DMS_WEBHOOK_SECRET` in environment variables
+- [ ] Deploy webhook endpoints to UAT/Production
+- [ ] Test webhook endpoints with sample payloads
+- [ ] Verify database updates after webhook processing
+- [ ] Set up monitoring/alerting for webhook failures
+- [ ] Document webhook endpoints for DMS team
+- [ ] Coordinate with DMS team for integration testing
+
+---
+
+## 9. Support & Troubleshooting
+
+### 9.1 Logs
+
+RE Workflow System logs webhook processing:
+
+- **Success:** `[DMSWebhook] Invoice webhook processed successfully`
+- **Error:** `[DMSWebhook] Error processing invoice webhook: <error>`
+- **Validation:** `[DMSWebhook] Invalid webhook signature`
+
+### 9.2 Common Issues
+
+**Issue: Webhook signature validation fails**
+- Verify `DMS_WEBHOOK_SECRET` matches in both systems
+- Check signature calculation method (HMAC-SHA256)
+- Ensure request body is JSON stringified correctly
+
+**Issue: Request not found**
+- Verify `request_number` matches the original request
+- Check if request exists in RE Workflow database
+- Ensure request was created before webhook is sent
+
+**Issue: Invoice/Credit Note record not found**
+- Verify invoice/credit note was created in RE Workflow
+- Check if webhook is sent before record creation
+- Review workflow step sequence
+
+---
+
+## 10. Environment Configuration
+
+### 10.1 Environment Variables
+
+Add to RE Workflow System `.env` file:
+
+```env
+# DMS Webhook Configuration
+DMS_WEBHOOK_SECRET=your_shared_secret_key_here
+```
+
+### 10.2 Webhook URLs by Environment
+
+| Environment | Invoice Webhook URL | Credit Note Webhook URL |
+|-------------|---------------------|-------------------------|
+| Development | `http://localhost:5000/api/v1/webhooks/dms/invoice` | `http://localhost:5000/api/v1/webhooks/dms/credit-note` |
+| UAT | `https://reflow-uat.{{APP_DOMAIN}}/api/v1/webhooks/dms/invoice` | `https://reflow-uat.{{APP_DOMAIN}}/api/v1/webhooks/dms/credit-note` |
+| Production | `https://reflow.{{APP_DOMAIN}}/api/v1/webhooks/dms/invoice` | `https://reflow.{{APP_DOMAIN}}/api/v1/webhooks/dms/credit-note` |
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** December 2024  
+**Maintained By:** RE Workflow Development Team
+

docs/ERD.mermaid

@@ -0,0 +1,507 @@
+erDiagram
+  users ||--o{ workflow_requests : initiates
+  users ||--o{ approval_levels : approves
+  users ||--o{ participants : participates
+  users ||--o{ work_notes : posts
+  users ||--o{ documents : uploads
+  users ||--o{ activities : performs
+  users ||--o{ notifications : receives
+  users ||--o{ user_sessions : has
+  workflow_requests ||--|{ approval_levels : has
+  workflow_requests ||--o{ participants : involves
+  workflow_requests ||--o{ documents : contains
+  workflow_requests ||--o{ work_notes : has
+  workflow_requests ||--o{ activities : logs
+  workflow_requests ||--o{ tat_tracking : monitors
+  workflow_requests ||--o{ notifications : triggers
+  workflow_requests ||--|| conclusion_remarks : concludes
+  workflow_requests ||--|| dealer_claim_details : claim_details
+  workflow_requests ||--|| dealer_proposal_details : proposal_details
+  dealer_proposal_details ||--o{ dealer_proposal_cost_items : cost_items
+  workflow_requests ||--|| dealer_completion_details : completion_details
+  workflow_requests ||--|| internal_orders : internal_order
+  workflow_requests ||--|| claim_budget_tracking : budget_tracking
+  workflow_requests ||--|| claim_invoices : claim_invoice
+  workflow_requests ||--|| claim_credit_notes : claim_credit_note
+  work_notes ||--o{ work_note_attachments : has
+  notifications ||--o{ email_logs : sends
+  notifications ||--o{ sms_logs : sends
+  workflow_requests ||--o{ report_cache : caches
+  workflow_requests ||--o{ audit_logs : audits
+  workflow_requests ||--o{ workflow_templates : templates
+  users ||--o{ system_settings : updates
+
+  users {
+    uuid user_id PK
+    varchar employee_id
+    varchar okta_sub
+    varchar email
+    varchar first_name
+    varchar last_name
+    varchar display_name
+    varchar department
+    varchar designation
+    varchar phone
+    varchar manager
+    varchar second_email
+    text job_title
+    varchar employee_number
+    varchar postal_address
+    varchar mobile_phone
+    jsonb ad_groups
+    jsonb location
+    boolean is_active
+    enum role
+    timestamp last_login
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  workflow_requests {
+    uuid request_id PK
+    varchar request_number
+    uuid initiator_id FK
+    varchar template_type
+    varchar title
+    text description
+    enum priority
+    enum status
+    integer current_level
+    integer total_levels
+    decimal total_tat_hours
+    timestamp submission_date
+    timestamp closure_date
+    text conclusion_remark
+    text ai_generated_conclusion
+    boolean is_draft
+    boolean is_deleted
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  approval_levels {
+    uuid level_id PK
+    uuid request_id FK
+    integer level_number
+    varchar level_name
+    uuid approver_id FK
+    varchar approver_email
+    varchar approver_name
+    decimal tat_hours
+    integer tat_days
+    enum status
+    timestamp level_start_time
+    timestamp level_end_time
+    timestamp action_date
+    text comments
+    text rejection_reason
+    boolean is_final_approver
+    decimal elapsed_hours
+    decimal remaining_hours
+    decimal tat_percentage_used
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  participants {
+    uuid participant_id PK
+    uuid request_id FK
+    uuid user_id FK
+    varchar user_email
+    varchar user_name
+    enum participant_type
+    boolean can_comment
+    boolean can_view_documents
+    boolean can_download_documents
+    boolean notification_enabled
+    uuid added_by FK
+    timestamp added_at
+    boolean is_active
+  }
+
+  documents {
+    uuid document_id PK
+    uuid request_id FK
+    uuid uploaded_by FK
+    varchar file_name
+    varchar original_file_name
+    varchar file_type
+    varchar file_extension
+    bigint file_size
+    varchar file_path
+    varchar storage_url
+    varchar mime_type
+    varchar checksum
+    boolean is_google_doc
+    varchar google_doc_url
+    enum category
+    integer version
+    uuid parent_document_id
+    boolean is_deleted
+    integer download_count
+    timestamp uploaded_at
+  }
+
+  work_notes {
+    uuid note_id PK
+    uuid request_id FK
+    uuid user_id FK
+    varchar user_name
+    varchar user_role
+    text message
+    varchar message_type
+    boolean is_priority
+    boolean has_attachment
+    uuid parent_note_id
+    uuid[] mentioned_users
+    jsonb reactions
+    boolean is_edited
+    boolean is_deleted
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  work_note_attachments {
+    uuid attachment_id PK
+    uuid note_id FK
+    varchar file_name
+    varchar file_type
+    bigint file_size
+    varchar file_path
+    varchar storage_url
+    boolean is_downloadable
+    integer download_count
+    timestamp uploaded_at
+  }
+
+  activities {
+    uuid activity_id PK
+    uuid request_id FK
+    uuid user_id FK
+    varchar user_name
+    varchar activity_type
+    text activity_description
+    varchar activity_category
+    varchar severity
+    jsonb metadata
+    boolean is_system_event
+    varchar ip_address
+    text user_agent
+    timestamp created_at
+  }
+
+  notifications {
+    uuid notification_id PK
+    uuid user_id FK
+    uuid request_id FK
+    varchar notification_type
+    varchar title
+    text message
+    boolean is_read
+    enum priority
+    varchar action_url
+    boolean action_required
+    jsonb metadata
+    varchar[] sent_via
+    boolean email_sent
+    boolean sms_sent
+    boolean push_sent
+    timestamp read_at
+    timestamp expires_at
+    timestamp created_at
+  }
+
+  tat_tracking {
+    uuid tracking_id PK
+    uuid request_id FK
+    uuid level_id FK
+    varchar tracking_type
+    enum tat_status
+    decimal total_tat_hours
+    decimal elapsed_hours
+    decimal remaining_hours
+    decimal percentage_used
+    boolean threshold_50_breached
+    timestamp threshold_50_alerted_at
+    boolean threshold_80_breached
+    timestamp threshold_80_alerted_at
+    boolean threshold_100_breached
+    timestamp threshold_100_alerted_at
+    integer alert_count
+    timestamp last_calculated_at
+  }
+
+  conclusion_remarks {
+    uuid conclusion_id PK
+    uuid request_id FK
+    text ai_generated_remark
+    varchar ai_model_used
+    decimal ai_confidence_score
+    text final_remark
+    uuid edited_by FK
+    boolean is_edited
+    integer edit_count
+    jsonb approval_summary
+    jsonb document_summary
+    text[] key_discussion_points
+    timestamp generated_at
+    timestamp finalized_at
+  }
+
+  audit_logs {
+    uuid audit_id PK
+    uuid user_id FK
+    varchar entity_type
+    uuid entity_id
+    varchar action
+    varchar action_category
+    jsonb old_values
+    jsonb new_values
+    text changes_summary
+    varchar ip_address
+    text user_agent
+    varchar session_id
+    varchar request_method
+    varchar request_url
+    integer response_status
+    integer execution_time_ms
+    timestamp created_at
+  }
+
+  user_sessions {
+    uuid session_id PK
+    uuid user_id FK
+    varchar session_token
+    varchar refresh_token
+    varchar ip_address
+    text user_agent
+    varchar device_type
+    varchar browser
+    varchar os
+    timestamp login_at
+    timestamp last_activity_at
+    timestamp logout_at
+    timestamp expires_at
+    boolean is_active
+    varchar logout_reason
+  }
+
+  email_logs {
+    uuid email_log_id PK
+    uuid request_id FK
+    uuid notification_id FK
+    varchar recipient_email
+    uuid recipient_user_id FK
+    text[] cc_emails
+    text[] bcc_emails
+    varchar subject
+    text body
+    varchar email_type
+    varchar status
+    integer send_attempts
+    timestamp sent_at
+    timestamp failed_at
+    text failure_reason
+    timestamp opened_at
+    timestamp clicked_at
+    timestamp created_at
+  }
+
+  sms_logs {
+    uuid sms_log_id PK
+    uuid request_id FK
+    uuid notification_id FK
+    varchar recipient_phone
+    uuid recipient_user_id FK
+    text message
+    varchar sms_type
+    varchar status
+    integer send_attempts
+    timestamp sent_at
+    timestamp delivered_at
+    timestamp failed_at
+    text failure_reason
+    varchar sms_provider
+    varchar sms_provider_message_id
+    decimal cost
+    timestamp created_at
+  }
+
+  system_settings {
+    uuid setting_id PK
+    varchar setting_key
+    text setting_value
+    varchar setting_type
+    varchar setting_category
+    text description
+    boolean is_editable
+    boolean is_sensitive
+    jsonb validation_rules
+    text default_value
+    uuid updated_by FK
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  workflow_templates {
+    uuid template_id PK
+    varchar template_name
+    text template_description
+    varchar template_category
+    jsonb approval_levels_config
+    decimal default_tat_hours
+    boolean is_active
+    integer usage_count
+    uuid created_by FK
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  report_cache {
+    uuid cache_id PK
+    varchar report_type
+    jsonb report_params
+    jsonb report_data
+    uuid generated_by FK
+    timestamp generated_at
+    timestamp expires_at
+    integer access_count
+    timestamp last_accessed_at
+  }
+
+  dealer_claim_details {
+    uuid claim_id PK
+    uuid request_id
+    varchar activity_name
+    varchar activity_type
+    varchar dealer_code
+    varchar dealer_name
+    varchar dealer_email
+    varchar dealer_phone
+    text dealer_address
+    date activity_date
+    varchar location
+    date period_start_date
+    date period_end_date
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  dealer_proposal_details {
+    uuid proposal_id PK
+    uuid request_id
+    string proposal_document_path
+    string proposal_document_url
+    decimal total_estimated_budget
+    string timeline_mode
+    date expected_completion_date
+    int expected_completion_days
+    text dealer_comments
+    date submitted_at
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  dealer_proposal_cost_items {
+    uuid cost_item_id PK
+    uuid proposal_id FK
+    uuid request_id FK
+    string item_description
+    decimal amount
+    int item_order
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  dealer_completion_details {
+    uuid completion_id PK
+    uuid request_id
+    date activity_completion_date
+    int number_of_participants
+    decimal total_closed_expenses
+    date submitted_at
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  dealer_completion_expenses {
+    uuid expense_id PK
+    uuid request_id
+    uuid completion_id
+    string description
+    decimal amount
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  internal_orders {
+    uuid io_id PK
+    uuid request_id
+    string io_number
+    text io_remark
+    decimal io_available_balance
+    decimal io_blocked_amount
+    decimal io_remaining_balance
+    uuid organized_by FK
+    date organized_at
+    string sap_document_number
+    enum status
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  claim_budget_tracking {
+    uuid budget_id PK
+    uuid request_id
+    decimal initial_estimated_budget
+    decimal proposal_estimated_budget
+    date proposal_submitted_at
+    decimal approved_budget
+    date approved_at
+    uuid approved_by FK
+    decimal io_blocked_amount
+    date io_blocked_at
+    decimal closed_expenses
+    date closed_expenses_submitted_at
+    decimal final_claim_amount
+    date final_claim_amount_approved_at
+    uuid final_claim_amount_approved_by FK
+    decimal credit_note_amount
+    date credit_note_issued_at
+    enum budget_status
+    string currency
+    decimal variance_amount
+    decimal variance_percentage
+    uuid last_modified_by FK
+    date last_modified_at
+    text modification_reason
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  claim_invoices {
+    uuid invoice_id PK
+    uuid request_id
+    string invoice_number
+    date invoice_date
+    string dms_number
+    decimal amount
+    string status
+    text description
+    timestamp created_at
+    timestamp updated_at
+  }
+
+  claim_credit_notes {
+    uuid credit_note_id PK
+    uuid request_id
+    string credit_note_number
+    date credit_note_date
+    decimal credit_note_amount
+    string status
+    text reason
+    text description
+    timestamp created_at
+    timestamp updated_at
+  }
+

docs/EXTENSIBLE_WORKFLOW_ARCHITECTURE.md

@@ -0,0 +1,583 @@
+# Extensible Workflow Architecture Plan
+## Supporting Multiple Template Types (Claim Management, Non-Templatized, Future Templates)
+
+## Overview
+
+This document outlines how to design the backend architecture to support:
+1. **Unified Request System**: All requests (templatized, non-templatized, claim management) use the same `workflow_requests` table
+2. **Template Identification**: Distinguish between different workflow types
+3. **Extensibility**: Easy addition of new templates by admins without code changes
+4. **Unified Views**: All requests appear in "My Requests", "Open Requests", etc. automatically
+
+---
+
+## Architecture Principles
+
+### 1. **Single Source of Truth: `workflow_requests` Table**
+
+All requests, regardless of type, are stored in the same table:
+
+```sql
+workflow_requests {
+    request_id UUID PK
+    request_number VARCHAR(20) UK
+    initiator_id UUID FK
+    template_type VARCHAR(20)        -- 'CUSTOM' | 'TEMPLATE' (high-level)
+    workflow_type VARCHAR(50)        -- 'NON_TEMPLATIZED' | 'CLAIM_MANAGEMENT' | 'DEALER_ONBOARDING' | etc.
+    template_id UUID FK (nullable)    -- Reference to workflow_templates if using admin template
+    title VARCHAR(500)
+    description TEXT
+    status workflow_status
+    current_level INTEGER
+    total_levels INTEGER
+    -- ... common fields
+}
+```
+
+**Key Fields:**
+- `template_type`: High-level classification ('CUSTOM' for user-created, 'TEMPLATE' for admin templates)
+- `workflow_type`: Specific workflow identifier (e.g., 'CLAIM_MANAGEMENT', 'NON_TEMPLATIZED')
+- `template_id`: Optional reference to `workflow_templates` table if using an admin-created template
+
+### 2. **Template-Specific Data Storage**
+
+Each workflow type can have its own extension table for type-specific data:
+
+```sql
+-- For Claim Management
+dealer_claim_details {
+    claim_id UUID PK
+    request_id UUID FK -> workflow_requests(request_id)
+    activity_name VARCHAR(500)
+    activity_type VARCHAR(100)
+    dealer_code VARCHAR(50)
+    dealer_name VARCHAR(200)
+    dealer_email VARCHAR(255)
+    dealer_phone VARCHAR(20)
+    dealer_address TEXT
+    activity_date DATE
+    location VARCHAR(255)
+    period_start_date DATE
+    period_end_date DATE
+    estimated_budget DECIMAL(15,2)
+    closed_expenses DECIMAL(15,2)
+    io_number VARCHAR(50)
+    io_blocked_amount DECIMAL(15,2)
+    sap_document_number VARCHAR(100)
+    dms_number VARCHAR(100)
+    e_invoice_number VARCHAR(100)
+    credit_note_number VARCHAR(100)
+    -- ... claim-specific fields
+}
+
+-- For Non-Templatized (if needed)
+non_templatized_details {
+    detail_id UUID PK
+    request_id UUID FK -> workflow_requests(request_id)
+    custom_fields JSONB  -- Flexible storage for any custom data
+    -- ... any specific fields
+}
+
+-- For Future Templates
+-- Each new template can have its own extension table
+```
+
+### 3. **Workflow Templates Table (Admin-Created Templates)**
+
+```sql
+workflow_templates {
+    template_id UUID PK
+    template_name VARCHAR(200)        -- Display name: "Claim Management", "Dealer Onboarding"
+    template_code VARCHAR(50) UK       -- Unique identifier: "CLAIM_MANAGEMENT", "DEALER_ONBOARDING"
+    template_description TEXT
+    template_category VARCHAR(100)     -- "Dealer Operations", "HR", "Finance", etc.
+    workflow_type VARCHAR(50)          -- Maps to workflow_requests.workflow_type
+    approval_levels_config JSONB       -- Step definitions, TAT, roles, etc.
+    default_tat_hours DECIMAL(10,2)
+    form_fields_config JSONB           -- Form field definitions for wizard
+    is_active BOOLEAN
+    is_system_template BOOLEAN         -- True for built-in (Claim Management), False for admin-created
+    created_by UUID FK
+    created_at TIMESTAMP
+    updated_at TIMESTAMP
+}
+```
+
+---
+
+## Database Schema Changes
+
+### Migration: Add Workflow Type Support
+
+```sql
+-- Migration: 20251210-add-workflow-type-support.ts
+
+-- 1. Add workflow_type column to workflow_requests
+ALTER TABLE workflow_requests 
+ADD COLUMN IF NOT EXISTS workflow_type VARCHAR(50) DEFAULT 'NON_TEMPLATIZED';
+
+-- 2. Add template_id column (nullable, for admin templates)
+ALTER TABLE workflow_requests 
+ADD COLUMN IF NOT EXISTS template_id UUID REFERENCES workflow_templates(template_id);
+
+-- 3. Create index for workflow_type
+CREATE INDEX IF NOT EXISTS idx_workflow_requests_workflow_type 
+ON workflow_requests(workflow_type);
+
+-- 4. Create index for template_id
+CREATE INDEX IF NOT EXISTS idx_workflow_requests_template_id 
+ON workflow_requests(template_id);
+
+-- 5. Create dealer_claim_details table
+CREATE TABLE IF NOT EXISTS dealer_claim_details (
+    claim_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    request_id UUID NOT NULL UNIQUE REFERENCES workflow_requests(request_id) ON DELETE CASCADE,
+    activity_name VARCHAR(500) NOT NULL,
+    activity_type VARCHAR(100) NOT NULL,
+    dealer_code VARCHAR(50) NOT NULL,
+    dealer_name VARCHAR(200) NOT NULL,
+    dealer_email VARCHAR(255),
+    dealer_phone VARCHAR(20),
+    dealer_address TEXT,
+    activity_date DATE,
+    location VARCHAR(255),
+    period_start_date DATE,
+    period_end_date DATE,
+    estimated_budget DECIMAL(15,2),
+    closed_expenses DECIMAL(15,2),
+    io_number VARCHAR(50),
+    io_available_balance DECIMAL(15,2),
+    io_blocked_amount DECIMAL(15,2),
+    io_remaining_balance DECIMAL(15,2),
+    sap_document_number VARCHAR(100),
+    dms_number VARCHAR(100),
+    e_invoice_number VARCHAR(100),
+    e_invoice_date DATE,
+    credit_note_number VARCHAR(100),
+    credit_note_date DATE,
+    credit_note_amount DECIMAL(15,2),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_dealer_claim_details_request_id ON dealer_claim_details(request_id);
+CREATE INDEX idx_dealer_claim_details_dealer_code ON dealer_claim_details(dealer_code);
+
+-- 6. Create proposal_details table (Step 1: Dealer Proposal)
+CREATE TABLE IF NOT EXISTS dealer_proposal_details (
+    proposal_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    request_id UUID NOT NULL REFERENCES workflow_requests(request_id) ON DELETE CASCADE,
+    proposal_document_path VARCHAR(500),
+    proposal_document_url VARCHAR(500),
+    cost_breakup JSONB,  -- Array of {description, amount}
+    total_estimated_budget DECIMAL(15,2),
+    timeline_mode VARCHAR(10),  -- 'date' | 'days'
+    expected_completion_date DATE,
+    expected_completion_days INTEGER,
+    dealer_comments TEXT,
+    submitted_at TIMESTAMP WITH TIME ZONE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_dealer_proposal_details_request_id ON dealer_proposal_details(request_id);
+
+-- 7. Create completion_documents table (Step 5: Dealer Completion)
+CREATE TABLE IF NOT EXISTS dealer_completion_details (
+    completion_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    request_id UUID NOT NULL REFERENCES workflow_requests(request_id) ON DELETE CASCADE,
+    activity_completion_date DATE NOT NULL,
+    number_of_participants INTEGER,
+    closed_expenses JSONB,  -- Array of {description, amount}
+    total_closed_expenses DECIMAL(15,2),
+    completion_documents JSONB,  -- Array of document references
+    activity_photos JSONB,  -- Array of photo references
+    submitted_at TIMESTAMP WITH TIME ZONE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_dealer_completion_details_request_id ON dealer_completion_details(request_id);
+```
+
+---
+
+## Model Updates
+
+### 1. Update WorkflowRequest Model
+
+```typescript
+// Re_Backend/src/models/WorkflowRequest.ts
+
+interface WorkflowRequestAttributes {
+  requestId: string;
+  requestNumber: string;
+  initiatorId: string;
+  templateType: 'CUSTOM' | 'TEMPLATE';
+  workflowType: string;  // NEW: 'NON_TEMPLATIZED' | 'CLAIM_MANAGEMENT' | etc.
+  templateId?: string;   // NEW: Reference to workflow_templates
+  title: string;
+  description: string;
+  // ... existing fields
+}
+
+// Add association
+WorkflowRequest.hasOne(DealerClaimDetails, {
+  as: 'claimDetails',
+  foreignKey: 'requestId',
+  sourceKey: 'requestId'
+});
+```
+
+### 2. Create DealerClaimDetails Model
+
+```typescript
+// Re_Backend/src/models/DealerClaimDetails.ts
+
+import { DataTypes, Model } from 'sequelize';
+import { sequelize } from '@config/database';
+import { WorkflowRequest } from './WorkflowRequest';
+
+interface DealerClaimDetailsAttributes {
+  claimId: string;
+  requestId: string;
+  activityName: string;
+  activityType: string;
+  dealerCode: string;
+  dealerName: string;
+  // ... all claim-specific fields
+}
+
+class DealerClaimDetails extends Model<DealerClaimDetailsAttributes> {
+  public claimId!: string;
+  public requestId!: string;
+  // ... fields
+}
+
+DealerClaimDetails.init({
+  claimId: {
+    type: DataTypes.UUID,
+    defaultValue: DataTypes.UUIDV4,
+    primaryKey: true,
+    field: 'claim_id'
+  },
+  requestId: {
+    type: DataTypes.UUID,
+    allowNull: false,
+    unique: true,
+    field: 'request_id',
+    references: {
+      model: 'workflow_requests',
+      key: 'request_id'
+    }
+  },
+  // ... all other fields
+}, {
+  sequelize,
+  modelName: 'DealerClaimDetails',
+  tableName: 'dealer_claim_details',
+  timestamps: true
+});
+
+// Association
+DealerClaimDetails.belongsTo(WorkflowRequest, {
+  as: 'workflowRequest',
+  foreignKey: 'requestId',
+  targetKey: 'requestId'
+});
+
+export { DealerClaimDetails };
+```
+
+---
+
+## Service Layer Pattern
+
+### 1. Template-Aware Service Factory
+
+```typescript
+// Re_Backend/src/services/templateService.factory.ts
+
+import { WorkflowRequest } from '../models/WorkflowRequest';
+import { DealerClaimService } from './dealerClaim.service';
+import { NonTemplatizedService } from './nonTemplatized.service';
+
+export class TemplateServiceFactory {
+  static getService(workflowType: string) {
+    switch (workflowType) {
+      case 'CLAIM_MANAGEMENT':
+        return new DealerClaimService();
+      case 'NON_TEMPLATIZED':
+        return new NonTemplatizedService();
+      default:
+        // For future templates, use a generic service or throw error
+        throw new Error(`Unsupported workflow type: ${workflowType}`);
+    }
+  }
+
+  static async getRequestDetails(requestId: string) {
+    const request = await WorkflowRequest.findByPk(requestId);
+    if (!request) return null;
+
+    const service = this.getService(request.workflowType);
+    return service.getRequestDetails(request);
+  }
+}
+```
+
+### 2. Unified Workflow Service (No Changes Needed)
+
+The existing `WorkflowService.listMyRequests()` and `listOpenForMe()` methods will **automatically** include all request types because they query `workflow_requests` table without filtering by `workflow_type`.
+
+```typescript
+// Existing code works as-is - no changes needed!
+async listMyRequests(userId: string, page: number, limit: number, filters?: {...}) {
+  // This query automatically includes ALL workflow types
+  const requests = await WorkflowRequest.findAll({
+    where: {
+      initiatorId: userId,
+      isDraft: false,
+      // ... filters
+      // NO workflow_type filter - includes everything!
+    }
+  });
+  return requests;
+}
+```
+
+---
+
+## API Endpoints
+
+### 1. Create Claim Management Request
+
+```typescript
+// Re_Backend/src/controllers/dealerClaim.controller.ts
+
+async createClaimRequest(req: AuthenticatedRequest, res: Response) {
+  const userId = req.user?.userId;
+  const {
+    activityName,
+    activityType,
+    dealerCode,
+    // ... claim-specific fields
+  } = req.body;
+
+  // 1. Create workflow request (common)
+  const workflowRequest = await WorkflowRequest.create({
+    initiatorId: userId,
+    templateType: 'CUSTOM',
+    workflowType: 'CLAIM_MANAGEMENT',  // Identify as claim
+    title: `${activityName} - Claim Request`,
+    description: req.body.requestDescription,
+    totalLevels: 8,  // Fixed 8-step workflow
+    // ... other common fields
+  });
+
+  // 2. Create claim-specific details
+  const claimDetails = await DealerClaimDetails.create({
+    requestId: workflowRequest.requestId,
+    activityName,
+    activityType,
+    dealerCode,
+    // ... claim-specific fields
+  });
+
+  // 3. Create approval levels (8 steps)
+  await this.createClaimApprovalLevels(workflowRequest.requestId);
+
+  return ResponseHandler.success(res, {
+    request: workflowRequest,
+    claimDetails
+  });
+}
+```
+
+### 2. Get Request Details (Template-Aware)
+
+```typescript
+async getRequestDetails(req: Request, res: Response) {
+  const { requestId } = req.params;
+  
+  const request = await WorkflowRequest.findByPk(requestId, {
+    include: [
+      { model: User, as: 'initiator' },
+      // Conditionally include template-specific data
+      ...(request.workflowType === 'CLAIM_MANAGEMENT' 
+        ? [{ model: DealerClaimDetails, as: 'claimDetails' }]
+        : [])
+    ]
+  });
+
+  // Use factory to get template-specific service
+  const templateService = TemplateServiceFactory.getService(request.workflowType);
+  const enrichedDetails = await templateService.enrichRequestDetails(request);
+
+  return ResponseHandler.success(res, enrichedDetails);
+}
+```
+
+---
+
+## Frontend Integration
+
+### 1. Request List Views (No Changes Needed)
+
+The existing "My Requests" and "Open Requests" pages will automatically show all request types because the backend doesn't filter by `workflow_type`.
+
+```typescript
+// Frontend: MyRequests.tsx - No changes needed!
+const fetchMyRequests = async () => {
+  const result = await workflowApi.listMyInitiatedWorkflows({
+    page,
+    limit: itemsPerPage
+  });
+  // Returns ALL request types automatically
+};
+```
+
+### 2. Request Detail Page (Template-Aware Rendering)
+
+```typescript
+// Frontend: RequestDetail.tsx
+
+const RequestDetail = ({ requestId }) => {
+  const request = useRequestDetails(requestId);
+  
+  // Render based on workflow type
+  if (request.workflowType === 'CLAIM_MANAGEMENT') {
+    return <ClaimManagementDetail request={request} />;
+  } else if (request.workflowType === 'NON_TEMPLATIZED') {
+    return <NonTemplatizedDetail request={request} />;
+  } else {
+    // Future templates - use generic renderer or template config
+    return <GenericWorkflowDetail request={request} />;
+  }
+};
+```
+
+---
+
+## Adding New Templates (Future)
+
+### Step 1: Admin Creates Template in UI
+
+1. Admin goes to "Template Management" page
+2. Creates new template with:
+   - Template name: "Vendor Payment"
+   - Template code: "VENDOR_PAYMENT"
+   - Approval levels configuration
+   - Form fields configuration
+
+### Step 2: Database Entry Created
+
+```sql
+INSERT INTO workflow_templates (
+  template_name,
+  template_code,
+  workflow_type,
+  approval_levels_config,
+  form_fields_config,
+  is_active,
+  is_system_template
+) VALUES (
+  'Vendor Payment',
+  'VENDOR_PAYMENT',
+  'VENDOR_PAYMENT',
+  '{"levels": [...], "tat": {...}}'::jsonb,
+  '{"fields": [...]}'::jsonb,
+  true,
+  false  -- Admin-created, not system template
+);
+```
+
+### Step 3: Create Extension Table (If Needed)
+
+```sql
+CREATE TABLE vendor_payment_details (
+    payment_id UUID PRIMARY KEY,
+    request_id UUID UNIQUE REFERENCES workflow_requests(request_id),
+    vendor_code VARCHAR(50),
+    invoice_number VARCHAR(100),
+    payment_amount DECIMAL(15,2),
+    -- ... vendor-specific fields
+);
+```
+
+### Step 4: Create Service (Optional - Can Use Generic Service)
+
+```typescript
+// Re_Backend/src/services/vendorPayment.service.ts
+
+export class VendorPaymentService {
+  async getRequestDetails(request: WorkflowRequest) {
+    const paymentDetails = await VendorPaymentDetails.findOne({
+      where: { requestId: request.requestId }
+    });
+    
+    return {
+      ...request.toJSON(),
+      paymentDetails
+    };
+  }
+}
+
+// Update factory
+TemplateServiceFactory.getService(workflowType: string) {
+  switch (workflowType) {
+    case 'VENDOR_PAYMENT':
+      return new VendorPaymentService();
+    // ... existing cases
+  }
+}
+```
+
+### Step 5: Frontend Component (Optional)
+
+```typescript
+// Frontend: components/VendorPaymentDetail.tsx
+
+export function VendorPaymentDetail({ request }) {
+  // Render vendor payment specific UI
+}
+```
+
+---
+
+## Benefits of This Architecture
+
+1. **Unified Data Model**: All requests in one table, easy to query
+2. **Automatic Inclusion**: My Requests/Open Requests show all types automatically
+3. **Extensibility**: Add new templates without modifying existing code
+4. **Type Safety**: Template-specific data in separate tables
+5. **Flexibility**: Support both system templates and admin-created templates
+6. **Backward Compatible**: Existing non-templatized requests continue to work
+
+---
+
+## Migration Strategy
+
+1. **Phase 1**: Add `workflow_type` column, set default to 'NON_TEMPLATIZED' for existing requests
+2. **Phase 2**: Create `dealer_claim_details` table and models
+3. **Phase 3**: Update claim management creation flow to use new structure
+4. **Phase 4**: Update request detail endpoints to be template-aware
+5. **Phase 5**: Frontend updates (if needed) for template-specific rendering
+
+---
+
+## Summary
+
+- **All requests** use `workflow_requests` table
+- **Template identification** via `workflow_type` field
+- **Template-specific data** in extension tables (e.g., `dealer_claim_details`)
+- **Unified views** automatically include all types
+- **Future templates** can be added by admins without code changes
+- **Existing functionality** remains unchanged
+
+This architecture ensures that:
+- ✅ Claim Management requests appear in My Requests/Open Requests
+- ✅ Non-templatized requests continue to work
+- ✅ Future templates can be added easily
+- ✅ No code duplication
+- ✅ Single source of truth for all requests
+

docs/FRESH_DATABASE_SETUP.md

@@ -157,7 +157,7 @@ npm run seed:config
 ```bash
 # Edit the script
 nano scripts/assign-admin-user.sql
-# Change: YOUR_EMAIL@royalenfield.com
+# Change: YOUR_EMAIL@{{APP_DOMAIN}}
 
 # Run it
 psql -d royal_enfield_workflow -f scripts/assign-admin-user.sql
@@ -170,7 +170,7 @@ psql -d royal_enfield_workflow
 
 UPDATE users 
 SET role = 'ADMIN'
-WHERE email = 'your-email@royalenfield.com';
+WHERE email = 'your-email@{{APP_DOMAIN}}';
 
 -- Verify
 SELECT email, role FROM users WHERE role = 'ADMIN';
@@ -188,7 +188,7 @@ psql -d royal_enfield_workflow -c "\dt"
 psql -d royal_enfield_workflow -c "\dT+ user_role_enum"
 
 # Check your user
-psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your-email@royalenfield.com';"
+psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your-email@{{APP_DOMAIN}}';"
 ```
 
 ---
@@ -241,13 +241,13 @@ Expected output:
 ```sql
 -- Single user
 UPDATE users SET role = 'MANAGEMENT' 
-WHERE email = 'manager@royalenfield.com';
+WHERE email = 'manager@{{APP_DOMAIN}}';
 
 -- Multiple users
 UPDATE users SET role = 'MANAGEMENT'
 WHERE email IN (
-  'manager1@royalenfield.com',
-  'manager2@royalenfield.com'
+  'manager1@{{APP_DOMAIN}}',
+  'manager2@{{APP_DOMAIN}}'
 );
 
 -- By department
@@ -260,13 +260,13 @@ WHERE department = 'Management' AND is_active = true;
 ```sql
 -- Single user
 UPDATE users SET role = 'ADMIN'
-WHERE email = 'admin@royalenfield.com';
+WHERE email = 'admin@{{APP_DOMAIN}}';
 
 -- Multiple admins
 UPDATE users SET role = 'ADMIN'
 WHERE email IN (
-  'admin1@royalenfield.com',
-  'admin2@royalenfield.com'
+  'admin1@{{APP_DOMAIN}}',
+  'admin2@{{APP_DOMAIN}}'
 );
 
 -- By department
@@ -331,7 +331,7 @@ SELECT
   mobile_phone,
   array_length(ad_groups, 1) as ad_group_count
 FROM users 
-WHERE email = 'your-email@royalenfield.com';
+WHERE email = 'your-email@{{APP_DOMAIN}}';
 ```
 
 ---
@@ -344,7 +344,7 @@ WHERE email = 'your-email@royalenfield.com';
 curl -X POST http://localhost:5000/api/v1/auth/okta/callback \
   -H "Content-Type: application/json" \
   -d '{
-    "email": "test@royalenfield.com",
+    "email": "test@{{APP_DOMAIN}}",
     "displayName": "Test User",
     "oktaSub": "test-sub-123"
   }'
@@ -353,14 +353,14 @@ curl -X POST http://localhost:5000/api/v1/auth/okta/callback \
 ### 2. Check User Created with Default Role
 
 ```sql
-SELECT email, role FROM users WHERE email = 'test@royalenfield.com';
+SELECT email, role FROM users WHERE email = 'test@{{APP_DOMAIN}}';
 -- Expected: role = 'USER'
 ```
 
 ### 3. Update to ADMIN
 
 ```sql
-UPDATE users SET role = 'ADMIN' WHERE email = 'test@royalenfield.com';
+UPDATE users SET role = 'ADMIN' WHERE email = 'test@{{APP_DOMAIN}}';
 ```
 
 ### 4. Verify API Access
@@ -369,7 +369,7 @@ UPDATE users SET role = 'ADMIN' WHERE email = 'test@royalenfield.com';
 # Login and get token
 curl -X POST http://localhost:5000/api/v1/auth/login \
   -H "Content-Type: application/json" \
-  -d '{"email": "test@royalenfield.com", ...}'
+  -d '{"email": "test@{{APP_DOMAIN}}", ...}'
 
 # Try admin endpoint (should work if ADMIN role)
 curl http://localhost:5000/api/v1/admin/configurations \
@@ -449,7 +449,7 @@ npm run migrate
 
 ```sql
 -- Check if user exists
-SELECT * FROM users WHERE email = 'your-email@royalenfield.com';
+SELECT * FROM users WHERE email = 'your-email@{{APP_DOMAIN}}';
 
 -- Check Okta sub
 SELECT * FROM users WHERE okta_sub = 'your-okta-sub';
@@ -459,7 +459,7 @@ SELECT * FROM users WHERE okta_sub = 'your-okta-sub';
 
 ```sql
 -- Verify role
-SELECT email, role, is_active FROM users WHERE email = 'your-email@royalenfield.com';
+SELECT email, role, is_active FROM users WHERE email = 'your-email@{{APP_DOMAIN}}';
 
 -- Check role enum
 \dT+ user_role_enum

docs/GCP_PRODUCTION_SETUP.md

@@ -0,0 +1,669 @@
+# GCP Cloud Storage - Production Setup Guide
+
+## Overview
+
+This guide provides step-by-step instructions for setting up Google Cloud Storage (GCS) for the **Royal Enfield Workflow System** in **Production** environment. This document focuses specifically on production deployment requirements, folder structure, and environment configuration.
+
+---
+
+## Table of Contents
+
+1. [Production Requirements](#1-production-requirements)
+2. [GCP Bucket Configuration](#2-gcp-bucket-configuration)
+3. [Service Account Setup](#3-service-account-setup)
+4. [Environment Variables Configuration](#4-environment-variables-configuration)
+5. [Folder Structure in GCS](#5-folder-structure-in-gcs)
+6. [Security & Access Control](#6-security--access-control)
+7. [CORS Configuration](#7-cors-configuration)
+8. [Lifecycle Management](#8-lifecycle-management)
+9. [Monitoring & Alerts](#9-monitoring--alerts)
+10. [Verification & Testing](#10-verification--testing)
+
+---
+
+## 1. Production Requirements
+
+### 1.1 Application Details
+
+| Item | Production Value |
+|------|------------------|
+| **Application** | Royal Enfield Workflow System |
+| **Environment** | Production |
+| **Domain** | `https://reflow.{{APP_DOMAIN}}` |
+| **Purpose** | Store workflow documents, attachments, invoices, and credit notes |
+| **Storage Type** | Google Cloud Storage (GCS) |
+| **Region** | `asia-south1` (Mumbai) |
+
+### 1.2 Storage Requirements
+
+The application stores:
+- **Workflow Documents**: Initial documents uploaded during request creation
+- **Work Note Attachments**: Files attached during approval workflow
+- **Invoice Files**: Generated e-invoice PDFs
+- **Credit Note Files**: Generated credit note PDFs
+- **Dealer Claim Documents**: Proposal documents, completion documents
+
+---
+
+## 2. GCP Bucket Configuration
+
+### 2.1 Production Bucket Settings
+
+| Setting | Production Value |
+|---------|------------------|
+| **Bucket Name** | `reflow-documents-prod` |
+| **Location Type** | Region |
+| **Region** | `asia-south1` (Mumbai) |
+| **Storage Class** | Standard (for active files) |
+| **Access Control** | Uniform bucket-level access |
+| **Public Access Prevention** | Enforced (Block all public access) |
+| **Versioning** | Enabled (for recovery) |
+| **Lifecycle Rules** | Configured (see section 8) |
+
+### 2.2 Create Production Bucket
+
+```bash
+# Create production bucket
+gcloud storage buckets create gs://reflow-documents-prod \
+  --project=re-platform-workflow-dealer \
+  --location=asia-south1 \
+  --uniform-bucket-level-access \
+  --public-access-prevention
+
+# Enable versioning
+gcloud storage buckets update gs://reflow-documents-prod \
+  --versioning
+
+# Verify bucket creation
+gcloud storage buckets describe gs://reflow-documents-prod
+```
+
+### 2.3 Bucket Naming Convention
+
+| Environment | Bucket Name | Purpose |
+|-------------|-------------|---------|
+| Development | `reflow-documents-dev` | Development testing |
+| UAT | `reflow-documents-uat` | User acceptance testing |
+| Production | `reflow-documents-prod` | Live production data |
+
+---
+
+## 3. Service Account Setup
+
+### 3.1 Create Production Service Account
+
+```bash
+# Create service account for production
+gcloud iam service-accounts create reflow-storage-prod-sa \
+  --display-name="RE Workflow Production Storage Service Account" \
+  --description="Service account for production file storage operations" \
+  --project=re-platform-workflow-dealer
+```
+
+### 3.2 Assign Required Roles
+
+The service account needs the following IAM roles:
+
+| Role | Purpose | Required For |
+|------|---------|--------------|
+| `roles/storage.objectAdmin` | Full control over objects | Upload, delete, update files |
+| `roles/storage.objectViewer` | Read objects | Download and preview files |
+| `roles/storage.legacyBucketReader` | Read bucket metadata | List files and check bucket status |
+
+```bash
+# Grant Storage Object Admin role
+gcloud projects add-iam-policy-binding re-platform-workflow-dealer \
+  --member="serviceAccount:reflow-storage-prod-sa@re-platform-workflow-dealer.iam.gserviceaccount.com" \
+  --role="roles/storage.objectAdmin"
+
+# Grant Storage Object Viewer role (for read operations)
+gcloud projects add-iam-policy-binding re-platform-workflow-dealer \
+  --member="serviceAccount:reflow-storage-prod-sa@re-platform-workflow-dealer.iam.gserviceaccount.com" \
+  --role="roles/storage.objectViewer"
+```
+
+### 3.3 Generate Service Account Key
+
+```bash
+# Generate JSON key file for production
+gcloud iam service-accounts keys create ./config/gcp-key-prod.json \
+  --iam-account=reflow-storage-prod-sa@re-platform-workflow-dealer.iam.gserviceaccount.com \
+  --project=re-platform-workflow-dealer
+```
+
+⚠️ **Security Warning:**
+- Store the key file securely (not in Git)
+- Use secure file transfer methods
+- Rotate keys periodically (every 90 days recommended)
+- Restrict file permissions: `chmod 600 ./config/gcp-key-prod.json`
+
+---
+
+## 4. Environment Variables Configuration
+
+### 4.1 Required Environment Variables
+
+Add the following environment variables to your production `.env` file:
+
+```env
+# ============================================
+# Google Cloud Storage (GCP) Configuration
+# ============================================
+# GCP Project ID - Must match the project_id in your service account key file
+GCP_PROJECT_ID=re-platform-workflow-dealer
+
+# GCP Bucket Name - Production bucket name
+GCP_BUCKET_NAME=reflow-documents-prod
+
+# GCP Service Account Key File Path
+# Can be relative to project root or absolute path
+# Example: ./config/gcp-key-prod.json
+# Example: /etc/reflow/config/gcp-key-prod.json
+GCP_KEY_FILE=./config/gcp-key-prod.json
+```
+
+### 4.2 Environment Variable Details
+
+| Variable | Description | Example Value | Required |
+|----------|-------------|---------------|----------|
+| `GCP_PROJECT_ID` | Your GCP project ID. Must match the `project_id` field in the service account JSON key file. | `re-platform-workflow-dealer` | ✅ Yes |
+| `GCP_BUCKET_NAME` | Name of the GCS bucket where files will be stored. Must exist in your GCP project. | `reflow-documents-prod` | ✅ Yes |
+| `GCP_KEY_FILE` | Path to the service account JSON key file. Can be relative (from project root) or absolute path. | `./config/gcp-key-prod.json` | ✅ Yes |
+
+### 4.3 File Path Configuration
+
+**Relative Path (Recommended for Development):**
+```env
+GCP_KEY_FILE=./config/gcp-key-prod.json
+```
+
+**Absolute Path (Recommended for Production):**
+```env
+GCP_KEY_FILE=/etc/reflow/config/gcp-key-prod.json
+```
+
+### 4.4 Verification
+
+After setting environment variables, verify the configuration:
+
+```bash
+# Check if variables are set
+echo $GCP_PROJECT_ID
+echo $GCP_BUCKET_NAME
+echo $GCP_KEY_FILE
+
+# Verify key file exists
+ls -la $GCP_KEY_FILE
+
+# Verify key file permissions (should be 600)
+stat -c "%a %n" $GCP_KEY_FILE
+```
+
+---
+
+## 5. Folder Structure in GCS
+
+### 5.1 Production Bucket Structure
+
+```
+reflow-documents-prod/
+│
+├── requests/                          # All workflow-related files
+│   ├── REQ-2025-12-0001/             # Request-specific folder
+│   │   ├── documents/                 # Initial request documents
+│   │   │   ├── 1701234567890-abc123-proposal.pdf
+│   │   │   ├── 1701234567891-def456-specification.docx
+│   │   │   └── 1701234567892-ghi789-budget.xlsx
+│   │   │
+│   │   ├── attachments/                # Work note attachments
+│   │   │   ├── 1701234567893-jkl012-approval_note.pdf
+│   │   │   ├── 1701234567894-mno345-signature.png
+│   │   │   └── 1701234567895-pqr678-supporting_doc.pdf
+│   │   │
+│   │   ├── invoices/                   # Generated invoice files
+│   │   │   └── 1701234567896-stu901-invoice_REQ-2025-12-0001.pdf
+│   │   │
+│   │   └── credit-notes/               # Generated credit note files
+│   │       └── 1701234567897-vwx234-credit_note_REQ-2025-12-0001.pdf
+│   │
+│   ├── REQ-2025-12-0002/
+│   │   ├── documents/
+│   │   ├── attachments/
+│   │   ├── invoices/
+│   │   └── credit-notes/
+│   │
+│   └── REQ-2025-12-0003/
+│       └── ...
+│
+└── temp/                               # Temporary uploads (auto-deleted after 24h)
+    └── (temporary files before processing)
+```
+
+### 5.2 File Path Patterns
+
+| File Type | Path Pattern | Example |
+|-----------|--------------|---------|
+| **Documents** | `requests/{requestNumber}/documents/{timestamp}-{hash}-{filename}` | `requests/REQ-2025-12-0001/documents/1701234567890-abc123-proposal.pdf` |
+| **Attachments** | `requests/{requestNumber}/attachments/{timestamp}-{hash}-{filename}` | `requests/REQ-2025-12-0001/attachments/1701234567893-jkl012-approval_note.pdf` |
+| **Invoices** | `requests/{requestNumber}/invoices/{timestamp}-{hash}-{filename}` | `requests/REQ-2025-12-0001/invoices/1701234567896-stu901-invoice_REQ-2025-12-0001.pdf` |
+| **Credit Notes** | `requests/{requestNumber}/credit-notes/{timestamp}-{hash}-{filename}` | `requests/REQ-2025-12-0001/credit-notes/1701234567897-vwx234-credit_note_REQ-2025-12-0001.pdf` |
+
+### 5.3 File Naming Convention
+
+Files are automatically renamed with the following pattern:
+```
+{timestamp}-{randomHash}-{sanitizedOriginalName}
+```
+
+**Example:**
+- Original: `My Proposal Document (Final).pdf`
+- Stored: `1701234567890-abc123-My_Proposal_Document__Final_.pdf`
+
+**Benefits:**
+- Prevents filename conflicts
+- Maintains original filename for reference
+- Ensures unique file identifiers
+- Safe for URL encoding
+
+---
+
+## 6. Security & Access Control
+
+### 6.1 Bucket Security Settings
+
+```bash
+# Enforce public access prevention
+gcloud storage buckets update gs://reflow-documents-prod \
+  --public-access-prevention
+
+# Enable uniform bucket-level access
+gcloud storage buckets update gs://reflow-documents-prod \
+  --uniform-bucket-level-access
+```
+
+### 6.2 Access Control Strategy
+
+**Production Approach:**
+- **Private Bucket**: All files are private by default
+- **Signed URLs**: Generate time-limited signed URLs for file access (recommended)
+- **Service Account**: Only service account has direct access
+- **IAM Policies**: Restrict access to specific service accounts only
+
+### 6.3 Signed URL Configuration (Recommended)
+
+For production, use signed URLs instead of public URLs:
+
+```typescript
+// Example: Generate signed URL (valid for 1 hour)
+const [url] = await file.getSignedUrl({
+  action: 'read',
+  expires: Date.now() + 60 * 60 * 1000, // 1 hour
+});
+```
+
+### 6.4 Security Checklist
+
+- [ ] Public access prevention enabled
+- [ ] Uniform bucket-level access enabled
+- [ ] Service account has minimal required permissions
+- [ ] JSON key file stored securely (not in Git)
+- [ ] Key file permissions set to 600
+- [ ] CORS configured for specific domains only
+- [ ] Bucket versioning enabled
+- [ ] Access logging enabled
+- [ ] Signed URLs used for file access (if applicable)
+
+---
+
+## 7. CORS Configuration
+
+### 7.1 Production CORS Policy
+
+Create `cors-config-prod.json`:
+
+```json
+[
+  {
+    "origin": [
+      "https://reflow.{{APP_DOMAIN}}",
+      "https://www.{{APP_DOMAIN}}"
+    ],
+    "method": ["GET", "PUT", "POST", "DELETE", "HEAD", "OPTIONS"],
+    "responseHeader": [
+      "Content-Type",
+      "Content-Disposition",
+      "Content-Length",
+      "Cache-Control",
+      "x-goog-meta-*"
+    ],
+    "maxAgeSeconds": 3600
+  }
+]
+```
+
+### 7.2 Apply CORS Configuration
+
+```bash
+gcloud storage buckets update gs://reflow-documents-prod \
+  --cors-file=cors-config-prod.json
+```
+
+### 7.3 Verify CORS
+
+```bash
+# Check CORS configuration
+gcloud storage buckets describe gs://reflow-documents-prod \
+  --format="value(cors)"
+```
+
+---
+
+## 8. Lifecycle Management
+
+### 8.1 Lifecycle Rules Configuration
+
+Create `lifecycle-config-prod.json`:
+
+```json
+{
+  "lifecycle": {
+    "rule": [
+      {
+        "action": { "type": "Delete" },
+        "condition": {
+          "age": 1,
+          "matchesPrefix": ["temp/"]
+        },
+        "description": "Delete temporary files after 24 hours"
+      },
+      {
+        "action": { "type": "SetStorageClass", "storageClass": "NEARLINE" },
+        "condition": {
+          "age": 90,
+          "matchesPrefix": ["requests/"]
+        },
+        "description": "Move old files to Nearline storage after 90 days"
+      },
+      {
+        "action": { "type": "SetStorageClass", "storageClass": "COLDLINE" },
+        "condition": {
+          "age": 365,
+          "matchesPrefix": ["requests/"]
+        },
+        "description": "Move archived files to Coldline storage after 1 year"
+      }
+    ]
+  }
+}
+```
+
+### 8.2 Apply Lifecycle Rules
+
+```bash
+gcloud storage buckets update gs://reflow-documents-prod \
+  --lifecycle-file=lifecycle-config-prod.json
+```
+
+### 8.3 Lifecycle Rule Benefits
+
+| Rule | Purpose | Cost Savings |
+|------|---------|--------------|
+| Delete temp files | Remove temporary uploads after 24h | Prevents storage bloat |
+| Move to Nearline | Archive files older than 90 days | ~50% cost reduction |
+| Move to Coldline | Archive files older than 1 year | ~70% cost reduction |
+
+---
+
+## 9. Monitoring & Alerts
+
+### 9.1 Enable Access Logging
+
+```bash
+# Create logging bucket (if not exists)
+gcloud storage buckets create gs://reflow-logs-prod \
+  --project=re-platform-workflow-dealer \
+  --location=asia-south1
+
+# Enable access logging
+gcloud storage buckets update gs://reflow-documents-prod \
+  --log-bucket=gs://reflow-logs-prod \
+  --log-object-prefix=reflow-storage-logs/
+```
+
+### 9.2 Set Up Monitoring Alerts
+
+**Recommended Alerts:**
+
+1. **Storage Quota Alert**
+   - Trigger: Storage exceeds 80% of quota
+   - Action: Notify DevOps team
+
+2. **Unusual Access Patterns**
+   - Trigger: Unusual download patterns detected
+   - Action: Security team notification
+
+3. **Failed Access Attempts**
+   - Trigger: Multiple failed authentication attempts
+   - Action: Immediate security alert
+
+4. **High Upload Volume**
+   - Trigger: Upload volume exceeds normal threshold
+   - Action: Performance team notification
+
+### 9.3 Cost Monitoring
+
+Monitor storage costs via:
+- GCP Console → Billing → Reports
+- Set up budget alerts at 50%, 75%, 90% of monthly budget
+- Review storage class usage (Standard vs Nearline vs Coldline)
+
+---
+
+## 10. Verification & Testing
+
+### 10.1 Pre-Deployment Verification
+
+```bash
+# 1. Verify bucket exists
+gcloud storage buckets describe gs://reflow-documents-prod
+
+# 2. Verify service account has access
+gcloud storage ls gs://reflow-documents-prod \
+  --impersonate-service-account=reflow-storage-prod-sa@re-platform-workflow-dealer.iam.gserviceaccount.com
+
+# 3. Test file upload
+echo "test file" > test-upload.txt
+gcloud storage cp test-upload.txt gs://reflow-documents-prod/temp/test-upload.txt
+
+# 4. Test file download
+gcloud storage cp gs://reflow-documents-prod/temp/test-upload.txt ./test-download.txt
+
+# 5. Test file delete
+gcloud storage rm gs://reflow-documents-prod/temp/test-upload.txt
+
+# 6. Clean up
+rm test-upload.txt test-download.txt
+```
+
+### 10.2 Application-Level Testing
+
+1. **Upload Test:**
+   - Upload a document via API
+   - Verify file appears in GCS bucket
+   - Check database `storage_url` field contains GCS URL
+
+2. **Download Test:**
+   - Download file via API
+   - Verify file is accessible
+   - Check response headers
+
+3. **Delete Test:**
+   - Delete file via API
+   - Verify file is removed from GCS
+   - Check database record is updated
+
+### 10.3 Production Readiness Checklist
+
+- [ ] Bucket created and configured
+- [ ] Service account created with correct permissions
+- [ ] JSON key file generated and stored securely
+- [ ] Environment variables configured in `.env`
+- [ ] CORS policy applied
+- [ ] Lifecycle rules configured
+- [ ] Versioning enabled
+- [ ] Access logging enabled
+- [ ] Monitoring alerts configured
+- [ ] Upload/download/delete operations tested
+- [ ] Backup and recovery procedures documented
+
+---
+
+## 11. Troubleshooting
+
+### 11.1 Common Issues
+
+**Issue: Files not uploading to GCS**
+- ✅ Check `.env` configuration matches credentials
+- ✅ Verify service account has correct permissions
+- ✅ Check bucket name exists and is accessible
+- ✅ Review application logs for GCS errors
+- ✅ Verify key file path is correct
+
+**Issue: Files uploading but not accessible**
+- ✅ Verify bucket permissions (private vs public)
+- ✅ Check CORS configuration if accessing from browser
+- ✅ Ensure `storage_url` is being saved correctly in database
+- ✅ Verify signed URL generation (if using private bucket)
+
+**Issue: Permission denied errors**
+- ✅ Verify service account has `roles/storage.objectAdmin`
+- ✅ Check bucket IAM policies
+- ✅ Verify key file is valid and not expired
+
+### 11.2 Log Analysis
+
+Check application logs for GCS-related messages:
+```bash
+# Search for GCS initialization
+grep "GCS.*Initialized" logs/app.log
+
+# Search for GCS errors
+grep "GCS.*Error" logs/app.log
+
+# Search for upload failures
+grep "GCS.*upload.*failed" logs/app.log
+```
+
+---
+
+## 12. Production Deployment Steps
+
+### 12.1 Deployment Checklist
+
+1. **Pre-Deployment:**
+   - [ ] Create production bucket
+   - [ ] Create production service account
+   - [ ] Generate and secure key file
+   - [ ] Configure environment variables
+   - [ ] Test upload/download operations
+
+2. **Deployment:**
+   - [ ] Deploy application with new environment variables
+   - [ ] Verify GCS initialization in logs
+   - [ ] Test file upload functionality
+   - [ ] Monitor for errors
+
+3. **Post-Deployment:**
+   - [ ] Verify files are being stored in GCS
+   - [ ] Check database `storage_url` fields
+   - [ ] Monitor storage costs
+   - [ ] Review access logs
+
+---
+
+## 13. Cost Estimation (Production)
+
+| Item | Monthly Estimate | Notes |
+|------|------------------|-------|
+| **Storage (500GB)** | ~$10.00 | Standard storage class |
+| **Operations (100K)** | ~$0.50 | Upload/download operations |
+| **Network Egress** | Variable | Depends on download volume |
+| **Nearline Storage** | ~$5.00 | Files older than 90 days |
+| **Coldline Storage** | ~$2.00 | Files older than 1 year |
+
+**Total Estimated Monthly Cost:** ~$17.50 (excluding network egress)
+
+---
+
+## 14. Support & Contacts
+
+| Role | Responsibility | Contact |
+|------|----------------|---------|
+| **DevOps Team** | GCP infrastructure setup | [DevOps Email] |
+| **Application Team** | Application configuration | [App Team Email] |
+| **Security Team** | Access control and permissions | [Security Email] |
+
+---
+
+## 15. Quick Reference
+
+### 15.1 Essential Commands
+
+```bash
+# Create bucket
+gcloud storage buckets create gs://reflow-documents-prod \
+  --project=re-platform-workflow-dealer \
+  --location=asia-south1 \
+  --uniform-bucket-level-access \
+  --public-access-prevention
+
+# Create service account
+gcloud iam service-accounts create reflow-storage-prod-sa \
+  --display-name="RE Workflow Production Storage" \
+  --project=re-platform-workflow-dealer
+
+# Generate key
+gcloud iam service-accounts keys create ./config/gcp-key-prod.json \
+  --iam-account=reflow-storage-prod-sa@re-platform-workflow-dealer.iam.gserviceaccount.com
+
+# Set CORS
+gcloud storage buckets update gs://reflow-documents-prod \
+  --cors-file=cors-config-prod.json
+
+# Enable versioning
+gcloud storage buckets update gs://reflow-documents-prod \
+  --versioning
+```
+
+### 15.2 Environment Variables Template
+
+```env
+# Production GCP Configuration
+GCP_PROJECT_ID=re-platform-workflow-dealer
+GCP_BUCKET_NAME=reflow-documents-prod
+GCP_KEY_FILE=./config/gcp-key-prod.json
+```
+
+---
+
+## Appendix: File Structure Reference
+
+### Database Storage Fields
+
+The application stores file information in the database:
+
+| Table | Field | Description |
+|-------|-------|-------------|
+| `documents` | `file_path` | GCS path: `requests/{requestNumber}/documents/{filename}` |
+| `documents` | `storage_url` | Full GCS URL: `https://storage.googleapis.com/bucket/path` |
+| `work_note_attachments` | `file_path` | GCS path: `requests/{requestNumber}/attachments/{filename}` |
+| `work_note_attachments` | `storage_url` | Full GCS URL |
+| `claim_invoices` | `invoice_file_path` | GCS path: `requests/{requestNumber}/invoices/{filename}` |
+| `claim_credit_notes` | `credit_note_file_path` | GCS path: `requests/{requestNumber}/credit-notes/{filename}` |
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** December 2024  
+**Maintained By:** RE Workflow Development Team
+

docs/GCP_STORAGE_SETUP.md

@@ -6,7 +6,7 @@
 |------|-------|
 | **Application** | RE Workflow System |
 | **Environment** | UAT |
-| **Domain** | https://reflow-uat.royalenfield.com |
+| **Domain** | https://reflow-uat.{{APP_DOMAIN}} |
 | **Purpose** | Store workflow documents and attachments |
 
 ---
@@ -131,8 +131,8 @@ Apply this CORS policy to allow browser uploads:
 [
   {
     "origin": [
-      "https://reflow-uat.royalenfield.com",
-      "https://reflow.royalenfield.com"
+      "https://reflow-uat.{{APP_DOMAIN}}",
+      "https://reflow.{{APP_DOMAIN}}"
     ],
     "method": ["GET", "PUT", "POST", "DELETE", "HEAD", "OPTIONS"],
     "responseHeader": [

docs/GOOGLE_SECRET_MANAGER_SETUP.md

@@ -0,0 +1,277 @@
+# Google Secret Manager Integration Guide
+
+This guide explains how to integrate Google Cloud Secret Manager with your Node.js application to securely manage environment variables.
+
+## Overview
+
+The Google Secret Manager integration allows you to:
+- Store sensitive configuration values (passwords, API keys, tokens) in Google Cloud Secret Manager
+- Load secrets at application startup and merge them with your existing environment variables
+- Maintain backward compatibility with `.env` files for local development
+- Use minimal code changes - existing `process.env.VARIABLE_NAME` access continues to work
+
+## Prerequisites
+
+1. **Google Cloud Project** with Secret Manager API enabled
+2. **Service Account** with Secret Manager Secret Accessor role
+3. **Authentication** - Service account credentials configured (via `GCP_KEY_FILE` or default credentials)
+
+## Setup Instructions
+
+### 1. Enable Secret Manager API
+
+```bash
+gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
+```
+
+### 2. Create Secrets in Google Secret Manager
+
+Create secrets using the Google Cloud Console or gcloud CLI:
+
+```bash
+# Example: Create a database password secret
+echo -n "your-secure-password" | gcloud secrets create DB_PASSWORD \
+  --project=YOUR_PROJECT_ID \
+  --data-file=-
+
+# Example: Create a JWT secret
+echo -n "your-jwt-secret-key" | gcloud secrets create JWT_SECRET \
+  --project=YOUR_PROJECT_ID \
+  --data-file=-
+
+# Grant service account access to secrets
+gcloud secrets add-iam-policy-binding DB_PASSWORD \
+  --member="serviceAccount:YOUR_SERVICE_ACCOUNT@YOUR_PROJECT.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor" \
+  --project=YOUR_PROJECT_ID
+```
+
+### 3. Configure Environment Variables
+
+Add the following to your `.env` file:
+
+```env
+# Google Secret Manager Configuration
+USE_GOOGLE_SECRET_MANAGER=true
+GCP_PROJECT_ID=your-project-id
+
+# Optional: Prefix for all secret names (e.g., "prod" -> looks for "prod-DB_PASSWORD")
+GCP_SECRET_PREFIX=
+
+# Optional: JSON file mapping secret names to env var names
+GCP_SECRET_MAP_FILE=./secret-map.json
+```
+
+**Important Notes:**
+- Set `USE_GOOGLE_SECRET_MANAGER=true` to enable the integration
+- `GCP_PROJECT_ID` must be set (same as used for GCS/Vertex AI)
+- `GCP_KEY_FILE` should already be configured for other GCP services
+- When `USE_GOOGLE_SECRET_MANAGER=false` or not set, the app uses `.env` file only
+
+### 4. Secret Name Mapping
+
+By default, secrets in Google Secret Manager are automatically mapped to environment variables:
+- Secret name: `DB_PASSWORD` → Environment variable: `DB_PASSWORD`
+- Secret name: `db-password` → Environment variable: `DB_PASSWORD` (hyphens converted to underscores, uppercase)
+- Secret name: `jwt-secret-key` → Environment variable: `JWT_SECRET_KEY`
+
+#### Custom Mapping (Optional)
+
+If you need custom mappings, create a JSON file (e.g., `secret-map.json`):
+
+```json
+{
+  "db-password-prod": "DB_PASSWORD",
+  "jwt-secret-key": "JWT_SECRET",
+  "okta-client-secret-prod": "OKTA_CLIENT_SECRET"
+}
+```
+
+Then set in `.env`:
+```env
+GCP_SECRET_MAP_FILE=./secret-map.json
+```
+
+### 5. Secret Prefix (Optional)
+
+If all your secrets share a common prefix:
+
+```env
+GCP_SECRET_PREFIX=prod
+```
+
+This will look for secrets named `prod-DB_PASSWORD`, `prod-JWT_SECRET`, etc.
+
+## How It Works
+
+1. **Application Startup:**
+   - `.env` file is loaded first (provides fallback values)
+   - If `USE_GOOGLE_SECRET_MANAGER=true`, secrets are fetched from Google Secret Manager
+   - Secrets are merged into `process.env`, overriding `.env` values if they exist
+   - Application continues with merged environment variables
+
+2. **Fallback Behavior:**
+   - If Secret Manager is disabled or fails, the app falls back to `.env` file
+   - No errors are thrown - the app continues with available configuration
+   - Logs indicate whether secrets were loaded successfully
+
+3. **Existing Code Compatibility:**
+   - No changes needed to existing code
+   - Continue using `process.env.VARIABLE_NAME` as before
+   - Secrets from GCS automatically populate `process.env`
+
+## Default Secrets Loaded
+
+The service automatically attempts to load these common secrets (if they exist in Secret Manager):
+
+**Database:**
+- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+
+**Authentication:**
+- `JWT_SECRET`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`
+
+**SSO/Okta:**
+- `OKTA_DOMAIN`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`, `OKTA_API_TOKEN`
+
+**Email:**
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`
+
+**Web Push (VAPID):**
+- `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`
+
+**Logging:**
+- `LOKI_HOST`, `LOKI_USER`, `LOKI_PASSWORD`
+
+### Loading Custom Secrets
+
+To load additional secrets, modify the code:
+
+```typescript
+// In server.ts or app.ts
+import { googleSecretManager } from './services/googleSecretManager.service';
+
+// Load default secrets + custom ones
+await googleSecretManager.loadSecrets([
+  'DB_PASSWORD',
+  'JWT_SECRET',
+  'CUSTOM_API_KEY',  // Your custom secret
+  'CUSTOM_SECRET_2'
+]);
+```
+
+Or load a single secret on-demand:
+
+```typescript
+import { googleSecretManager } from './services/googleSecretManager.service';
+
+const apiKey = await googleSecretManager.getSecretValue('CUSTOM_API_KEY', 'API_KEY');
+```
+
+## Security Best Practices
+
+1. **Service Account Permissions:**
+   - Grant only `roles/secretmanager.secretAccessor` role
+   - Use separate service accounts for different environments
+   - Never grant `roles/owner` or `roles/editor` to service accounts
+
+2. **Secret Rotation:**
+   - Rotate secrets regularly in Google Secret Manager
+   - The app automatically uses the `latest` version of each secret
+   - No code changes needed when secrets are rotated
+
+3. **Environment Separation:**
+   - Use different Google Cloud projects for dev/staging/prod
+   - Use `GCP_SECRET_PREFIX` to namespace secrets by environment
+   - Never commit `.env` files with production secrets to version control
+
+4. **Access Control:**
+   - Use IAM policies to control who can read secrets
+   - Enable audit logging for secret access
+   - Regularly review secret access logs
+
+## Troubleshooting
+
+### Secrets Not Loading
+
+**Check logs for:**
+```
+[Secret Manager] Google Secret Manager is disabled (USE_GOOGLE_SECRET_MANAGER != true)
+[Secret Manager] GCP_PROJECT_ID not set, skipping Google Secret Manager
+[Secret Manager] Failed to load secrets: [error message]
+```
+
+**Common issues:**
+1. `USE_GOOGLE_SECRET_MANAGER` not set to `true`
+2. `GCP_PROJECT_ID` not configured
+3. Service account lacks Secret Manager permissions
+4. Secrets don't exist in Secret Manager
+5. Incorrect secret names (check case sensitivity)
+
+### Service Account Authentication
+
+Ensure service account credentials are available:
+- Set `GCP_KEY_FILE` to point to service account JSON file
+- Or configure Application Default Credentials (ADC)
+- Test with: `gcloud auth application-default login`
+
+### Secret Not Found
+
+If a secret doesn't exist in Secret Manager:
+- The app logs a debug message and continues
+- Falls back to `.env` file value
+- This is expected behavior - not all secrets need to be in GCS
+
+### Debugging
+
+Enable debug logging by setting:
+```env
+LOG_LEVEL=debug
+```
+
+This will show detailed logs about which secrets are being loaded.
+
+## Example Configuration
+
+**Local Development (.env):**
+```env
+USE_GOOGLE_SECRET_MANAGER=false
+DB_PASSWORD=local-dev-password
+JWT_SECRET=local-jwt-secret
+```
+
+**Production (.env):**
+```env
+USE_GOOGLE_SECRET_MANAGER=true
+GCP_PROJECT_ID=re-platform-workflow-dealer
+GCP_SECRET_PREFIX=prod
+GCP_KEY_FILE=./credentials/service-account.json
+# DB_PASSWORD and other secrets loaded from GCS
+```
+
+## Migration Strategy
+
+1. **Phase 1: Setup**
+   - Create secrets in Google Secret Manager
+   - Keep `.env` file with current values (as backup)
+
+2. **Phase 2: Test**
+   - Set `USE_GOOGLE_SECRET_MANAGER=true` in development
+   - Verify secrets are loaded correctly
+   - Test application functionality
+
+3. **Phase 3: Production**
+   - Deploy with `USE_GOOGLE_SECRET_MANAGER=true`
+   - Monitor logs for secret loading success
+   - Remove sensitive values from `.env` file (keep placeholders)
+
+4. **Phase 4: Cleanup**
+   - Remove production secrets from `.env` file
+   - Ensure all secrets are in Secret Manager
+   - Document secret names and mappings
+
+## Additional Resources
+
+- [Google Secret Manager Documentation](https://cloud.google.com/secret-manager/docs)
+- [Secret Manager Client Library](https://cloud.google.com/nodejs/docs/reference/secret-manager/latest)
+- [Service Account Best Practices](https://cloud.google.com/iam/docs/best-practices-service-accounts)
+

docs/IMPLEMENTATION_PROGRESS.md

@@ -0,0 +1,78 @@
+# Dealer Claim Management - Implementation Progress
+
+## ✅ Completed
+
+### 1. Database Migrations
+- ✅ `20251210-add-workflow-type-support.ts` - Adds `workflow_type` and `template_id` to `workflow_requests`
+- ✅ `20251210-enhance-workflow-templates.ts` - Enhances `workflow_templates` with form configuration fields
+- ✅ `20251210-create-dealer-claim-tables.ts` - Creates dealer claim related tables:
+  - `dealer_claim_details` - Main claim information
+  - `dealer_proposal_details` - Step 1: Dealer proposal submission
+  - `dealer_completion_details` - Step 5: Dealer completion documents
+
+### 2. Models
+- ✅ Updated `WorkflowRequest` model with `workflowType` and `templateId` fields
+- ✅ Created `DealerClaimDetails` model
+- ✅ Created `DealerProposalDetails` model
+- ✅ Created `DealerCompletionDetails` model
+
+### 3. Services
+- ✅ Created `TemplateFieldResolver` service for dynamic user field references
+
+## 🚧 In Progress
+
+### 4. Services (Next Steps)
+- ⏳ Create `EnhancedTemplateService` - Main service for template operations
+- ⏳ Create `DealerClaimService` - Claim-specific business logic
+
+### 5. Controllers & Routes
+- ⏳ Create `DealerClaimController` - API endpoints for claim management
+- ⏳ Create routes for dealer claim operations
+- ⏳ Create template management endpoints
+
+## 📋 Next Steps
+
+1. **Create EnhancedTemplateService**
+   - Get form configuration with resolved user references
+   - Save step data
+   - Validate form data
+
+2. **Create DealerClaimService**
+   - Create claim request
+   - Handle 8-step workflow transitions
+   - Manage proposal and completion submissions
+
+3. **Create Controllers**
+   - POST `/api/v1/dealer-claims` - Create claim request
+   - GET `/api/v1/dealer-claims/:requestId` - Get claim details
+   - POST `/api/v1/dealer-claims/:requestId/proposal` - Submit proposal (Step 1)
+   - POST `/api/v1/dealer-claims/:requestId/completion` - Submit completion (Step 5)
+   - GET `/api/v1/templates/:templateId/form-config` - Get form configuration
+
+4. **Integration Services**
+   - SAP integration for IO validation and budget blocking
+   - DMS integration for e-invoice and credit note generation
+
+## 📝 Notes
+
+- All migrations are ready to run
+- Models are created with proper associations
+- Template field resolver supports dynamic user references
+- System is designed to be extensible for future templates
+
+## 🔄 Running Migrations
+
+To apply the migrations:
+
+```bash
+cd Re_Backend
+npm run migrate
+```
+
+Or run individually:
+```bash
+npx ts-node src/scripts/run-migration.ts 20251210-add-workflow-type-support
+npx ts-node src/scripts/run-migration.ts 20251210-enhance-workflow-templates
+npx ts-node src/scripts/run-migration.ts 20251210-create-dealer-claim-tables
+```
+

docs/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,159 @@
+# Dealer Claim Management - Implementation Summary
+
+## ✅ Completed Implementation
+
+### 1. Database Migrations (4 files)
+- ✅ `20251210-add-workflow-type-support.ts` - Adds `workflow_type` and `template_id` to `workflow_requests`
+- ✅ `20251210-enhance-workflow-templates.ts` - Enhances `workflow_templates` with form configuration
+- ✅ `20251210-add-template-id-foreign-key.ts` - Adds FK constraint for `template_id`
+- ✅ `20251210-create-dealer-claim-tables.ts` - Creates dealer claim tables:
+  - `dealer_claim_details` - Main claim information
+  - `dealer_proposal_details` - Step 1: Dealer proposal
+  - `dealer_completion_details` - Step 5: Completion documents
+
+### 2. Models (5 files)
+- ✅ Updated `WorkflowRequest` - Added `workflowType` and `templateId` fields
+- ✅ Created `DealerClaimDetails` - Main claim information model
+- ✅ Created `DealerProposalDetails` - Proposal submission model
+- ✅ Created `DealerCompletionDetails` - Completion documents model
+- ✅ Created `WorkflowTemplate` - Template configuration model
+
+### 3. Services (3 files)
+- ✅ Created `TemplateFieldResolver` - Resolves dynamic user field references
+- ✅ Created `EnhancedTemplateService` - Template form management
+- ✅ Created `DealerClaimService` - Claim-specific business logic:
+  - `createClaimRequest()` - Create new claim with 8-step workflow
+  - `getClaimDetails()` - Get complete claim information
+  - `submitDealerProposal()` - Step 1: Dealer proposal submission
+  - `submitCompletionDocuments()` - Step 5: Completion submission
+  - `updateIODetails()` - Step 3: IO budget blocking
+  - `updateEInvoiceDetails()` - Step 7: E-Invoice generation
+  - `updateCreditNoteDetails()` - Step 8: Credit note issuance
+
+### 4. Controllers & Routes (2 files)
+- ✅ Created `DealerClaimController` - API endpoints for claim operations
+- ✅ Created `dealerClaim.routes.ts` - Route definitions
+- ✅ Registered routes in `routes/index.ts`
+
+### 5. Frontend Utilities (1 file)
+- ✅ Created `claimRequestUtils.ts` - Utility functions for detecting claim requests
+
+## 📋 API Endpoints Created
+
+### Dealer Claim Management
+- `POST /api/v1/dealer-claims` - Create claim request
+- `GET /api/v1/dealer-claims/:requestId` - Get claim details
+- `POST /api/v1/dealer-claims/:requestId/proposal` - Submit dealer proposal (Step 1)
+- `POST /api/v1/dealer-claims/:requestId/completion` - Submit completion (Step 5)
+- `PUT /api/v1/dealer-claims/:requestId/io` - Update IO details (Step 3)
+- `PUT /api/v1/dealer-claims/:requestId/e-invoice` - Update e-invoice (Step 7)
+- `PUT /api/v1/dealer-claims/:requestId/credit-note` - Update credit note (Step 8)
+
+## 🔄 8-Step Workflow Implementation
+
+The system automatically creates 8 approval levels:
+
+1. **Dealer Proposal Submission** (72h) - Dealer submits proposal
+2. **Requestor Evaluation** (48h) - Initiator reviews and confirms
+3. **Department Lead Approval** (72h) - Dept lead approves and blocks IO
+4. **Activity Creation** (1h, Auto) - System creates activity record
+5. **Dealer Completion Documents** (120h) - Dealer submits completion docs
+6. **Requestor Claim Approval** (48h) - Initiator approves claim
+7. **E-Invoice Generation** (1h, Auto) - System generates e-invoice via DMS
+8. **Credit Note Confirmation** (48h) - Finance confirms credit note
+
+## 🎯 Key Features
+
+1. **Unified Request System**
+   - All requests use same `workflow_requests` table
+   - Identified by `workflowType: 'CLAIM_MANAGEMENT'`
+   - Automatically appears in "My Requests" and "Open Requests"
+
+2. **Template-Specific Data Storage**
+   - Claim data stored in extension tables
+   - Linked via `request_id` foreign key
+   - Supports future templates with their own tables
+
+3. **Dynamic User References**
+   - Auto-populate fields from initiator, dealer, approvers
+   - Supports team lead, department lead references
+   - Configurable per template
+
+4. **File Upload Integration**
+   - Uses GCS with local fallback
+   - Organized by request number and file type
+   - Supports proposal documents and completion files
+
+## 📝 Next Steps
+
+### Backend
+1. ⏳ Add SAP integration for IO validation and budget blocking
+2. ⏳ Add DMS integration for e-invoice and credit note generation
+3. ⏳ Create template management API endpoints
+4. ⏳ Add validation for dealer codes (SAP integration)
+
+### Frontend
+1. ⏳ Create `claimDataMapper.ts` utility functions
+2. ⏳ Update `RequestDetail.tsx` to conditionally render claim components
+3. ⏳ Update API services to include `workflowType`
+4. ⏳ Create `dealerClaimApi.ts` service
+5. ⏳ Update request cards to show workflow type
+
+## 🚀 Running the Implementation
+
+### 1. Run Migrations
+```bash
+cd Re_Backend
+npm run migrate
+```
+
+### 2. Test API Endpoints
+```bash
+# Create claim request
+POST /api/v1/dealer-claims
+{
+  "activityName": "Diwali Campaign",
+  "activityType": "Marketing Activity",
+  "dealerCode": "RE-MH-001",
+  "dealerName": "Royal Motors Mumbai",
+  "location": "Mumbai",
+  "requestDescription": "Marketing campaign details..."
+}
+
+# Submit proposal
+POST /api/v1/dealer-claims/:requestId/proposal
+FormData with proposalDocument file and JSON data
+```
+
+## 📊 Database Structure
+
+```
+workflow_requests (common)
+  ├── workflow_type: 'CLAIM_MANAGEMENT'
+  └── template_id: (nullable)
+
+dealer_claim_details (claim-specific)
+  └── request_id → workflow_requests
+
+dealer_proposal_details (Step 1)
+  └── request_id → workflow_requests
+
+dealer_completion_details (Step 5)
+  └── request_id → workflow_requests
+
+approval_levels (8 steps)
+  └── request_id → workflow_requests
+```
+
+## ✅ Testing Checklist
+
+- [ ] Run migrations successfully
+- [ ] Create claim request via API
+- [ ] Submit dealer proposal
+- [ ] Update IO details
+- [ ] Submit completion documents
+- [ ] Verify request appears in "My Requests"
+- [ ] Verify request appears in "Open Requests"
+- [ ] Test file uploads (GCS and local fallback)
+- [ ] Test workflow progression through 8 steps
+

docs/MIGRATION_SETUP_SUMMARY.md

@@ -0,0 +1,164 @@
+# Migration and Setup Summary
+
+## ✅ Current Status
+
+### Tables Created by Migrations
+
+All **6 new dealer claim tables** are included in the migration system:
+
+1. ✅ `dealer_claim_details` - Main claim information
+2. ✅ `dealer_proposal_details` - Step 1: Dealer proposal
+3. ✅ `dealer_completion_details` - Step 5: Completion documents
+4. ✅ `dealer_proposal_cost_items` - Cost breakdown items
+5. ✅ `internal_orders` ⭐ - IO details with dedicated fields
+6. ✅ `claim_budget_tracking` ⭐ - Comprehensive budget tracking
+
+## Migration Commands
+
+### 1. **`npm run migrate`** ✅
+**Status:** ✅ **Fully configured**
+
+This command runs `src/scripts/migrate.ts` which includes **ALL** migrations including:
+- ✅ All dealer claim tables (m25-m28)
+- ✅ New tables: `internal_orders` (m27) and `claim_budget_tracking` (m28)
+
+**Usage:**
+```bash
+npm run migrate
+```
+
+**What it does:**
+- Checks which migrations have already run (via `migrations` table)
+- Runs only pending migrations
+- Marks them as executed
+- Creates all new tables automatically
+
+---
+
+### 2. **`npm run dev`** ✅
+**Status:** ✅ **Now fixed and configured**
+
+This command runs:
+```bash
+npm run setup && nodemon --exec ts-node ...
+```
+
+Which calls `npm run setup` → `src/scripts/auto-setup.ts`
+
+**What `auto-setup.ts` does:**
+1. ✅ Checks if database exists, creates if missing
+2. ✅ Installs PostgreSQL extensions (uuid-ossp)
+3. ✅ **Runs all pending migrations** (including dealer claim tables)
+4. ✅ Tests database connection
+
+**Fixed:** ✅ Now includes all dealer claim migrations (m29-m35)
+
+**Usage:**
+```bash
+npm run dev
+```
+
+This will automatically:
+- Create database if needed
+- Run all migrations (including new tables)
+- Start the development server
+
+---
+
+### 3. **`npm run setup`** ✅
+**Status:** ✅ **Now fixed and configured**
+
+Same as what `npm run dev` calls - runs `auto-setup.ts`
+
+**Usage:**
+```bash
+npm run setup
+```
+
+---
+
+## Migration Files Included
+
+### In `migrate.ts` (for `npm run migrate`):
+- ✅ `20251210-add-workflow-type-support` (m22)
+- ✅ `20251210-enhance-workflow-templates` (m23)
+- ✅ `20251210-add-template-id-foreign-key` (m24)
+- ✅ `20251210-create-dealer-claim-tables` (m25) - Creates 3 tables
+- ✅ `20251210-create-proposal-cost-items-table` (m26)
+- ✅ `20251211-create-internal-orders-table` (m27) ⭐ NEW
+- ✅ `20251211-create-claim-budget-tracking-table` (m28) ⭐ NEW
+
+### In `auto-setup.ts` (for `npm run dev` / `npm run setup`):
+- ✅ All migrations from `migrate.ts` are now included (m29-m35)
+
+---
+
+## What Gets Created
+
+When you run either `npm run migrate` or `npm run dev`, these tables will be created:
+
+### Dealer Claim Tables (from `20251210-create-dealer-claim-tables.ts`):
+1. `dealer_claim_details`
+2. `dealer_proposal_details`
+3. `dealer_completion_details`
+
+### Additional Tables:
+4. `dealer_proposal_cost_items` (from `20251210-create-proposal-cost-items-table.ts`)
+5. `internal_orders` ⭐ (from `20251211-create-internal-orders-table.ts`)
+6. `claim_budget_tracking` ⭐ (from `20251211-create-claim-budget-tracking-table.ts`)
+
+---
+
+## Verification
+
+After running migrations, verify tables exist:
+
+```sql
+-- Check if new tables exist
+SELECT table_name 
+FROM information_schema.tables 
+WHERE table_schema = 'public' 
+AND table_name IN (
+  'dealer_claim_details',
+  'dealer_proposal_details',
+  'dealer_completion_details',
+  'dealer_proposal_cost_items',
+  'internal_orders',
+  'claim_budget_tracking'
+)
+ORDER BY table_name;
+```
+
+Should return 6 rows.
+
+---
+
+## Summary
+
+| Command | Runs Migrations? | Includes New Tables? | Status |
+|---------|------------------|---------------------|--------|
+| `npm run migrate` | ✅ Yes | ✅ Yes | ✅ Working |
+| `npm run dev` | ✅ Yes | ✅ Yes | ✅ Fixed |
+| `npm run setup` | ✅ Yes | ✅ Yes | ✅ Fixed |
+
+**All commands now create the new tables automatically!** 🎉
+
+---
+
+## Next Steps
+
+1. **Run migrations:**
+   ```bash
+   npm run migrate
+   ```
+   OR
+   ```bash
+   npm run dev  # This will also run migrations via setup
+   ```
+
+2. **Verify tables created:**
+   Check the database to confirm all 6 tables exist.
+
+3. **Start using:**
+   The tables are ready for dealer claim management!
+

docs/NEW_TABLES_SUMMARY.md

@@ -0,0 +1,216 @@
+# New Tables Created for Dealer Claim Management
+
+## Overview
+
+This document lists all the new database tables created specifically for the Dealer Claim Management system.
+
+## Tables Created
+
+### 1. **`dealer_claim_details`** 
+**Migration:** `20251210-create-dealer-claim-tables.ts`
+
+**Purpose:** Main table storing claim-specific information
+
+**Key Fields:**
+- `claim_id` (PK)
+- `request_id` (FK to `workflow_requests`, unique)
+- `activity_name`, `activity_type`
+- `dealer_code`, `dealer_name`, `dealer_email`, `dealer_phone`, `dealer_address`
+- `activity_date`, `location`
+- `period_start_date`, `period_end_date`
+- `estimated_budget`, `closed_expenses`
+- `io_number`, `io_available_balance`, `io_blocked_amount`, `io_remaining_balance` (legacy - now in `internal_orders`)
+- `sap_document_number`, `dms_number`
+- `e_invoice_number`, `e_invoice_date`
+- `credit_note_number`, `credit_note_date`, `credit_note_amount`
+
+**Created:** December 10, 2025
+
+---
+
+### 2. **`dealer_proposal_details`**
+**Migration:** `20251210-create-dealer-claim-tables.ts`
+
+**Purpose:** Stores dealer proposal submission data (Step 1 of workflow)
+
+**Key Fields:**
+- `proposal_id` (PK)
+- `request_id` (FK to `workflow_requests`, unique)
+- `proposal_document_path`, `proposal_document_url`
+- `cost_breakup` (JSONB - legacy, now use `dealer_proposal_cost_items`)
+- `total_estimated_budget`
+- `timeline_mode` ('date' | 'days')
+- `expected_completion_date`, `expected_completion_days`
+- `dealer_comments`
+- `submitted_at`
+
+**Created:** December 10, 2025
+
+---
+
+### 3. **`dealer_completion_details`**
+**Migration:** `20251210-create-dealer-claim-tables.ts`
+
+**Purpose:** Stores dealer completion documents and expenses (Step 5 of workflow)
+
+**Key Fields:**
+- `completion_id` (PK)
+- `request_id` (FK to `workflow_requests`, unique)
+- `activity_completion_date`
+- `number_of_participants`
+- `closed_expenses` (JSONB array)
+- `total_closed_expenses`
+- `completion_documents` (JSONB array)
+- `activity_photos` (JSONB array)
+- `submitted_at`
+
+**Created:** December 10, 2025
+
+---
+
+### 4. **`dealer_proposal_cost_items`**
+**Migration:** `20251210-create-proposal-cost-items-table.ts`
+
+**Purpose:** Separate table for cost breakdown items (replaces JSONB in `dealer_proposal_details`)
+
+**Key Fields:**
+- `cost_item_id` (PK)
+- `proposal_id` (FK to `dealer_proposal_details`)
+- `request_id` (FK to `workflow_requests` - denormalized for easier querying)
+- `item_description`
+- `amount` (DECIMAL 15,2)
+- `item_order` (for maintaining order in cost breakdown)
+
+**Benefits:**
+- Better querying and filtering
+- Easier to update individual cost items
+- Better for analytics and reporting
+- Maintains referential integrity
+
+**Created:** December 10, 2025
+
+---
+
+### 5. **`internal_orders`** ⭐ NEW
+**Migration:** `20251211-create-internal-orders-table.ts`
+
+**Purpose:** Dedicated table for IO (Internal Order) details with proper structure
+
+**Key Fields:**
+- `io_id` (PK)
+- `request_id` (FK to `workflow_requests`, unique - one IO per request)
+- `io_number` (STRING 50)
+- `io_remark` (TEXT) ⭐ - Dedicated field for IO remarks (not in comments)
+- `io_available_balance` (DECIMAL 15,2)
+- `io_blocked_amount` (DECIMAL 15,2)
+- `io_remaining_balance` (DECIMAL 15,2)
+- `organized_by` (FK to `users`) ⭐ - Tracks who organized the IO
+- `organized_at` (DATE) ⭐ - When IO was organized
+- `sap_document_number` (STRING 100)
+- `status` (ENUM: 'PENDING', 'BLOCKED', 'RELEASED', 'CANCELLED')
+
+**Why This Table:**
+- Previously IO details were stored in `dealer_claim_details` table
+- IO remark was being parsed from comments
+- Now dedicated table with proper fields and relationships
+- Better data integrity and querying
+
+**Created:** December 11, 2025
+
+---
+
+### 6. **`claim_budget_tracking`** ⭐ NEW
+**Migration:** `20251211-create-claim-budget-tracking-table.ts`
+
+**Purpose:** Comprehensive budget tracking throughout the claim lifecycle
+
+**Key Fields:**
+- `budget_id` (PK)
+- `request_id` (FK to `workflow_requests`, unique - one budget record per request)
+
+**Budget Values:**
+- `initial_estimated_budget` - From claim creation
+- `proposal_estimated_budget` - From Step 1 (Dealer Proposal)
+- `approved_budget` - From Step 2 (Requestor Evaluation)
+- `io_blocked_amount` - From Step 3 (Department Lead - IO blocking)
+- `closed_expenses` - From Step 5 (Dealer Completion)
+- `final_claim_amount` - From Step 6 (Requestor Claim Approval)
+- `credit_note_amount` - From Step 8 (Finance)
+
+**Tracking Fields:**
+- `proposal_submitted_at`
+- `approved_at`, `approved_by` (FK to `users`)
+- `io_blocked_at`
+- `closed_expenses_submitted_at`
+- `final_claim_amount_approved_at`, `final_claim_amount_approved_by` (FK to `users`)
+- `credit_note_issued_at`
+
+**Status & Analysis:**
+- `budget_status` (ENUM: 'DRAFT', 'PROPOSED', 'APPROVED', 'BLOCKED', 'CLOSED', 'SETTLED')
+- `currency` (STRING 3, default: 'INR')
+- `variance_amount` - Difference between approved and closed expenses
+- `variance_percentage` - Variance as percentage
+
+**Audit Fields:**
+- `last_modified_by` (FK to `users`)
+- `last_modified_at`
+- `modification_reason` (TEXT)
+
+**Why This Table:**
+- Previously budget data was scattered across multiple tables
+- No single source of truth for budget lifecycle
+- No audit trail for budget modifications
+- Now comprehensive tracking with status and variance calculation
+
+**Created:** December 11, 2025
+
+---
+
+## Summary
+
+### Total New Tables: **6**
+
+1. ✅ `dealer_claim_details` - Main claim information
+2. ✅ `dealer_proposal_details` - Step 1: Dealer proposal
+3. ✅ `dealer_completion_details` - Step 5: Completion documents
+4. ✅ `dealer_proposal_cost_items` - Cost breakdown items
+5. ✅ `internal_orders` ⭐ - IO details with dedicated fields
+6. ✅ `claim_budget_tracking` ⭐ - Comprehensive budget tracking
+
+### Most Recent Additions (December 11, 2025):
+- **`internal_orders`** - Proper IO data structure with `ioRemark` field
+- **`claim_budget_tracking`** - Complete budget lifecycle tracking
+
+## Migration Order
+
+Run migrations in this order:
+```bash
+npm run migrate
+```
+
+The migrations will run in chronological order:
+1. `20251210-create-dealer-claim-tables.ts` (creates tables 1-3)
+2. `20251210-create-proposal-cost-items-table.ts` (creates table 4)
+3. `20251211-create-internal-orders-table.ts` (creates table 5)
+4. `20251211-create-claim-budget-tracking-table.ts` (creates table 6)
+
+## Relationships
+
+```
+workflow_requests (1)
+  ├── dealer_claim_details (1:1)
+  ├── dealer_proposal_details (1:1)
+  │   └── dealer_proposal_cost_items (1:many)
+  ├── dealer_completion_details (1:1)
+  ├── internal_orders (1:1) ⭐ NEW
+  └── claim_budget_tracking (1:1) ⭐ NEW
+```
+
+## Notes
+
+- All tables have `request_id` foreign key to `workflow_requests`
+- Most tables have unique constraint on `request_id` (one record per request)
+- `dealer_proposal_cost_items` can have multiple items per proposal
+- All tables use UUID primary keys
+- All tables have `created_at` and `updated_at` timestamps
+

docs/OKTA_USERS_API_INTEGRATION.md

@@ -0,0 +1,167 @@
+# Okta Users API Integration
+
+## Overview
+
+The authentication service now uses the Okta Users API (`/api/v1/users/{userId}`) to fetch complete user profile information including manager, employeeID, designation, and other fields that may not be available in the standard OAuth2 userinfo endpoint.
+
+## Configuration
+
+Add the following environment variable to your `.env` file:
+
+```env
+OKTA_API_TOKEN=your_okta_api_token_here
+```
+
+This is the SSWS (Server-Side Web Service) token for Okta API access. You can generate this token from your Okta Admin Console under **Security > API > Tokens**.
+
+## How It Works
+
+### 1. Primary Method: Okta Users API
+
+When a user logs in for the first time:
+
+1. The system exchanges the authorization code for tokens (OAuth2 flow)
+2. Gets the `oktaSub` (subject identifier) from the userinfo endpoint
+3. **Attempts to fetch full user profile from Users API** using:
+   - First: Email address (as shown in curl example)
+   - Fallback: oktaSub (user ID) if email lookup fails
+4. Extracts complete user information including:
+   - `profile.employeeID` - Employee ID
+   - `profile.manager` - Manager name
+   - `profile.title` - Job title/designation
+   - `profile.department` - Department
+   - `profile.mobilePhone` - Phone number
+   - `profile.firstName`, `profile.lastName`, `profile.displayName`
+   - And other profile fields
+
+### 2. Fallback Method: OAuth2 Userinfo Endpoint
+
+If the Users API:
+- Is not configured (missing `OKTA_API_TOKEN`)
+- Returns an error (4xx/5xx)
+- Fails for any reason
+
+The system automatically falls back to the standard OAuth2 userinfo endpoint (`/oauth2/default/v1/userinfo`) which provides basic user information.
+
+## API Endpoint
+
+```
+GET https://{oktaDomain}/api/v1/users/{userId}
+Authorization: SSWS {OKTA_API_TOKEN}
+Accept: application/json
+```
+
+Where `{userId}` can be:
+- Email address (e.g., `testuser10@eichergroup.com`)
+- Okta user ID (e.g., `00u1e1japegDV2DkP0h8`)
+
+## Response Structure
+
+The Users API returns a complete user object:
+
+```json
+{
+  "id": "00u1e1japegDV2DkP0h8",
+  "status": "ACTIVE",
+  "profile": {
+    "firstName": "Sanjay",
+    "lastName": "Sahu",
+    "manager": "Ezhilan subramanian",
+    "mobilePhone": "8826740087",
+    "displayName": "Sanjay Sahu",
+    "employeeID": "E09994",
+    "title": "Supports Business Applications (SAP) portfolio",
+    "department": "Deputy Manager - Digital & IT",
+    "login": "sanjaysahu@{{APP_DOMAIN}}",
+    "email": "sanjaysahu@{{APP_DOMAIN}}"
+  },
+  ...
+}
+```
+
+## Field Mapping
+
+| Users API Field | Database Field | Notes |
+|----------------|----------------|-------|
+| `profile.employeeID` | `employeeId` | Employee ID from HR system |
+| `profile.manager` | `manager` | Manager name |
+| `profile.title` | `designation` | Job title/designation |
+| `profile.department` | `department` | Department name |
+| `profile.mobilePhone` | `phone` | Phone number |
+| `profile.firstName` | `firstName` | First name |
+| `profile.lastName` | `lastName` | Last name |
+| `profile.displayName` | `displayName` | Display name |
+| `profile.email` | `email` | Email address |
+| `id` | `oktaSub` | Okta subject identifier |
+
+## Benefits
+
+1. **Complete User Profile**: Gets all available user information including manager, employeeID, and other custom attributes
+2. **Automatic Fallback**: If Users API is unavailable, gracefully falls back to userinfo endpoint
+3. **No Breaking Changes**: Existing functionality continues to work even without API token
+4. **Better Data Quality**: Reduces missing user information (manager, employeeID, etc.)
+
+## Logging
+
+The service logs:
+- When Users API is used vs. userinfo fallback
+- Which lookup method succeeded (email or oktaSub)
+- Extracted fields (employeeId, manager, department, etc.)
+- Any errors or warnings
+
+Example log:
+```
+[AuthService] Fetching user from Okta Users API (using email)
+[AuthService] Successfully fetched user from Okta Users API (using email)
+[AuthService] Extracted user data from Okta Users API
+  - oktaSub: 00u1e1japegDV2DkP0h8
+  - email: testuser10@eichergroup.com
+  - employeeId: E09994
+  - hasManager: true
+  - hasDepartment: true
+  - hasDesignation: true
+```
+
+## Testing
+
+### Test with curl
+
+```bash
+curl --location 'https://{{IDP_DOMAIN}}/api/v1/users/testuser10@eichergroup.com' \
+  --header 'Authorization: SSWS YOUR_OKTA_API_TOKEN' \
+  --header 'Accept: application/json'
+```
+
+### Test in Application
+
+1. Set `OKTA_API_TOKEN` in `.env`
+2. Log in with a user
+3. Check logs to see if Users API was used
+4. Verify user record in database has complete information (manager, employeeID, etc.)
+
+## Troubleshooting
+
+### Users API Not Being Used
+
+- Check if `OKTA_API_TOKEN` is set in `.env`
+- Check logs for warnings about missing API token
+- Verify API token has correct permissions in Okta
+
+### Users API Returns 404
+
+- User may not exist in Okta
+- Email format may be incorrect
+- Try using oktaSub (user ID) instead
+
+### Missing Fields in Database
+
+- Check if fields exist in Okta user profile
+- Verify field mapping in `extractUserDataFromUsersAPI` method
+- Check logs to see which fields were extracted
+
+## Security Notes
+
+- **API Token Security**: Store `OKTA_API_TOKEN` securely, never commit to version control
+- **Token Permissions**: Ensure API token has read access to user profiles
+- **Rate Limiting**: Be aware of Okta API rate limits when fetching user data
+

docs/RBAC_IMPLEMENTATION.md

@@ -450,16 +450,16 @@ Before Migration:
 +-------------------------+-----------+
 | email                   | is_admin  |
 +-------------------------+-----------+
-| admin@royalenfield.com  | true      |
-| user1@royalenfield.com  | false     |
+| admin@{{APP_DOMAIN}}  | true      |
+| user1@{{APP_DOMAIN}}  | false     |
 +-------------------------+-----------+
 
 After Migration:
 +-------------------------+-----------+-----------+
 | email                   | role      | is_admin  |
 +-------------------------+-----------+-----------+
-| admin@royalenfield.com  | ADMIN     | true      |
-| user1@royalenfield.com  | USER      | false     |
+| admin@{{APP_DOMAIN}}  | ADMIN     | true      |
+| user1@{{APP_DOMAIN}}  | USER      | false     |
 +-------------------------+-----------+-----------+
 ```
 
@@ -473,17 +473,17 @@ After Migration:
 -- Make user a MANAGEMENT role
 UPDATE users 
 SET role = 'MANAGEMENT', is_admin = false 
-WHERE email = 'manager@royalenfield.com';
+WHERE email = 'manager@{{APP_DOMAIN}}';
 
 -- Make user an ADMIN role
 UPDATE users 
 SET role = 'ADMIN', is_admin = true 
-WHERE email = 'admin@royalenfield.com';
+WHERE email = 'admin@{{APP_DOMAIN}}';
 
 -- Revert to USER role
 UPDATE users 
 SET role = 'USER', is_admin = false 
-WHERE email = 'user@royalenfield.com';
+WHERE email = 'user@{{APP_DOMAIN}}';
 ```
 
 ### Via API (Admin Endpoint)

docs/RBAC_QUICK_START.md

@@ -47,12 +47,12 @@ psql -d royal_enfield_db -f scripts/assign-user-roles.sql
 -- Make specific users ADMIN
 UPDATE users 
 SET role = 'ADMIN', is_admin = true 
-WHERE email IN ('admin@royalenfield.com', 'it.admin@royalenfield.com');
+WHERE email IN ('admin@{{APP_DOMAIN}}', 'it.admin@{{APP_DOMAIN}}');
 
 -- Make specific users MANAGEMENT
 UPDATE users 
 SET role = 'MANAGEMENT', is_admin = false 
-WHERE email IN ('manager@royalenfield.com', 'auditor@royalenfield.com');
+WHERE email IN ('manager@{{APP_DOMAIN}}', 'auditor@{{APP_DOMAIN}}');
 
 -- Verify roles
 SELECT email, display_name, role, is_admin FROM users ORDER BY role, email;
@@ -219,7 +219,7 @@ GROUP BY role;
 -- Check specific user
 SELECT email, role, is_admin 
 FROM users 
-WHERE email = 'your-email@royalenfield.com';
+WHERE email = 'your-email@{{APP_DOMAIN}}';
 ```
 
 ### Test 2: Test API Access
@@ -356,7 +356,7 @@ WHERE designation ILIKE '%manager%' OR designation ILIKE '%head%';
 ```sql
 SELECT email, role, is_admin 
 FROM users 
-WHERE email = 'your-email@royalenfield.com';
+WHERE email = 'your-email@{{APP_DOMAIN}}';
 ```
 
 ---

docs/SAP_INTEGRATION_TESTING.md

@@ -0,0 +1,214 @@
+# SAP Integration Testing Guide
+
+## Postman Testing
+
+### 1. Testing IO Validation API
+
+**Endpoint:** `GET /api/v1/dealer-claims/:requestId/io`
+
+**Method:** GET
+
+**Headers:**
+```
+Authorization: Bearer <your_jwt_token>
+Content-Type: application/json
+```
+
+**Note:** The CSRF error in Postman is likely coming from SAP, not our backend. Our backend doesn't have CSRF protection enabled.
+
+### 2. Testing Budget Blocking API
+
+**Endpoint:** `PUT /api/v1/dealer-claims/:requestId/io`
+
+**Method:** PUT
+
+**Headers:**
+```
+Authorization: Bearer <your_jwt_token>
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "ioNumber": "600060",
+  "ioRemark": "Test remark",
+  "availableBalance": 1000000,
+  "blockedAmount": 500,
+  "remainingBalance": 999500
+}
+```
+
+### 3. Direct SAP API Testing in Postman
+
+If you want to test SAP API directly (bypassing our backend):
+
+#### IO Validation
+- **URL:** `https://RENOIHND01.Eichergroup.com:1443/sap/opu/odata/sap/ZFI_BUDGET_CHECK_API_SRV/GetSenderDataSet?$filter=IONumber eq '600060'&$select=Sender,ResponseDate,GetIODetailsSet01&$expand=GetIODetailsSet01&$format=json`
+- **Method:** GET
+- **Authentication:** Basic Auth
+  - Username: Your SAP username
+  - Password: Your SAP password
+- **Headers:**
+  - `Accept: application/json`
+  - `Content-Type: application/json`
+
+#### Budget Blocking
+- **URL:** `https://RENOIHND01.Eichergroup.com:1443/sap/opu/odata/sap/ZFI_BUDGET_BLOCK_API_SRV/RequesterInputSet`
+- **Method:** POST
+- **Authentication:** Basic Auth
+  - Username: Your SAP username
+  - Password: Your SAP password
+- **Headers:**
+  - `Accept: application/json`
+  - `Content-Type: application/json`
+- **Body:**
+```json
+{
+  "Request_Date_Time": "2025-08-29T10:51:00",
+  "Requester": "REFMS",
+  "lt_io_input": [
+    {
+      "IONumber": "600060",
+      "Amount": "500"
+    }
+  ],
+  "lt_io_output": [],
+  "ls_response": []
+}
+```
+
+## Common Errors and Solutions
+
+### 1. CSRF Token Validation Error
+
+**Error:** "CSRF token validation error"
+
+**Possible Causes:**
+- SAP API requires CSRF tokens for POST/PUT requests
+- SAP might be checking for specific headers
+
+**Solutions:**
+1. **Get CSRF Token First:**
+   - Make a GET request to the SAP service root to get CSRF token
+   - Example: `GET https://RENOIHND01.Eichergroup.com:1443/sap/opu/odata/sap/ZFI_BUDGET_BLOCK_API_SRV/`
+   - Look for `x-csrf-token` header in response
+   - Add this token to subsequent POST/PUT requests as header: `X-CSRF-Token: <token>`
+
+2. **Add Required Headers:**
+   ```
+   X-CSRF-Token: Fetch
+   X-Requested-With: XMLHttpRequest
+   ```
+
+### 2. Authentication Failed
+
+**Error:** "Authentication failed" or "401 Unauthorized"
+
+**Possible Causes:**
+1. Wrong username/password
+2. Basic auth not being sent correctly
+3. SSL certificate issues
+4. SAP account locked or expired
+
+**Solutions:**
+
+1. **Verify Credentials:**
+   - Double-check `SAP_USERNAME` and `SAP_PASSWORD` in `.env`
+   - Ensure no extra spaces or special characters
+   - Test credentials in browser first
+
+2. **Check SSL Certificate:**
+   - If using self-signed certificate, set `SAP_DISABLE_SSL_VERIFY=true` in `.env` (testing only!)
+   - For production, ensure proper SSL certificates are configured
+
+3. **Test Basic Auth Manually:**
+   - Use Postman with Basic Auth enabled
+   - Verify the Authorization header format: `Basic <base64(username:password)>`
+
+4. **Check SAP Account Status:**
+   - Verify account is active and not locked
+   - Check if password has expired
+   - Contact SAP administrator if needed
+
+### 3. Connection Errors
+
+**Error:** "ECONNREFUSED" or "ENOTFOUND"
+
+**Solutions:**
+1. Verify `SAP_BASE_URL` is correct
+2. Check network connectivity to SAP server
+3. Ensure firewall allows connections to port 1443
+4. Verify Zscaler is configured correctly
+
+### 4. Timeout Errors
+
+**Error:** "Request timeout"
+
+**Solutions:**
+1. Increase `SAP_TIMEOUT_MS` in `.env` (default: 30000ms = 30 seconds)
+2. Check SAP server response time
+3. Verify network latency
+
+## Debugging
+
+### Enable Debug Logging
+
+Set log level to debug in your `.env`:
+```
+LOG_LEVEL=debug
+```
+
+This will log:
+- Request URLs
+- Request payloads
+- Response status codes
+- Response data
+- Error details
+
+### Check Backend Logs
+
+Look for `[SAP]` prefixed log messages:
+```bash
+# In development
+npm run dev
+
+# Check logs for SAP-related messages
+```
+
+### Test SAP Connection
+
+You can test if SAP is reachable:
+```bash
+curl -u "username:password" \
+  "https://RENOIHND01.Eichergroup.com:1443/sap/opu/odata/sap/ZFI_BUDGET_CHECK_API_SRV/"
+```
+
+## Environment Variables Checklist
+
+Ensure these are set in your `.env`:
+
+```bash
+# Required
+SAP_BASE_URL=https://RENOIHND01.Eichergroup.com:1443
+SAP_USERNAME=your_username
+SAP_PASSWORD=your_password
+
+# Optional (with defaults)
+SAP_TIMEOUT_MS=30000
+SAP_SERVICE_NAME=ZFI_BUDGET_CHECK_API_SRV
+SAP_BLOCK_SERVICE_NAME=ZFI_BUDGET_BLOCK_API_SRV
+SAP_REQUESTER=REFMS
+SAP_DISABLE_SSL_VERIFY=false  # Only for testing
+```
+
+## Next Steps
+
+If you're still getting errors:
+
+1. **Check Backend Logs:** Look for detailed error messages
+2. **Test Directly in Postman:** Bypass backend and test SAP API directly
+3. **Verify SAP Credentials:** Test with SAP administrator
+4. **Check Network:** Ensure server can reach SAP URL
+5. **Review SAP Documentation:** Check if there are additional requirements
+

docs/SSO_IMPLEMENTATION.md

@@ -314,7 +314,7 @@ JWT_EXPIRY=24h
 REFRESH_TOKEN_EXPIRY=7d
 
 # Okta Configuration
-OKTA_DOMAIN=https://dev-830839.oktapreview.com
+OKTA_DOMAIN=https://{{IDP_DOMAIN}}
 OKTA_CLIENT_ID=your-client-id
 OKTA_CLIENT_SECRET=your-client-secret
 
@@ -334,7 +334,7 @@ GCP_BUCKET_PUBLIC=true
 
 **Identity Provider**: Okta
 - **Domain**: Configurable via `OKTA_DOMAIN` environment variable
-- **Default**: `https://dev-830839.oktapreview.com`
+- **Default**: `https://{{IDP_DOMAIN}}`
 - **Protocol**: OAuth 2.0 / OpenID Connect (OIDC)
 - **Grant Types**: Authorization Code, Resource Owner Password Credentials
 
@@ -650,7 +650,7 @@ graph LR
 {
   "userId": "uuid",
   "employeeId": "EMP001",
-  "email": "user@royalenfield.com",
+  "email": "user@{{APP_DOMAIN}}",
   "role": "USER" | "MANAGEMENT" | "ADMIN",
   "iat": 1234567890,
   "exp": 1234654290
@@ -1048,7 +1048,7 @@ JWT_EXPIRY=24h
 REFRESH_TOKEN_EXPIRY=7d
 
 # Okta
-OKTA_DOMAIN=https://dev-830839.oktapreview.com
+OKTA_DOMAIN=https://{{IDP_DOMAIN}}
 OKTA_CLIENT_ID=your-client-id
 OKTA_CLIENT_SECRET=your-client-secret
 
@@ -1063,7 +1063,7 @@ GCP_BUCKET_PUBLIC=true
 **Frontend (.env):**
 ```env
 VITE_API_BASE_URL=https://api.rebridge.co.in/api/v1
-VITE_OKTA_DOMAIN=https://dev-830839.oktapreview.com
+VITE_OKTA_DOMAIN=https://{{IDP_DOMAIN}}
 VITE_OKTA_CLIENT_ID=your-client-id
 ```
 

docs/STEP3_APPROVER_ANALYSIS.md

@@ -0,0 +1,299 @@
+# Step 3 (Department Lead Approval) - User Addition Flow Analysis
+
+## Overview
+This document analyzes how Step 3 approvers (Department Lead) are added to the dealer claim workflow, covering both frontend and backend implementation.
+
+---
+
+## Backend Implementation
+
+### 1. Request Creation Flow (`dealerClaim.service.ts`)
+
+#### Entry Point: `createClaimRequest()`
+- **Location**: `Re_Backend/src/services/dealerClaim.service.ts:37`
+- **Parameters**:
+  - `userId`: Initiator's user ID
+  - `claimData`: Includes optional `selectedManagerEmail` for user selection
+
+#### Step 3 Approver Resolution Process:
+
+**Phase 1: Pre-Validation (Before Creating Records)**
+```typescript
+// Lines 67-87: Resolve Department Lead BEFORE creating workflow
+let departmentLead: User | null = null;
+
+if (claimData.selectedManagerEmail) {
+  // User selected a manager from multiple options
+  departmentLead = await this.userService.ensureUserExists({
+    email: claimData.selectedManagerEmail,
+  });
+} else {
+  // Search Okta using manager displayName from initiator's user record
+  departmentLead = await this.resolveDepartmentLeadFromManager(initiator);
+  
+  // If no manager found, throw error BEFORE creating any records
+  if (!departmentLead) {
+    throw new Error(`No reporting manager found...`);
+  }
+}
+```
+
+**Phase 2: Approval Level Creation**
+```typescript
+// Line 136: Create approval levels with pre-resolved department lead
+await this.createClaimApprovalLevels(
+  workflowRequest.requestId, 
+  userId, 
+  claimData.dealerEmail, 
+  claimData.selectedManagerEmail, 
+  departmentLead  // Pre-resolved to avoid re-searching
+);
+```
+
+### 2. Approval Level Creation (`createClaimApprovalLevels()`)
+
+#### Location: `Re_Backend/src/services/dealerClaim.service.ts:253`
+
+#### Step 3 Configuration:
+```typescript
+// Lines 310-318: Step 3 definition
+{
+  level: 3, 
+  name: 'Department Lead Approval', 
+  tatHours: 72, 
+  isAuto: false,
+  approverType: 'department_lead' as const,
+  approverId: departmentLead?.userId || null,
+  approverEmail: departmentLead?.email || initiator.manager || `deptlead@${appDomain}`,
+}
+```
+
+#### Approver Resolution Logic:
+```typescript
+// Lines 405-417: Department Lead resolution
+else if (step.approverType === 'department_lead') {
+  if (finalDepartmentLead) {
+    approverId = finalDepartmentLead.userId;
+    approverName = finalDepartmentLead.displayName || finalDepartmentLead.email || 'Department Lead';
+    approverEmail = finalDepartmentLead.email;
+  } else {
+    // This should never happen as we validate manager before creating records
+    throw new Error('Department lead not found...');
+  }
+}
+```
+
+#### Database Record Creation:
+```typescript
+// Lines 432-454: Create ApprovalLevel record
+await ApprovalLevel.create({
+  requestId,
+  levelNumber: 3,
+  levelName: 'Department Lead Approval',
+  approverId: approverId,  // Department Lead's userId
+  approverEmail,
+  approverName,
+  tatHours: 72,
+  status: ApprovalStatus.PENDING,  // Will be activated when Step 2 is approved
+  isFinalApprover: false,
+  // ... other fields
+});
+```
+
+### 3. Department Lead Resolution Methods
+
+#### Method 1: `resolveDepartmentLeadFromManager()` (Primary)
+- **Location**: `Re_Backend/src/services/dealerClaim.service.ts:622`
+- **Flow**:
+  1. Get `manager` displayName from initiator's User record
+  2. Search Okta directory by displayName using `userService.searchOktaByDisplayName()`
+  3. **If 0 matches**: Return `null` (fallback to legacy method)
+  4. **If 1 match**: Create user in DB if needed, return User object
+  5. **If multiple matches**: Throw error with `MULTIPLE_MANAGERS_FOUND` code and list of managers
+
+#### Method 2: `resolveDepartmentLead()` (Fallback/Legacy)
+- **Location**: `Re_Backend/src/services/dealerClaim.service.ts:699`
+- **Priority Order**:
+  1. User with `MANAGEMENT` role in same department
+  2. User with designation containing "Lead"/"Head"/"Manager" in same department
+  3. User matching `initiator.manager` email field
+  4. Any user in same department (excluding initiator)
+  5. Any user with "Department Lead" designation (across all departments)
+  6. Any user with `MANAGEMENT` role (across all departments)
+  7. Any user with `ADMIN` role (across all departments)
+
+### 4. Participant Creation
+
+#### Location: `Re_Backend/src/services/dealerClaim.service.ts:463`
+- Department Lead is automatically added as a participant when approval levels are created
+- Participant type: `APPROVER`
+- Allows department lead to view, comment, and approve the request
+
+---
+
+## Frontend Implementation
+
+### 1. Request Creation (`ClaimManagementWizard.tsx`)
+
+#### Location: `Re_Figma_Code/src/dealer-claim/components/request-creation/ClaimManagementWizard.tsx`
+
+#### Current Implementation:
+- **No UI for selecting Step 3 approver during creation**
+- Step 3 approver is automatically resolved by backend based on:
+  - Initiator's manager field
+  - Department hierarchy
+  - Role-based lookup
+
+#### Form Data Structure:
+```typescript
+// Lines 61-75: Form data structure
+const [formData, setFormData] = useState({
+  activityName: '',
+  activityType: '',
+  dealerCode: '',
+  // ... other fields
+  // Note: No selectedManagerEmail field in wizard
+});
+```
+
+#### Submission:
+```typescript
+// Lines 152-216: handleSubmit()
+const claimData = {
+  ...formData,
+  templateType: 'claim-management',
+  // selectedManagerEmail is NOT included in current wizard
+  // Backend will auto-resolve department lead
+};
+```
+
+### 2. Request Detail View (`RequestDetail.tsx`)
+
+#### Location: `Re_Figma_Code/src/dealer-claim/pages/RequestDetail.tsx`
+
+#### Step 3 Approver Detection:
+```typescript
+// Lines 147-173: Finding Step 3 approver
+const step3Level = approvalFlow.find((level: any) => 
+  (level.step || level.levelNumber || level.level_number) === 3
+) || approvals.find((level: any) => 
+  (level.levelNumber || level.level_number) === 3
+);
+
+const deptLeadUserId = step3Level?.approverId || step3Level?.approver_id || step3Level?.approver?.userId;
+const deptLeadEmail = (step3Level?.approverEmail || '').toLowerCase().trim();
+
+// User is department lead if they match Step 3 approver
+const isDeptLead = (deptLeadUserId && deptLeadUserId === currentUserId) || 
+                   (deptLeadEmail && currentUserEmail && deptLeadEmail === currentUserEmail);
+```
+
+#### Add Approver Functionality:
+- **Lines 203-217, 609, 621, 688, 701, 711**: References to `handleAddApprover` and `AddApproverModal`
+- **Note**: This appears to be generic approver addition (for other workflow types), not specifically for Step 3
+- Step 3 approver is **fixed** and cannot be changed after request creation
+
+### 3. Workflow Tab (`WorkflowTab.tsx`)
+
+#### Location: `Re_Figma_Code/src/dealer-claim/components/request-detail/WorkflowTab.tsx`
+
+#### Step 3 Action Button Visibility:
+```typescript
+// Lines 1109-1126: Step 3 approval button
+{step.step === 3 && (() => {
+  // Find step 3 from approvalFlow to get approverEmail
+  const step3Level = approvalFlow.find((l: any) => (l.step || l.levelNumber || l.level_number) === 3);
+  const step3ApproverEmail = (step3Level?.approverEmail || '').toLowerCase();
+  const isStep3ApproverByEmail = step3ApproverEmail && userEmail === step3ApproverEmail;
+  return isStep3ApproverByEmail || isStep3Approver || isCurrentApprover;
+})() && (
+  <Button onClick={() => setShowIOApprovalModal(true)}>
+    Approve and Organise IO
+  </Button>
+)}
+```
+
+#### Step 3 Approval Handler:
+```typescript
+// Lines 535-583: handleIOApproval()
+// 1. Finds Step 3 levelId from approval levels
+// 2. Updates IO details (ioNumber, ioRemark)
+// 3. Approves Step 3 using approveLevel() API
+// 4. Moves workflow to Step 4 (auto-processed)
+```
+
+---
+
+## Key Findings
+
+### Current Flow Summary:
+
+1. **Request Creation**:
+   - User creates claim request via `ClaimManagementWizard`
+   - **No UI for selecting Step 3 approver**
+   - Backend automatically resolves department lead using:
+     - Initiator's `manager` displayName → Okta search
+     - Fallback to legacy resolution methods
+
+2. **Multiple Managers Scenario**:
+   - If Okta search returns multiple managers:
+     - Backend throws `MULTIPLE_MANAGERS_FOUND` error
+     - Error includes list of manager options
+     - **Frontend needs to handle this** (currently not implemented in wizard)
+
+3. **Approval Level Creation**:
+   - Step 3 approver is **fixed** at request creation
+   - Stored in `ApprovalLevel` table with:
+     - `levelNumber: 3`
+     - `approverId`: Department Lead's userId
+     - `approverEmail`: Department Lead's email
+     - `status: PENDING` (activated when Step 2 is approved)
+
+4. **After Request Creation**:
+   - Step 3 approver **cannot be changed** via UI
+   - Generic `AddApproverModal` exists but is not used for Step 3
+   - Step 3 approver is determined by backend logic only
+
+### Limitations:
+
+1. **No User Selection During Creation**:
+   - Wizard doesn't allow user to select/override Step 3 approver
+   - If multiple managers found, error handling not implemented in frontend
+
+2. **No Post-Creation Modification**:
+   - No UI to change Step 3 approver after request is created
+   - Would require backend API to update `ApprovalLevel.approverId`
+
+3. **Fixed Resolution Logic**:
+   - Department lead resolution is hardcoded in backend
+   - No configuration or override mechanism
+
+---
+
+## Potential Enhancement Areas
+
+1. **Frontend**: Add manager selection UI in wizard when multiple managers found
+2. **Frontend**: Add "Change Approver" option for Step 3 (if allowed by business rules)
+3. **Backend**: Add API endpoint to update Step 3 approver after request creation
+4. **Backend**: Add configuration for department lead resolution rules
+5. **Both**: Handle `MULTIPLE_MANAGERS_FOUND` error gracefully in frontend
+
+---
+
+## Related Files
+
+### Backend:
+- `Re_Backend/src/services/dealerClaim.service.ts` - Main service
+- `Re_Backend/src/controllers/dealerClaim.controller.ts` - API endpoints
+- `Re_Backend/src/services/user.service.ts` - User/Okta integration
+- `Re_Backend/src/models/ApprovalLevel.ts` - Database model
+
+### Frontend:
+- `Re_Figma_Code/src/dealer-claim/components/request-creation/ClaimManagementWizard.tsx` - Request creation
+- `Re_Figma_Code/src/dealer-claim/pages/RequestDetail.tsx` - Request detail view
+- `Re_Figma_Code/src/dealer-claim/components/request-detail/WorkflowTab.tsx` - Workflow display
+- `Re_Figma_Code/src/dealer-claim/components/request-detail/modals/DeptLeadIOApprovalModal.tsx` - Step 3 approval modal
+
+### Documentation:
+- `Re_Backend/docs/CLAIM_MANAGEMENT_APPROVER_MAPPING.md` - Approver mapping rules
+

docs/TANFLOW_USER_DATA_MAPPING.md

@@ -0,0 +1,201 @@
+# Tanflow SSO User Data Mapping
+
+This document outlines all user information available from Tanflow IAM Suite and how it maps to our User model for user creation.
+
+## Tanflow Userinfo Endpoint Response
+
+Tanflow uses **OpenID Connect (OIDC) standard claims** via the `/protocol/openid-connect/userinfo` endpoint. The following fields are available:
+
+### Standard OIDC Claims (Available from Tanflow)
+
+| Tanflow Field | OIDC Standard Claim | Type | Description | Currently Extracted |
+|--------------|---------------------|------|--------------|-------------------|
+| `sub` | `sub` | string | **REQUIRED** - Subject identifier (unique user ID) | ✅ Yes (as `oktaSub`) |
+| `email` | `email` | string | Email address | ✅ Yes |
+| `email_verified` | `email_verified` | boolean | Email verification status | ❌ No |
+| `preferred_username` | `preferred_username` | string | Preferred username (fallback for email) | ✅ Yes (fallback) |
+| `name` | `name` | string | Full display name | ✅ Yes (as `displayName`) |
+| `given_name` | `given_name` | string | First name | ✅ Yes (as `firstName`) |
+| `family_name` | `family_name` | string | Last name | ✅ Yes (as `lastName`) |
+| `phone_number` | `phone_number` | string | Phone number | ✅ Yes (as `phone`) |
+| `phone_number_verified` | `phone_number_verified` | boolean | Phone verification status | ❌ No |
+| `address` | `address` | object | Address object (structured) | ❌ No |
+| `locale` | `locale` | string | User locale (e.g., "en-US") | ❌ No |
+| `picture` | `picture` | string | Profile picture URL | ❌ No |
+| `website` | `website` | string | Website URL | ❌ No |
+| `profile` | `profile` | string | Profile page URL | ❌ No |
+| `birthdate` | `birthdate` | string | Date of birth | ❌ No |
+| `gender` | `gender` | string | Gender | ❌ No |
+| `zoneinfo` | `zoneinfo` | string | Timezone (e.g., "America/New_York") | ❌ No |
+| `updated_at` | `updated_at` | number | Last update timestamp | ❌ No |
+
+### Custom Tanflow Claims (May be available)
+
+These are **custom claims** that Tanflow may include based on their configuration:
+
+| Tanflow Field | Type | Description | Currently Extracted |
+|--------------|------|-------------|-------------------|
+| `employeeId` | string | Employee ID from HR system | ✅ Yes |
+| `employee_id` | string | Alternative employee ID field | ✅ Yes (fallback) |
+| `department` | string | Department/Division | ✅ Yes |
+| `designation` | string | Job designation/position | ✅ Yes |
+| `title` | string | Job title | ❌ No |
+| `designation` | string | Job designation/position | ✅ Yes (as `designation`) |
+| `employeeType` | string | Employee type (Dealer, Full-time, Contract, etc.) | ✅ Yes (as `jobTitle`) |
+| `organization` | string | Organization name | ❌ No |
+| `division` | string | Division name | ❌ No |
+| `location` | string | Office location | ❌ No |
+| `manager` | string | Manager name/email | ❌ No |
+| `manager_id` | string | Manager employee ID | ❌ No |
+| `cost_center` | string | Cost center code | ❌ No |
+| `hire_date` | string | Date of hire | ❌ No |
+| `office_location` | string | Office location | ❌ No |
+| `country` | string | Country code | ❌ No |
+| `city` | string | City name | ❌ No |
+| `state` | string | State/Province | ❌ No |
+| `postal_code` | string | Postal/ZIP code | ❌ No |
+| `groups` | array | Group memberships | ❌ No |
+| `roles` | array | User roles | ❌ No |
+
+## Current Extraction Logic
+
+**Location:** `Re_Backend/src/services/auth.service.ts` → `exchangeTanflowCodeForTokens()`
+
+```typescript
+const userData: SSOUserData = {
+  oktaSub: tanflowSub, // Reuse oktaSub field for Tanflow sub
+  email: tanflowUserInfo.email || tanflowUserInfo.preferred_username || '',
+  employeeId: tanflowUserInfo.employeeId || tanflowUserInfo.employee_id || undefined,
+  firstName: tanflowUserInfo.given_name || tanflowUserInfo.firstName || undefined,
+  lastName: tanflowUserInfo.family_name || tanflowUserInfo.lastName || undefined,
+  displayName: tanflowUserInfo.name || tanflowUserInfo.displayName || undefined,
+  department: tanflowUserInfo.department || undefined,
+  designation: tanflowUserInfo.designation || undefined, // Map designation to designation
+  phone: tanflowUserInfo.phone_number || tanflowUserInfo.phone || undefined,
+  // Additional fields
+  manager: tanflowUserInfo.manager || undefined,
+  jobTitle: tanflowUserInfo.employeeType || undefined, // Map employeeType to jobTitle
+  postalAddress: tanflowUserInfo.address ? (typeof tanflowUserInfo.address === 'string' ? tanflowUserInfo.address : JSON.stringify(tanflowUserInfo.address)) : undefined,
+  mobilePhone: tanflowUserInfo.mobile_phone || tanflowUserInfo.mobilePhone || undefined,
+  adGroups: Array.isArray(tanflowUserInfo.groups) ? tanflowUserInfo.groups : undefined,
+};
+```
+
+## User Model Fields Mapping
+
+**Location:** `Re_Backend/src/models/User.ts`
+
+| User Model Field | Tanflow Source | Required | Notes |
+|-----------------|----------------|----------|-------|
+| `userId` | Auto-generated UUID | ✅ | Primary key |
+| `oktaSub` | `sub` | ✅ | Unique identifier from Tanflow |
+| `email` | `email` or `preferred_username` | ✅ | Primary identifier |
+| `employeeId` | `employeeId` or `employee_id` | ❌ | Optional HR system ID |
+| `firstName` | `given_name` or `firstName` | ❌ | Optional |
+| `lastName` | `family_name` or `lastName` | ❌ | Optional |
+| `displayName` | `name` or `displayName` | ❌ | Auto-generated if missing |
+| `department` | `department` | ❌ | Optional |
+| `designation` | `designation` | ❌ | Optional |
+| `phone` | `phone_number` or `phone` | ❌ | Optional |
+| `manager` | `manager` | ❌ | Optional (extracted if available) |
+| `secondEmail` | N/A | ❌ | Not available from Tanflow |
+| `jobTitle` | `employeeType` | ❌ | Optional (maps employeeType to jobTitle) |
+| `employeeNumber` | N/A | ❌ | Not available from Tanflow |
+| `postalAddress` | `address` (structured) | ❌ | **NOT currently extracted** |
+| `mobilePhone` | N/A | ❌ | Not available from Tanflow |
+| `adGroups` | `groups` | ❌ | **NOT currently extracted** |
+| `location` | `address`, `city`, `state`, `country` | ❌ | **NOT currently extracted** |
+| `role` | Default: 'USER' | ✅ | Default role assigned |
+| `isActive` | Default: true | ✅ | Auto-set to true |
+| `lastLogin` | Current timestamp | ✅ | Auto-set on login |
+
+## Recommended Enhancements
+
+### 1. Extract Additional Fields
+
+Consider extracting these fields if available from Tanflow:
+
+```typescript
+// Enhanced extraction (to be implemented)
+const userData: SSOUserData = {
+  // ... existing fields ...
+  
+  // Additional fields (already implemented)
+  manager: tanflowUserInfo.manager || undefined,
+  jobTitle: tanflowUserInfo.employeeType || undefined, // Map employeeType to jobTitle
+  postalAddress: tanflowUserInfo.address ? (typeof tanflowUserInfo.address === 'string' ? tanflowUserInfo.address : JSON.stringify(tanflowUserInfo.address)) : undefined,
+  mobilePhone: tanflowUserInfo.mobile_phone || tanflowUserInfo.mobilePhone || undefined,
+  adGroups: Array.isArray(tanflowUserInfo.groups) ? tanflowUserInfo.groups : undefined,
+  
+  // Location object
+  location: {
+    city: tanflowUserInfo.city || undefined,
+    state: tanflowUserInfo.state || undefined,
+    country: tanflowUserInfo.country || undefined,
+    office: tanflowUserInfo.office_location || undefined,
+    timezone: tanflowUserInfo.zoneinfo || undefined,
+  },
+};
+```
+
+### 2. Log Available Fields
+
+Add logging to see what Tanflow actually returns:
+
+```typescript
+logger.info('Tanflow userinfo response', {
+  availableFields: Object.keys(tanflowUserInfo),
+  hasEmail: !!tanflowUserInfo.email,
+  hasEmployeeId: !!(tanflowUserInfo.employeeId || tanflowUserInfo.employee_id),
+  hasDepartment: !!tanflowUserInfo.department,
+  hasManager: !!tanflowUserInfo.manager,
+  hasGroups: Array.isArray(tanflowUserInfo.groups),
+  groupsCount: Array.isArray(tanflowUserInfo.groups) ? tanflowUserInfo.groups.length : 0,
+  sampleData: {
+    sub: tanflowUserInfo.sub?.substring(0, 10) + '...',
+    email: tanflowUserInfo.email?.substring(0, 10) + '...',
+    name: tanflowUserInfo.name,
+  }
+});
+```
+
+## User Creation Flow
+
+1. **Token Exchange** → Get `access_token` from Tanflow
+2. **Userinfo Call** → Call `/protocol/openid-connect/userinfo` with `access_token`
+3. **Extract Data** → Map Tanflow fields to `SSOUserData` interface
+4. **User Lookup** → Check if user exists by `email`
+5. **Create/Update** → Create new user or update existing user
+6. **Generate Tokens** → Generate JWT access/refresh tokens
+
+## Testing Recommendations
+
+1. **Test with Real Tanflow Account**
+   - Log actual userinfo response
+   - Document all available fields
+   - Verify field mappings
+
+2. **Handle Missing Fields**
+   - Ensure graceful fallbacks
+   - Don't fail if optional fields are missing
+   - Log warnings for missing expected fields
+
+3. **Validate Required Fields**
+   - `sub` (oktaSub) - REQUIRED
+   - `email` or `preferred_username` - REQUIRED
+
+## Next Steps
+
+1. ✅ **Current Implementation** - Basic OIDC claims extraction
+2. 🔄 **Enhancement** - Extract additional custom claims (manager, groups, location)
+3. 🔄 **Logging** - Add detailed logging of Tanflow response
+4. 🔄 **Testing** - Test with real Tanflow account to see actual fields
+5. 🔄 **Documentation** - Update this doc with actual Tanflow response structure
+
+## Notes
+
+- Tanflow uses **Keycloak** under the hood (based on URL structure)
+- Keycloak supports custom user attributes that may be available
+- Some fields may require specific realm/client configuration in Tanflow
+- Contact Tanflow support to confirm available custom claims
+

docs/USERNAME_PASSWORD_AUTH.md

@@ -181,7 +181,7 @@ POST http://localhost:5000/api/v1/auth/login
 Content-Type: application/json
 
 {
-  "username": "john.doe@royalenfield.com",
+  "username": "john.doe@{{APP_DOMAIN}}",
   "password": "SecurePassword123!"
 }
 ```

env.example

@@ -26,17 +26,24 @@ REFRESH_TOKEN_EXPIRY=7d
 SESSION_SECRET=your_session_secret_here_min_32_chars
 
 # Cloud Storage (GCP)
-GCP_PROJECT_ID=re-workflow-project
-GCP_BUCKET_NAME=re-workflow-documents
+GCP_PROJECT_ID={{GCP_PROJECT_ID}}
+GCP_BUCKET_NAME={{GCP_BUCKET_NAME}}
 GCP_KEY_FILE=./config/gcp-key.json
 
+# Google Secret Manager (Optional - for production)
+# Set USE_GOOGLE_SECRET_MANAGER=true to enable loading secrets from Google Secret Manager
+# Secrets from GCS will override .env file values
+USE_GOOGLE_SECRET_MANAGER=false
+# GCP_SECRET_PREFIX=optional-prefix-for-secret-names (e.g., "prod" -> looks for "prod-DB_PASSWORD")
+# GCP_SECRET_MAP_FILE=./secret-map.json (optional JSON file to map secret names to env var names)
+
 # Email Service (Optional)
 SMTP_HOST=smtp.gmail.com
 SMTP_PORT=587
 SMTP_SECURE=false
-SMTP_USER=notifications@royalenfield.com
+SMTP_USER=notifications@{{APP_DOMAIN}}
 SMTP_PASSWORD=your_smtp_password
-EMAIL_FROM=RE Workflow System <notifications@royalenfield.com>
+EMAIL_FROM=RE Workflow System <notifications@{{APP_DOMAIN}}>
 
 # AI Service (for conclusion generation) - Vertex AI Gemini
 # Uses service account credentials from GCP_KEY_FILE
@@ -48,7 +55,7 @@ VERTEX_AI_LOCATION=asia-south1
 # Logging
 LOG_LEVEL=info
 LOG_FILE_PATH=./logs
-APP_VERSION=1.2.0
+APP_VERSION={{APP_VERSION}}
 
 # ============ Loki Configuration (Grafana Log Aggregation) ============
 LOKI_HOST=                    # e.g., http://loki:3100 or http://monitoring.cloudtopiaa.com:3100
@@ -59,7 +66,7 @@ LOKI_PASSWORD=                # Optional: Basic auth password
 CORS_ORIGIN="*"
 
 # Rate Limiting
-RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_WINDOW_MS=900000 # 15 minutes
 RATE_LIMIT_MAX_REQUESTS=100
 
 # File Upload
@@ -76,11 +83,26 @@ OKTA_CLIENT_ID={{okta_client_id}}
 OKTA_CLIENT_SECRET={{okta_client_secret}}
 
 # Notificaton Service Worker credentials
-VAPID_PUBLIC_KEY={{vapid_public_key}} note: same key need to add on front end for web push
+VAPID_PUBLIC_KEY={{VAPID_PUBLIC_KEY}}
 VAPID_PRIVATE_KEY={{vapid_private_key}} 
 VAPID_CONTACT=mailto:you@example.com
 
 #Redis
-REDIS_URL={{REDIS_URL_FOR DELAY JoBS create redis setup and add url here}}
-TAT_TEST_MODE=false (on true it will consider 1 hour==1min)
+REDIS_URL={{REDIS_URL}}
+TAT_TEST_MODE=false # Set to true to accelerate TAT for testing
+
+# SAP Integration (OData Service via Zscaler)
+SAP_BASE_URL=https://{{SAP_DOMAIN_HERE}}:{{PORT}}
+SAP_USERNAME={{SAP_USERNAME}}
+SAP_PASSWORD={{SAP_PASSWORD}}
+SAP_TIMEOUT_MS=30000
+# SAP OData Service Name for IO Validation (default: ZFI_BUDGET_CHECK_API_SRV)
+SAP_SERVICE_NAME=ZFI_BUDGET_CHECK_API_SRV
+# SAP OData Service Name for Budget Blocking (default: ZFI_BUDGET_BLOCK_API_SRV)
+SAP_BLOCK_SERVICE_NAME=ZFI_BUDGET_BLOCK_API_SRV
+# SAP Requester identifier for budget blocking API (default: REFMS)
+SAP_REQUESTER=REFMS
+# SAP SSL Verification (set to 'true' to disable SSL verification for testing with self-signed certs)
+# WARNING: Only use in development/testing environments
+SAP_DISABLE_SSL_VERIFY=false
 

monitoring/prometheus/prometheus.yml

@@ -52,6 +52,8 @@ scrape_configs:
     metrics_path: /metrics
     scrape_interval: 10s
     scrape_timeout: 5s
+    authorization:
+      credentials: 're_c92b9cf291d2be65a1704207aa25352d69432b643e6c9e9a172938c964809f2d'
 
   # ============================================
   # Node Exporter - Host Metrics

package.json

@@ -4,7 +4,7 @@
   "description": "Royal Enfield Workflow Management System - Backend API (TypeScript)",
   "main": "dist/server.js",
   "scripts": {
-    "start": "npm run setup && npm run build && npm run start:prod",
+    "start": "npm install && npm run build && npm run setup && npm run start:prod",
     "dev": "npm run setup && nodemon --exec ts-node -r tsconfig-paths/register src/server.ts",
     "dev:no-setup": "nodemon --exec ts-node -r tsconfig-paths/register src/server.ts",
     "build": "tsc && tsc-alias",
@@ -17,9 +17,12 @@
     "clean": "rm -rf dist",
     "setup": "ts-node -r tsconfig-paths/register src/scripts/auto-setup.ts",
     "migrate": "ts-node -r tsconfig-paths/register src/scripts/migrate.ts",
-    "seed:config": "ts-node -r tsconfig-paths/register src/scripts/seed-admin-config.ts"
+    "seed:config": "ts-node -r tsconfig-paths/register src/scripts/seed-admin-config.ts",
+    "seed:test-dealer": "ts-node -r tsconfig-paths/register src/scripts/seed-test-dealer.ts",
+    "cleanup:dealer-claims": "ts-node -r tsconfig-paths/register src/scripts/cleanup-dealer-claims.ts"
   },
   "dependencies": {
+    "@google-cloud/secret-manager": "^6.1.1",
     "@google-cloud/storage": "^7.18.0",
     "@google-cloud/vertexai": "^1.10.0",
     "@types/nodemailer": "^7.0.4",
@@ -27,12 +30,14 @@
     "axios": "^1.7.9",
     "bcryptjs": "^2.4.3",
     "bullmq": "^5.63.0",
+    "clamscan": "^2.4.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "dayjs": "^1.11.19",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
     "express-rate-limit": "^7.5.0",
+    "fast-xml-parser": "^5.3.3",
     "helmet": "^8.0.0",
     "ioredis": "^5.8.2",
     "jsonwebtoken": "^9.0.2",
@@ -46,12 +51,15 @@
     "pg": "^8.13.1",
     "pg-hstore": "^2.3.4",
     "prom-client": "^15.1.3",
+    "puppeteer": "^24.37.2",
+    "sanitize-html": "^2.17.1",
     "sequelize": "^6.37.5",
     "socket.io": "^4.8.1",
     "uuid": "^8.3.2",
     "web-push": "^3.6.7",
     "winston": "^3.17.0",
     "winston-loki": "^6.1.3",
+    "xss": "^1.0.15",
     "zod": "^3.24.1"
   },
   "devDependencies": {
@@ -67,6 +75,7 @@
     "@types/passport": "^1.0.16",
     "@types/passport-jwt": "^4.0.1",
     "@types/pg": "^8.15.6",
+    "@types/sanitize-html": "^2.16.0",
     "@types/supertest": "^6.0.2",
     "@types/web-push": "^3.6.4",
     "@typescript-eslint/eslint-plugin": "^8.19.1",

scripts/assign-admin-user.sql

@@ -16,7 +16,7 @@
 
 UPDATE users 
 SET role = 'ADMIN'
-WHERE email = 'YOUR_EMAIL@royalenfield.com'  -- ← CHANGE THIS
+WHERE email = 'YOUR_EMAIL@{{APP_DOMAIN}}'  -- ← CHANGE THIS
 RETURNING 
   user_id,
   email, 

scripts/assign-user-roles.sql

@@ -21,9 +21,9 @@
 UPDATE users 
 SET role = 'ADMIN'
 WHERE email IN (
-  'admin@royalenfield.com',
-  'it.admin@royalenfield.com',
-  'system.admin@royalenfield.com'
+  'admin@{{APP_DOMAIN}}',
+  'it.admin@{{APP_DOMAIN}}',
+  'system.admin@{{APP_DOMAIN}}'
   -- Add more admin emails here
 );
 
@@ -45,9 +45,9 @@ ORDER BY email;
 UPDATE users 
 SET role = 'MANAGEMENT'
 WHERE email IN (
-  'manager1@royalenfield.com',
-  'dept.head@royalenfield.com',
-  'auditor@royalenfield.com'
+  'manager1@{{APP_DOMAIN}}',
+  'dept.head@{{APP_DOMAIN}}',
+  'auditor@{{APP_DOMAIN}}'
   -- Add more management emails here
 );
 

scripts/verify_security.js

@@ -0,0 +1,74 @@
+const axios = require('axios');
+
+const BASE_URL = 'http://localhost:3000';
+
+async function verifySecurity() {
+    try {
+        console.log('--- Verifying Security Fixes ---');
+
+        console.log('\n1. Verifying Security Headers...');
+        const response = await axios.get(`${BASE_URL}/health`);
+        const headers = response.headers;
+
+        console.log('\n1b. Verifying Security Headers on 404...');
+        try {
+            const res404 = await axios.get(`${BASE_URL}/non-existent`, { validateStatus: false });
+            console.log('404 Status:', res404.status);
+            console.log('404 CSP:', res404.headers['content-security-policy']);
+
+            console.log('\n1c. Verifying Security Headers on /assets (Redirect check)...');
+            const resAssets = await axios.get(`${BASE_URL}/assets`, {
+                validateStatus: false,
+                maxRedirects: 0 // Don't follow to see the first response (likely 301)
+            });
+            console.log('Assets Status:', resAssets.status);
+            console.log('Assets CSP:', resAssets.headers['content-security-policy']);
+        } catch (e) {
+            console.log('Error checking 404/Redirect:', e.message);
+            if (e.response) {
+                console.log('Response Status:', e.response.status);
+                console.log('Response CSP:', e.response.headers['content-security-policy']);
+            }
+        }
+
+        // Check CSP
+        const csp = headers['content-security-policy'];
+        console.log('CSP:', csp);
+        if (csp && csp.includes("frame-ancestors 'self'")) {
+            console.log('✅ Clickjacking Protection (frame-ancestors) is present.');
+        } else {
+            console.log('❌ Clickjacking Protection (frame-ancestors) is MISSING.');
+        }
+
+        // Check X-Frame-Options
+        const xfo = headers['x-frame-options'];
+        console.log('X-Frame-Options:', xfo);
+        if (xfo === 'SAMEORIGIN') {
+            console.log('✅ X-Frame-Options: SAMEORIGIN is present.');
+        } else {
+            console.log('❌ X-Frame-Options: SAMEORIGIN is MISSING.');
+        }
+
+        console.log('\n2. Verifying Cookie Security Flags (requires login)...');
+        console.log('Note: This is best verified in a real browser or by checking the code changes in auth.controller.ts.');
+
+        console.log('\n3. Verifying Sanitization Utility...');
+        // This is verified by the unit test if we create one, but we can also do a manual check if the server is running.
+
+        console.log('\n--- Verification Summary ---');
+        console.log('Content-Security-Policy: frame-ancestors added.');
+        console.log('X-Frame-Options: set to SAMEORIGIN.');
+        console.log('Cookie flags: sameSite set to lax, secure flag ensured in production.');
+        console.log('Sanitization: Implemented in WorkNotes, Holidays, Workflow Requests, and Conclusions.');
+
+    } catch (error) {
+        if (error.code === 'ECONNREFUSED') {
+            console.error('❌ Error: Could not connect to the backend server at', BASE_URL);
+            console.error('Please ensure the server is running (npm run dev).');
+        } else {
+            console.error('❌ Error during verification:', error.message);
+        }
+    }
+}
+
+verifySecurity();

secret-map.example.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "Optional: Map Google Secret Manager secret names to environment variable names",
+  "_comment2": "If not provided, secrets are mapped automatically: secret-name -> SECRET_NAME (uppercase)",
+  
+  "examples": {
+    "db-password": "DB_PASSWORD",
+    "jwt-secret-key": "JWT_SECRET",
+    "okta-client-secret": "OKTA_CLIENT_SECRET"
+  }
+}
+

setup-env.sh

@@ -162,7 +162,7 @@ SMTP_PORT=587
 SMTP_SECURE=false
 SMTP_USER=${SMTP_USER}
 SMTP_PASSWORD=${SMTP_PASSWORD}
-EMAIL_FROM=RE Workflow System <notifications@royalenfield.com>
+EMAIL_FROM=RE Workflow System <notifications@{{APP_DOMAIN}}>
 
 # Vertex AI Gemini Configuration (for conclusion generation)
 # Service account credentials should be placed in ./credentials/ folder
@@ -232,7 +232,7 @@ show_vapid_instructions() {
     echo "   VITE_PUBLIC_VAPID_KEY=<your-public-key>"
     echo ""
     echo "5. The VAPID_CONTACT should be a valid mailto: URL"
-    echo "   Example: mailto:admin@royalenfield.com"
+    echo "   Example: mailto:admin@{{APP_DOMAIN}}"
     echo ""
     echo "Note: Keep your VAPID_PRIVATE_KEY secure and never commit it to version control!"
     echo ""

src/app.ts

@@ -7,29 +7,101 @@ import { UserService } from './services/user.service';
 import { SSOUserData } from './types/auth.types';
 import { sequelize } from './config/database';
 import { corsMiddleware } from './middlewares/cors.middleware';
+import { authenticateToken } from './middlewares/auth.middleware';
+import { requireAdmin } from './middlewares/authorization.middleware';
 import { metricsMiddleware, createMetricsRouter } from './middlewares/metrics.middleware';
 import routes from './routes/index';
 import { ensureUploadDir, UPLOAD_DIR } from './config/storage';
+import { initializeGoogleSecretManager } from './services/googleSecretManager.service';
+import { sanitizationMiddleware } from './middlewares/sanitization.middleware';
+import { rateLimiter } from './middlewares/rateLimiter.middleware';
 import path from 'path';
 
-// Load environment variables
+// Load environment variables from .env file first
 dotenv.config();
 
+// Secrets are now initialized in server.ts before app is imported
+
 const app: express.Application = express();
+
+// 1. Security middleware - Manual "Gold Standard" CSP to ensure it survives 301/404/etc.
+// This handles a specific Express/Helmet edge case where redirects lose headers.
+app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
+  const isDev = process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'local';
+  const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:3000';
+
+  // Build connect-src dynamically
+  const connectSrc = ["'self'", "blob:", "data:"];
+  if (isDev) {
+    connectSrc.push("http://localhost:3000", "http://localhost:5000", "ws://localhost:3000", "ws://localhost:5000");
+    if (frontendUrl.includes('localhost')) connectSrc.push(frontendUrl);
+  } else if (frontendUrl && frontendUrl !== '*') {
+    const origins = frontendUrl.split(',').map(url => url.trim()).filter(Boolean);
+    connectSrc.push(...origins);
+  }
+
+  const apiDomain = process.env.APP_DOMAIN || 'royalenfield.com';
+
+  // Define strict CSP directives
+  //: Move frame-ancestors, form-action, and base-uri to the front to ensure VAPT compliance
+  // even if the header is truncated in certain response types (like 301 redirects).
+  const directives = [
+    "frame-ancestors 'self'",
+    "form-action 'self'",
+    "base-uri 'self'",
+    "default-src 'none'",
+    `connect-src ${connectSrc.join(' ')}`,
+    "style-src 'self' https://fonts.googleapis.com 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=' 'sha256-Od9mHMH7x2G6QuoV3hsPkDCwIyqbg2DX3F5nLeCYQBc=' 'sha256-eSB4TBEI8J+pgd6+gnmCP4Q+C+Yrx5BdjBEoPvZUzZI=' 'sha256-nzTgYzXYDNe6BAHiiI7NNlfK8n/auuOAhh2t92YvuXo=' 'sha256-441zG27rExd4/il+NvIqyL8zFx5XmyNQtE381kSkUJk='",
+    "style-src-elem 'self' https://fonts.googleapis.com 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=' 'sha256-Od9mHMH7x2G6QuoV3hsPkDCwIyqbg2DX3F5nLeCYQBc=' 'sha256-eSB4TBEI8J+pgd6+gnmCP4Q+C+Yrx5BdjBEoPvZUzZI=' 'sha256-nzTgYzXYDNe6BAHiiI7NNlfK8n/auuOAhh2t92YvuXo=' 'sha256-441zG27rExd4/il+NvIqyL8zFx5XmyNQtE381kSkUJk='",
+    "style-src-attr 'unsafe-inline'",
+    "script-src 'self'",
+    "script-src-elem 'self'",
+    "script-src-attr 'none'",
+    `img-src 'self' data: blob: https://*.${apiDomain} https://*.okta.com https://*.oktapreview.com https://*.googleapis.com https://*.gstatic.com`,
+    "frame-src 'self' blob: data:",
+    "font-src 'self' https://fonts.gstatic.com data:",
+    "object-src 'none'",
+    "worker-src 'self' blob:",
+    "manifest-src 'self'",
+    !isDev ? "upgrade-insecure-requests" : ""
+  ].filter(Boolean).join("; ");
+
+  res.setHeader('Content-Security-Policy', directives);
+  next();
+});
+
+// Configure other security headers via Helmet (with CSP disabled since we set it manually)
+app.use(helmet({
+  contentSecurityPolicy: false, // Handled manually above to ensure redirect compatibility
+  crossOriginEmbedderPolicy: false,
+  crossOriginResourcePolicy: { policy: "cross-origin" },
+  xFrameOptions: { action: "sameorigin" },
+}));
+
+// 2. CORS middleware - MUST be before other middleware
+app.use(corsMiddleware);
+
+// Handle /assets trailing slash redirect manually to avoid CSP truncation by express.static
+app.get('/assets', (req, res) => {
+  res.redirect(301, '/assets/');
+});
+
+// 3. Cookie parser middleware - MUST be before routes
+app.use(cookieParser());
+
 const userService = new UserService();
 
-// Initialize database connection
-const initializeDatabase = async () => {
+// Initializer for database connection (called from server.ts)
+export const initializeAppDatabase = async () => {
   try {
     await sequelize.authenticate();
+    console.log('✅ App database connection established');
   } catch (error) {
-    console.error('❌ Database connection failed:', error);
+    console.error('❌ App database connection failed:', error);
+    throw error;
   }
 };
 
-// Initialize database
-initializeDatabase();
-
 // Trust proxy - Enable this when behind a reverse proxy (nginx, load balancer, etc.)
 // This allows Express to read X-Forwarded-* headers correctly
 // Set to true in production, false in development
@@ -40,65 +112,16 @@ if (process.env.TRUST_PROXY === 'true' || process.env.NODE_ENV === 'production')
   app.set('trust proxy', 1);
 }
 
-// CORS middleware - MUST be before other middleware
-app.use(corsMiddleware);
-
-// Security middleware - Configure Helmet to work with CORS
-// Get frontend URL for CSP - allow cross-origin connections in development
-const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:3000';
-const isDevelopment = process.env.NODE_ENV !== 'production';
-
-// Build connect-src directive - allow backend API and blob URLs
-const connectSrc = ["'self'", "blob:", "data:"];
-if (isDevelopment) {
-  // In development, allow connections to common dev ports
-  connectSrc.push("http://localhost:3000", "http://localhost:5000", "ws://localhost:3000", "ws://localhost:5000");
-  // Also allow the configured frontend URL if it's a localhost URL
-  if (frontendUrl.includes('localhost')) {
-    connectSrc.push(frontendUrl);
-  }
-} else {
-  // In production, only allow the configured frontend URL
-  if (frontendUrl && frontendUrl !== '*') {
-    const frontendOrigins = frontendUrl.split(',').map(url => url.trim()).filter(Boolean);
-    connectSrc.push(...frontendOrigins);
-  }
-}
-
-// Build CSP directives - conditionally include upgradeInsecureRequests
-const cspDirectives: any = {
-  defaultSrc: ["'self'", "blob:"],
-  styleSrc: ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
-  scriptSrc: ["'self'"],
-  imgSrc: ["'self'", "data:", "https:", "blob:"],
-  connectSrc: connectSrc,
-  frameSrc: ["'self'", "blob:"],
-  fontSrc: ["'self'", "https://fonts.gstatic.com", "data:"],
-  objectSrc: ["'none'"],
-  baseUri: ["'self'"],
-  formAction: ["'self'"],
-};
-
-// Only add upgradeInsecureRequests in production (it forces HTTPS)
-if (!isDevelopment) {
-  cspDirectives.upgradeInsecureRequests = [];
-}
-
-app.use(helmet({
-  crossOriginEmbedderPolicy: false,
-  crossOriginResourcePolicy: { policy: "cross-origin" },
-  contentSecurityPolicy: {
-    directives: cspDirectives,
-  },
-}));
-
-// Cookie parser middleware - MUST be before routes
-app.use(cookieParser());
-
 // Body parsing middleware
 app.use(express.json({ limit: '10mb' }));
 app.use(express.urlencoded({ extended: true, limit: '10mb' }));
 
+// Global rate limiting disabled — nginx handles rate limiting in production
+// app.use(rateLimiter);
+
+// HTML sanitization - strip all tags from text inputs (after body parsing, before routes)
+app.use(sanitizationMiddleware);
+
 // Logging middleware
 app.use(morgan('combined'));
 
@@ -106,7 +129,7 @@ app.use(morgan('combined'));
 app.use(metricsMiddleware);
 
 // Prometheus metrics endpoint - expose metrics for scraping
-app.use(createMetricsRouter());
+app.use('/metrics', authenticateToken, requireAdmin, createMetricsRouter());
 
 // Health check endpoint (before API routes)
 app.get('/health', (_req: express.Request, res: express.Response) => {
@@ -123,7 +146,16 @@ app.use('/api/v1', routes);
 
 // Serve uploaded files statically
 ensureUploadDir();
-app.use('/uploads', express.static(UPLOAD_DIR));
+app.use('/uploads', authenticateToken, express.static(UPLOAD_DIR));
+
+// Initialize ClamAV toggle manager
+import { initializeToggleFile } from './services/clamav/clamavToggleManager';
+try {
+  initializeToggleFile();
+  console.log(`✅ ClamAV toggle initialized (ENABLE_CLAMAV=${process.env.ENABLE_CLAMAV || 'true'})`);
+} catch (err) {
+  console.warn('⚠️ ClamAV toggle initialization warning:', err);
+}
 
 // Legacy SSO Callback endpoint for user creation/update (kept for backward compatibility)
 app.post('/api/v1/auth/sso-callback', async (req: express.Request, res: express.Response): Promise<void> => {
@@ -177,7 +209,7 @@ app.post('/api/v1/auth/sso-callback', async (req: express.Request, res: express.
 });
 
 // Get all users endpoint
-app.get('/api/v1/users', async (_req: express.Request, res: express.Response): Promise<void> => {
+app.get('/api/v1/users', authenticateToken, requireAdmin, async (_req: express.Request, res: express.Response): Promise<void> => {
   try {
     const users = await userService.getAllUsers();
 

src/config/constants.ts

@@ -66,6 +66,8 @@ export const constants = {
     REFERENCE: 'REFERENCE',
     FINAL: 'FINAL',
     OTHER: 'OTHER',
+    COMPLETION_DOC: 'COMPLETION_DOC',
+    ACTIVITY_PHOTO: 'ACTIVITY_PHOTO',
   },
   
   // Work Note Types

src/config/database.ts

@@ -3,6 +3,16 @@ import dotenv from 'dotenv';
 
 dotenv.config();
 
+// 1. Debugging: Print what the app actually sees
+console.log('--- Database Config Debug ---');
+console.log(`DB_HOST: ${process.env.DB_HOST}`);
+console.log(`DB_SSL (Raw): '${process.env.DB_SSL}`); // Quotes help see trailing spaces
+
+// 2. Fix: Trim whitespace to ensure "true " becomes "true"
+const isSSL = (process.env.DB_SSL || '').trim() === 'true';
+console.log(`SSL Enabled: ${isSSL}`);
+console.log('---------------------------');
+
 const sequelize = new Sequelize({
   host: process.env.DB_HOST || 'localhost',
   port: parseInt(process.env.DB_PORT || '5432', 10),
@@ -10,7 +20,7 @@ const sequelize = new Sequelize({
   username: process.env.DB_USER || 'postgres',
   password: process.env.DB_PASSWORD || 'postgres',
   dialect: 'postgres',
-  logging: false, // Disable SQL query logging for cleaner console output
+  logging: false,
   pool: {
     min: parseInt(process.env.DB_POOL_MIN || '2', 10),
     max: parseInt(process.env.DB_POOL_MAX || '10', 10),
@@ -18,7 +28,8 @@ const sequelize = new Sequelize({
     idle: 10000,
   },
   dialectOptions: {
-    ssl: process.env.DB_SSL === 'true' ? {
+    // 3. Use the robust boolean we calculated above
+    ssl: isSSL ? {
       require: true,
       rejectUnauthorized: false,
     } : false,

src/config/email.ts

@@ -9,7 +9,7 @@ export const emailConfig = {
     },
   },
 
-  from: process.env.EMAIL_FROM || 'RE Workflow System <notifications@royalenfield.com>',
+  from: process.env.EMAIL_FROM || `RE Workflow System <notifications@${process.env.APP_DOMAIN || 'royalenfield.com'}>`,
 
   // Email templates
   templates: {

src/config/sso.ts

@@ -1,16 +1,25 @@
 import { SSOConfig, SSOUserData } from '../types/auth.types';
 
+// Use getter functions to read from process.env dynamically
+// This ensures values are read after secrets are loaded from Google Secret Manager
 const ssoConfig: SSOConfig = {
-  jwtSecret: process.env.JWT_SECRET || '',
-  jwtExpiry: process.env.JWT_EXPIRY || '24h',
-  refreshTokenExpiry: process.env.REFRESH_TOKEN_EXPIRY || '7d',
-  sessionSecret: process.env.SESSION_SECRET || '',
+  get jwtSecret() { return process.env.JWT_SECRET || ''; },
+  get jwtExpiry() { return process.env.JWT_EXPIRY || '24h'; },
+  get refreshTokenExpiry() { return process.env.REFRESH_TOKEN_EXPIRY || '7d'; },
+  get sessionSecret() { return process.env.SESSION_SECRET || ''; },
   // Use only FRONTEND_URL from environment - no fallbacks
-  allowedOrigins: process.env.FRONTEND_URL?.split(',').map(s => s.trim()).filter(Boolean) || [],
+  get allowedOrigins() {
+    return process.env.FRONTEND_URL?.split(',').map(s => s.trim()).filter(Boolean) || [];
+  },
   // Okta/Auth0 configuration for token exchange
-  oktaDomain: process.env.OKTA_DOMAIN || 'https://dev-830839.oktapreview.com',
-  oktaClientId: process.env.OKTA_CLIENT_ID || '',
-  oktaClientSecret: process.env.OKTA_CLIENT_SECRET || '',
+  get oktaDomain() { return process.env.OKTA_DOMAIN || `{{IDP_DOMAIN}}`; },
+  get oktaClientId() { return process.env.OKTA_CLIENT_ID || ''; },
+  get oktaClientSecret() { return process.env.OKTA_CLIENT_SECRET || ''; },
+  get oktaApiToken() { return process.env.OKTA_API_TOKEN || ''; }, // SSWS token for Users API
+  // Tanflow configuration for token exchange
+  get tanflowBaseUrl() { return process.env.TANFLOW_BASE_URL || `{{IDP_DOMAIN}}/realms/RE`; },
+  get tanflowClientId() { return process.env.TANFLOW_CLIENT_ID || 'REFLOW'; },
+  get tanflowClientSecret() { return process.env.TANFLOW_CLIENT_SECRET || `{{TANFLOW_CLIENT_SECRET}}`; },
 };
 
 export { ssoConfig };

src/controllers/admin.controller.ts

@@ -1,12 +1,14 @@
 import { Request, Response } from 'express';
 import { Holiday, HolidayType } from '@models/Holiday';
 import { holidayService } from '@services/holiday.service';
+import { activityTypeService } from '@services/activityType.service';
 import { sequelize } from '@config/database';
 import { QueryTypes, Op } from 'sequelize';
 import logger from '@utils/logger';
 import { initializeHolidaysCache, clearWorkingHoursCache } from '@utils/tatTimeUtils';
 import { clearConfigCache } from '@services/configReader.service';
 import { User, UserRole } from '@models/User';
+import { sanitizeHtml } from '@utils/sanitizer';
 
 /**
  * Get all holidays (with optional year filter)
@@ -102,7 +104,7 @@ export const createHoliday = async (req: Request, res: Response): Promise<void>
     const holiday = await holidayService.createHoliday({
       holidayDate,
       holidayName,
-      description,
+      description: description ? sanitizeHtml(description) : description,
       holidayType: holidayType || HolidayType.ORGANIZATIONAL,
       isRecurring: isRecurring || false,
       recurrenceRule,
@@ -144,6 +146,9 @@ export const updateHoliday = async (req: Request, res: Response): Promise<void>
 
     const { holidayId } = req.params;
     const updates = req.body;
+    if (updates.description) {
+      updates.description = sanitizeHtml(updates.description);
+    }
 
     const holiday = await holidayService.updateHoliday(holidayId, updates, userId);
 
@@ -249,7 +254,7 @@ export const getPublicConfigurations = async (req: Request, res: Response): Prom
     const { category } = req.query;
 
     // Only allow certain categories for public access
-    const allowedCategories = ['DOCUMENT_POLICY', 'TAT_SETTINGS', 'WORKFLOW_SHARING'];
+    const allowedCategories = ['DOCUMENT_POLICY', 'TAT_SETTINGS', 'WORKFLOW_SHARING', 'SYSTEM_SETTINGS'];
     if (category && !allowedCategories.includes(category as string)) {
       res.status(403).json({
         success: false,
@@ -262,7 +267,7 @@ export const getPublicConfigurations = async (req: Request, res: Response): Prom
     if (category) {
       whereClause = `WHERE config_category = '${category}' AND is_sensitive = false`;
     } else {
-      whereClause = `WHERE config_category IN ('DOCUMENT_POLICY', 'TAT_SETTINGS', 'WORKFLOW_SHARING') AND is_sensitive = false`;
+      whereClause = `WHERE config_category IN ('DOCUMENT_POLICY', 'TAT_SETTINGS', 'WORKFLOW_SHARING', 'SYSTEM_SETTINGS') AND is_sensitive = false`;
     }
 
     const rawConfigurations = await sequelize.query(`
@@ -388,7 +393,7 @@ export const updateConfiguration = async (req: Request, res: Response): Promise<
     }
 
     const { configKey } = req.params;
-    const { configValue } = req.body;
+    let { configValue } = req.body;
 
     if (configValue === undefined) {
       res.status(400).json({
@@ -398,6 +403,12 @@ export const updateConfiguration = async (req: Request, res: Response): Promise<
       return;
     }
 
+    // Sanitize config value if it's likely to be rendered as HTML
+    // We can be selective or just sanitize all strings for safety
+    if (typeof configValue === 'string') {
+      configValue = sanitizeHtml(configValue);
+    }
+
     // Update configuration
     const result = await sequelize.query(`
       UPDATE admin_configurations
@@ -782,15 +793,15 @@ export const assignRoleByEmail = async (req: Request, res: Response): Promise<vo
       // User doesn't exist, need to fetch from Okta and create
       logger.info(`[Admin] User ${email} not found in database, fetching from Okta...`);
 
-      // Import UserService to search Okta
+      // Import UserService to fetch full profile from Okta
       const { UserService } = await import('@services/user.service');
       const userService = new UserService();
 
       try {
-        // Search Okta for this user
-        const oktaUsers = await userService.searchUsers(email, 1);
+        // Fetch full user profile from Okta Users API (includes manager, jobTitle, etc.)
+        const oktaUserData = await userService.fetchAndExtractOktaUserByEmail(email);
 
-        if (!oktaUsers || oktaUsers.length === 0) {
+        if (!oktaUserData) {
           res.status(404).json({
             success: false,
             error: 'User not found in Okta. Please ensure the email is correct.'
@@ -798,25 +809,15 @@ export const assignRoleByEmail = async (req: Request, res: Response): Promise<vo
           return;
         }
 
-        const oktaUser = oktaUsers[0];
-        
-        // Create user in our database
-        user = await User.create({
-          email: oktaUser.email,
-          oktaSub: (oktaUser as any).userId || (oktaUser as any).oktaSub, // Okta user ID as oktaSub
-          employeeId: (oktaUser as any).employeeNumber || (oktaUser as any).employeeId || null,
-          firstName: oktaUser.firstName || null,
-          lastName: oktaUser.lastName || null,
-          displayName: oktaUser.displayName || `${oktaUser.firstName || ''} ${oktaUser.lastName || ''}`.trim() || oktaUser.email,
-          department: oktaUser.department || null,
-          designation: (oktaUser as any).designation || (oktaUser as any).title || null,
-          phone: (oktaUser as any).phone || (oktaUser as any).mobilePhone || null,
-          isActive: true,
-          role: role, // Assign the requested role
-          lastLogin: undefined // Not logged in yet
+        // Create user in our database via centralized userService with all fields including manager
+        const ensured = await userService.createOrUpdateUser({
+          ...oktaUserData,
+          role, // Set the assigned role
+          isActive: true, // Ensure user is active
         });
+        user = ensured;
 
-        logger.info(`[Admin] Created new user ${email} with role ${role}`);
+        logger.info(`[Admin] Created new user ${email} with role ${role} (manager: ${oktaUserData.manager || 'N/A'})`);
       } catch (oktaError: any) {
         logger.error('[Admin] Error fetching from Okta:', oktaError);
         res.status(500).json({
@@ -826,7 +827,7 @@ export const assignRoleByEmail = async (req: Request, res: Response): Promise<vo
         return;
       }
     } else {
-      // User exists, update their role
+      // User exists - fetch latest data from Okta and sync all fields including role
       const previousRole = user.role;
 
       // Prevent self-demotion
@@ -838,9 +839,35 @@ export const assignRoleByEmail = async (req: Request, res: Response): Promise<vo
         return;
       }
 
-      await user.update({ role });
+      // Import UserService to fetch latest data from Okta
+      const { UserService } = await import('@services/user.service');
+      const userService = new UserService();
 
-      logger.info(`[Admin] Updated user ${email} role from ${previousRole} to ${role}`);
+      try {
+        // Fetch full user profile from Okta Users API to sync manager and other fields
+        const oktaUserData = await userService.fetchAndExtractOktaUserByEmail(email);
+
+        if (oktaUserData) {
+          // Sync all fields from Okta including the new role using centralized method
+          const updated = await userService.createOrUpdateUser({
+            ...oktaUserData, // Includes all fields: manager, jobTitle, postalAddress, etc.
+            role, // Set the new role
+            isActive: true, // Ensure user is active
+          });
+          user = updated;
+
+          logger.info(`[Admin] Synced user ${email} from Okta (manager: ${oktaUserData.manager || 'N/A'}) and updated role from ${previousRole} to ${role}`);
+        } else {
+          // Okta user not found, just update role
+          await user.update({ role });
+          logger.info(`[Admin] Updated user ${email} role from ${previousRole} to ${role} (Okta data not available)`);
+        }
+      } catch (oktaError: any) {
+        // If Okta fetch fails, just update the role
+        logger.warn(`[Admin] Failed to fetch Okta data for ${email}, updating role only:`, oktaError.message);
+        await user.update({ role });
+        logger.info(`[Admin] Updated user ${email} role from ${previousRole} to ${role} (Okta sync failed)`);
+      }
     }
 
     res.json({
@@ -862,3 +889,174 @@ export const assignRoleByEmail = async (req: Request, res: Response): Promise<vo
   }
 };
 
+// ==================== Activity Type Management Routes ====================
+
+/**
+ * Get all activity types (optionally filtered by active status)
+ */
+export const getAllActivityTypes = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const { activeOnly } = req.query;
+    const activeOnlyBool = activeOnly === 'true';
+
+    const activityTypes = await activityTypeService.getAllActivityTypes(activeOnlyBool);
+
+    res.json({
+      success: true,
+      data: activityTypes,
+      count: activityTypes.length
+    });
+  } catch (error: any) {
+    logger.error('[Admin] Error fetching activity types:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to fetch activity types'
+    });
+  }
+};
+
+/**
+ * Get a single activity type by ID
+ */
+export const getActivityTypeById = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const { activityTypeId } = req.params;
+
+    const activityType = await activityTypeService.getActivityTypeById(activityTypeId);
+
+    if (!activityType) {
+      res.status(404).json({
+        success: false,
+        error: 'Activity type not found'
+      });
+      return;
+    }
+
+    res.json({
+      success: true,
+      data: activityType
+    });
+  } catch (error: any) {
+    logger.error('[Admin] Error fetching activity type:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to fetch activity type'
+    });
+  }
+};
+
+/**
+ * Create a new activity type
+ */
+export const createActivityType = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const userId = req.user?.userId;
+    if (!userId) {
+      res.status(401).json({
+        success: false,
+        error: 'User not authenticated'
+      });
+      return;
+    }
+
+    const {
+      title,
+      itemCode,
+      taxationType,
+      sapRefNo
+    } = req.body;
+
+    // Validate required fields
+    if (!title) {
+      res.status(400).json({
+        success: false,
+        error: 'Activity type title is required'
+      });
+      return;
+    }
+
+    const activityType = await activityTypeService.createActivityType({
+      title,
+      itemCode: itemCode || null,
+      taxationType: taxationType || null,
+      sapRefNo: sapRefNo || null,
+      createdBy: userId
+    });
+
+    res.status(201).json({
+      success: true,
+      message: 'Activity type created successfully',
+      data: activityType
+    });
+  } catch (error: any) {
+    logger.error('[Admin] Error creating activity type:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to create activity type'
+    });
+  }
+};
+
+/**
+ * Update an activity type
+ */
+export const updateActivityType = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const userId = req.user?.userId;
+    if (!userId) {
+      res.status(401).json({
+        success: false,
+        error: 'User not authenticated'
+      });
+      return;
+    }
+
+    const { activityTypeId } = req.params;
+    const updates = req.body;
+
+    const activityType = await activityTypeService.updateActivityType(activityTypeId, updates, userId);
+
+    if (!activityType) {
+      res.status(404).json({
+        success: false,
+        error: 'Activity type not found'
+      });
+      return;
+    }
+
+    res.json({
+      success: true,
+      message: 'Activity type updated successfully',
+      data: activityType
+    });
+  } catch (error: any) {
+    logger.error('[Admin] Error updating activity type:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to update activity type'
+    });
+  }
+};
+
+/**
+ * Delete (deactivate) an activity type
+ */
+export const deleteActivityType = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const { activityTypeId } = req.params;
+
+    await activityTypeService.deleteActivityType(activityTypeId);
+
+    res.json({
+      success: true,
+      message: 'Activity type deleted successfully'
+    });
+  } catch (error: any) {
+    logger.error('[Admin] Error deleting activity type:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to delete activity type'
+    });
+  }
+};
+

src/controllers/apiToken.controller.ts

@@ -0,0 +1,79 @@
+import { Request, Response } from 'express';
+import { ApiTokenService } from '../services/apiToken.service';
+import { ResponseHandler } from '../utils/responseHandler';
+import { AuthenticatedRequest } from '../types/express';
+import { z } from 'zod';
+
+const createTokenSchema = z.object({
+    name: z.string().min(1).max(100),
+    expiresInDays: z.number().int().positive().optional(),
+});
+
+export class ApiTokenController {
+    private apiTokenService: ApiTokenService;
+
+    constructor() {
+        this.apiTokenService = new ApiTokenService();
+    }
+
+    /**
+     * Create a new API Token
+     */
+    async create(req: AuthenticatedRequest, res: Response): Promise<void> {
+        try {
+            const validation = createTokenSchema.safeParse(req.body);
+            if (!validation.success) {
+                ResponseHandler.error(res, 'Validation error', 400, validation.error.message);
+                return;
+            }
+
+            const { name, expiresInDays } = validation.data;
+            const userId = req.user.userId;
+
+            const result = await this.apiTokenService.createToken(userId, name, expiresInDays);
+
+            ResponseHandler.success(res, {
+                token: result.token,
+                apiToken: result.apiToken
+            }, 'API Token created successfully. Please copy the token now, you will not be able to see it again.');
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            ResponseHandler.error(res, 'Failed to create API token', 500, errorMessage);
+        }
+    }
+
+    /**
+     * List user's API Tokens
+     */
+    async list(req: AuthenticatedRequest, res: Response): Promise<void> {
+        try {
+            const userId = req.user.userId;
+            const tokens = await this.apiTokenService.listTokens(userId);
+            ResponseHandler.success(res, { tokens }, 'API Tokens retrieved successfully');
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            ResponseHandler.error(res, 'Failed to list API tokens', 500, errorMessage);
+        }
+    }
+
+    /**
+     * Revoke an API Token
+     */
+    async revoke(req: AuthenticatedRequest, res: Response): Promise<void> {
+        try {
+            const userId = req.user.userId;
+            const { id } = req.params;
+
+            const success = await this.apiTokenService.revokeToken(userId, id);
+
+            if (success) {
+                ResponseHandler.success(res, null, 'API Token revoked successfully');
+            } else {
+                ResponseHandler.notFound(res, 'Token not found or already revoked');
+            }
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            ResponseHandler.error(res, 'Failed to revoke API token', 500, errorMessage);
+        }
+    }
+}

src/controllers/approval.controller.ts

@@ -1,11 +1,15 @@
 import { Request, Response } from 'express';
 import { ApprovalService } from '@services/approval.service';
+import { DealerClaimApprovalService } from '@services/dealerClaimApproval.service';
+import { ApprovalLevel } from '@models/ApprovalLevel';
+import { WorkflowRequest } from '@models/WorkflowRequest';
 import { validateApprovalAction } from '@validators/approval.validator';
 import { ResponseHandler } from '@utils/responseHandler';
 import type { AuthenticatedRequest } from '../types/express';
 import { getRequestMetadata } from '@utils/requestUtils';
 
 const approvalService = new ApprovalService();
+const dealerClaimApprovalService = new DealerClaimApprovalService();
 
 export class ApprovalController {
   async approveLevel(req: AuthenticatedRequest, res: Response): Promise<void> {
@@ -13,18 +17,54 @@ export class ApprovalController {
       const { levelId } = req.params;
       const validatedData = validateApprovalAction(req.body);
       
-      const requestMeta = getRequestMetadata(req);
-      const level = await approvalService.approveLevel(levelId, validatedData, req.user.userId, {
-        ipAddress: requestMeta.ipAddress,
-        userAgent: requestMeta.userAgent
-      });
-      
+      // Determine which service to use based on workflow type
+      const level = await ApprovalLevel.findByPk(levelId);
       if (!level) {
         ResponseHandler.notFound(res, 'Approval level not found');
         return;
       }
 
-      ResponseHandler.success(res, level, 'Approval level updated successfully');
+      const workflow = await WorkflowRequest.findByPk(level.requestId);
+      if (!workflow) {
+        ResponseHandler.notFound(res, 'Workflow not found');
+        return;
+      }
+
+      const workflowType = (workflow as any)?.workflowType;
+      const requestMeta = getRequestMetadata(req);
+      
+      // Route to appropriate service based on workflow type
+      let approvedLevel: any;
+      if (workflowType === 'CLAIM_MANAGEMENT') {
+        // Use DealerClaimApprovalService for claim management workflows
+        approvedLevel = await dealerClaimApprovalService.approveLevel(
+          levelId, 
+          validatedData, 
+          req.user.userId, 
+          {
+            ipAddress: requestMeta.ipAddress,
+            userAgent: requestMeta.userAgent
+          }
+        );
+      } else {
+        // Use ApprovalService for custom workflows
+        approvedLevel = await approvalService.approveLevel(
+          levelId, 
+          validatedData, 
+          req.user.userId, 
+          {
+            ipAddress: requestMeta.ipAddress,
+            userAgent: requestMeta.userAgent
+          }
+        );
+      }
+      
+      if (!approvedLevel) {
+        ResponseHandler.notFound(res, 'Approval level not found');
+        return;
+      }
+
+      ResponseHandler.success(res, approvedLevel, 'Approval level updated successfully');
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       ResponseHandler.error(res, 'Failed to update approval level', 400, errorMessage);
@@ -34,7 +74,23 @@ export class ApprovalController {
   async getCurrentApprovalLevel(req: Request, res: Response): Promise<void> {
     try {
       const { id } = req.params;
-      const level = await approvalService.getCurrentApprovalLevel(id);
+      
+      // Determine which service to use based on workflow type
+      const workflow = await WorkflowRequest.findByPk(id);
+      if (!workflow) {
+        ResponseHandler.notFound(res, 'Workflow not found');
+        return;
+      }
+
+      const workflowType = (workflow as any)?.workflowType;
+      
+      // Route to appropriate service based on workflow type
+      let level: any;
+      if (workflowType === 'CLAIM_MANAGEMENT') {
+        level = await dealerClaimApprovalService.getCurrentApprovalLevel(id);
+      } else {
+        level = await approvalService.getCurrentApprovalLevel(id);
+      }
       
       ResponseHandler.success(res, level, 'Current approval level retrieved successfully');
     } catch (error) {
@@ -46,7 +102,23 @@ export class ApprovalController {
   async getApprovalLevels(req: Request, res: Response): Promise<void> {
     try {
       const { id } = req.params;
-      const levels = await approvalService.getApprovalLevels(id);
+      
+      // Determine which service to use based on workflow type
+      const workflow = await WorkflowRequest.findByPk(id);
+      if (!workflow) {
+        ResponseHandler.notFound(res, 'Workflow not found');
+        return;
+      }
+
+      const workflowType = (workflow as any)?.workflowType;
+      
+      // Route to appropriate service based on workflow type
+      let levels: any[];
+      if (workflowType === 'CLAIM_MANAGEMENT') {
+        levels = await dealerClaimApprovalService.getApprovalLevels(id);
+      } else {
+        levels = await approvalService.getApprovalLevels(id);
+      }
       
       ResponseHandler.success(res, levels, 'Approval levels retrieved successfully');
     } catch (error) {

src/controllers/auth.controller.ts

@@ -84,6 +84,7 @@ export class AuthController {
         displayName: user.displayName,
         department: user.department,
         designation: user.designation,
+        jobTitle: user.jobTitle,
         phone: user.phone,
         location: user.location,
         role: user.role,
@@ -131,10 +132,13 @@ export class AuthController {
 
       // Set new access token in cookie if using cookie-based auth
       const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
+
       const cookieOptions = {
         httpOnly: true,
-        secure: isProduction,
-        sameSite: isProduction ? 'none' as const : 'lax' as const, // 'none' for cross-domain in production
+        secure: isSecureEnv,
+        sameSite: isSecureEnv ? 'lax' as const : 'lax' as const, // 'lax' is safer and works on same-domain
         maxAge: 24 * 60 * 60 * 1000, // 24 hours
       };
 
@@ -147,7 +151,7 @@ export class AuthController {
           message: 'Token refreshed successfully'
         }, 'Token refreshed successfully');
       } else {
-        // Development: Include token for debugging
+        // Dev: Include token for debugging
         ResponseHandler.success(res, {
           accessToken: newAccessToken
         }, 'Token refreshed successfully');
@@ -159,6 +163,134 @@ export class AuthController {
     }
   }
 
+  /**
+   * Exchange Tanflow authorization code for tokens
+   * POST /api/v1/auth/tanflow/token-exchange
+   */
+  async exchangeTanflowToken(req: Request, res: Response): Promise<void> {
+    try {
+      logger.info('Tanflow token exchange request received', {
+        body: {
+          code: req.body?.code ? `${req.body.code.substring(0, 10)}...` : 'MISSING',
+          redirectUri: req.body?.redirectUri,
+          state: req.body?.state ? 'PRESENT' : 'MISSING',
+        },
+      });
+
+      const { code, redirectUri } = validateTokenExchange(req.body);
+      logger.info('Tanflow token exchange validation passed', { redirectUri });
+
+      const result = await this.authService.exchangeTanflowCodeForTokens(code, redirectUri);
+
+      // Log login activity
+      const requestMeta = getRequestMetadata(req);
+      await activityService.log({
+        requestId: SYSTEM_EVENT_REQUEST_ID,
+        type: 'login',
+        user: {
+          userId: result.user.userId,
+          name: result.user.displayName || result.user.email,
+          email: result.user.email
+        },
+        timestamp: new Date().toISOString(),
+        action: 'User Login',
+        details: `User logged in via Tanflow SSO from ${requestMeta.ipAddress || 'unknown IP'}`,
+        metadata: {
+          loginMethod: 'TANFLOW_SSO',
+          employeeId: result.user.employeeId,
+          department: result.user.department,
+          role: result.user.role
+        },
+        ipAddress: requestMeta.ipAddress,
+        userAgent: requestMeta.userAgent,
+        category: 'AUTHENTICATION',
+        severity: 'INFO'
+      });
+
+      // Set tokens in httpOnly cookies (production) or return in body (development)
+      const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
+
+      const cookieOptions = {
+        httpOnly: true,
+        secure: isSecureEnv,
+        sameSite: isSecureEnv ? ('lax' as const) : ('lax' as const),
+        maxAge: 24 * 60 * 60 * 1000, // 24 hours
+        path: '/',
+      };
+
+      res.cookie('accessToken', result.accessToken, cookieOptions);
+      res.cookie('refreshToken', result.refreshToken, cookieOptions);
+
+      // In production, don't return tokens in response body (security)
+      // In development, include tokens for cross-port setup
+      if (isProduction) {
+        ResponseHandler.success(res, {
+          user: result.user,
+          idToken: result.oktaIdToken, // Include id_token for Tanflow logout
+        }, 'Authentication successful');
+      } else {
+        ResponseHandler.success(res, {
+          user: result.user,
+          accessToken: result.accessToken,
+          refreshToken: result.refreshToken,
+          idToken: result.oktaIdToken,
+        }, 'Authentication successful');
+      }
+    } catch (error) {
+      logger.error('Tanflow token exchange failed:', error);
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      ResponseHandler.error(res, 'Tanflow authentication failed', 400, errorMessage);
+    }
+  }
+
+  /**
+   * Refresh Tanflow access token
+   * POST /api/v1/auth/tanflow/refresh
+   */
+  async refreshTanflowToken(req: Request, res: Response): Promise<void> {
+    try {
+      const refreshToken = req.body?.refreshToken;
+
+      if (!refreshToken) {
+        ResponseHandler.error(res, 'Refresh token is required', 400, 'Refresh token is required in request body');
+        return;
+      }
+
+      const newAccessToken = await this.authService.refreshTanflowToken(refreshToken);
+
+      // Set new access token in cookie
+      const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
+
+      const cookieOptions = {
+        httpOnly: true,
+        secure: isSecureEnv,
+        sameSite: isSecureEnv ? ('lax' as const) : ('lax' as const),
+        maxAge: 24 * 60 * 60 * 1000,
+        path: '/',
+      };
+
+      res.cookie('accessToken', newAccessToken, cookieOptions);
+
+      if (isProduction) {
+        ResponseHandler.success(res, {
+          message: 'Token refreshed successfully'
+        }, 'Token refreshed successfully');
+      } else {
+        ResponseHandler.success(res, {
+          accessToken: newAccessToken
+        }, 'Token refreshed successfully');
+      }
+    } catch (error) {
+      logger.error('Tanflow token refresh failed:', error);
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      ResponseHandler.error(res, 'Token refresh failed', 401, errorMessage);
+    }
+  }
+
   /**
    * Logout user
    * POST /api/v1/auth/logout
@@ -170,13 +302,16 @@ export class AuthController {
 
     // Helper function to clear cookies with all possible option combinations
     const clearCookiesCompletely = () => {
+      const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
       const cookieNames = ['accessToken', 'refreshToken'];
 
       // Get the EXACT options used when setting cookies (from exchangeToken)
       // These MUST match exactly: httpOnly, secure, sameSite, path
       const cookieOptions = {
         httpOnly: true,
-        secure: isProduction,
+        secure: isSecureEnv,
         sameSite: 'lax' as const,
         path: '/',
       };
@@ -346,10 +481,13 @@ export class AuthController {
 
       // Set cookies for web clients
       const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
+
       const cookieOptions = {
         httpOnly: true,
-        secure: isProduction,
-        sameSite: isProduction ? 'none' as const : 'lax' as const,
+        secure: isSecureEnv,
+        sameSite: isSecureEnv ? 'lax' as const : 'lax' as const,
         maxAge: 24 * 60 * 60 * 1000, // 24 hours
       };
 
@@ -426,10 +564,13 @@ export class AuthController {
 
       // Set cookies with httpOnly flag for security
       const isProduction = process.env.NODE_ENV === 'production';
+      const isUat = process.env.NODE_ENV === 'uat';
+      const isSecureEnv = isProduction || isUat;
+
       const cookieOptions = {
         httpOnly: true,
-        secure: isProduction,
-        sameSite: isProduction ? 'none' as const : 'lax' as const, // 'none' for cross-domain in production
+        secure: isSecureEnv,
+        sameSite: isSecureEnv ? 'lax' as const : 'lax' as const, // 'lax' for same-domain
         maxAge: 24 * 60 * 60 * 1000, // 24 hours for access token
       };
 
@@ -461,7 +602,7 @@ export class AuthController {
           idToken: result.oktaIdToken
         }, 'Token exchange successful');
       } else {
-        // Development: Include tokens for debugging and different-port setup
+        // Dev: Include tokens for debugging and different-port setup
         ResponseHandler.success(res, {
           user: result.user,
           accessToken: result.accessToken,

src/controllers/conclusion.controller.ts

@@ -5,6 +5,7 @@ import { activityService } from '@services/activity.service';
 import logger from '@utils/logger';
 import { getRequestMetadata } from '@utils/requestUtils';
 
+
 export class ConclusionController {
   /**
    * Generate AI conclusion remark for a request
@@ -79,7 +80,7 @@ export class ConclusionController {
       const workNotes = await WorkNote.findAll({
         where: { requestId },
         order: [['createdAt', 'ASC']],
-        limit: 20 // Last 20 work notes
+        limit: 20 // Last 20 work notes - keep full context for better conclusions
       });
 
       const documents = await Document.findAll({
@@ -90,7 +91,7 @@ export class ConclusionController {
       const activities = await Activity.findAll({
         where: { requestId },
         order: [['createdAt', 'ASC']],
-        limit: 50 // Last 50 activities
+        limit: 50 // Last 50 activities - keep full context for better conclusions
       });
 
       // Build context object
@@ -248,6 +249,7 @@ export class ConclusionController {
       }
 
       // Update conclusion
+      // Note: finalRemark is already sanitized by the sanitization middleware (RICH_TEXT_FIELDS)
       const wasEdited = (conclusion as any).aiGeneratedRemark !== finalRemark;
 
       await conclusion.update({
@@ -283,6 +285,8 @@ export class ConclusionController {
         return res.status(400).json({ error: 'Final remark is required' });
       }
 
+      // Note: finalRemark is already sanitized by the sanitization middleware (RICH_TEXT_FIELDS)
+
       // Fetch request
       const request = await WorkflowRequest.findOne({
         where: { requestId },

src/controllers/dashboard.controller.ts

@@ -46,6 +46,7 @@ export class DashboardController {
       const endDate = req.query.endDate as string | undefined;
       const status = req.query.status as string | undefined; // Status filter (not used in stats - stats show all statuses)
       const priority = req.query.priority as string | undefined;
+      const templateType = req.query.templateType as string | undefined;
       const department = req.query.department as string | undefined;
       const initiator = req.query.initiator as string | undefined;
       const approver = req.query.approver as string | undefined;
@@ -61,6 +62,7 @@ export class DashboardController {
         endDate, 
         status,
         priority,
+        templateType,
         department,
         initiator,
         approver,

src/controllers/dealer.controller.ts

@@ -0,0 +1,123 @@
+import { Request, Response } from 'express';
+import type { AuthenticatedRequest } from '../types/express';
+import * as dealerService from '../services/dealer.service';
+import { ResponseHandler } from '../utils/responseHandler';
+import logger from '../utils/logger';
+
+export class DealerController {
+  /**
+   * Get all dealers
+   * GET /api/v1/dealers?q=searchTerm&limit=10 (optional search and limit)
+   */
+  async getAllDealers(req: Request, res: Response): Promise<void> {
+    try {
+      const searchTerm = req.query.q as string | undefined;
+      const limitParam = req.query.limit as string | undefined;
+      // Parse limit, default to 10, max 100
+      const limit = limitParam ? Math.min(Math.max(1, parseInt(limitParam, 10)), 100) : 10;
+      const dealers = await dealerService.getAllDealers(searchTerm, limit);
+      return ResponseHandler.success(res, dealers, 'Dealers fetched successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DealerController] Error fetching dealers:', error);
+      return ResponseHandler.error(res, 'Failed to fetch dealers', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Get dealer by code
+   * GET /api/v1/dealers/code/:dealerCode
+   */
+  async getDealerByCode(req: Request, res: Response): Promise<void> {
+    try {
+      const { dealerCode } = req.params;
+      const dealer = await dealerService.getDealerByCode(dealerCode);
+
+      if (!dealer) {
+        return ResponseHandler.error(res, 'Dealer not found', 404);
+      }
+
+      return ResponseHandler.success(res, dealer, 'Dealer fetched successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DealerController] Error fetching dealer by code:', error);
+      return ResponseHandler.error(res, 'Failed to fetch dealer', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Get dealer by email
+   * GET /api/v1/dealers/email/:email
+   */
+  async getDealerByEmail(req: Request, res: Response): Promise<void> {
+    try {
+      const { email } = req.params;
+      const dealer = await dealerService.getDealerByEmail(email);
+
+      if (!dealer) {
+        return ResponseHandler.error(res, 'Dealer not found', 404);
+      }
+
+      return ResponseHandler.success(res, dealer, 'Dealer fetched successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DealerController] Error fetching dealer by email:', error);
+      return ResponseHandler.error(res, 'Failed to fetch dealer', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Search dealers
+   * GET /api/v1/dealers/search?q=searchTerm&limit=10
+   */
+  async searchDealers(req: Request, res: Response): Promise<void> {
+    try {
+      const { q, limit: limitParam } = req.query;
+      
+      if (!q || typeof q !== 'string') {
+        return ResponseHandler.error(res, 'Search term is required', 400);
+      }
+
+      // Parse limit, default to 10, max 100
+      const limit = limitParam ? Math.min(Math.max(1, parseInt(limitParam as string, 10)), 100) : 10;
+      const dealers = await dealerService.searchDealers(q, limit);
+      return ResponseHandler.success(res, dealers, 'Dealers searched successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DealerController] Error searching dealers:', error);
+      return ResponseHandler.error(res, 'Failed to search dealers', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Verify dealer is logged in
+   * GET /api/v1/dealers/verify/:dealerCode
+   * Returns dealer info with isLoggedIn flag
+   */
+  async verifyDealerLogin(req: Request, res: Response): Promise<void> {
+    try {
+      const { dealerCode } = req.params;
+      const dealer = await dealerService.getDealerByCode(dealerCode);
+
+      if (!dealer) {
+        return ResponseHandler.error(res, 'Dealer not found', 404);
+      }
+
+      if (!dealer.isLoggedIn) {
+        return ResponseHandler.error(
+          res,
+          'Dealer not logged in to the system',
+          400,
+          `The dealer with code ${dealerCode} (${dealer.email}) has not logged in to the system. Please ask them to log in first.`
+        );
+      }
+
+      return ResponseHandler.success(res, dealer, 'Dealer verified and logged in');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DealerController] Error verifying dealer login:', error);
+      return ResponseHandler.error(res, 'Failed to verify dealer', 500, errorMessage);
+    }
+  }
+}
+

src/controllers/dealerDashboard.controller.ts

@@ -0,0 +1,39 @@
+import { Request, Response } from 'express';
+import { dealerDashboardService } from '../services/dealerDashboard.service';
+import logger from '@utils/logger';
+
+export class DealerDashboardController {
+  /**
+   * Get dealer dashboard KPIs and category data
+   * GET /api/v1/dealer-claims/dashboard
+   */
+  async getDashboard(req: Request, res: Response): Promise<void> {
+    try {
+      const userId = (req as any).user?.userId;
+      const userEmail = (req as any).user?.email;
+      const dateRange = req.query.dateRange as string | undefined;
+      const startDate = req.query.startDate as string | undefined;
+      const endDate = req.query.endDate as string | undefined;
+
+      const result = await dealerDashboardService.getDashboardKPIs(
+        userEmail,
+        userId,
+        dateRange,
+        startDate,
+        endDate
+      );
+
+      res.json({
+        success: true,
+        data: result
+      });
+    } catch (error) {
+      logger.error('[DealerDashboard] Error fetching dashboard:', error);
+      res.status(500).json({
+        success: false,
+        error: 'Failed to fetch dealer dashboard data'
+      });
+    }
+  }
+}
+

src/controllers/dealerExternal.controller.ts

@@ -0,0 +1,34 @@
+import { Request, Response } from 'express';
+import { dealerExternalService } from '../services/dealerExternal.service';
+import { ResponseHandler } from '../utils/responseHandler';
+import logger from '../utils/logger';
+
+export class DealerExternalController {
+    /**
+     * Search dealer by code via external API
+     * GET /api/v1/dealers-external/search/:dealerCode
+     */
+    async searchByDealerCode(req: Request, res: Response): Promise<void> {
+        try {
+            const { dealerCode } = req.params;
+
+            if (!dealerCode) {
+                return ResponseHandler.error(res, 'Dealer code is required', 400);
+            }
+
+            const dealerInfo = await dealerExternalService.getDealerByCode(dealerCode);
+
+            if (!dealerInfo) {
+                return ResponseHandler.error(res, 'Dealer not found in external system', 404);
+            }
+
+            return ResponseHandler.success(res, dealerInfo, 'Dealer found successfully');
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`[DealerExternalController] Error searching dealer ${req.params.dealerCode}:`, error);
+            return ResponseHandler.error(res, 'Failed to fetch dealer from external source', 500, errorMessage);
+        }
+    }
+}
+
+export const dealerExternalController = new DealerExternalController();

src/controllers/dmsWebhook.controller.ts

@@ -0,0 +1,117 @@
+import { Request, Response } from 'express';
+import { DMSWebhookService } from '../services/dmsWebhook.service';
+import { ResponseHandler } from '../utils/responseHandler';
+import logger from '../utils/logger';
+
+/**
+ * DMS Webhook Controller
+ * Handles webhook callbacks from DMS system for invoice and credit note generation
+ */
+export class DMSWebhookController {
+  private webhookService = new DMSWebhookService();
+
+  /**
+   * Handle invoice generation webhook from DMS
+   * POST /api/v1/webhooks/dms/invoice
+   */
+  async handleInvoiceWebhook(req: Request, res: Response): Promise<void> {
+    try {
+      const payload = req.body;
+
+      logger.info('[DMSWebhook] Invoice webhook received', {
+        requestNumber: payload.request_number,
+        documentNo: payload.document_no,
+      });
+
+      // Validate webhook signature if configured
+      const isValid = await this.webhookService.validateWebhookSignature(req);
+      if (!isValid) {
+        logger.warn('[DMSWebhook] Invalid webhook signature');
+        return ResponseHandler.error(res, 'Invalid webhook signature', 401);
+      }
+
+      // Process invoice webhook
+      const result = await this.webhookService.processInvoiceWebhook(payload);
+
+      if (!result.success) {
+        logger.error('[DMSWebhook] Invoice webhook processing failed', {
+          error: result.error,
+          requestNumber: payload.request_number,
+        });
+        return ResponseHandler.error(res, result.error || 'Failed to process invoice webhook', 400);
+      }
+
+      logger.info('[DMSWebhook] Invoice webhook processed successfully', {
+        requestNumber: payload.request_number,
+        invoiceNumber: result.invoiceNumber,
+      });
+
+      return ResponseHandler.success(
+        res,
+        {
+          message: 'Invoice webhook processed successfully',
+          invoiceNumber: result.invoiceNumber,
+          requestNumber: payload.request_number,
+        },
+        'Webhook processed'
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DMSWebhook] Error processing invoice webhook:', error);
+      return ResponseHandler.error(res, 'Failed to process invoice webhook', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Handle credit note generation webhook from DMS
+   * POST /api/v1/webhooks/dms/credit-note
+   */
+  async handleCreditNoteWebhook(req: Request, res: Response): Promise<void> {
+    try {
+      const payload = req.body;
+
+      logger.info('[DMSWebhook] Credit note webhook received', {
+        requestNumber: payload.request_number,
+        documentNo: payload.document_no,
+      });
+
+      // Validate webhook signature if configured
+      const isValid = await this.webhookService.validateWebhookSignature(req);
+      if (!isValid) {
+        logger.warn('[DMSWebhook] Invalid webhook signature');
+        return ResponseHandler.error(res, 'Invalid webhook signature', 401);
+      }
+
+      // Process credit note webhook
+      const result = await this.webhookService.processCreditNoteWebhook(payload);
+
+      if (!result.success) {
+        logger.error('[DMSWebhook] Credit note webhook processing failed', {
+          error: result.error,
+          requestNumber: payload.request_number,
+        });
+        return ResponseHandler.error(res, result.error || 'Failed to process credit note webhook', 400);
+      }
+
+      logger.info('[DMSWebhook] Credit note webhook processed successfully', {
+        requestNumber: payload.request_number,
+        creditNoteNumber: result.creditNoteNumber,
+      });
+
+      return ResponseHandler.success(
+        res,
+        {
+          message: 'Credit note webhook processed successfully',
+          creditNoteNumber: result.creditNoteNumber,
+          requestNumber: payload.request_number,
+        },
+        'Webhook processed'
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[DMSWebhook] Error processing credit note webhook:', error);
+      return ResponseHandler.error(res, 'Failed to process credit note webhook', 500, errorMessage);
+    }
+  }
+}
+

src/controllers/document.controller.ts

@@ -5,9 +5,14 @@ import fs from 'fs';
 import { Document } from '@models/Document';
 import { User } from '@models/User';
 import { WorkflowRequest } from '@models/WorkflowRequest';
+import { Participant } from '@models/Participant';
+import { ApprovalLevel } from '@models/ApprovalLevel';
+import { Op } from 'sequelize';
 import { ResponseHandler } from '@utils/responseHandler';
 import { activityService } from '@services/activity.service';
 import { gcsStorageService } from '@services/gcsStorage.service';
+import { emailNotificationService } from '@services/emailNotification.service';
+import { notificationService } from '@services/notification.service';
 import type { AuthenticatedRequest } from '../types/express';
 import { getRequestMetadata } from '@utils/requestUtils';
 import { getConfigNumber, getConfigValue } from '@services/configReader.service';
@@ -22,20 +27,57 @@ export class DocumentController {
         return;
       }
 
-      const requestId = String((req.body?.requestId || '').trim());
-      if (!requestId) {
+      // Extract requestId from body (multer should parse form fields)
+      // Try both req.body and req.body.requestId for compatibility
+      const identifier = String((req.body?.requestId || req.body?.request_id || '').trim());
+      if (!identifier || identifier === 'undefined' || identifier === 'null') {
+        logWithContext('error', 'RequestId missing or invalid in document upload', {
+          body: req.body,
+          bodyKeys: Object.keys(req.body || {}),
+          userId: req.user?.userId
+        });
         ResponseHandler.error(res, 'requestId is required', 400);
         return;
       }
 
-      // Get workflow request to retrieve requestNumber
-      const workflowRequest = await WorkflowRequest.findOne({ where: { requestId } });
+      // Helper to check if identifier is UUID
+      const isUuid = (id: string): boolean => {
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        return uuidRegex.test(id);
+      };
+
+      // Get workflow request - handle both UUID (requestId) and requestNumber
+      let workflowRequest: WorkflowRequest | null = null;
+      if (isUuid(identifier)) {
+        workflowRequest = await WorkflowRequest.findByPk(identifier);
+      } else {
+        workflowRequest = await WorkflowRequest.findOne({ where: { requestNumber: identifier } });
+      }
+
       if (!workflowRequest) {
+        logWithContext('error', 'Workflow request not found for document upload', {
+          identifier,
+          isUuid: isUuid(identifier),
+          userId: req.user?.userId
+        });
         ResponseHandler.error(res, 'Workflow request not found', 404);
         return;
       }
+
+      // Get the actual requestId (UUID) and requestNumber
+      const requestId = (workflowRequest as any).requestId || (workflowRequest as any).request_id;
       const requestNumber = (workflowRequest as any).requestNumber || (workflowRequest as any).request_number;
       
+      if (!requestNumber) {
+        logWithContext('error', 'Request number not found for workflow', {
+          requestId,
+          workflowRequest: JSON.stringify(workflowRequest.toJSON()),
+          userId: req.user?.userId
+        });
+        ResponseHandler.error(res, 'Request number not found for workflow', 500);
+        return;
+      }
+
       const file = (req as any).file as Express.Multer.File | undefined;
       if (!file) {
         ResponseHandler.error(res, 'No file uploaded', 400);
@@ -254,13 +296,223 @@ export class DocumentController {
         userAgent: requestMeta.userAgent
       });
 
+      // Send notifications for additional document added
+      try {
+        const initiatorId = (workflowRequest as any).initiatorId || (workflowRequest as any).initiator_id;
+        const isInitiator = userId === initiatorId;
+
+        // Get all participants (spectators)
+        const spectators = await Participant.findAll({
+          where: { 
+            requestId,
+            participantType: 'SPECTATOR'
+          },
+          include: [{
+            model: User,
+            as: 'user',
+            attributes: ['userId', 'email', 'displayName']
+          }]
+        });
+
+        // Get current approver (pending or in-progress approval level)
+        const currentApprovalLevel = await ApprovalLevel.findOne({
+          where: {
+            requestId,
+            status: { [Op.in]: ['PENDING', 'IN_PROGRESS'] }
+          },
+          order: [['levelNumber', 'ASC']],
+          include: [{
+            model: User,
+            as: 'approver',
+            attributes: ['userId', 'email', 'displayName']
+          }]
+        });
+
+        logWithContext('info', 'Current approver lookup for document notification', {
+          requestId,
+          currentApprovalLevelFound: !!currentApprovalLevel,
+          approverUserId: currentApprovalLevel ? ((currentApprovalLevel as any).approver || (currentApprovalLevel as any).Approver)?.userId : null,
+          isInitiator
+        });
+
+        // Determine who to notify based on who uploaded
+        const recipientsToNotify: Array<{ userId: string; email: string; displayName: string }> = [];
+
+        if (isInitiator) {
+          // Initiator added → notify spectators and current approver
+          spectators.forEach((spectator: any) => {
+            const spectatorUser = spectator.user || spectator.User;
+            if (spectatorUser && spectatorUser.userId !== userId) {
+              recipientsToNotify.push({
+                userId: spectatorUser.userId,
+                email: spectatorUser.email,
+                displayName: spectatorUser.displayName || spectatorUser.email
+              });
+            }
+          });
+
+          if (currentApprovalLevel) {
+            const approverUser = (currentApprovalLevel as any).approver || (currentApprovalLevel as any).Approver;
+            if (approverUser && approverUser.userId !== userId) {
+              recipientsToNotify.push({
+                userId: approverUser.userId,
+                email: approverUser.email,
+                displayName: approverUser.displayName || approverUser.email
+              });
+            }
+          }
+        } else {
+          // Check if uploader is a spectator
+          const uploaderParticipant = await Participant.findOne({
+            where: {
+              requestId,
+              userId,
+              participantType: 'SPECTATOR'
+            }
+          });
+
+          if (uploaderParticipant) {
+            // Spectator added → notify initiator and current approver
+            const initiator = await User.findByPk(initiatorId);
+            if (initiator) {
+              const initiatorData = initiator.toJSON();
+              if (initiatorData.userId !== userId) {
+                recipientsToNotify.push({
+                  userId: initiatorData.userId,
+                  email: initiatorData.email,
+                  displayName: initiatorData.displayName || initiatorData.email
+                });
+              }
+            }
+
+            if (currentApprovalLevel) {
+              const approverUser = (currentApprovalLevel as any).approver || (currentApprovalLevel as any).Approver;
+              if (approverUser && approverUser.userId !== userId) {
+                recipientsToNotify.push({
+                  userId: approverUser.userId,
+                  email: approverUser.email,
+                  displayName: approverUser.displayName || approverUser.email
+                });
+              }
+            }
+          } else {
+            // Approver added → notify initiator and spectators
+            const initiator = await User.findByPk(initiatorId);
+            if (initiator) {
+              const initiatorData = initiator.toJSON();
+              if (initiatorData.userId !== userId) {
+                recipientsToNotify.push({
+                  userId: initiatorData.userId,
+                  email: initiatorData.email,
+                  displayName: initiatorData.displayName || initiatorData.email
+                });
+              }
+            }
+
+            spectators.forEach((spectator: any) => {
+              const spectatorUser = spectator.user || spectator.User;
+              if (spectatorUser && spectatorUser.userId !== userId) {
+                recipientsToNotify.push({
+                  userId: spectatorUser.userId,
+                  email: spectatorUser.email,
+                  displayName: spectatorUser.displayName || spectatorUser.email
+                });
+              }
+            });
+          }
+        }
+
+        // Send notifications (email, in-app, and web-push)
+        const requestData = {
+          requestNumber: requestNumber,
+          requestId: requestId,
+          title: (workflowRequest as any).title || 'Request'
+        };
+
+        // Prepare user IDs for in-app and web-push notifications
+        const recipientUserIds = recipientsToNotify.map(r => r.userId);
+
+        // Send in-app and web-push notifications
+        if (recipientUserIds.length > 0) {
+          try {
+            await notificationService.sendToUsers(
+              recipientUserIds,
+              {
+                title: 'Additional Document Added',
+                body: `${uploaderName} added "${file.originalname}" to ${requestNumber}`,
+                requestId,
+                requestNumber,
+                url: `/request/${requestNumber}`,
+                type: 'document_added',
+                priority: 'MEDIUM',
+                actionRequired: false,
+                metadata: {
+                  documentName: file.originalname,
+                  fileSize: file.size,
+                  addedByName: uploaderName,
+                  source: 'Documents Tab'
+                }
+              }
+            );
+            logWithContext('info', 'In-app and web-push notifications sent for additional document', {
+              requestId,
+              documentName: file.originalname,
+              recipientsCount: recipientUserIds.length
+            });
+          } catch (notifyError) {
+            logWithContext('error', 'Failed to send in-app/web-push notifications for additional document', {
+              requestId,
+              error: notifyError instanceof Error ? notifyError.message : 'Unknown error'
+            });
+          }
+        }
+
+        // Send email notifications
+        for (const recipient of recipientsToNotify) {
+          await emailNotificationService.sendAdditionalDocumentAdded(
+            requestData,
+            recipient,
+            {
+              documentName: file.originalname,
+              fileSize: file.size,
+              addedByName: uploaderName,
+              source: 'Documents Tab'
+            }
+          );
+        }
+
+        logWithContext('info', 'Additional document notifications sent', {
+          requestId,
+          documentName: file.originalname,
+          recipientsCount: recipientsToNotify.length,
+          isInitiator
+        });
+      } catch (notifyError) {
+        // Don't fail document upload if notifications fail
+        logWithContext('error', 'Failed to send additional document notifications', {
+          requestId,
+          error: notifyError instanceof Error ? notifyError.message : 'Unknown error'
+        });
+      }
+
       ResponseHandler.success(res, doc, 'File uploaded', 201);
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Unknown error';
+      const errorStack = error instanceof Error ? error.stack : undefined;
       logWithContext('error', 'Document upload failed', {
         userId: req.user?.userId,
-        requestId: req.body?.requestId,
-        error,
+        requestId: req.body?.requestId || req.body?.request_id,
+        body: req.body,
+        bodyKeys: Object.keys(req.body || {}),
+        file: req.file ? {
+          originalname: req.file.originalname,
+          size: req.file.size,
+          mimetype: req.file.mimetype,
+          hasBuffer: !!req.file.buffer,
+          hasPath: !!req.file.path
+        } : 'No file',
+        error: message,
+        stack: errorStack
       });
       ResponseHandler.error(res, 'Upload failed', 500, message);
     }

src/controllers/template.controller.ts

@@ -0,0 +1,214 @@
+import { Request, Response } from 'express';
+import type { AuthenticatedRequest } from '../types/express';
+import { TemplateService } from '../services/template.service';
+import { ResponseHandler } from '../utils/responseHandler';
+import logger from '../utils/logger';
+
+export class TemplateController {
+  private templateService = new TemplateService();
+
+  /**
+   * Create a new template
+   * POST /api/v1/templates
+   */
+  async createTemplate(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const userId = req.user?.userId;
+      if (!userId) {
+        return ResponseHandler.error(res, 'Unauthorized', 401);
+      }
+
+      const {
+        // New fields
+        templateName,
+        templateCode,
+        templateDescription,
+        templateCategory,
+        workflowType,
+        approvalLevelsConfig,
+        defaultTatHours,
+        formStepsConfig,
+        userFieldMappings,
+        dynamicApproverConfig,
+        isActive,
+
+        // Legacy fields (from frontend)
+        name,
+        description,
+        category,
+        approvers,
+        suggestedSLA
+      } = req.body;
+
+      // Map legacy to new
+      const finalTemplateName = templateName || name;
+      const finalTemplateDescription = templateDescription || description;
+      const finalTemplateCategory = templateCategory || category;
+      const finalApprovalLevelsConfig = approvalLevelsConfig || approvers;
+      const finalDefaultTatHours = defaultTatHours || suggestedSLA;
+
+      if (!finalTemplateName) {
+        return ResponseHandler.error(res, 'Template name is required', 400);
+      }
+
+      const template = await this.templateService.createTemplate(userId, {
+        templateName: finalTemplateName,
+        templateCode,
+        templateDescription: finalTemplateDescription,
+        templateCategory: finalTemplateCategory,
+        workflowType,
+        approvalLevelsConfig: finalApprovalLevelsConfig,
+        defaultTatHours: finalDefaultTatHours ? parseFloat(finalDefaultTatHours) : undefined,
+        formStepsConfig,
+        userFieldMappings,
+        dynamicApproverConfig,
+        isActive,
+      });
+
+      return ResponseHandler.success(res, template, 'Template created successfully', 201);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error creating template:', error);
+      return ResponseHandler.error(res, 'Failed to create template', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Get template by ID
+   * GET /api/v1/templates/:templateId
+   */
+  async getTemplate(req: Request, res: Response): Promise<void> {
+    try {
+      const { templateId } = req.params;
+
+      const template = await this.templateService.getTemplate(templateId);
+
+      if (!template) {
+        return ResponseHandler.error(res, 'Template not found', 404);
+      }
+
+      return ResponseHandler.success(res, template, 'Template fetched');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error getting template:', error);
+      return ResponseHandler.error(res, 'Failed to fetch template', 500, errorMessage);
+    }
+  }
+
+  /**
+   * List templates
+   * GET /api/v1/templates
+   */
+  async listTemplates(req: Request, res: Response): Promise<void> {
+    try {
+      const {
+        category,
+        workflowType,
+        isActive,
+        isSystemTemplate,
+        search,
+      } = req.query;
+
+      const filters: any = {};
+      if (category) filters.category = category as string;
+      if (workflowType) filters.workflowType = workflowType as string;
+      if (isActive !== undefined) filters.isActive = isActive === 'true';
+      if (isSystemTemplate !== undefined) filters.isSystemTemplate = isSystemTemplate === 'true';
+      if (search) filters.search = search as string;
+
+      const templates = await this.templateService.listTemplates(filters);
+
+      return ResponseHandler.success(res, templates, 'Templates fetched');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error listing templates:', error);
+      return ResponseHandler.error(res, 'Failed to fetch templates', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Get active templates (for workflow creation)
+   * GET /api/v1/templates/active
+   */
+  async getActiveTemplates(req: Request, res: Response): Promise<void> {
+    try {
+      const templates = await this.templateService.getActiveTemplates();
+
+      return ResponseHandler.success(res, templates, 'Active templates fetched');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error getting active templates:', error);
+      return ResponseHandler.error(res, 'Failed to fetch active templates', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Update template
+   * PUT /api/v1/templates/:templateId
+   */
+  async updateTemplate(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { templateId } = req.params;
+      const userId = req.user?.userId;
+      if (!userId) {
+        return ResponseHandler.error(res, 'Unauthorized', 401);
+      }
+
+      const {
+        templateName,
+        templateDescription,
+        templateCategory,
+        approvalLevelsConfig,
+        defaultTatHours,
+        formStepsConfig,
+        userFieldMappings,
+        dynamicApproverConfig,
+        isActive,
+
+        // Legacy
+        name,
+        description,
+        category,
+        approvers,
+        suggestedSLA
+      } = req.body;
+
+      const template = await this.templateService.updateTemplate(templateId, userId, {
+        templateName: templateName || name,
+        templateDescription: templateDescription || description,
+        templateCategory: templateCategory || category,
+        approvalLevelsConfig: approvalLevelsConfig || approvers,
+        defaultTatHours: (defaultTatHours || suggestedSLA) ? parseFloat(defaultTatHours || suggestedSLA) : undefined,
+        formStepsConfig,
+        userFieldMappings,
+        dynamicApproverConfig,
+        isActive,
+      });
+
+      return ResponseHandler.success(res, template, 'Template updated successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error updating template:', error);
+      return ResponseHandler.error(res, 'Failed to update template', 500, errorMessage);
+    }
+  }
+
+  /**
+   * Delete template
+   * DELETE /api/v1/templates/:templateId
+   */
+  async deleteTemplate(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { templateId } = req.params;
+
+      await this.templateService.deleteTemplate(templateId);
+
+      return ResponseHandler.success(res, { message: 'Template deleted successfully' }, 'Template deleted');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[TemplateController] Error deleting template:', error);
+      return ResponseHandler.error(res, 'Failed to delete template', 500, errorMessage);
+    }
+  }
+}
+

src/controllers/user.controller.ts

@@ -10,13 +10,37 @@ export class UserController {
     this.userService = new UserService();
   }
 
+  async getAllUsers(req: Request, res: Response): Promise<void> {
+    try {
+      const users = await this.userService.getAllUsers();
+
+      const result = {
+        users: users.map(u => ({
+          userId: u.userId,
+          email: u.email,
+          displayName: u.displayName,
+          department: u.department,
+          designation: u.designation,
+          isActive: u.isActive,
+        })),
+        total: users.length
+      };
+
+      ResponseHandler.success(res, result, 'All users fetched');
+    } catch (error) {
+      logger.error('Failed to fetch all users', { error });
+      ResponseHandler.error(res, 'Failed to fetch all users', 500);
+    }
+  }
+
   async searchUsers(req: Request, res: Response): Promise<void> {
     try {
       const q = String(req.query.q || '').trim();
       const limit = Number(req.query.limit || 10);
+      const source = String(req.query.source || 'default') as 'local' | 'okta' | 'default';
       const currentUserId = (req as any).user?.userId || (req as any).user?.id;
 
-      const users = await this.userService.searchUsers(q, limit, currentUserId);
+      const users = await this.userService.searchUsers(q, limit, currentUserId, source);
 
       const result = users.map(u => ({
         userId: (u as any).userId,
@@ -36,6 +60,64 @@ export class UserController {
     }
   }
 
+  /**
+   * Search users in Okta by displayName
+   * GET /api/v1/users/search-by-displayname?displayName=John Doe
+   * Used when creating claim requests to find manager by displayName
+   */
+  async searchByDisplayName(req: Request, res: Response): Promise<void> {
+    try {
+      const displayName = String(req.query.displayName || '').trim();
+
+      if (!displayName) {
+        ResponseHandler.error(res, 'displayName query parameter is required', 400);
+        return;
+      }
+
+      const oktaUsers = await this.userService.searchOktaByDisplayName(displayName);
+
+      const result = oktaUsers.map(u => ({
+        userId: u.id,
+        email: u.profile.email || u.profile.login,
+        displayName: u.profile.displayName || `${u.profile.firstName || ''} ${u.profile.lastName || ''}`.trim(),
+        firstName: u.profile.firstName,
+        lastName: u.profile.lastName,
+        department: u.profile.department,
+        status: u.status,
+      }));
+
+      ResponseHandler.success(res, result, 'Users found by displayName');
+    } catch (error: any) {
+      logger.error('Search by displayName failed', { error });
+      ResponseHandler.error(res, error.message || 'Search by displayName failed', 500);
+    }
+  }
+
+  async getUserById(req: Request, res: Response): Promise<void> {
+    try {
+      const { userId } = req.params;
+      const user = await this.userService.getUserById(userId);
+
+      if (!user) {
+        ResponseHandler.error(res, 'User not found', 404);
+        return;
+      }
+
+      ResponseHandler.success(res, {
+        userId: user.userId,
+        email: user.email,
+        displayName: user.displayName,
+        firstName: user.firstName,
+        lastName: user.lastName,
+        department: user.department,
+        isActive: user.isActive
+      }, 'User fetched');
+    } catch (error) {
+      logger.error('Failed to fetch user by ID', { error });
+      ResponseHandler.error(res, 'Failed to fetch user by ID', 500);
+    }
+  }
+
   /**
    * Ensure user exists in database (create if not exists)
    * Called when user is selected/tagged in the frontend

src/controllers/workflow.controller.ts

@@ -12,10 +12,12 @@ import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 import { getRequestMetadata } from '@utils/requestUtils';
-import { enrichApprovalLevels, enrichSpectators, validateInitiator } from '@services/userEnrichment.service';
+import { enrichApprovalLevels, enrichSpectators, validateInitiator, validateDealerUser } from '@services/userEnrichment.service';
+import { DealerClaimService } from '@services/dealerClaim.service';
 import logger from '@utils/logger';
 
 const workflowService = new WorkflowService();
+const dealerClaimService = new DealerClaimService();
 
 export class WorkflowController {
   async createWorkflow(req: AuthenticatedRequest, res: Response): Promise<void> {
@@ -25,6 +27,15 @@ export class WorkflowController {
       // Validate initiator exists
       await validateInitiator(req.user.userId);
 
+      // Dealer Validation if dealerCode is provided or it's a DEALER CLAIM
+      const dealerCode = req.body.dealerCode || (req.body as any).dealer_code;
+      if (dealerCode || validatedData.templateType === 'DEALER CLAIM') {
+        if (!dealerCode) {
+          throw new Error('Dealer code is required for dealer claim requests');
+        }
+        await validateDealerUser(dealerCode);
+      }
+
       // Handle frontend format: map 'approvers' -> 'approvalLevels' for backward compatibility
       let approvalLevels = validatedData.approvalLevels || [];
       if (!approvalLevels.length && (req.body as any).approvers) {
@@ -168,6 +179,15 @@ export class WorkflowController {
       // Validate initiator exists
       await validateInitiator(userId);
 
+      // Dealer Validation if dealerCode is provided or it's a DEALER CLAIM
+      const dealerCode = parsed.dealerCode || parsed.dealer_code;
+      if (dealerCode || validated.templateType === 'DEALER CLAIM') {
+        if (!dealerCode) {
+          throw new Error('Dealer code is required for dealer claim requests');
+        }
+        await validateDealerUser(dealerCode);
+      }
+
       // Use the approval levels from validation (already transformed above)
       let approvalLevels = validated.approvalLevels || [];
 
@@ -234,6 +254,7 @@ export class WorkflowController {
         priority: validated.priority as Priority,
         approvalLevels: enrichedApprovalLevels,
         participants: autoGeneratedParticipants,
+        isDraft: parsed.isDraft === true, // Submit by default unless isDraft is explicitly true
       } as any;
 
       const requestMeta = getRequestMetadata(req);
@@ -474,6 +495,7 @@ export class WorkflowController {
         search: req.query.search as string | undefined,
         status: req.query.status as string | undefined,
         priority: req.query.priority as string | undefined,
+        templateType: req.query.templateType as string | undefined,
         department: req.query.department as string | undefined,
         initiator: req.query.initiator as string | undefined,
         approver: req.query.approver as string | undefined,
@@ -535,6 +557,7 @@ export class WorkflowController {
       const search = req.query.search as string | undefined;
       const status = req.query.status as string | undefined;
       const priority = req.query.priority as string | undefined;
+      const templateType = req.query.templateType as string | undefined;
       const department = req.query.department as string | undefined;
       const initiator = req.query.initiator as string | undefined;
       const approver = req.query.approver as string | undefined;
@@ -544,7 +567,7 @@ export class WorkflowController {
       const startDate = req.query.startDate as string | undefined;
       const endDate = req.query.endDate as string | undefined;
 
-      const filters = { search, status, priority, department, initiator, approver, approverType, slaCompliance, dateRange, startDate, endDate };
+      const filters = { search, status, priority, templateType, department, initiator, approver, approverType, slaCompliance, dateRange, startDate, endDate };
 
       const result = await workflowService.listParticipantRequests(userId, page, limit, filters);
       ResponseHandler.success(res, result, 'Participant requests fetched');
@@ -567,13 +590,14 @@ export class WorkflowController {
       const search = req.query.search as string | undefined;
       const status = req.query.status as string | undefined;
       const priority = req.query.priority as string | undefined;
+      const templateType = req.query.templateType as string | undefined;
       const department = req.query.department as string | undefined;
       const slaCompliance = req.query.slaCompliance as string | undefined;
       const dateRange = req.query.dateRange as string | undefined;
       const startDate = req.query.startDate as string | undefined;
       const endDate = req.query.endDate as string | undefined;
 
-      const filters = { search, status, priority, department, slaCompliance, dateRange, startDate, endDate };
+      const filters = { search, status, priority, templateType, department, slaCompliance, dateRange, startDate, endDate };
 
       const result = await workflowService.listMyInitiatedRequests(userId, page, limit, filters);
       ResponseHandler.success(res, result, 'My initiated requests fetched');
@@ -593,7 +617,8 @@ export class WorkflowController {
       const filters = {
         search: req.query.search as string | undefined,
         status: req.query.status as string | undefined,
-        priority: req.query.priority as string | undefined
+        priority: req.query.priority as string | undefined,
+        templateType: req.query.templateType as string | undefined
       };
 
       // Extract sorting parameters
@@ -618,7 +643,8 @@ export class WorkflowController {
       const filters = {
         search: req.query.search as string | undefined,
         status: req.query.status as string | undefined,
-        priority: req.query.priority as string | undefined
+        priority: req.query.priority as string | undefined,
+        templateType: req.query.templateType as string | undefined
       };
 
       // Extract sorting parameters
@@ -675,7 +701,10 @@ export class WorkflowController {
       }
       const parsed = JSON.parse(raw);
       const validated = validateUpdateWorkflow(parsed);
-      const updateData: UpdateWorkflowRequest = { ...validated } as any;
+      const updateData: UpdateWorkflowRequest = {
+        ...validated,
+        isDraft: parsed.isDraft !== undefined ? (parsed.isDraft === true) : undefined
+      } as any;
       if (validated.priority) {
         updateData.priority = validated.priority === 'EXPRESS' ? Priority.EXPRESS : Priority.STANDARD;
       }
@@ -881,4 +910,54 @@ export class WorkflowController {
       ResponseHandler.error(res, 'Failed to submit workflow', 400, errorMessage);
     }
   }
+
+  async handleInitiatorAction(req: Request, res: Response): Promise<void> {
+    try {
+      const { id } = req.params;
+      const { action, ...data } = req.body;
+      const userId = req.user?.userId;
+
+      if (!userId) {
+        ResponseHandler.unauthorized(res, 'User ID missing from request');
+        return;
+      }
+
+      await dealerClaimService.handleInitiatorAction(id, userId, action as any, data);
+      ResponseHandler.success(res, null, `Action ${action} performed successfully`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[WorkflowController] handleInitiatorAction failed', {
+        error: errorMessage,
+        requestId: req.params.id,
+        userId: req.user?.userId,
+        action: req.body.action
+      });
+      ResponseHandler.error(res, 'Failed to perform initiator action', 400, errorMessage);
+    }
+  }
+
+  async getHistory(req: Request, res: Response): Promise<void> {
+    try {
+      const { id } = req.params;
+
+      // Resolve requestId UUID from identifier (could be requestNumber or UUID)
+      const workflowService = new WorkflowService();
+      const wf = await (workflowService as any).findWorkflowByIdentifier(id);
+      if (!wf) {
+        ResponseHandler.notFound(res, 'Workflow not found');
+        return;
+      }
+      const requestId = wf.getDataValue('requestId');
+
+      const history = await dealerClaimService.getHistory(requestId);
+      ResponseHandler.success(res, history, 'Revision history fetched successfully');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('[WorkflowController] getHistory failed', {
+        error: errorMessage,
+        requestId: req.params.id
+      });
+      ResponseHandler.error(res, 'Failed to fetch revision history', 400, errorMessage);
+    }
+  }
 }

src/controllers/workflowTemplate.controller.ts

@@ -0,0 +1,130 @@
+import { Request, Response } from 'express';
+import { WorkflowTemplate } from '../models';
+import logger from '../utils/logger';
+
+export const createTemplate = async (req: Request, res: Response) => {
+    try {
+        const { name, description, category, priority, estimatedTime, approvers, suggestedSLA } = req.body;
+        const userId = (req as any).user?.userId;
+
+        const template = await WorkflowTemplate.create({
+            templateName: name,
+            templateDescription: description,
+            templateCategory: category,
+            approvalLevelsConfig: approvers,
+            defaultTatHours: suggestedSLA,
+            createdBy: userId,
+            isActive: true,
+            isSystemTemplate: false,
+            usageCount: 0
+        });
+
+        res.status(201).json({
+            success: true,
+            message: 'Workflow template created successfully',
+            data: template
+        });
+    } catch (error) {
+        logger.error('Error creating workflow template:', error);
+        res.status(500).json({
+            success: false,
+            message: 'Failed to create workflow template',
+            error: error instanceof Error ? error.message : 'Unknown error'
+        });
+    }
+};
+
+export const getTemplates = async (req: Request, res: Response) => {
+    try {
+        const templates = await WorkflowTemplate.findAll({
+            where: { isActive: true },
+            order: [['createdAt', 'DESC']]
+        });
+
+        res.status(200).json({
+            success: true,
+            data: templates
+        });
+    } catch (error) {
+        logger.error('Error fetching workflow templates:', error);
+        res.status(500).json({
+            success: false,
+            message: 'Failed to fetch workflow templates',
+            error: error instanceof Error ? error.message : 'Unknown error'
+        });
+    }
+}
+
+
+export const updateTemplate = async (req: Request, res: Response) => {
+    try {
+        const { id } = req.params;
+        const { name, description, category, approvers, suggestedSLA, isActive } = req.body;
+
+        const updates: any = {};
+        if (name) updates.templateName = name;
+        if (description) updates.templateDescription = description;
+        if (category) updates.templateCategory = category;
+        if (approvers) updates.approvalLevelsConfig = approvers;
+        if (suggestedSLA) updates.defaultTatHours = suggestedSLA;
+        if (isActive !== undefined) updates.isActive = isActive;
+
+        const template = await WorkflowTemplate.findByPk(id);
+
+        if (!template) {
+            return res.status(404).json({
+                success: false,
+                message: 'Workflow template not found'
+            });
+        }
+
+        await template.update(updates);
+
+        return res.status(200).json({
+            success: true,
+            message: 'Workflow template updated successfully',
+            data: template
+        });
+    } catch (error) {
+        logger.error('Error updating workflow template:', error);
+        return res.status(500).json({
+            success: false,
+            message: 'Failed to update workflow template',
+            error: error instanceof Error ? error.message : 'Unknown error'
+        });
+    }
+};
+
+export const deleteTemplate = async (req: Request, res: Response) => {
+    try {
+        const { id } = req.params;
+        const template = await WorkflowTemplate.findByPk(id);
+
+        if (!template) {
+            return res.status(404).json({
+                success: false,
+                message: 'Workflow template not found'
+            });
+        }
+
+        // Hard delete or Soft delete based on preference. 
+        // Since we have isActive flag, let's use that (Soft Delete) or just destroy if it's unused.
+        // For now, let's do a hard delete to match the expectation of "Delete" in the UI 
+        // unless there are FK constraints (which sequelize handles). 
+        // Actually, safer to Soft Delete by setting isActive = false if we want history, 
+        // but user asked for Delete. Let's do destroy.
+        await template.destroy();
+
+        return res.status(200).json({
+            success: true,
+            message: 'Workflow template deleted successfully'
+        });
+    } catch (error) {
+        logger.error('Error deleting workflow template:', error);
+        return res.status(500).json({
+            success: false,
+            message: 'Failed to delete workflow template',
+            error: error instanceof Error ? error.message : 'Unknown error'
+        });
+    }
+};