feat(verbal): Implement 400 real TCS NQT sentence completion question…

backend/models/DeveloperDebugLog.js

@@ -0,0 +1,25 @@
+import mongoose from 'mongoose';
+
+const developerDebugLogSchema = new mongoose.Schema({
+  userId: {
+    type: mongoose.Schema.Types.ObjectId,
+    ref: 'User',
+    index: true
+  },
+  provider: { type: String, required: true },
+  model: { type: String, required: true },
+  latencyMs: { type: Number },
+  retryCount: { type: Number, default: 0 },
+  promptVersion: { type: String },
+  validationSuccess: { type: Boolean, default: true },
+  errorReason: { type: String },
+  createdAt: {
+    type: Date,
+    default: Date.now,
+    index: true,
+    expires: 86400 // Expire in 24 hours (86400 seconds)
+  }
+});
+
+const DeveloperDebugLog = mongoose.model('DeveloperDebugLog', developerDebugLogSchema);
+export default DeveloperDebugLog;

backend/models/Draft.js

@@ -0,0 +1,45 @@
+import mongoose from 'mongoose';
+
+const draftSchema = new mongoose.Schema({
+  userId: {
+    type: mongoose.Schema.Types.ObjectId,
+    ref: 'User',
+    required: true,
+    index: true
+  },
+  questionId: {
+    type: mongoose.Schema.Types.ObjectId,
+    ref: 'Question',
+    required: true,
+    index: true
+  },
+  mode: {
+    type: String,
+    enum: ['practice', 'mock'],
+    required: true
+  },
+  content: {
+    type: String,
+    default: ''
+  },
+  timeRemainingSec: {
+    type: Number
+  },
+  version: {
+    type: Number,
+    default: 1
+  },
+  deviceId: {
+    type: String
+  },
+  lastSavedAt: {
+    type: Date,
+    default: Date.now
+  }
+});
+
+// Index to find draft for a user/question combination quickly
+draftSchema.index({ userId: 1, questionId: 1 }, { unique: true });
+
+const Draft = mongoose.model('Draft', draftSchema);
+export default Draft;

backend/models/Question.js

@@ -39,6 +39,11 @@ const baseQuestionSchema = new mongoose.Schema(
     questionNo: { type: Number, unique: true, index: true },
     questionId: { type: String, unique: true, sparse: true, index: true }, // MVP (e.g. "QA-ARITH-0001"), sparse for legacy compatibility
     slug: { type: String, unique: true, required: true, index: true },       // MVP (e.g. "avg-speed-train-problem-1")
+    isPublic: { type: Boolean, default: true, index: true },
+    visibility: { type: String, enum: ['official', 'personal'], default: 'official', index: true },
+    owner: { type: mongoose.Schema.Types.ObjectId, ref: 'User', default: null, index: true },
+    sourceType: { type: String, enum: ['manual', 'seed', 'ai', 'imported'], default: 'seed', index: true },
+    categoryTag: { type: String, trim: true, index: true },
 
     // ---------- Classification ----------
     domain: {

backend/models/UserAttempt.js

@@ -26,7 +26,18 @@ const userAttemptSchema = new mongoose.Schema(
       default: null, 
       index: true 
     },
-    submittedAnswer: [{ type: String, required: true }], // Array of strings supporting multiple correct or numeric input formats
+    questionType: {
+      type: String,
+      enum: ['coding', 'mcq', 'email_writing', 'passage_recall'],
+      default: 'email_writing',
+      index: true
+    },
+    visibility: {
+      type: String,
+      enum: ['official', 'personal'],
+      default: 'official'
+    },
+    submittedAnswer: [{ type: String, required: true }],
     isCorrect: { 
       type: Boolean, 
       required: true, 
@@ -36,47 +47,106 @@ const userAttemptSchema = new mongoose.Schema(
       type: Number, 
       required: true 
     },
+    evaluationMode: {
+      type: String,
+      enum: ['RULE_ONLY', 'AI_SHARED', 'AI_BYOK', 'shared_backend', 'byok_client', 'quota_exceeded', 'deterministic_offline'],
+      default: 'RULE_ONLY',
+      required: true,
+      index: true
+    },
+    evaluationVersion: {
+      type: String,
+      default: 'rule_v1'
+    },
+    promptVersion: {
+      type: String,
+      default: 'email_v3'
+    },
+    aiModel: {
+      type: String,
+      default: 'gemini-2.5-flash'
+    },
+    schemaVersion: {
+      type: Number,
+      default: 1
+    },
+    snapshotVersion: {
+      type: Number,
+      default: 1
+    },
+    questionSnapshot: {
+      emailPrompt: { type: String },
+      passageText: { type: String },
+      guidelines: [{ type: String }],
+      targetKeyFacts: [{ type: mongoose.Schema.Types.Mixed }],
+      minWords: { type: Number },
+      maxWords: { type: Number }
+    },
+
+    // Deterministic Rule-Based Engine Results (Instant <50ms)
+    deterministic: {
+      ruleScore: { type: Number, default: 0 },
+      grammarMechanicsScore: { type: Number, default: 0 },
+      guidelinesMatched: [{ type: String }],
+      guidelinesMissed: [{ type: String }],
+      wordCount: { type: Number, default: 0 },
+      minWords: { type: Number },
+      maxWords: { type: Number },
+      structurePass: { type: Boolean, default: false },
+      hasGreeting: { type: Boolean, default: false },
+      hasSignoff: { type: Boolean, default: false },
+
+      // Passage Recall Facts Breakdown
+      recallBreakdown: {
+        coveragePercent: { type: Number, default: 0 },
+        factsCount: { remembered: { type: Number, default: 0 }, total: { type: Number, default: 0 } },
+        numbersCount: { remembered: { type: Number, default: 0 }, total: { type: Number, default: 0 } },
+        namesCount: { remembered: { type: Number, default: 0 }, total: { type: Number, default: 0 } },
+        locationsCount: { remembered: { type: Number, default: 0 }, total: { type: Number, default: 0 } },
+        sequenceCorrect: { type: Boolean, default: true }
+      },
+      evaluatedAt: { type: Date, default: Date.now }
+    },
+
+    // ✨ AI Deep Coaching Results (Async Background Worker)
+    ai: {
+      status: {
+        type: String,
+        enum: ['pending', 'completed', 'failed', 'skipped', 'quota_exceeded'],
+        default: 'skipped',
+        index: true
+      },
+      toneScore: { type: Number, default: 0 },
+      tcsReadiness: { type: String, enum: ['Low', 'Medium', 'High', 'Pending'], default: 'Pending' },
+      feedback: { type: String },
+      grammarErrors: [
+        {
+          originalText: { type: String },
+          suggestedFix: { type: String },
+          explanation: { type: String }
+        }
+      ],
+      strengths: [{ type: String }],
+      weaknesses: [{ type: String }],
+      modelSuggestedAnswer: { type: String },
+      evaluatedAt: { type: Date }
+    },
+
+    // Legacy verbalEvaluation field for backward compatibility
+    verbalEvaluation: {
+      type: mongoose.Schema.Types.Mixed,
+      default: null
+    },
+
     attemptedAt: { 
       type: Date, 
       default: Date.now, 
       required: true 
-    },
-    verbalEvaluation: {
-      type: new mongoose.Schema(
-        {
-          status: {
-            type: String,
-            enum: ['pending', 'completed', 'quota_exceeded', 'failed'],
-            default: 'pending',
-            required: true,
-            index: true
-          },
-          score: { type: Number },
-          grammarScore: { type: Number, default: 0 },
-          vocabularyScore: { type: Number, default: 0 },
-          contentRelevanceScore: { type: Number, default: 0 },
-          feedback: { type: String },
-          grammarErrors: [
-            {
-              originalText: { type: String },
-              suggestedFix: { type: String },
-              explanation: { type: String }
-            }
-          ],
-          keyPointsMatched: [{ type: String }],
-          keyPointsMissed: [{ type: String }],
-          modelSuggestedAnswer: { type: String },
-          evaluatedAt: { type: Date }
-        },
-        { _id: false }
-      ),
-      default: null
     }
   },
   { timestamps: true }
 );
 
-// Compound index to quickly fetch user attempts on a question
 userAttemptSchema.index({ userId: 1, questionId: 1 });
 
 const UserAttempt = mongoose.model('UserAttempt', userAttemptSchema);

backend/routes/practiceRoutes.js

@@ -9,7 +9,17 @@ import {
   getPracticeProgress,
   toggleBookmark,
   getBookmarks,
-  getRevisionQueue
+  getRevisionQueue,
+  getPracticeQuota,
+  getQuestionDraft,
+  saveQuestionDraft,
+  deleteQuestionDraft,
+  generateAIQuestion,
+  generateCustomScenario,
+  getAICoachImprovements,
+  getAIDebugLogs,
+  getAIHealthStatus,
+  getAttemptAIStatus
 } from '../controllers/practiceController.js';
 
 const router = express.Router();
@@ -18,13 +28,30 @@ const router = express.Router();
 router.get('/topics', optionalProtect, getSyllabusTopics);
 router.get('/questions', optionalProtect, getPracticeQuestions);
 router.get('/questions/:id', optionalProtect, getPracticeQuestionById);
+router.get('/health', optionalProtect, getAIHealthStatus);
 
 // ── Protected routes (login required) ───────────────────────────────────────
+router.get('/quota', protect, getPracticeQuota);
 router.get('/progress', protect, getPracticeProgress);
 router.post('/sessions', protect, startPracticeSession);
 router.get('/bookmarks', protect, getBookmarks);
 router.get('/revision-queue', protect, getRevisionQueue);
+router.post('/questions/improve', protect, getAICoachImprovements);
+router.post('/questions/:id/improve', protect, getAICoachImprovements);
 router.post('/questions/:id/submit', protect, submitPracticeAnswer);
 router.post('/questions/:id/bookmark', protect, toggleBookmark);
+router.get('/attempts/:attemptId/ai-status', protect, getAttemptAIStatus);
+
+// Draft management routes
+router.get('/drafts/:questionId', protect, getQuestionDraft);
+router.post('/drafts/:questionId', protect, saveQuestionDraft);
+router.delete('/drafts/:questionId', protect, deleteQuestionDraft);
+
+// AI Scenarios generators
+router.post('/questions/generate-ai', protect, generateAIQuestion);
+router.post('/questions/custom-scenario', protect, generateCustomScenario);
+
+// Admin-only debugging logs
+router.get('/debug-logs', protect, getAIDebugLogs);
 
 export default router;

backend/scripts/checkVerbalQuestionsDB.js

@@ -0,0 +1,36 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+import mongoose from 'mongoose';
+import connectDB from '../config/db.js';
+import Question from '../models/Question.js';
+
+const checkDB = async () => {
+  try {
+    await connectDB();
+    console.log('--- MongoDB Diagnostic Report ---');
+
+    const passageCount = await Question.countDocuments({ topic: 'passage-recall' });
+    const emailCount = await Question.countDocuments({ topic: 'email-writing' });
+    const totalVerbal = await Question.countDocuments({ section: 'verbal' });
+    const totalQuestions = await Question.countDocuments();
+
+    console.log(`Total Questions in MongoDB: ${totalQuestions}`);
+    console.log(`Total Verbal Questions: ${totalVerbal}`);
+    console.log(`Passage Recall Questions: ${passageCount}`);
+    console.log(`Email Writing Questions: ${emailCount}`);
+
+    const passageSamples = await Question.find({ topic: 'passage-recall' }).limit(3).select('title domain section topic kind');
+    console.log('Sample Passage Recall Questions:', passageSamples);
+
+    const emailSamples = await Question.find({ topic: 'email-writing' }).limit(3).select('title domain section topic kind');
+    console.log('Sample Email Writing Questions:', emailSamples);
+
+    process.exit(0);
+  } catch (err) {
+    console.error('DB Check Failed:', err);
+    process.exit(1);
+  }
+};
+
+checkDB();

backend/scripts/checkVerbalTopics.js

@@ -0,0 +1,34 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+import mongoose from 'mongoose';
+import connectDB from '../config/db.js';
+import Question from '../models/Question.js';
+
+const checkTopics = async () => {
+  try {
+    await connectDB();
+    const verbalTopics = await Question.find({ section: 'verbal' }).distinct('topic');
+    console.log('Distinct verbal topics in Question collection:', verbalTopics);
+
+    const passageRecallDash = await Question.countDocuments({ topic: 'passage-recall' });
+    const passageRecallUnder = await Question.countDocuments({ topic: 'passage_recall' });
+    const emailWritingDash = await Question.countDocuments({ topic: 'email-writing' });
+    const emailWritingUnder = await Question.countDocuments({ topic: 'email_writing' });
+
+    console.log(`topic 'passage-recall': ${passageRecallDash}`);
+    console.log(`topic 'passage_recall': ${passageRecallUnder}`);
+    console.log(`topic 'email-writing': ${emailWritingDash}`);
+    console.log(`topic 'email_writing': ${emailWritingUnder}`);
+
+    const samples = await Question.find({ verbalType: 'passage_recall' }).limit(3);
+    console.log('Passage recall questions topics:', samples.map(s => ({ title: s.title, topic: s.topic, verbalType: s.verbalType })));
+
+    process.exit(0);
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+};
+
+checkTopics();