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

## 🎨 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.