Exercise Library Architecture Implementation

[brylie]

Overview

Our current dropdown-based exercise selection system is approaching its limits as we add more exercise types and variations. We need to transition to a library-based architecture that can handle our growing exercise collection while providing a better user experience and supporting future extensibility.

Current Limitations

The existing system faces several challenges:

Our current three-dropdown approach (Hands, Exercise, Practice Key) creates a combinatorial complexity problem. As we add new dimensions like octave ranges or modalities, the number of possible combinations grows exponentially. Not all combinations make sense for every exercise type, leading to potential user confusion and interface complexity.

Furthermore, different exercise types have different configuration needs. Some exercises benefit from multiple octaves or modalities, while others don't. This creates a challenging user interface problem where we either need complex show/hide logic for selection boxes or risk presenting irrelevant options to users.

Proposed Solution

We should implement an Exercise Library architecture that treats each exercise as a self-contained entity with its own metadata and configuration options. This approach will provide a more scalable and maintainable system while improving the user experience.

Core Components

1. Exercise Metadata System

Each exercise will be defined with standardized metadata:

class_name ExerciseMetadata
extends Resource

enum Category {
    SCALES,
    CHORDS,
    ARPEGGIOS,
    PROGRESSIONS,
    TECHNICAL
}

# Required metadata
var title: String
var description: String
var category: Category

# Optional metadata (for future expansion)
var creator_name: String
var prerequisite_exercises: Array[String]
var enabled_analytics: Array[String]
var difficulty_level: int

2. Exercise Library Interface

A dedicated library screen that:

• Displays exercises in a clear, categorized layout
• Provides filtering and search capabilities
• Shows exercise details and requirements
• Supports future expandability for downloadable content

3. Exercise Discovery System

An automated system for:

• Discovering available exercises
• Parsing exercise metadata
• Organizing exercises into categories
• Managing exercise dependencies

Implementation Benefits

This architectural change provides several immediate and long-term benefits:

Immediate Benefits

1. Clearer User Experience: Students can browse and select exercises in a more intuitive way, with all relevant information readily available.

2. Simplified Exercise Definition: Each exercise can specify exactly what configuration options it supports, eliminating the need for complex UI logic.

3. Better Organization: Exercises can be properly categorized and grouped, making it easier for students to find appropriate practice material.

Future Possibilities

1. Progress-Based Exercise Unlocking

   • Track proficiency in prerequisite exercises
   • Gradually reveal more advanced content
   • Provide clear learning pathways

2. Downloadable Content Support

   • Package new exercise collections
   • Distribute specialized practice routines
   • Support marketplace for additional content

3. Custom Exercise Bundles

   • Teacher-created exercise collections
   • Specialized practice routines
   • Student-customized practice sets

Technical Implementation

Exercise Definition Interface

class_name Exercise
extends Node

# Required interface methods
func get_metadata() -> ExerciseMetadata:
    return metadata

func get_configuration_options() -> Dictionary:
    return {
        "supported_hands": ["left", "right", "both"],
        "key_signatures": ["C", "G", "D", ...],
        "octave_ranges": [1, 2, 3]  # if applicable
    }

func initialize_exercise(config: Dictionary) -> void:
    # Set up exercise with given configuration
    pass

Library Management

The system needs to:

1. Automatically discover exercise files in designated directories
2. Parse metadata and validate exercise implementations
3. Organize exercises based on categories and dependencies
4. Handle exercise availability and unlocking logic

Analytics Integration

The library system should:

1. Track which analytics are relevant for each exercise type
2. Enable/disable appropriate tracking based on exercise metadata
3. Store progress data in a format that supports exercise prerequisites

Development Phases

Phase 1: Core Architecture

1. Define metadata and exercise interfaces
2. Implement basic library screen
3. Convert existing exercises to new format
4. Add basic filtering and categorization

Phase 2: Enhanced Features

1. Add search functionality
2. Implement exercise prerequisites
3. Add detailed exercise information views
4. Enhance filtering and sorting options

Phase 3: Future Features

1. Add downloadable content support
2. Implement progress-based unlocking
3. Add exercise routine support
4. Create marketplace infrastructure

Success Criteria

• Improved user experience in exercise selection
• Successful migration of existing exercises
• Maintainable system for adding new exercises
• Foundation for future expandability

Related Concepts

Exercise Routines

While not part of this epic, the library architecture should consider future support for exercise routines:

• Sequences of exercises with specific durations
• Customizable practice patterns
• Shareable routine definitions
• Progress tracking across routine components

This functionality would be implemented in a separate epic but should influence our architectural decisions.

Next Steps

This epic will be broken down into focused sub-tasks:

1. Metadata system implementation
2. Library interface design
3. Exercise discovery system
4. Analytics integration
5. Exercise conversion