6.7 KiB
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:
- Read
CLAUDE.mdfirst - Read
HANZI-LEARNING-APP-SPECIFICATION.md - Read
PROJECT-NAMING.mdfor 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.mdfor 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.