implementation_plan-for_seeing_javascript_questions

# Add 47 JavaScript Array Questions to the Platform

## Background

The file [`javascript-array-questions.md`](file:///D:/interview-prep-platform/javascript-array-questions.md) contains **47 array-focused JavaScript problems** that need to be added to the platform. Each question requires:
- A rich markdown description with examples
- Hints (AI-powered via the existing `GetHintForProblem` use case)
- A working solution (in `solutionCode`)
- Test cases (visible + hidden)
- A starter code skeleton

The project uses **Clean Architecture** with Prisma + PostgreSQL. The recommended and established way to bulk-add problems is through the **seed file** ([`seed.ts`](file:///D:/interview-prep-platform/apps/backend-api/src/infrastructure/database/prisma/seed.ts)), which is already used to seed 30+ existing problems.

For adding new questions via the **Admin UI/API** (for future extensibility), the `POST /api/admin/problems` + `POST /api/admin/test-cases` endpoints are already live and fully wired.

---

## Open Questions

> [!IMPORTANT]
> **Should these 47 problems be APPENDED to the existing seed data or replace it?**
> The current `seed.ts` does a `deleteMany` first, which wipes all problems. Options:
> 1. **(Recommended)** Append — create a separate `seed-arrays.ts` file that only adds array problems (safe, idempotent using `upsert`)
> 2. **Merge** — add the 47 problems into the existing `seed.ts` array (simpler, but requires running full seed to refresh)

> [!IMPORTANT]
> **Difficulty breakdown** — The list has mixed difficulty levels. Please confirm my proposed mapping or specify overrides:
> - `EASY`: avg/sum of arrays, reverse array, find max/min, check element exists, find occurrences, shift/rotate, FizzBuzz, pairs sum, etc.
> - `MEDIUM`: sum of primes, second largest, highest even/odd using reduce, remove duplicates, common elements, sort manually, frequency map, find pairs closest to zero, insert at index, reverse-multiply halves
> - `HARD`: None proposed for this batch (these are all foundational array topics)

> [!NOTE]
> **Hints are AI-generated** — the platform uses `GetHintForProblem` (Gemini AI) dynamically, so no static hints need to be stored in the DB. The hint system is already fully functional. However, each problem's `description` should be detailed enough for the AI to generate good hints.

---

## Proposed Changes

The plan uses the **recommended approach**: a separate idempotent seed script for array questions, plus documentation on how to add new questions via the Admin API.

---

### Phase 1 — Seed Script (Bulk Add All 47 Questions)

#### [NEW] `seed-arrays.ts` (alongside existing seed.ts)
**Path:** `apps/backend-api/src/infrastructure/database/prisma/seed-arrays.ts`

A standalone seed file that:
- Uses `prisma.problem.upsert({ where: { slug }, ... })` to be **idempotent** (safe to run multiple times)
- Does NOT delete existing problems
- Seeds all 47 questions with full descriptions, starter code, solution code, and test cases
- Assigns `category: 'JAVASCRIPT'`, `order` starting at 100 (to avoid conflicts with existing problems ordered 1–30)

The 47 problems mapped to seed data objects:

| # | Title | Slug | Difficulty |
|---|-------|------|------------|
| 1 | Average of Even Numbers | `average-of-even-numbers` | EASY |
| 2 | Sum of Odd Numbers | `sum-of-odd-numbers` | EASY |
| 3 | Sum of Prime Numbers | `sum-of-prime-numbers` | MEDIUM |
| 4 | Sum of Positive Numbers | `sum-of-positive-numbers` | EASY |
| 5 | Sum of Array Elements | `sum-of-array-elements` | EASY |
| 6 | Calculate Array Sum | `calculate-array-sum` | EASY |
| 7 | Reverse an Array | `reverse-an-array` | EASY |
| 8 | Reverse Array In-Place | `reverse-array-in-place` | EASY |
| 9 | Reverse Array Without Built-ins | `reverse-array-without-builtins` | EASY |
| 10 | Reverse Array Without Second Array | `reverse-array-no-second-array` | EASY |
| 11 | Reverse and Multiply Halves | `reverse-and-multiply-halves` | MEDIUM |
| 12 | Second Largest Element | `second-largest-element` | EASY |
| 13 | Highest Even with Reduce | `highest-even-with-reduce` | MEDIUM |
| 14 | Highest Odd Number | `highest-odd-number` | EASY |
| 15 | Find and Remove Duplicates | `find-and-remove-duplicates` | MEDIUM |
| 16 | Remove Duplicate Even Numbers | `remove-duplicate-even-numbers` | MEDIUM |
| 17 | Remove Multiples of Three | `remove-multiples-of-three` | EASY |
| 18 | Remove Odd Numbers | `remove-odd-numbers` | EASY |
| 19 | Remove Adjacent Odd Numbers | `remove-adjacent-odd-numbers` | MEDIUM |
| 20 | Replace Odd Numbers with Squares | `replace-odds-with-squares` | EASY |
| 21 | Common Elements from Two Arrays | `common-elements-two-arrays` | MEDIUM |
| 22 | Concatenate Two Arrays | `concatenate-two-arrays` | EASY |
| 23 | Merge Two Arrays Manually | `merge-two-arrays-manually` | EASY |
| 24 | Merge Two Arrays with Apply | `merge-arrays-with-apply` | MEDIUM |
| 25 | Add Element Without Push/Unshift | `add-element-without-push-unshift` | MEDIUM |
| 26 | Remove Last Without Pop | `remove-last-without-pop` | EASY |
| 27 | Shift Array Elements Left | `shift-elements-left` | EASY |
| 28 | Rotate Array N Times | `rotate-array-n-times` | MEDIUM |
| 29 | Sort Array Manually | `sort-array-manually` | MEDIUM |
| 30 | Check Element Without Includes | `check-element-without-includes` | EASY |
| 31 | Find First Occurrence | `find-first-occurrence` | EASY |
| 32 | Find All Occurrences | `find-all-occurrences` | EASY |
| 33 | Find Max and Min Without Math | `find-max-min-without-math` | EASY |
| 34 | Frequency of Elements | `frequency-of-elements` | MEDIUM |
| 35 | Count 1s in Numbers | `count-ones-in-numbers` | MEDIUM |
| 36 | Flip Sign with ForEach | `flip-sign-with-foreach` | EASY |
| 37 | Sum Values Multiple Ways | `sum-values-multiple-ways` | MEDIUM |
| 38 | FizzBuzz Array | `fizzbuzz-array` | EASY |
| 39 | Pairs with Target Sum | `pairs-with-target-sum` | MEDIUM |
| 40 | Two Numbers Closest to Zero | `two-numbers-closest-to-zero` | MEDIUM |
| 41 | Remove the Nth Element | `remove-nth-element` | EASY |
| 42 | Remove Second-Last Element | `remove-second-last-element` | EASY |
| 43 | Insert at Specific Index | `insert-at-specific-index` | EASY |
| 44 | First 5 Multiples of 3 (while) | `first-five-multiples-of-three` | EASY |
| 45 | Even Numbers 20 to 2 (while) | `even-numbers-20-to-2` | EASY |
| 46 | Array Length Without .length | `array-length-without-property` | MEDIUM |
| 47 | Remove Duplicates with Reduce | `remove-duplicates-with-reduce` | MEDIUM |

Each seed object will include:
```typescript
{
  title: string,
  slug: string,
  description: string,          // Rich markdown with examples
  difficulty: 'EASY' | 'MEDIUM',
  category: 'JAVASCRIPT',
  tags: string[],               // e.g. ['arrays', 'loops', 'reduce']
  starterCode: string,          // Function skeleton
  solutionCode: string,         // Complete working solution
  isPublished: true,
  order: number,                // 101–147
  testCases: {
    create: [
      { input, expectedOutput, isHidden: false, order: 1 },  // 2 visible
      { input, expectedOutput, isHidden: false, order: 2 },
      { input, expectedOutput, isHidden: true,  order: 3 },  // 2–3 hidden
      { input, expectedOutput, isHidden: true,  order: 4 },
    ]
  }
}
```

#### [MODIFY] `package.json` in `apps/backend-api`
Add a new npm script to run the array seed independently:
```json
"db:seed:arrays": "tsx src/infrastructure/database/prisma/seed-arrays.ts"
```

---

### Phase 2 — Admin API (How to Add New Questions — The Recommended Way)

This is already fully implemented. Here's the documented workflow for adding a **single new question** via the API without touching the seed file:

#### Step 1 — Create the Problem
```http
POST /api/admin/problems
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "title": "My New Array Problem",
  "slug": "my-new-array-problem",
  "description": "## Description\n\nGiven an array...",
  "difficulty": "EASY",
  "category": "JAVASCRIPT",
  "starterCode": "function solve(arr) {\n  // your code\n}",
  "solutionCode": "function solve(arr) {\n  return arr.filter(x => x > 0);\n}",
  "tags": ["arrays"],
  "isPublished": false
}
```

#### Step 2 — Add Test Cases
```http
POST /api/admin/test-cases
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "problemId": "<id from step 1>",
  "input": "[[1, -2, 3, -4]]",
  "expectedOutput": "[1, 3]",
  "isHidden": false,
  "order": 1
}
```

#### Step 3 — Publish
```http
PUT /api/admin/problems/<id>
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{ "isPublished": true }
```

> [!NOTE]
> The Admin UI (Sprint 4) will provide a form-based interface for this flow. Until then, use the REST API directly (via Postman, curl, or the Swagger UI at `/api/docs`).

---

### Phase 3 — Documentation

#### [NEW] `ADDING_QUESTIONS.md`
**Path:** `D:/interview-prep-platform/ADDING_QUESTIONS.md`

A concise guide documenting both methods:
1. **Bulk via seed script** (for dev/initial population)
2. **Single via Admin API** (for production — no re-seeding needed)

---

## Verification Plan

### Automated
- Run `npm run db:seed:arrays` — confirm all 47 problems are created with no errors
- Spot-check 5 random problems via `GET /api/problems?category=JAVASCRIPT&limit=50` to confirm they appear
- Verify test cases exist: `GET /api/admin/problems/:id/test-cases`

### Manual
- Visit the frontend problems list page → filter by `JAVASCRIPT` → confirm new problems appear
- Open a problem (e.g., "Reverse an Array") → verify description, starter code render correctly
- Submit a valid solution → verify test cases run and pass
- Click "Get Hint" on a problem → confirm AI hint is generated from the description
- Test the Admin API "add new question" flow end-to-end (create → add test cases → publish)

---

## How Hints Work (No Changes Needed)

Hints are **not stored statically** in the database. The existing `GetHintForProblem` use case:
1. Looks up the problem by slug
2. Checks the daily hint limit (3 per problem per user)
3. Calls Gemini AI (`IHintService`) with `problem.description + user's current code`
4. Returns a contextual, dynamic hint

Since all 47 new problems will have rich markdown descriptions, hints will work automatically with no code changes needed.

---

## Summary of Files to Create/Modify

| Action | File | Purpose |
|--------|------|---------|
| **[NEW]** | `apps/backend-api/src/infrastructure/database/prisma/seed-arrays.ts` | Idempotent seed for all 47 array questions |
| **[MODIFY]** | `apps/backend-api/package.json` | Add `db:seed:arrays` script |
| **[NEW]** | `ADDING_QUESTIONS.md` | Developer guide for adding questions |