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:

Read CLAUDE.md first
Read HANZI-LEARNING-APP-SPECIFICATION.md
Read PROJECT-NAMING.md for naming conventions
Start with Milestone 1 (Week 1: Foundation)

For Human Developers:

Read HANZI-LEARNING-APP-SPECIFICATION.md - this is your blueprint
Check PROJECT-NAMING.md for naming consistency
Follow the 12-week milestone plan
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

Read the spec before implementing anything
Ask questions if anything is unclear
Don't make up alternatives or "improvements"
Write tests as you go
Follow the milestone sequence
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:

Set up your development environment
Create project directory: memohanzi/
Begin Milestone 1 tasks
Reference the specification frequently

Good luck building MemoHanzi! 🎯

记汉字 - Remember Hanzi, effortlessly.