LinguaDrill Development Guide

This skill guides you through building or modifying LinguaDrill, a language learning application that helps users achieve minimal fluency through intelligent iterative drilling of the 200 most common words.

What This Skill Does

Helps you build a PWA-based language learning app with:

Architecture Overview

**Frontend**: Vanilla HTML/CSS/JS PWA with tab-based interface (Vocabulary, Grammar, Dialog)

**Backend**: Node.js file server reading JSON datasets from `~/languages/`

**Storage**: User progress in localStorage; language data in JSON files

**Languages**: Configured via `learner-languages.txt` (one language per line)

Step-by-Step Implementation Instructions

1. Verify or Create Project Structure

Check for these directories and files:

If missing, create them.

2. Follow Strict Code Style Requirements

**CRITICAL**: This project has non-negotiable JavaScript conventions:

```javascript

myobj = {

attrib1: "",

attrib2: ""

}

myobj.method1 = function(p1, p2) {

// code here

}

myobj.method2 = function(p1, p2) {

// code here

}

```

3. Implement Language Dataset Structure

Each `~/languages/{language}.json` file must contain 20 iterations with:

```json

{

"alphabet": [

{

"character": "A",

"sound": "ah",

"name": "alpha"

}

],

"iterations": [

{

"iteration": 1,

"vocabulary": [

{

"word": "hello",

"translation": "hola",

"normativeForm": "hola"

}

],

"grammars": [

{

"rule": "Subject-Verb Order",

"example": "Yo hablo",

"explanation": "Subject precedes verb"

}

],

"dialog": {

"lines": [

{

"speaker": "A",

"text": "Hola",

"translation": "Hello"

}

]

}

}

]

}

```

4. Build the Backend (Node.js Server)

**Key responsibilities**:

Example endpoint structure:

5. Build the Frontend (PWA)

**User Flow**:

1. **Onboarding**: Email, password, native language, target language (stored in localStorage)

2. **Alphabet Drill**: User must get each letter correct 3 times before advancing

3. **Tab-Based Learning**: Three tabs (Vocabulary, Grammar, Dialog)

**Tab Details**:

- New words: 3 consecutive correct answers to master

- Previously mastered words: 1 correct answer (resets to 3 if incorrect)

**Critical Requirements**:

6. Implement Mastery Rules

**New content**: Requires 3 consecutive correct answers

**Previously mastered content**: Requires 1 correct answer (resets to 3 if wrong)

**Iteration advancement**: All three tabs (Vocabulary, Grammar, Dialog) must be completed

7. Add Navigation

Hamburger menu with:

8. Ensure PWA Functionality

Add:

9. Test Key Scenarios

Constraints and Important Notes

Example Usage

**Scenario**: User wants to add Mandarin Chinese

1. Add `mandarin` to `learner-languages.txt`

2. Generate `~/languages/mandarin.json` with 20 iterations (200 most common words, grammar rules, dialogs)

3. User selects Mandarin in onboarding

4. Frontend fetches `GET /api/languages/mandarin`

5. User drills alphabet (Pinyin characters, 3 correct each)

6. User completes Iteration 1 (Vocabulary, Grammar, Dialog tabs)

7. Progress stored in localStorage: `{ currentIteration: 1, masteredWords: [...], ... }`

**Scenario**: Developer modifies grammar drill logic

1. Open `public/app.js`

2. Locate `grammarTab.drill` function (object literal pattern)

3. Update multiple-choice generation or mastery counting

4. Test with sample language dataset

5. Verify 3-correct requirement still enforced

---

**Key Files to Work With**: