From 7ea8f12a31b731c63d917aa7e256ab9f88171c4a Mon Sep 17 00:00:00 2001 From: Allen McGhan Date: Wed, 29 Apr 2026 15:18:08 -0500 Subject: [PATCH] =?UTF-8?q?=E2=9A=A1=20Initial=20commit:=20MorseQuest=20-?= =?UTF-8?q?=20Complete=20amateur=20radio=20education=20platform?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Complete Product Requirements Document with full technical specs - MorseQuest adventure-based branding and visual identity - All logos, icons, and brand assets ready for development - Freemium business model ($9.95/year, first year free launch strategy) - Ready for Keylink IT Forge platform deployment Phase 1 MVP ready to begin (10-12 week timeline) --- .gitignore | 218 ++++++++++ LICENSE | 52 +++ README.md | 210 +++++++++ assets/badges/badge-expert.svg | 62 +++ assets/badges/badge-novice.svg | 46 ++ assets/icons/morse-dash.svg | 21 + assets/icons/morse-dot.svg | 21 + assets/icons/telegraph-key.svg | 33 ++ assets/logos/logo-horizontal.svg | 88 ++++ assets/logos/logo-icon.svg | 80 ++++ assets/logos/primary-logo.svg | 86 ++++ docs/BRAND_GUIDELINES.md | 261 +++++++++++ docs/PRODUCT_REQUIREMENTS_DOCUMENT.md | 594 ++++++++++++++++++++++++++ 13 files changed, 1772 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 assets/badges/badge-expert.svg create mode 100644 assets/badges/badge-novice.svg create mode 100644 assets/icons/morse-dash.svg create mode 100644 assets/icons/morse-dot.svg create mode 100644 assets/icons/telegraph-key.svg create mode 100644 assets/logos/logo-horizontal.svg create mode 100644 assets/logos/logo-icon.svg create mode 100644 assets/logos/primary-logo.svg create mode 100644 docs/BRAND_GUIDELINES.md create mode 100644 docs/PRODUCT_REQUIREMENTS_DOCUMENT.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a62964e --- /dev/null +++ b/.gitignore @@ -0,0 +1,218 @@ +# Dependencies +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +package-lock.json +yarn.lock + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Coverage directory used by tools like istanbul +coverage/ +*.lcov + +# nyc test coverage +.nyc_output + +# ESLint cache +.eslintcache + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test +.env.production + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +public + +# Storybook build outputs +.out +.storybook-out + +# Temporary folders +tmp/ +temp/ + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# Vuepress build output +.vuepress/dist + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +# Database files +*.db +*.sqlite +*.sqlite3 +data/ + +# Build artifacts +build/ +dist/ + +# Docker +.dockerignore +Dockerfile* +docker-compose*.yml + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Application specific +uploads/ +storage/ +public/uploads/ + +# Forge Platform specific +forge-config.json +.forge/ +deployment-keys/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..188958c --- /dev/null +++ b/LICENSE @@ -0,0 +1,52 @@ +MIT License + +Copyright (c) 2024 Keylink IT - Allen McGhan + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +## Additional Terms for Keylink IT Forge Platform + +This software is developed as part of the Keylink IT Forge platform for +educational technology deployment. While the core software is MIT licensed, +the following additional terms apply: + +### Educational Use +This software is specifically designed for educational purposes including: +- Scout programs and merit badge preparation +- Amateur radio license examination preparation +- STEM education curriculum enhancement +- Lifelong learning and skill development + +### Brand and Trademark +"MorseQuest" name and associated branding elements (logos, color schemes, +visual identity) are proprietary to Keylink IT and are not covered under +this MIT license. Use of branding elements requires separate permission. + +### Forge Platform Integration +Deployment through the Keylink IT Forge platform includes additional +commercial terms for: +- White-label customization services +- Multi-tenant deployment capabilities +- Professional support and maintenance +- Revenue sharing agreements + +Contact Allen McGhan at Keylink IT for commercial licensing and Forge +platform deployment arrangements. diff --git a/README.md b/README.md new file mode 100644 index 0000000..265249d --- /dev/null +++ b/README.md @@ -0,0 +1,210 @@ +# ⚡ 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!** 🚀 diff --git a/assets/badges/badge-expert.svg b/assets/badges/badge-expert.svg new file mode 100644 index 0000000..4fb3cce --- /dev/null +++ b/assets/badges/badge-expert.svg @@ -0,0 +1,62 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + E + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/assets/badges/badge-novice.svg b/assets/badges/badge-novice.svg new file mode 100644 index 0000000..0964f6a --- /dev/null +++ b/assets/badges/badge-novice.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NOVICE + + + + + + + + + + + + diff --git a/assets/icons/morse-dash.svg b/assets/icons/morse-dash.svg new file mode 100644 index 0000000..18cd46d --- /dev/null +++ b/assets/icons/morse-dash.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/assets/icons/morse-dot.svg b/assets/icons/morse-dot.svg new file mode 100644 index 0000000..533b307 --- /dev/null +++ b/assets/icons/morse-dot.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/assets/icons/telegraph-key.svg b/assets/icons/telegraph-key.svg new file mode 100644 index 0000000..c4c74bb --- /dev/null +++ b/assets/icons/telegraph-key.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/assets/logos/logo-horizontal.svg b/assets/logos/logo-horizontal.svg new file mode 100644 index 0000000..fa4afe7 --- /dev/null +++ b/assets/logos/logo-horizontal.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MORSEQUEST + + + + + + + + + + + + + + + + + + + + + + Learn Morse Code + + + Master Amateur Radio + + + Adventure Awaits + + + + + + + + + + + + + diff --git a/assets/logos/logo-icon.svg b/assets/logos/logo-icon.svg new file mode 100644 index 0000000..698345a --- /dev/null +++ b/assets/logos/logo-icon.svg @@ -0,0 +1,80 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/primary-logo.svg b/assets/logos/primary-logo.svg new file mode 100644 index 0000000..76f387c --- /dev/null +++ b/assets/logos/primary-logo.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MORSE + + + + + QUEST + + + + + + + + + + + + + + + + + + + + + + + + + + Learn Morse Code • Master Amateur Radio • Adventure Awaits + + + + + + + + diff --git a/docs/BRAND_GUIDELINES.md b/docs/BRAND_GUIDELINES.md new file mode 100644 index 0000000..88251f9 --- /dev/null +++ b/docs/BRAND_GUIDELINES.md @@ -0,0 +1,261 @@ +# 🎨 MorseQuest Brand Guidelines + +## Visual Identity Overview + +**MorseQuest** uses an adventure / quest theme that balances authenticity with modern educational design principles. The brand conveys exploration, learning, and technical mastery through a quest-driven aesthetic with gentle gaming elements. + +## Color Palette + +### Primary Colors +- **Quest Gold**: `#D4AF37` - Primary brand color, represents brass telegraph equipment and treasure +- **Adventure Blue**: `#4169E1` - Secondary brand color, represents quest gems and the open horizon +- **Brass**: `#CD7F32` - Accent color, represents authentic equipment and forged tools + +### Secondary Colors +- **Aged Parchment**: `#F5E6D3` - Background color, represents quest scrolls +- **Deep Forest**: `#3C2415` - UI elements, represents night-camp and adventurer gear +- **Signal Gold**: `#FFD700` - Highlights and active states +- **Quest Red**: `#CC0000` - Error states and urgent CTAs + +### Supporting Colors +- **Brass Dust**: `#B8860B` - Muted accent +- **Telegraph Wire**: `#654321` - Border and line elements +- **Gem Sky**: `#87CEEB` - Success states and achievements +- **Midnight**: `#191970` - Adventure-blue depth and emphasis + +## Typography + +### Primary Font Stack +**Headers**: `"Cinzel", "MedievalSharp", serif` +- Adventure-ready serif for main headings +- Conveys quest narrative and heroic tone +- Available via Google Fonts + +**Body Text**: `"Open Sans", sans-serif` +- Clean, readable sans-serif for content +- Excellent cross-platform compatibility +- Accessible at all sizes + +**Code/Morse**: `"Source Code Pro", monospace` +- Technical content and Morse code display +- Clear distinction between dots and dashes +- Professional development feel + +### Typography Scale +- **Hero Text**: 48px - Main landing page titles +- **Page Headers**: 32px - Section titles +- **Subheaders**: 24px - Component headers +- **Body Text**: 16px - Standard reading content +- **Caption Text**: 14px - Secondary information +- **Small Text**: 12px - Legal/disclaimer text + +## Logo Usage + +### Primary Logo +**File**: `primary-logo.svg` +- Full horizontal logo with telegraph key and quest gem +- Use for main branding, headers, marketing materials +- Minimum width: 300px +- Clear space: 1x logo height on all sides + +### Horizontal Logo +**File**: `logo-horizontal.svg` +- Compact version for headers and wide spaces +- Use when vertical space is limited +- Minimum width: 200px +- Clear space: 0.5x logo height on all sides + +### Icon Logo +**File**: `logo-icon.svg` +- Icon-only version for favicons and app icons +- Use at 32px and larger +- Square format with telegraph key focus +- Minimum size: 16px + +## Iconography + +### UI Icons +All icons follow the brass/telegraph theme with quest accents: + +**Telegraph Key**: `telegraph-key.svg` +- Primary interaction icon +- Represents Morse code input/practice +- Use at 24px, 32px, or 48px + +**Morse Dot**: `morse-dot.svg` +- Represents short Morse signals +- Consistent with audio/visual learning +- Use at 16px, 24px + +**Morse Dash**: `morse-dash.svg` +- Represents long Morse signals +- 2:1 aspect ratio maintains proper Morse timing +- Use at 32x16px, 48x24px + +### Achievement Badges +**Novice Badge**: `badge-novice.svg` +- Bronze-colored for beginning ranks +- Adventure crest for the first steps of the quest +- 80x80px standard size + +**Expert Badge**: `badge-expert.svg` +- Gold-colored for advanced ranks +- Star shape with gems for mastery +- 80x80px standard size + +## Voice & Tone + +### Brand Personality +- **Educational**: Clearly instructional but never condescending +- **Adventurous**: Quest theme with gentle humor +- **Encouraging**: Positive reinforcement, no penalties for mistakes +- **Authentic**: Historically accurate telegraph references +- **Inclusive**: Accessible to all ages and skill levels + +### Writing Guidelines +- Use quest terminology naturally (adventurer, quest, level, achievement) +- Include "STOP" in telegraph messages for authenticity +- Keep humor gentle and family-friendly +- Write in active voice for clarity +- Avoid technical jargon without explanation + +### Example Voice +``` +✓ "Great work, adventurer! You've mastered that signal." +✓ "Telegraph line connected! Ready for your next quest." +✓ "Time to upgrade your equipment, expert operator!" + +✗ "Incorrect response detected." +✗ "User failed validation check." +✗ "Error in Morse code processing." +``` + +### Quest Messaging +- **Success**: "Adventure complete!" / "Quest cleared!" +- **Encouragement on miss**: "Try again, adventurer!" +- **Connection issue**: "Quest interrupted — reconnecting telegraph lines..." +- **Level-up**: "Continue your adventure — new quest unlocked!" + +## UI Design Principles + +### Layout +- **Adventure Theme**: UI should feel like an evolving quest log and telegraph station +- **Progressive Enhancement**: Equipment "upgrades" as the player advances +- **Clear Hierarchy**: Important elements use primary colors +- **Breathing Room**: Generous white space prevents clutter + +### Interactive Elements +- **Brass Styling**: Buttons and controls use metallic gradients +- **Quest Accents**: Adventure-blue gems mark critical actions +- **Telegraph Animations**: Key presses and signal sending +- **Scroll Effects**: Results appear as printed quest messages + +### Accessibility +- **High Contrast**: All text meets WCAG AA standards +- **Color Independence**: Never rely solely on color for meaning +- **Touch Targets**: Minimum 44px touch targets on mobile +- **Screen Readers**: Proper ARIA labels and semantic HTML + +## Animation & Motion + +### Micro-Interactions +- **Telegraph Key Press**: 200ms spring animation +- **Signal Flash**: Synchronized with audio timing +- **Quest Scroll**: 500ms slide-in effect for results +- **Points Animation**: Satisfying score increment with sound + +### Timing Standards +- **Morse Dot**: 300ms duration (visual and audio) +- **Morse Dash**: 900ms duration (3:1 ratio to dot) +- **Element Gap**: 300ms between elements +- **Character Gap**: 900ms between characters +- **Word Gap**: 2100ms between words + +## Asset Specifications + +### File Formats +- **Logos**: SVG (vector), PNG fallbacks +- **Icons**: SVG preferred, 24x24px minimum +- **Badges**: SVG, 80x80px standard +- **Backgrounds**: SVG patterns, CSS gradients + +### Naming Convention +``` +primary-logo.svg - Main brand logo +logo-horizontal.svg - Wide format logo +logo-icon.svg - Icon/favicon version +telegraph-key.svg - UI icon for telegraph key +morse-dot.svg - Morse code dot symbol +morse-dash.svg - Morse code dash symbol +badge-{rank}.svg - Achievement badges +color-{name}.svg - Color swatches +``` + +### Export Settings +- **SVG**: Optimized, remove unnecessary metadata +- **PNG**: 2x and 3x retina versions for fallbacks +- **Favicon**: 16x16, 32x32, 48x48 ICO format +- **Web**: Optimized for fast loading + +## Brand Applications + +### Website Header +- Use horizontal logo at 300px width +- Quest gold (#D4AF37) on aged parchment background +- Include tagline: "Learn Morse Code • Master Amateur Radio • Adventure Awaits" + +### Mobile App Icon +- Use icon logo version +- Ensure visibility at 16px for favicons +- Include proper iOS and Android format exports + +### Educational Materials +- Primary logo for official documents +- Consistent color usage throughout +- Professional typography for credibility + +### Social Media +- Square icon version for profile images +- Horizontal logo for cover images +- Consistent messaging and visual style + +## Brand Don'ts + +### Visual +- ❌ Don't distort logo proportions +- ❌ Don't use colors outside the defined palette +- ❌ Don't add drop shadows to logos +- ❌ Don't use the logo smaller than minimum sizes +- ❌ Don't place logos on busy backgrounds + +### Voice +- ❌ Don't use overly complex fantasy slang +- ❌ Don't make jokes about failure or mistakes +- ❌ Don't use technical jargon without explanation +- ❌ Don't break the fourth wall unnecessarily + +### Theme +- ❌ Don't lean into specific historical periods (no Wild West, no medieval-only) +- ❌ Don't use violent or aggressive imagery +- ❌ Don't stereotype or caricature cultures +- ❌ Don't sacrifice accessibility for aesthetic + +## Implementation Checklist + +### Development +- [ ] All colors defined as CSS custom properties +- [ ] Logo SVGs properly optimized and embedded +- [ ] Icon system implemented consistently +- [ ] Typography loaded with fallback fonts +- [ ] Brand voice implemented in all copy + +### Quality Assurance +- [ ] Brand consistency across all pages +- [ ] Accessibility standards met (WCAG AA) +- [ ] Mobile responsiveness maintained +- [ ] Loading performance optimized +- [ ] Cross-browser compatibility verified + +--- + +**This brand system creates a cohesive, educational, and engaging experience that honors the heritage of amateur radio while making it accessible and fun for modern adventurers.** diff --git a/docs/PRODUCT_REQUIREMENTS_DOCUMENT.md b/docs/PRODUCT_REQUIREMENTS_DOCUMENT.md new file mode 100644 index 0000000..4d46af2 --- /dev/null +++ b/docs/PRODUCT_REQUIREMENTS_DOCUMENT.md @@ -0,0 +1,594 @@ +# 📋 PRODUCT REQUIREMENTS DOCUMENT +## **MorseQuest** ⚡ +### *Complete Amateur Radio Education Platform* + +**Version:** 1.0 +**Date:** December 2024 +**Prepared for:** Keylink IT Forge Development Team +**Prepared by:** Allen McGhan, Pack 404 Cubmaster & KIT Owner + +--- + +## 🎯 **EXECUTIVE SUMMARY** + +### **Product Vision** +Create an engaging, gamified platform that teaches Morse code and amateur radio concepts through personalized mnemonic creation and progressive challenges, themed around adventure and quest progression with gentle gaming elements. + +### **Business Opportunity** +- **Primary Market:** 800,000+ licensed amateur radio operators plus aspiring hams +- **Secondary Markets:** Scout programs, STEM education, general learning enthusiasts +- **Revenue Potential:** $500K+ ARR within 3 years +- **Competitive Advantage:** Only adventure-themed amateur radio education platform with integrated Morse code training + +### **Success Criteria** +- 5,000+ registered adventurers in Year 1 +- 15% freemium conversion rate +- 85% player satisfaction score +- Integration with 10+ Scout councils and ham radio clubs + +--- + +## 👥 **TARGET MARKET ANALYSIS** + +### **Primary Users** + +**1. Aspiring Ham Radio Operators (Ages 12-70)** +- **Pain Point:** Current exam prep is dry, boring flashcard drilling +- **Motivation:** Want to earn amateur radio license but need engaging study method +- **Success Metric:** 90%+ exam pass rate after completing our curriculum + +**2. Scout Programs (Ages 8-17)** +- **Pain Point:** Traditional Morse code teaching is tedious and has high abandonment +- **Motivation:** Merit badge requirements, STEM education, group activities +- **Success Metric:** 80% completion rate vs 30% with traditional methods + +**3. Licensed Hams Maintaining Skills (Ages 25-80)** +- **Pain Point:** Morse code skills atrophy without practice +- **Motivation:** Contest preparation, skill maintenance, nostalgia +- **Success Metric:** Measurable WPM improvement within 30 days + +**4. STEM Educators (Ages 25-65)** +- **Pain Point:** Need engaging ways to teach communication technology concepts +- **Motivation:** Interactive curriculum that connects history with modern tech +- **Success Metric:** Classroom adoption and positive student engagement + +### **Market Size** +- **Total Addressable Market:** $50M+ educational gaming market +- **Serviceable Market:** 2M+ potential amateur radio learners globally +- **Initial Target:** 10,000 adventurers in first 18 months + +--- + +## 🎮 **CORE FEATURES & REQUIREMENTS** + +### **1. Mnemonic Creation System** (CRITICAL) + +**Pedagogical Foundation:** +Players must create personal memory phrases where short words represent dots (•) and long words represent dashes (−). This builds dual neural pathways for superior retention. + +**Implementation Requirements:** +``` +User Story: As a new adventurer, I need to create memorable phrases for each +Morse letter so I can quickly recognize patterns during my quest. + +Acceptance Criteria: +✓ Guided tutorial explains dot=short word, dash=long word concept +✓ Input validation ensures phrases follow proper pattern structure +✓ 50 points awarded per mnemonic phrase created (600 total possible) +✓ Printable reference sheet generated with player's custom phrases +✓ Skip option available but caps progression at Operator level +✓ Examples provided but never forced on players +``` + +**Technical Specifications:** +- Real-time pattern validation as player types +- Character count analysis (1-2 syllables = dot, 3+ = dash) +- Local storage backup of player mnemonics +- Export to printable PDF format +- Import/export for device switching + +### **2. Progressive Difficulty Curriculum** + +**Morse Code Mastery Track (Always Free):** +``` +Level 1 - Novice (0-1,000 pts): Letters A,E,T,I,N,S,H,R,D,L,U,O +Level 2 - Operator (1K-5K pts): 3-letter words (CAT, DOG, SUN, etc.) +Level 3 - General (5K-15K pts): Quest messages with STOP +Level 4 - Extra (15K-50K pts): Multi-sentence adventure scenarios +Level 5 - Expert (50K-150K pts): High-speed challenges (20+ WPM) +Level 6 - Legend (150K+ pts): Historical recreations, extreme challenges +``` + +**Ham Radio License Track (Freemium):** +``` +FREE PREVIEW: +- Technician Module 1: Basic Electronics Foundations +- Technician Module 2: Frequency Frontier Basics +- Technician Module 3: Safety Essentials Intro + +PREMIUM UNLOCK: +- Complete Technician License (10 modules, ~350 questions) +- General License Track (8 modules, ~450 questions) +- Extra License Track (6 modules, ~600 questions) +``` + +**Adaptive Progression Logic:** +- 10 consecutive correct answers triggers level-up offer +- Player choice to advance or continue current level +- Smart difficulty adjustment based on accuracy trends +- No penalties for wrong answers, only positive reinforcement + +### **3. Unified Scoring & Gamification** + +**Points System:** +```javascript +const calculatePoints = (level, streak, dailyBonus) => { + const basePoints = level * 10; // Novice=10, Legend=60 + const streakMultiplier = streak >= 10 ? 2 : 1; + const dailyMultiplier = dailyBonus ? 1.25 : 1; + + return Math.floor(basePoints * streakMultiplier * dailyMultiplier); +}; +``` + +**Achievement System:** +- **Progress Badges:** "First 1000 Points", "Operator Rank Achieved" +- **Streak Badges:** "7 Day Practice", "Perfect Month" +- **Skill Badges:** "Speed Demon (25 WPM)", "Perfect Accuracy" +- **Social Badges:** "Helped New Adventurer", "Top 10 Leaderboard" + +**Ranking Progression:** +1. **Novice** → Basic letters and numbers +2. **Operator** → Simple words and phrases +3. **General** → Complex messages and HF theory +4. **Extra** → Advanced technical concepts +5. **Expert** → High-speed operation and edge cases +6. **Legend** → Teaching and mentoring capabilities + +### **4. Synchronized Audio-Visual Learning** + +**Multi-Modal Signal Presentation:** +``` +Default Mode: Synchronized audio + visual flash +Audio Only: For quiet environments, commuting, accessibility +Visual Only: For loud environments, hearing accessibility +Custom Speed: Adjustable from 5 WPM to 40+ WPM +``` + +**Technical Requirements:** +- Web Audio API implementation for precise timing +- Visual flash synchronization within 10ms of audio +- Dot: 300ms duration, Dash: 900ms duration +- Proper inter-element and inter-character spacing per ITU standards +- Volume control and accessibility features + +### **5. Adventure / Quest Theme** + +**Visual Design Requirements:** +- Quest environment that upgrades with rank progression +- Adventure-appropriate color palette: quest gold, adventure blue, brass +- Typography: Adventure-ready serif aesthetic +- Animations: Telegraph key operation, quest completion effects +- Equipment upgrades: Apprentice key → Brass telegraph → Legendary station + +**Message Content Guidelines:** +- Adventure-themed scenarios with gentle, family-friendly humor +- Historical accuracy in telegraph format ("STOP" instead of periods) +- Progressive narrative while maintaining educational value +- Cultural sensitivity and global appeal consideration + +**Humor Examples:** +``` +Beginner: "CAT stuck in tree STOP Send rescue party STOP" +Intermediate: "URGENT rabbit invasion at outpost STOP Mayor negotiating with carrot demands STOP" +Advanced: "CONFIDENTIAL time traveler asking for WiFi password STOP Told him quest123 STOP He tipped in Bitcoin STOP What is Bitcoin STOP" +``` + +--- + +## 💰 **BUSINESS MODEL & MONETIZATION** + +### **Freemium Structure** + +**Always Free Tier:** +- Complete Morse code curriculum (6 levels) +- First 3 Technician license modules +- Basic progress tracking +- Community features and leaderboards + +**Premium Unlock Trigger:** +- After completing Technician Module 3 preview +- OR after 50 total gameplay sessions +- OR after 30 days of use (whichever comes first) + +**Premium Features ($9.95/year Individual, $19.95/year Family):** +- Complete amateur radio license preparation (Technician, General, Extra) +- 1,400+ official exam questions with detailed explanations +- Advanced practice tools and weak area identification +- Exam simulation with timing and scoring +- Unlimited Morse speed building beyond 20 WPM +- Progress analytics and performance tracking +- Printable certificates and reference materials + +### **Launch Strategy: First Year Free** + +**Early Adopter Program:** +- All players get complete platform access during launch year +- Builds user base, testimonials, and product feedback +- Admin toggle to activate billing when ready +- Grandfather early adopters with extended free access + +**Revenue Projections:** +``` +Year 1 (Launch): $0 revenue, 2,000+ adventurers, product refinement +Year 2: $18,000 ARR (15% conversion of 600 premium-ready players) +Year 3: $75,000 ARR (1,200 premium players from 8,000 total adventurers) +Year 4: $200,000+ ARR (market expansion and feature additions) +``` + +### **Payment Processing: Authorize.net Integration** + +**Subscription Management Requirements:** +```javascript +// Required Authorize.net integration points +- Recurring subscription creation and management +- Secure payment tokenization +- Failed payment handling and retry logic +- Proration for plan changes +- Cancellation and refund processing +- PCI compliance and security standards +``` + +**Admin Controls:** +- Global billing enable/disable toggle +- Individual user subscription overrides +- Revenue reporting and analytics +- Failed payment management dashboard +- Grandfathered user tracking + +--- + +## 🛠️ **TECHNICAL REQUIREMENTS** + +### **Platform Architecture** + +**Frontend Requirements:** +- **Technology:** React 18+ with TypeScript +- **Responsive Design:** Mobile-first, works on phones through desktops +- **PWA Features:** Offline capability for practice mode +- **Performance:** <3 second load time, 60fps animations +- **Accessibility:** WCAG 2.1 AA compliance, screen reader support + +**Backend Requirements:** +- **Technology:** Node.js with Express framework +- **Database:** SQLite for development, PostgreSQL for production scaling +- **Authentication:** Session-based, no account creation required initially +- **API Design:** RESTful endpoints with proper error handling +- **Security:** Helmet.js, CORS, rate limiting, input validation + +**Database Schema:** +```sql +-- Core user tracking +users (session_id, username, created_at, grandfathered_status) +user_progress (session_id, level, score, streak, accuracy_stats) +user_mnemonics (session_id, letter, mnemonic_phrase) + +-- Subscription management +subscriptions (user_id, authnet_subscription_id, plan_type, status, dates) +payments (subscription_id, authnet_transaction_id, amount, status) + +-- Admin configuration +admin_settings (setting_key, setting_value, updated_at) +``` + +### **Audio System Specifications** + +**Web Audio API Implementation:** +- Precise timing control (±5ms accuracy required) +- Standard amateur radio timing: 20 WPM = 60ms dot duration +- Clean sine wave tones at 800Hz ±50Hz +- Volume control and mute functionality +- Browser compatibility fallbacks + +### **Data Privacy & Security** + +**Privacy Requirements:** +- Minimal data collection (session ID, progress only) +- No personal information required for free tier +- GDPR compliance for EU users +- Easy data export and deletion +- Transparent privacy policy + +**Security Measures:** +- HTTPS enforcement in production +- Input sanitization and validation +- Rate limiting on API endpoints +- Secure payment processing through Authorize.net +- Regular security updates and monitoring + +--- + +## 🎨 **UI/UX REQUIREMENTS** + +### **Design System** + +**Color Palette:** +- Primary: Quest gold (#D4AF37), adventure blue (#4169E1) +- Secondary: Brass (#CD7F32), midnight (#191970) +- Accent: Quest red (#CC0000) for alerts and CTAs +- Backgrounds: Aged parchment (#F5E6D3), deep forest (#3C2415) + +**Typography:** +- Headers: Adventure-ready serif font (Google Fonts: "Cinzel" or "MedievalSharp") +- Body: Clean, readable sans-serif (Google Fonts: "Open Sans") +- Monospace: Telegraph code display (Google Fonts: "Source Code Pro") + +**Iconography:** +- Telegraph keys, quest gems, achievement badges, adventure symbols +- Consistent style across all interactive elements +- Accessibility considerations for color-blind users + +### **User Interface Components** + +**Game Interface:** +``` +┌─────────────────────────────────────┐ +│ ⚡ MorseQuest │ +├─────────────────────────────────────┤ +│ Score: 2,847 Rank: Operator ⭐ │ +│ Streak: 12 🔥 Daily: +25% │ +├─────────────────────────────────────┤ +│ │ +│ [Telegraph Flash Area] │ +│ │ +│ Pattern: • − • • │ +│ Your phrase: "Go WALKING go go" │ +│ │ +│ [▶️ Play Signal] [🔊/💡 Toggle] │ +│ │ +│ Answer: [________________] [Submit] │ +└─────────────────────────────────────┘ +``` + +**Mobile Responsiveness:** +- Touch-optimized button sizes (minimum 44px) +- Swipe gestures for navigation +- Portrait and landscape support +- Adaptive font sizing + +### **Animation & Feedback** + +**Micro-Interactions:** +- Telegraph key animation during signal playback +- Quest scroll effect for message display +- Satisfying "ding" and points animation for correct answers +- Gentle shake animation for incorrect attempts +- Rank-up celebration with confetti and sound effects + +**Loading States:** +- "Connecting telegraph lines..." with quest-themed loading animation +- Progress indicators for long-running operations +- Skeleton screens for content loading + +--- + +## 📊 **SUCCESS METRICS & KPIs** + +### **User Engagement Metrics** + +**Acquisition:** +- **Target:** 1,000 adventurers in first 6 months +- **Source Tracking:** Organic, referral, Scout programs, ham radio forums +- **Conversion Rate:** Landing page to first session >25% + +**Activation:** +- **Mnemonic Creation Rate:** >85% complete at least 8 phrases +- **First Session Completion:** >70% complete first level +- **Return Rate:** >60% return within 7 days + +**Retention:** +- **Daily Active Users:** 20% of registered adventurers +- **Weekly Active Users:** 60% of registered adventurers +- **Monthly Active Users:** 80% of registered adventurers +- **Churn Rate:** <10% monthly for active players + +### **Learning Effectiveness** + +**Skill Development:** +- **Morse Proficiency:** 85% accuracy on common letters after 3 sessions +- **Speed Development:** Average 15 WPM at Expert level +- **Knowledge Retention:** 70% accuracy after 1 week without practice +- **License Exam Success:** 90%+ pass rate for premium players + +### **Business Metrics** + +**Revenue:** +- **Freemium Conversion:** 15% of eligible players convert to premium +- **Average Revenue Per User:** $12+ annually +- **Customer Lifetime Value:** $25+ (2+ year retention) +- **Churn Rate:** <20% annually for premium subscribers + +**Market Penetration:** +- **Scout Program Adoption:** 10+ packs using regularly +- **Ham Radio Club Partnerships:** 5+ official endorsements +- **Educational Institution Adoption:** 3+ schools/colleges + +--- + +## 🗺️ **DEVELOPMENT ROADMAP** + +### **Phase 1: MVP (10-12 weeks)** + +**Sprint 1-2: Core Foundation** +- Basic React application structure +- SQLite database setup and user session management +- Simple quest UI with adventure theme implementation +- Basic Morse code audio/visual playback system + +**Sprint 3-4: Mnemonic System** +- Mnemonic creation interface with validation +- Pattern matching logic for dot/dash word structure +- Points system and basic progression tracking +- Printable reference sheet generation + +**Sprint 5-6: Game Mechanics** +- Complete Morse curriculum (6 levels) +- Scoring system with streaks and bonuses +- Achievement/badge system implementation +- Local storage and data persistence + +**Sprint 7: Polish & Testing** +- Mobile responsiveness and cross-browser testing +- Performance optimization and loading improvements +- User testing and feedback integration +- Basic admin panel for monitoring + +### **Phase 2: Premium Features (8-10 weeks)** + +**Sprint 8-9: Ham Radio Content** +- Technician license module creation (10 modules) +- Question bank integration with explanations +- Exam simulation engine +- Progress tracking across multiple curriculum tracks + +**Sprint 10-11: Payment Integration** +- Authorize.net subscription setup +- Billing flow implementation +- Admin controls for billing management +- Free trial and conversion funnel + +**Sprint 12: Advanced Features** +- General and Extra license content +- Advanced analytics and reporting +- Social features (leaderboards, sharing) +- Performance optimization for scale + +### **Phase 3: Platform Enhancement (6-8 weeks)** + +**Sprint 13-14: Community Features** +- User profiles and achievement display +- Scout group and club integration tools +- Mentoring/teaching mode for experienced players +- User-generated content capabilities + +**Sprint 15-16: Advanced Analytics** +- Detailed learning analytics dashboard +- A/B testing framework for conversion optimization +- Instructor/leader reporting tools +- Advanced admin management features + +## ⚠️ **RISK ASSESSMENT & MITIGATION** + +### **Technical Risks** + +**Audio Timing Precision (HIGH)** +- **Risk:** Browser inconsistencies in Web Audio API timing +- **Mitigation:** Extensive cross-browser testing, visual-only fallback mode +- **Contingency:** Server-side audio generation if client-side fails + +**Mobile Performance (MEDIUM)** +- **Risk:** Complex animations causing poor performance on older devices +- **Mitigation:** Progressive enhancement, simplified mobile animations +- **Contingency:** Device detection with performance-appropriate features + +**Payment Processing (MEDIUM)** +- **Risk:** Authorize.net integration complexity and failure handling +- **Mitigation:** Thorough testing in sandbox, comprehensive error handling +- **Contingency:** Alternative payment processor (Stripe) integration ready + +### **Market Risks** + +**Educational Market Adoption (MEDIUM)** +- **Risk:** Schools/Scout programs slow to adopt new technology +- **Mitigation:** Free tier, pilot programs, educator testimonials +- **Contingency:** Focus on individual consumer market initially + +**Competition Response (LOW)** +- **Risk:** Established players copying our approach +- **Mitigation:** First-mover advantage, unique theme, patent considerations +- **Contingency:** Continuous innovation and feature development + +### **User Experience Risks** + +**Mnemonic Creation Abandonment (HIGH)** +- **Risk:** Players quit during mnemonic creation phase +- **Mitigation:** Compelling tutorial, skip option, immediate value demonstration +- **Contingency:** A/B testing on different onboarding approaches + +**Theme Appeal (LOW)** +- **Risk:** Adventure theme doesn't resonate globally +- **Mitigation:** Universal quest motifs, gentle humor, cultural sensitivity +- **Contingency:** Theme customization options in future versions + +--- + +## 🎯 **FORGE DEPLOYMENT SPECIFICATIONS** + +### **Keylink IT Forge Integration** + +**Deployment Requirements:** +- **Platform:** Docker containerization for easy deployment +- **Environment:** Support for development, staging, production environments +- **Scaling:** Horizontal scaling capability for user growth +- **Monitoring:** Health checks, error reporting, performance metrics + +**White-Label Capabilities:** +- **Custom Branding:** Configurable logos, colors, domain names +- **Content Customization:** Custom quest packs for specific organizations +- **Analytics:** Client-specific dashboards and reporting +- **Integration:** API endpoints for external learning management systems + +**Revenue Sharing Model:** +- **Platform Fee:** 20% of subscription revenue to Forge platform +- **White-Label Fee:** $500 setup + $100/month for custom deployments +- **Support Tier:** Premium support for enterprise clients + +### **Technical Deliverables** + +**Code Repository:** +- **Gitea Integration:** Source code management with CI/CD pipeline +- **Documentation:** Comprehensive README, API documentation, deployment guides +- **Testing:** Unit tests, integration tests, end-to-end test suites +- **Security:** Code scanning, dependency updates, security best practices + +**Production Deployment:** +- **Infrastructure:** AWS/DigitalOcean compatible Docker containers +- **Database:** PostgreSQL for production, migration scripts included +- **CDN:** Static asset optimization and global distribution +- **SSL:** HTTPS enforcement and certificate management + +**Monitoring & Analytics:** +- **Application Monitoring:** Error tracking, performance monitoring +- **Business Analytics:** User behavior tracking, conversion funnel analysis +- **Revenue Reporting:** Subscription metrics, churn analysis, growth tracking + +--- + +## 📞 **PROJECT CONTACTS & STAKEHOLDERS** + +### **Product Owner** +**Allen McGhan** +- Owner/Operator, Keylink IT +- Cubmaster, Pack 404 Scouts +- Hendersonville, TN +- Subject Matter Expert: Amateur Radio (General License), Scout Education + +### **Target Stakeholders** +- **Pack 404 Scout Leadership:** Initial pilot deployment and feedback +- **Amateur Radio Community:** Beta testing and content validation +- **Educational Partners:** Scout councils, STEM educators, ham radio clubs + +### **Success Criteria** +- **User Satisfaction:** >4.5/5.0 app store rating +- **Educational Effectiveness:** Measurable improvement in Morse code proficiency +- **Business Viability:** Sustainable revenue covering development and hosting costs +- **Market Impact:** Recognition as leading amateur radio education platform + +--- + +**This PRD provides complete specifications for building an engaging, educational, and commercially viable amateur radio education platform that fills a significant gap in the market while providing substantial value to learners of all ages.** + +--- +*Document Version: 1.0* +*Last Updated: December 2024* +*Prepared for: Keylink IT Forge Development Team*