SpellBuddy is a modern web application designed to help students with dyslexia practice English spelling in a fun and encouraging way. The application uses AI to generate personalized exercises, evaluate spelling, and provide helpful tips for improvement.
- Personalized Exercises: Generates Swedish texts for translation that include words the student has struggled with in the past
- Speech Recognition: Allows students to speak their translations before writing them
- Spelling Evaluation: AI-powered evaluation of spelling with personalized tips for improvement
- Word Practice: Focused practice on misspelled words until they are mastered
- Progress Tracking: Tracks progress over time and provides encouraging feedback
- User Accounts: Personalized experience with user-specific exercises and progress tracking
- Preferences: Customize exercises based on age, interests, and difficulty level
- Gamification: Level up system, achievements, and streaks to keep students motivated
- Modern Design: Beautiful glass morphism UI with dark mode support
- Responsive: Works on desktop, tablet, and mobile devices
SpellBuddy features a comprehensive achievement system with 44 achievements across 9 categories:
- Streak Achievements: Rewards for consistent daily practice
- Exercise Count: Milestones for completing exercises
- Perfect Exercises: Recognition for exercises completed without mistakes
- Word Count: Achievements for learning new words
- Level Achievements: Rewards for reaching specific levels
- Challenge Achievements: Recognition for completing challenges
- Accuracy Achievements: Rewards for achieving high accuracy
- Time-based Achievements: Recognition for completing exercises quickly
- Difficulty Achievements: Rewards for tackling harder content
See ACHIEVEMENTS.md for detailed documentation on the achievement system.
- Node.js 18.0 or higher
- npm or yarn
- OpenAI API key
-
Clone the repository
git clone https://github.com/yourusername/spellbuddy.git cd spellbuddy -
Install dependencies
npm install
-
Create a
.env.localfile in the root directory with your environment variables# Authentication JWT_SECRET=your_jwt_secret_key_here # OpenAI API OPENAI_API_KEY=your_openai_api_key_here OPENAI_MODEL=gpt-4o-mini # Database DATABASE_URL=file:./spellbuddy.db -
Generate the database schema
npm run db:generate
-
Run database migrations
npm run db:migrate
Start the development server:
npm run devThe application will be available at http://localhost:3000
Build the application for production:
npm run buildStart the production server:
npm startRun the container with a volume to persist the database:
# Create a directory for persistent data
mkdir -p ~/spellbuddy-data
# Run the container with a mounted volume
docker run -d -p 3000:3000 \
-v ~/spellbuddy-data:/app/data \
-e JWT_SECRET=your_jwt_secret \
-e OPENAI_API_KEY=your_openai_api_key \
-e OPENAI_MODEL=gpt-4o-mini \
yourusername/spellbuddy:latestThe database will be automatically created if it doesn't exist, and migrations will be run on container startup.
If you need to run database migrations manually (for example, after updating the application):
# Get the container ID
CONTAINER_ID=$(docker ps -q -f "ancestor=yourusername/spellbuddy:latest")
# Run migrations
docker exec $CONTAINER_ID npm run db:migrateIf you're developing on an ARM-based Mac (M1/M2/M3) but deploying to an AMD64 server, make sure to use the amd64 version of the image:
# Pull the amd64 version explicitly
docker pull --platform linux/amd64 yourusername/spellbuddy:latest
# Run with platform specified
docker run --platform linux/amd64 -d -p 3000:3000 \
-v ~/spellbuddy-data:/app/data \
-e JWT_SECRET=your_jwt_secret \
-e OPENAI_API_KEY=your_openai_api_key \
-e OPENAI_MODEL=gpt-4o-mini \
yourusername/spellbuddy:latestThis project uses GitHub Actions for continuous integration and deployment:
- Build: Builds and tests the application on every push and pull request
- Docker: Creates a Docker image and pushes it to Docker Hub on every push to the main branch
- Versioning: Creates tagged Docker images for every Git tag with the format
v*
To use the CI/CD pipeline, set the following secrets in your GitHub repository:
DOCKER_HUB_USERNAME: Your Docker Hub usernameDOCKER_HUB_TOKEN: Your Docker Hub access token
- Create an account or log in to access personalized exercises
- Set your preferences (age, interests, difficulty level)
- The student is presented with a short Swedish text to translate
- They first speak their translation (using speech recognition)
- Then they write their translation
- The AI evaluates their spelling and provides feedback
- For any misspelled words, the student practices them until they get them right
- Progress is tracked and used to generate personalized exercises
- Achievements are unlocked as the student progresses
- The student can view their progress and achievements on the progress page
- Frontend: Next.js, React, TypeScript, Tailwind CSS
- Backend: Next.js API Routes, SQLite with Drizzle ORM
- AI: OpenAI API for exercise generation and spelling evaluation
- Speech: React Speech Recognition
- Authentication: JWT
- Deployment: Docker, GitHub Actions
- Design: Glass morphism, CSS animations, responsive design
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- ACHIEVEMENTS.md: Detailed documentation of the achievement system
- RELEASE.md: Information about the release process
- CONTRIBUTING.md: Guidelines for contributing to the project
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenAI for providing the AI capabilities
- Next.js team for the amazing framework
- All contributors who have helped improve this project