# MemoHanzi - Implementation Package

Welcome! This package contains everything needed to implement MemoHanzi (记汉字 - "Remember Hanzi"), a self-hosted Chinese character learning application.

## 📦 What's Included

### 1. **HANZI-LEARNING-APP-SPECIFICATION.md** (Main Spec)
Complete technical specification including:
- ✅ System architecture
- ✅ Complete database schema (Prisma)
- ✅ All Server Actions API
- ✅ SM-2 algorithm implementation
- ✅ UI/UX specifications
- ✅ Testing strategy
- ✅ 12-week milestone plan
- ✅ Docker configuration
- ✅ Phase 2 & 3 roadmaps

### 2. **CLAUDE.md** (Instructions for Claude Code)
Strict implementation guidelines to prevent deviation from spec:
- Critical rules for following the specification
- Milestone approach
- Common mistakes to avoid
- Progress reporting format

### 3. **PROJECT-NAMING.md** (Naming Conventions)
All naming conventions for the MemoHanzi project:
- Application naming (display vs technical)
- Database naming
- Code conventions
- Branding guidelines

## 🚀 Quick Start

### For Claude Code:
1. Read `CLAUDE.md` first
2. Read `HANZI-LEARNING-APP-SPECIFICATION.md`
3. Read `PROJECT-NAMING.md` for naming conventions
4. Start with Milestone 1 (Week 1: Foundation)

### For Human Developers:
1. Read `HANZI-LEARNING-APP-SPECIFICATION.md` - this is your blueprint
2. Check `PROJECT-NAMING.md` for naming consistency
3. Follow the 12-week milestone plan
4. Use the testing strategy throughout

## 📋 Project Overview

**Name:** MemoHanzi (记汉字)  
**Tagline:** Remember Hanzi, effortlessly  
**Type:** Self-hosted web application  
**Purpose:** Learn Chinese characters using spaced repetition (SM-2 algorithm)

**Tech Stack:**
- Next.js 16 (TypeScript, App Router)
- PostgreSQL 18 + Prisma
- NextAuth.js v5
- Docker Compose + Nginx
- Tailwind CSS

**Timeline:** 10-12 weeks for MVP

## 🎯 Key Features (MVP)

**For Users:**
- Learn Hanzi with spaced repetition
- Multiple choice pinyin quiz (4 options)
- Create custom collections or use HSK levels
- Track progress with charts and statistics
- Search complete Hanzi database

**For Admins:**
- Import HSK vocabulary (JSON/CSV)
- Manage global collections
- User administration

## 📁 Project Structure

```
memohanzi/                          # Your project root
├── src/
│   ├── app/                        # Next.js App Router
│   ├── actions/                    # Server Actions
│   ├── components/                 # React components
│   ├── lib/                        # Utils (SM-2, parsers, etc)
│   └── types/                      # TypeScript types
├── prisma/
│   └── schema.prisma              # Database schema
├── docker/
│   ├── Dockerfile
│   └── nginx.conf
├── docker-compose.yml
└── README.md
```

## 🔑 Critical Implementation Notes

### 1. Follow the Specification EXACTLY
The specification is the single source of truth. Do not deviate without approval.

### 2. Implement Milestones Sequentially
Complete Week 1 → Week 2 → Week 3... in order.

### 3. SM-2 Algorithm is Critical
Use the EXACT formulas provided in Section 5 of the spec.

### 4. Testing is Mandatory
Write tests as you implement. Target: 70%+ coverage.

### 5. Database Schema is Fixed
Implement ALL models exactly as specified in the Prisma schema.

## 📊 Development Milestones

| Week | Milestone | Focus | Status |
|------|-----------|-------|--------|
| 1 | Foundation | Setup project, Docker, Prisma schema | ✅ Complete |
| 2 | Authentication | User registration, login, preferences | ✅ Complete |
| 3-4 | Data Import | Admin imports HSK data (JSON/CSV) | ✅ Complete |
| 5 | Collections | User collections + global HSK collections | ✅ Complete |
| 5 | Hanzi Search | Search interface and detail views | ✅ Complete |
| 6 | SM-2 Algorithm | Core learning algorithm + tests | ✅ Complete |
| 7-8 | Learning UI | Learning session interface | ✅ Complete |
| 9 | Dashboard | Progress tracking and visualizations | ✅ Complete |
| 10 | UI Polish | Responsive design, dark mode | 🔄 Next |
| 11 | Testing & Docs | Complete test coverage | |
| 12 | Deployment | Production deployment + data import | |

### ✅ Milestone 3 Completed Features

**Data Import System:**
- ✅ HSK JSON parser supporting complete-hsk-vocabulary format
- ✅ CSV parser with flexible column mapping
- ✅ Admin import page with file upload and paste functionality
- ✅ Update existing entries or skip duplicates option
- ✅ Detailed import results with success/failure counts and line-level errors
- ✅ Format validation and error reporting
- ✅ Support for multi-character hanzi (words like 中国)
- ✅ All transcription types (pinyin, numeric, wade-giles, zhuyin, ipa)
- ✅ 14 passing integration tests for both JSON and CSV parsers

**Database Initialization System:**
- ✅ Multi-file selection for batch initialization
- ✅ Real-time progress updates via Server-Sent Events (SSE)
- ✅ Progress bar showing current operation and percentage
- ✅ Automatic HSK level collection creation
- ✅ Auto-populate collections with hanzi based on level attribute
- ✅ Optional clean data mode (delete all existing data before import)
- ✅ Comprehensive statistics: hanzi imported, collections created, items added
- ✅ Admin initialization page at /admin/initialize
- ✅ SSE API route at /api/admin/initialize for long-running operations

**Files Created:**
- `src/lib/import/json-parser.ts` - HSK JSON format parser
- `src/lib/import/csv-parser.ts` - CSV format parser
- `src/lib/import/json-parser.test.ts` - JSON parser tests
- `src/lib/import/csv-parser.test.ts` - CSV parser tests
- `src/actions/admin.ts` - Admin-only import and initialization actions
- `src/actions/admin.integration.test.ts` - Admin action tests
- `src/app/(admin)/admin/import/page.tsx` - Import UI
- `src/app/(admin)/admin/initialize/page.tsx` - Initialization UI with SSE progress
- `src/app/api/admin/initialize/route.ts` - SSE API endpoint for real-time progress

### ✅ Milestone 4 Completed Features

**Collections Management:**
- ✅ Complete CRUD operations for collections (create, read, update, delete)
- ✅ Global HSK collections (admin-created, read-only for users)
- ✅ User personal collections (full control)
- ✅ Add hanzi to collections via:
  - Search & multi-select with checkboxes
  - Paste list (comma, space, or newline separated)
  - Create collection with hanzi list
- ✅ Remove hanzi (individual and bulk selection)
- ✅ Collection detail view with hanzi list
- ✅ Order preservation for added hanzi
- ✅ Duplicate detection and validation
- ✅ 21 passing integration tests

**Files Created:**
- `src/actions/collections.ts` - Collection Server Actions
- `src/actions/collections.integration.test.ts` - Complete test suite
- `src/app/(app)/collections/page.tsx` - Collections list page
- `src/app/(app)/collections/[id]/page.tsx` - Collection detail page
- `src/app/(app)/collections/new/page.tsx` - Create collection page

### ✅ Milestone 5 Completed Features

**Hanzi Search & Detail Views:**
- ✅ Public hanzi search (no authentication required)
- ✅ Search by simplified, traditional, pinyin, or meaning
- ✅ HSK level filtering (12 levels: new-1 through new-6, old-1 through old-6)
- ✅ Pagination with hasMore indicator (20 results per page)
- ✅ Comprehensive detail view showing:
  - All forms (simplified, traditional with isDefault indicator)
  - All transcriptions (pinyin, numeric, wade-giles, etc.)
  - All meanings with language codes
  - HSK level badges
  - Parts of speech
  - Classifiers, radical, frequency
- ✅ Add to collection from detail page
- ✅ 16 passing integration tests

**Files Created:**
- `src/actions/hanzi.ts` - Public hanzi search actions
- `src/app/(app)/hanzi/page.tsx` - Search page with filters
- `src/app/(app)/hanzi/[id]/page.tsx` - Detail page with all data
- `src/actions/hanzi.integration.test.ts` - Complete test suite

**Key Features:**
- searchHanzi(): Fuzzy search across simplified, traditional, pinyin, and meanings
- HSK level filtering for targeted vocabulary
- Pagination with hasMore indicator for infinite scroll support
- Complete hanzi data display including rare transcription types
- Direct integration with collections (add from detail page)

### ✅ Milestone 6 Completed Features

**SM-2 Algorithm Implementation:**
- ✅ Core SM-2 spaced repetition algorithm following SuperMemo specification
- ✅ Exact formulas for correct and incorrect answer calculations
- ✅ Initial values: easeFactor=2.5, interval=1, consecutiveCorrect=0
- ✅ Correct answer logic:
  - First correct: interval = 1 day
  - Second correct: interval = 6 days
  - Third+ correct: interval = Math.round(interval × easeFactor)
  - Increase easeFactor by 0.1 with each correct answer
- ✅ Incorrect answer logic:
  - Reset interval to 1 day
  - Reset consecutiveCorrect to 0
  - Decrease easeFactor by 0.2 (minimum 1.3)
  - Increment incorrectCount
- ✅ Card selection algorithm:
  - Filter out SUSPENDED cards
  - Select due cards (nextReviewDate ≤ now)
  - Priority: HARD > NORMAL > EASY
  - Sort by: nextReviewDate ASC, incorrectCount DESC, consecutiveCorrect ASC
  - Limit to cardsPerSession
- ✅ Wrong answer generation with Fisher-Yates shuffle
- ✅ 38 passing unit tests with 100% statement and line coverage
- ✅ 94.11% branch coverage (exceeds 90% requirement)

**Files Created:**
- `src/lib/learning/sm2.ts` - Core algorithm implementation
- `src/lib/learning/sm2.test.ts` - Comprehensive unit tests

**Functions Implemented:**
- `calculateCorrectAnswer()` - Update progress for correct answers
- `calculateIncorrectAnswer()` - Update progress for incorrect answers
- `selectCardsForSession()` - Select due cards with priority sorting
- `generateWrongAnswers()` - Generate 3 incorrect options from same HSK level
- `shuffleOptions()` - Fisher-Yates shuffle for randomizing answer positions

### ✅ Milestone 7-8 Completed Features

**Learning Interface:**
- ✅ Learning session page (`/learn/[collectionId]`) with dynamic routing
- ✅ Large hanzi display (text-9xl) for easy reading
- ✅ 4 pinyin answer options in 2x2 grid layout
- ✅ Auto-submit after answer selection (100ms delay)
- ✅ Progress bar showing "Card X of Y" with percentage
- ✅ Green/red feedback overlay with checkmark/X icons
- ✅ Correct answer display for incorrect responses
- ✅ English meaning display after answer submission
- ✅ Session summary screen with statistics:
  - Total cards, correct/incorrect counts
  - Accuracy percentage
  - Session duration in minutes
- ✅ Keyboard shortcuts:
  - Press 1-4 to select answer options
  - Press Space to continue after feedback
- ✅ Loading and error states
- ✅ Responsive mobile-first design

**Learning Server Actions:**
- ✅ `startLearningSession()` - Initialize session with card selection and answer generation
- ✅ `submitAnswer()` - Record answer and update SM-2 progress
- ✅ `endSession()` - Mark session complete and return summary
- ✅ `getDueCards()` - Count cards due today/this week
- ✅ `updateCardDifficulty()` - Manual difficulty override (EASY/MEDIUM/HARD/SUSPENDED)
- ✅ `removeFromLearning()` - Suspend card from learning

**SM-2 Integration:**
- ✅ Automatic progress tracking with SM-2 algorithm
- ✅ Due card selection with priority sorting
- ✅ New card introduction when insufficient due cards
- ✅ Two-stage card randomization:
  - Random tiebreaker for equal-priority cards during selection
  - Final shuffle of selected cards for presentation
- ✅ Wrong answer generation from same HSK level
- ✅ Session tracking in database (LearningSession, SessionReview)

**Navigation Integration:**
- ✅ "Start Learning" button on collection detail pages
- ✅ "Learn All" option on dashboard
- ✅ Routes: `/learn/all` and `/learn/[collectionId]`

**Files Created:**
- `src/actions/learning.ts` - Learning session Server Actions (700+ lines)
- `src/app/(app)/learn/[collectionId]/page.tsx` - Learning session UI (340+ lines)

**Enhancements:**
- ✅ English meaning display for vocabulary reinforcement
- ✅ Randomized card presentation to prevent demoralization
- ✅ All 38 SM-2 algorithm tests passing with 98.92% coverage

### ✅ Milestone 9 Completed Features

**Dashboard Enhancements:**
- ✅ Real-time statistics widgets replacing hardcoded zeros
- ✅ Due cards counter (now, today, this week)
- ✅ Total learned cards count
- ✅ Daily goal progress tracker (reviewed today / daily goal)
- ✅ Learning streak calculation (consecutive days with reviews)
- ✅ Recent activity section showing last 5 learning sessions
- ✅ Session cards with accuracy percentages and collection names
- ✅ Navigation link to progress page

**Progress Page:**
- ✅ Comprehensive progress page at `/progress`
- ✅ Date range selector (7/30/90/365 days)
- ✅ Summary statistics cards:
  - Cards reviewed in selected period
  - Overall accuracy percentage
  - Total cards in learning
  - Average session length (minutes)
- ✅ Daily Activity bar chart (Recharts):
  - Stacked correct/incorrect reviews by date
  - Interactive tooltips with detailed counts
- ✅ Accuracy Trend line chart:
  - Daily accuracy percentage over time
  - Smooth line visualization
- ✅ Session history table:
  - Sortable by date
  - Shows collection, cards reviewed, accuracy, session length
  - Responsive design
- ✅ Dark mode compatible color schemes

**Progress Server Actions:**
- ✅ `getStatistics()` - Returns due cards, total learned, daily goal, streak
- ✅ `getUserProgress()` - Returns overview stats and daily activity breakdown
- ✅ `getLearningSessions()` - Returns paginated session history
- ✅ `getHanziProgress()` - Individual hanzi progress details
- ✅ `resetHanziProgress()` - Reset card to initial state

**Statistics Calculations:**
- ✅ Streak calculation algorithm (consecutive days with reviews)
- ✅ Daily activity aggregation using Map for efficient grouping
- ✅ Accuracy calculations (correct / total reviews)
- ✅ Average session length (total duration / session count)
- ✅ Date range filtering for historical data

**Recharts Integration:**
- ✅ Installed and configured Recharts library
- ✅ Line chart component for trends
- ✅ Bar chart component with stacking for activity
- ✅ Responsive containers for mobile/desktop
- ✅ Custom tooltips and legends

**Files Created:**
- `src/actions/progress.ts` - Progress tracking Server Actions (550+ lines)
- `src/app/(app)/progress/page.tsx` - Progress visualization page (380+ lines)

**Files Modified:**
- `src/app/(app)/dashboard/page.tsx` - Added real statistics and recent activity
- Navigation updated across dashboard and progress pages

## 🎨 Naming Conventions

**User-Facing:**
- Always: "MemoHanzi" (capitalized)
- Tagline: "Remember Hanzi, effortlessly"
- Include Chinese: 记汉字

**Technical:**
- Directory: `memohanzi/`
- Database: `memohanzi_db`
- User: `memohanzi_user`
- Container: `memohanzi-app`, `memohanzi-postgres`

See `PROJECT-NAMING.md` for complete guidelines.

## 📚 Data Source

HSK Vocabulary: https://github.com/drkameleon/complete-hsk-vocabulary/

This repository contains comprehensive HSK (Chinese proficiency test) vocabulary data that will be imported into MemoHanzi.

## 🔐 Security Highlights

- ✅ Passwords hashed with bcrypt
- ✅ NextAuth.js session management
- ✅ HTTPS via Nginx
- ✅ Rate limiting
- ✅ Input validation (Zod)
- ✅ SQL injection prevention (Prisma)

## 🧪 Testing Strategy

- **Unit Tests (70%):** Business logic, SM-2 algorithm, parsers
- **Integration Tests (20%):** Server Actions, database operations
- **E2E Tests (10%):** Critical user flows

**Tools:** Vitest (unit/integration), Playwright (E2E)

## 📖 Additional Resources

- **Next.js Docs:** https://nextjs.org/docs
- **Prisma Docs:** https://www.prisma.io/docs
- **NextAuth Docs:** https://authjs.dev
- **SM-2 Algorithm:** https://www.supermemo.com/en/archives1990-2015/english/ol/sm2

## 🎯 Success Criteria (MVP)

**Technical:**
- [ ] All tests passing (70%+ coverage)
- [ ] Can import complete HSK vocabulary
- [ ] Page load <2s
- [ ] Mobile responsive

**Functional:**
- [ ] Complete learning session works end-to-end
- [ ] SM-2 algorithm accurate
- [ ] Progress tracking working
- [ ] Collections management functional
- [ ] Search efficient

**User Experience:**
- [ ] Can learn 20+ cards in 5-10 minutes
- [ ] Interface intuitive
- [ ] Daily use sustainable

## 🚦 Getting Started Checklist

Before beginning implementation:

- [ ] Read complete specification document
- [ ] Understand the tech stack
- [ ] Review the milestone approach
- [ ] Check naming conventions
- [ ] Set up development environment
- [ ] Confirm understanding of SM-2 algorithm

## 💡 Important Reminders

1. **Read the spec before implementing anything**
2. **Ask questions if anything is unclear**
3. **Don't make up alternatives or "improvements"**
4. **Write tests as you go**
5. **Follow the milestone sequence**
6. **Use consistent naming (check PROJECT-NAMING.md)**

## 📞 Next Steps

**For Claude Code:**
Start by saying: "I've read CLAUDE.md and HANZI-LEARNING-APP-SPECIFICATION.md. Ready to begin Milestone 1: Project Foundation."

**For Human Developers:**
1. Set up your development environment
2. Create project directory: `memohanzi/`
3. Begin Milestone 1 tasks
4. Reference the specification frequently

---

**Good luck building MemoHanzi! 🎯**

记汉字 - Remember Hanzi, effortlessly.