# WordWise — PET Vocabulary Spaced Repetition System

## Overview

A PHP/MySQL spaced repetition system for Cambridge B1 Preliminary (PET) vocabulary,
designed for 8 weeks of homework alongside classroom instruction.

**Algorithm:** SM-2 (Wozniak & Gorzelanczyk, 1994)
**Words:** ~400 PET headwords, tiered by frequency (Nation, 2001 principles)
**Accessibility:** WCAG 2.1 AA compliant

---

## Files

    pet_srs/
    ├── config.php      <- Database credentials (edit this first)
    ├── schema.sql      <- Database tables + all seeded vocabulary
    ├── sm2.php         <- SM-2 algorithm, card management
    ├── auth.php        <- Login / register
    └── index.php       <- Main app (dashboard + flashcard review)

---

## cPanel Setup

### 1. Create a MySQL database

In cPanel > MySQL Databases:
- Create database:  youraccount_pet_srs
- Create user:      youraccount_srsuser  (strong password)
- Add user to database with ALL PRIVILEGES

### 2. Import the schema

In cPanel > phpMyAdmin:
- Select your new database
- Import > choose schema.sql
- This creates all tables AND seeds the full word list

### 3. Edit config.php

    define('DB_HOST', 'localhost');
    define('DB_USER', 'youraccount_srsuser');
    define('DB_PASS', 'your_strong_password');
    define('DB_NAME', 'youraccount_pet_srs');

### 4. Upload files

Upload all 5 files to your storygame/ directory (e.g. storygame/vocab/).

---

## How It Works

### For Students
1. Register with username + email
2. Each day, up to 7 new words are introduced (lowest frequency tier first)
3. Review due cards: Easy / Good / Hard / Forgot
4. SM-2 schedules the next review optimally
5. ~20 cards per session, about 5-10 minutes

### Word Sequencing (8-Week Plan)

Week 1  Tier 1  Core grammar words, ultra-high frequency verbs & nouns
Week 2  Tier 2  Essential everyday vocabulary
Week 3  Tier 3  Travel, education, communication
Week 4  Tier 4  Topic vocabulary, opinion language
Week 5  Tier 5  Adjectives, health, work
Week 6  Tier 6  Formal vocabulary, shopping, environment
Week 7  Tier 7  Academic-adjacent, discourse markers
Week 8  Tier 8  Challenging / specialist PET vocabulary

---

## Research Basis

Spacing effect:        Cepeda et al. (2006), Psychological Bulletin
SM-2 algorithm:        Wozniak & Gorzelanczyk (1994), Acta Neurobiologiae Experimentalis
Testing effect:        Roediger & Karpicke (2006), Psychological Science
Frequency sequencing:  Nation (2001), Learning Vocabulary in Another Language
Simplified ratings:    Settles & Meeder (2016), ACL 2016
Accessibility:         W3C WCAG 2.1 (2018), https://www.w3.org/TR/WCAG21/

---

## WCAG 2.1 AA Features

1.4.3  Colour contrast >= 4.5:1 throughout
1.4.4  Text scales to 200% without loss
2.1.1  Full keyboard navigation (Space to reveal, 1-4 to rate)
2.4.1  Skip link to main content
2.4.3  Focus managed to word heading on each new card
3.3.1  Error messages with aria-invalid on form fields
4.1.3  ARIA live regions for dynamic card content and stats
1.3.1  Semantic HTML: article, header, main, section with aria-label

---

## Customisation

- WORDS_PER_SESSION (config.php): max cards per session (default 20)
- NEW_WORDS_PER_DAY (config.php): new words introduced daily (default 7)
- Add your own words: INSERT INTO vocabulary_items (word, part_of_speech, ...)
- Adjust frequency_tier to change when words are introduced
