230 lines
6.7 KiB
Markdown
230 lines
6.7 KiB
Markdown
# 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.
|