feat: encode/decode choices and improve code structure

Author: MmagdyHafezZ

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": null,
     "lines": null
   },
-  "generated_at": "2025-10-28T02:41:25Z",
+  "generated_at": "2025-10-28T23:54:36Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -227,6 +227,52 @@
         "verified_result": null
       }
     ],
+    "apps/web/app/Helpers/__tests__/actual-api-format.test.ts": [
+      {
+        "hashed_secret": "1eb9369bcdb20f6c88138c9427f009b6afe19c7c",
+        "is_verified": false,
+        "line_number": 22,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "655dc5abb6b0ee511e4676b0739bb2077937014a",
+        "is_verified": false,
+        "line_number": 22,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "6eff76dbb551ea7769517f3a7188862f85a7354e",
+        "is_verified": false,
+        "line_number": 69,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "4f043b03a11e8b760986f07490ee76f48c6c7342",
+        "is_verified": false,
+        "line_number": 71,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "618eb19f52dfe817f292f54554346cad3e3a88b3",
+        "is_verified": false,
+        "line_number": 71,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      }
+    ],
+    "apps/web/app/Helpers/__tests__/choice-feedback-decoding.test.ts": [
+      {
+        "hashed_secret": "6eff76dbb551ea7769517f3a7188862f85a7354e",
+        "is_verified": false,
+        "line_number": 236,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      }
+    ],
     "apps/web/app/api/markChat/route.ts": [
       {
         "hashed_secret": "3f70a0183ead614880b70bff64fd39c0d9155d62",

apps/api/src/common/interceptors/data-transform.interceptor.ts

@@ -7,6 +7,7 @@ import {
 import { Reflector } from "@nestjs/core";
 import { Observable } from "rxjs";
 import { map } from "rxjs/operators";
+import { TRANSFORM_FIELDS } from "../../helpers/transform-config";
 
 export interface TransformOptions {
   fields?: string[];
@@ -198,19 +199,7 @@ export class DataTransformInterceptor implements NestInterceptor {
       return {
         encodeResponse: true,
         decodeRequest: true,
-        fields: [
-          "introduction",
-          "instructions",
-          "gradingCriteriaOverview",
-          "question",
-          "content",
-          "rubricQuestion",
-          "description",
-          "questions.scoring.rubrics.rubricQuestion",
-          "questions.scoring.rubrics.criteria.description",
-          "responsesForQuestions.learnerTextResponse",
-          "responsesForQuestions.learnerChoices",
-        ],
+        fields: [...TRANSFORM_FIELDS],
         deep: true,
       };
     }

apps/api/src/helpers/data-transformer.ts

@@ -1,10 +1,28 @@
+import type { API_CONFIG, DATABASE_CONFIG } from "./transform-config";
+
 export interface TransformConfig {
   fields?: string[];
   exclude?: string[];
   deep?: boolean;
   preserveTypes?: boolean;
 }
 
+// Lazy-loaded config to avoid circular dependencies
+let _transformConfig:
+  | {
+      DATABASE_CONFIG: typeof DATABASE_CONFIG;
+      API_CONFIG: typeof API_CONFIG;
+    }
+  | undefined;
+
+function getTransformConfig() {
+  if (!_transformConfig) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment, unicorn/prefer-module
+    _transformConfig = require("./transform-config");
+  }
+  return _transformConfig;
+}
+
 export interface TransformResult<T = any> {
   data: T;
   metadata: {
@@ -15,7 +33,6 @@ export interface TransformResult<T = any> {
   };
 }
 
-const HTML_TAG_REGEX = /<\/?[a-z][\S\s]*>/i;
 const BASE64_FULL_REGEX = /^[\d+/A-Za-z]+={0,2}$/;
 const BASE64_SEGMENT_REGEX = /[\d+/=A-Za-z]{4,}/g;
 const MAX_BASE64_DEPTH = 5;
@@ -418,59 +435,27 @@ export function batchDecode<T = any>(
 }
 
 export const DataTransformer = {
-  encodeForDatabase: <T>(data: T) => {
-    const result = smartEncode(data, {
-      fields: [
-        "introduction",
-        "instructions",
-        "gradingCriteriaOverview",
-        "question",
-        "content",
-        "rubricQuestion",
-        "description",
-        "questions.choices.choice",
-        "questions.scoring.rubrics.rubricQuestion",
-        "questions.scoring.rubrics.criteria.description",
-        "learnerTextResponse",
-        "learnerChoices",
-      ],
-      deep: true,
-    });
+  encodeForDatabase: <T>(data: T, config?: TransformConfig) => {
+    const { DATABASE_CONFIG } = getTransformConfig();
+    const result = smartEncode(data, config || DATABASE_CONFIG);
     return result;
   },
 
-  decodeFromDatabase: <T>(data: T) => {
-    const result = smartDecode(data, {
-      fields: [
-        "introduction",
-        "instructions",
-        "gradingCriteriaOverview",
-        "question",
-        "content",
-        "rubricQuestion",
-        "description",
-        "questions.choices.choice",
-        "questions.scoring.rubrics.rubricQuestion",
-        "questions.scoring.rubrics.criteria.description",
-        "responsesForQuestions.learnerTextResponse",
-        "responsesForQuestions.learnerChoices",
-      ],
-      deep: true,
-    });
+  decodeFromDatabase: <T>(data: T, config?: TransformConfig) => {
+    const { DATABASE_CONFIG } = getTransformConfig();
+    const result = smartDecode(data, config || DATABASE_CONFIG);
     return result;
   },
 
-  encodeForAPI: <T>(data: T) =>
-    smartEncode(data, {
-      exclude: ["id", "createdAt", "updatedAt"],
-      deep: true,
-    }),
-
-  decodeFromAPI: <T>(data: T) =>
-    smartDecode(data, {
-      exclude: ["id", "createdAt", "updatedAt"],
-      deep: true,
-    }),
+  encodeForAPI: <T>(data: T, config?: TransformConfig) => {
+    const { API_CONFIG } = getTransformConfig();
+    return smartEncode(data, config || API_CONFIG);
+  },
+
+  decodeFromAPI: <T>(data: T, config?: TransformConfig) => {
+    const { API_CONFIG } = getTransformConfig();
+    return smartDecode(data, config || API_CONFIG);
+  },
 
   batchEncode,
   batchDecode,

apps/api/src/helpers/transform-config.ts

@@ -0,0 +1,56 @@
+import { TransformConfig } from "./data-transformer";
+
+/**
+ * Centralized transform configuration for encoding and decoding data.
+ * This ensures consistency across the application and provides a single source of truth.
+ */
+
+/**
+ * Fields that should be base64 encoded/decoded for API transmission and storage
+ */
+export const TRANSFORM_FIELDS = [
+  "introduction",
+  "instructions",
+  "gradingCriteriaOverview",
+
+  "question",
+  "content",
+  "rubricQuestion",
+  "description",
+
+  "choice",
+  "feedback",
+  "choices.choice",
+  "choices.feedback",
+  "questions.choices.choice",
+  "questions.choices.feedback",
+
+  "questions.scoring.rubrics.rubricQuestion",
+  "questions.scoring.rubrics.criteria.description",
+
+  "learnerTextResponse",
+  "learnerChoices",
+
+  "questionVersions.choices.choice",
+  "questionVersions.choices.feedback",
+  "questionVersions.scoring.rubrics.rubricQuestion",
+  "questionVersions.scoring.rubrics.criteria.description",
+  "questionVersions.question",
+] as const;
+
+/**
+ * Default configuration for database encoding/decoding
+ */
+export const DATABASE_CONFIG: TransformConfig = {
+  fields: [...TRANSFORM_FIELDS],
+  deep: true,
+};
+
+/**
+ * Configuration for API encoding/decoding (used when backend acts as pass-through)
+ */
+export const API_CONFIG: TransformConfig = {
+  fields: [...TRANSFORM_FIELDS],
+  exclude: ["id", "createdAt", "updatedAt"],
+  deep: true,
+};

apps/web/app/Helpers/__tests__/actual-api-format.test.ts

@@ -0,0 +1,109 @@
+import { DataTransformer } from "../data-transformer";
+import { API_DECODE_CONFIG } from "../transform-config";
+
+/**
+ * Test with the ACTUAL API response format from production
+ */
+describe("Actual API Response Format", () => {
+  it("should decode choices that come as a JSON string", () => {
+    // This is the EXACT format from the user's API response
+    const apiResponse = {
+      id: 2246,
+      questionId: 6998,
+      totalPoints: 2,
+      type: "SINGLE_CORRECT",
+      responseType: "OTHER",
+      question:
+        "PHA+V2hpY2ggU1FMIHF1ZXJ5IGNvcnJlY3RseSByZXRyaWV2ZXMgdGhlIGZpcnN0IDEwMCByb3dzIGZyb20gdGhlIHNhbGVzX2RldGFpbCB0YWJsZSBpbiBQb3N0Z3JlU1FMPzwvcD4=",
+      maxWords: null,
+      scoring: null,
+      // NOTE: choices comes as a JSON STRING, not an array!
+      choices:
+        '[{"choice":"U0VMRUNUICogRlJPTSBzYWxlc19kZXRhaWwgTElNSVQgMTAwOw==","isCorrect":true,"points":2,"feedback":"Q29ycmVjdCEgVGhpcyBxdWVyeSByZXRyaWV2ZXMgdGhlIGZpcnN0IDEwMCByb3dzIGZyb20gdGhlIHNhbGVzX2RldGFpbCB0YWJsZSB1c2luZyB0aGUgTElNSVQgY2xhdXNlLg=="},{"choice":"U0VMRUNUIFRPUCAxMDAgKiBGUk9NIHNhbGVzX2RldGFpbDs=","isCorrect":false,"points":0,"feedback":"SW5jb3JyZWN0LiBUaGUgVE9QIGNsYXVzZSBpcyB1c2VkIGluIFNRTCBTZXJ2ZXIsIG5vdCBpbiBQb3N0Z3JlU1FMLg=="}]',
+      randomizedChoices: true,
+    };
+
+    console.log("\n=== BEFORE DECODE ===");
+    console.log("Question (base64):", apiResponse.question);
+    console.log("Choices type:", typeof apiResponse.choices);
+    console.log(
+      "Choices value:",
+      apiResponse.choices.substring(0, 100) + "...",
+    );
+
+    // Decode using the DataTransformer
+    const decoded = DataTransformer.decodeFromAPI(
+      apiResponse,
+      API_DECODE_CONFIG,
+    );
+
+    console.log("\n=== AFTER DECODE ===");
+    console.log("Question:", decoded.question);
+    console.log("Choices type:", typeof decoded.choices);
+    console.log("Choices:", JSON.stringify(decoded.choices, null, 2));
+
+    // Verify the question is decoded
+    expect(decoded.question).toBe(
+      "<p>Which SQL query correctly retrieves the first 100 rows from the sales_detail table in PostgreSQL?</p>",
+    );
+
+    // Verify choices is now an array (parsed from JSON string)
+    expect(Array.isArray(decoded.choices)).toBe(true);
+    expect(decoded.choices).toHaveLength(2);
+
+    // Verify the first choice is decoded
+    expect(decoded.choices[0].choice).toBe(
+      "SELECT * FROM sales_detail LIMIT 100;",
+    );
+    expect(decoded.choices[0].feedback).toBe(
+      "Correct! This query retrieves the first 100 rows from the sales_detail table using the LIMIT clause.",
+    );
+
+    // Verify the second choice is decoded
+    expect(decoded.choices[1].choice).toBe(
+      "SELECT TOP 100 * FROM sales_detail;",
+    );
+    expect(decoded.choices[1].feedback).toBe(
+      "Incorrect. The TOP clause is used in SQL Server, not in PostgreSQL.",
+    );
+  });
+
+  it("should handle the full questionVersions structure", () => {
+    const apiResponse = {
+      id: 1025,
+      questionVersions: [
+        {
+          id: 2246,
+          questionId: 6998,
+          question:
+            "PHA+V2hpY2ggU1FMIHF1ZXJ5IGNvcnJlY3RseSByZXRyaWV2ZXMgdGhlIGZpcnN0IDEwMCByb3dzIGZyb20gdGhlIHNhbGVzX2RldGFpbCB0YWJsZSBpbiBQb3N0Z3JlU1FMPzwvcD4=",
+          choices:
+            '[{"choice":"U0VMRUNUICogRlJPTSBzYWxlc19kZXRhaWwgTElNSVQgMTAwOw==","isCorrect":true,"points":2,"feedback":"Q29ycmVjdCEgVGhpcyBxdWVyeSByZXRyaWV2ZXMgdGhlIGZpcnN0IDEwMCByb3dzIGZyb20gdGhlIHNhbGVzX2RldGFpbCB0YWJsZSB1c2luZyB0aGUgTElNSVQgY2xhdXNlLg=="}]',
+        },
+      ],
+    };
+
+    const decoded = DataTransformer.decodeFromAPI(
+      apiResponse,
+      API_DECODE_CONFIG,
+    );
+
+    console.log("\n=== QUESTION VERSIONS STRUCTURE ===");
+    console.log(
+      "Question:",
+      decoded.questionVersions[0].question.substring(0, 50) + "...",
+    );
+    console.log("Choices:", decoded.questionVersions[0].choices);
+
+    expect(decoded.questionVersions[0].question).toContain(
+      "Which SQL query correctly retrieves",
+    );
+    expect(Array.isArray(decoded.questionVersions[0].choices)).toBe(true);
+    expect(decoded.questionVersions[0].choices[0].choice).toBe(
+      "SELECT * FROM sales_detail LIMIT 100;",
+    );
+    expect(decoded.questionVersions[0].choices[0].feedback).toContain(
+      "Correct! This query retrieves",
+    );
+  });
+});