# ⚡ MorseQuest

> *Adventure-based Morse code learning with amateur radio mastery*

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform: Web](https://img.shields.io/badge/Platform-Web-blue.svg)](https://git.keylinkit.net/games/morsequest)
[![Status: Development](https://img.shields.io/badge/Status-Development-orange.svg)](https://git.keylinkit.net/games/morsequest)

## 🎯 Overview

**MorseQuest** is a gamified amateur radio education platform that teaches Morse code through personalized mnemonic creation and progressive adventures. Built for Scout programs, amateur radio enthusiasts, STEM education, and lifelong learners.

### ⚡ Key Features

- **🧠 Personal Memory System**: Create your own mnemonic phrases for superior retention
- **🎮 Quest Progression**: 6 adventure levels + complete amateur radio license prep
- **🎵 Multi-Modal Learning**: Synchronized audio-visual Morse code presentation
- **🏆 Achievement System**: Points, badges, streaks, and rank advancement
- **⚔️ Adventure Theme**: Quest-based learning with gentle gaming elements
- **📱 Mobile-First**: Works perfectly on all devices

## 🚀 Quick Start

### For Developers

```bash
# Clone the repository
git clone https://git.keylinkit.net/games/morsequest.git
cd morsequest

# Install dependencies
npm install

# Start development server
npm run dev

# Open browser to http://localhost:3000
```

### For Deployment

```bash
# Build and run with Docker
docker-compose up -d

# Access at http://localhost:3000
```

## 🎮 Game Experience

### **Quest Structure**
```
Level 1 - Novice (0-1K pts): Learn basic letters through adventure stories
Level 2 - Operator (1K-5K pts): Simple words and messages
Level 3 - General (5K-15K pts): Complex telegraph scenarios
Level 4 - Extra (15K-50K pts): Multi-part adventures
Level 5 - Expert (50K-150K pts): High-speed challenges
Level 6 - Legend (150K+ pts): Master-level quests
```

### **Adventure Learning**
- **Personal Mnemonics**: "Create memory phrases where short words are dots, LONG words are dashes"
- **Story-Driven**: Each level has adventure scenarios and challenges
- **No Penalties**: Wrong answers just mean "try again, adventurer!"
- **Progressive**: Gentle difficulty curve prevents frustration

## 💰 Business Model

### **Free Adventure**
- Complete Morse code quest (6 levels)
- First 3 amateur radio modules
- Basic progress tracking and achievements

### **Premium Quest** ($9.95/year Individual, $19.95/year Family)
- Complete amateur radio license preparation (Technician, General, Extra)
- 1,400+ official exam questions with explanations
- Advanced analytics and progress tracking
- Unlimited speed challenges and practice modes

### **Launch Strategy**
- **First year completely free** for all players to build community
- **Admin controls** to activate premium when ready
- **Early adopter rewards** for loyalty and testimonials

## 🎯 Target Markets

1. **Amateur Radio Community** (800K+ licensed operators + aspiring hams)
2. **Scout Programs** (Merit badge prep, group activities, Pack 404 pilot)
3. **STEM Education** (Schools, colleges, communication curriculum)
4. **Gaming/Learning** (Adventure-based education enthusiasts)

## 🛠️ Technical Stack

- **Frontend**: React 18+, TypeScript, adventure-themed CSS
- **Backend**: Node.js, Express, SQLite/PostgreSQL
- **Payments**: Authorize.net integration with freemium model
- **Deployment**: Docker, nginx, SSL/HTTPS
- **Audio**: Web Audio API for precise Morse timing
- **Analytics**: Learning progression and quest completion tracking

## 📈 Development Roadmap

### **Phase 1: Core Quest** (10-12 weeks)
- [ ] Personal mnemonic creation system
- [ ] Complete Morse code adventure (6 levels)
- [ ] Audio-visual quest presentation
- [ ] Achievement and progression system
- [ ] Mobile-responsive adventure interface

### **Phase 2: Premium Expansion** (8-10 weeks)
- [ ] Amateur radio license quest modules
- [ ] Authorize.net premium subscription
- [ ] Admin dashboard and user management
- [ ] Advanced analytics and reporting

### **Phase 3: Community Platform** (6-8 weeks)
- [ ] Multiplayer features and leaderboards
- [ ] White-label deployment for organizations
- [ ] Advanced learning analytics
- [ ] Performance optimization and scaling

## 🎨 Brand Identity

### **Adventure Theme**
- **Colors**: Quest gold (#D4AF37), adventure blue (#4169E1), brass (#CD7F32)
- **Typography**: Adventure-ready serif headers, clean sans-serif body
- **Iconography**: Telegraph keys, quest gems, achievement badges
- **Experience**: Story-driven learning with gentle gaming elements

### **Voice & Tone**
- **Encouraging**: "Great work, adventurer!" not "Incorrect answer"
- **Adventure-focused**: Quest terminology without being overwhelming
- **Educational**: Serious learning disguised as engaging adventure
- **Inclusive**: Welcoming to all ages and skill levels

## 📊 Success Metrics

### **Quest Engagement**
- 85% complete personal mnemonic creation
- 70% return within 7 days for next quest
- 15% convert to premium adventures
- 85% player satisfaction score

### **Learning Effectiveness**
- 85% accuracy on common letters after 3 quests
- 90%+ amateur radio exam pass rate for premium players
- 70% knowledge retention after 1 week

### **Business Success**
- 5,000+ registered adventurers in Year 1
- $75K+ ARR by Year 3
- 10+ Scout council partnerships
- 5+ ham radio club endorsements

## 🤝 Contributing

Join the adventure! We welcome contributions from the amateur radio and educational gaming communities.

### **How to Contribute**
1. Fork the repository
2. Create a quest branch (`git checkout -b quest/amazing-feature`)
3. Commit your adventures (`git commit -m 'Add amazing quest feature'`)
4. Push to the branch (`git push origin quest/amazing-feature`)
5. Open a Pull Request

### **Adventure Guidelines**
- Maintain the quest/adventure theme
- Focus on educational value with gaming elements
- Ensure mobile-friendly adventures
- Add tests for new quest features
- Update adventure documentation

## 📞 Quest Masters

**Lead Developer**: Allen McGhan  
**Organization**: Keylink IT  
**Location**: Hendersonville, TN  
**Specialties**: Amateur Radio Education, Scout Adventures, Gaming Platforms

### **Adventure Community**
- **Pilot Quest**: Pack 404 Scouts (Hendersonville, TN)
- **Amateur Radio**: General license holder, active in local clubs
- **Educational Gaming**: 160+ client MSP background

### **Business Adventures**
- White-label quest deployments
- Educational institution licensing
- Scout council adventure partnerships
- Ham radio club quest integrations

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

**Copyright (c) 2024 Keylink IT - Allen McGhan**

## 🎯 Forge Platform

This adventure is built for deployment on the **Keylink IT Forge** platform, providing:
- Streamlined Docker deployment
- White-label adventure customization
- Educational institution quest management
- Revenue sharing and analytics
- Professional support and maintenance

---

*Built with ❤️ for adventurous learners and the amateur radio community*

**Ready to begin your Morse code adventure?** ⚡ **Start your quest today!** 🚀