morsequest/docs/PRODUCT_REQUIREMENTS_DOCUMENT.md

📋 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:

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:

// 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:

-- 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