SongDrive

Appearance

Edit

Development Guide ​

Development Tools ​

Testing Strategy ​

Testing Approach ​

Based on the comprehensive technical planning, testing includes:

Unit Testing ​

  • Component-level tests for UI components
  • Module-level tests for business logic
  • State management testing with Redux DevTools integration

Integration Testing ​

  • API integration tests
  • File upload/download workflows
  • DAW integration testing
  • Mobile share extension testing

End-to-End Testing ​

  • Cross-platform workflows (mobile → desktop)
  • Collaboration scenarios (multi-user)
  • Passive data entry validation

Performance Testing ​

  • Large data set handling
  • Waveform generation performance
  • Virtual scrolling efficiency
  • Search query performance

Development Workflow ​

Local Development ​

Desktop Development ​

  1. Set up local development environment
  2. Install dependencies
  3. Run desktop app in development mode
  4. Test DAW integration locally
  5. Test file system sync

Mobile Development ​

  1. Set up Expo development environment
  2. Install mobile dependencies
  3. Run on iOS simulator / Android emulator
  4. Test share extension workflow
  5. Test push notifications (requires backend)

Web Development ​

  1. Set up web development environment
  2. Install dependencies
  3. Run local development server
  4. Test in browser
  5. Integrate with local/staging backend

Build Process ​

Desktop Builds ​

  • Platform: Mac M1 (Apple Silicon) currently supported
  • Packaging: Tauri/native packaging
  • Distribution: Self-hosted DMG files
  • Code Signing: Not currently implemented (requires manual security bypass)
  • Build Command: TBD (not specified in docs)

Mobile Builds ​

iOS:

  • Platform: Expo development builds
  • Distribution: Beta testing via Expo device registration
  • OTA Updates: Supported via Expo
  • Build Command: expo build:ios (or equivalent)

Android:

  • Platform: Expo development builds
  • Distribution: Direct APK sideloading
  • Build Command: expo build:android (or equivalent)

Web Builds ​

  • Standard React build process
  • Hosted on Cloudflare Pages (based on preview URLs in docs)
  • CI/CD via GitHub Actions (implied)

Deployment ​

Distribution Channels ​

Desktop:

  • Self-hosted at https://assets.songdrive.app/builds/desktop/
  • Direct DMG downloads
  • Manual installation required
  • Security bypass command needed: xattr -cr "/Applications/SongDrive.app"

Mobile iOS:

Mobile Android:

  • Self-hosted APK at https://assets.songdrive.app/builds/mobile/
  • Direct sideloading installation
  • No Google Play Store presence yet

Web:

CI/CD Pipeline ​

Continuous Integration ​

Based on documentation references:

  • GitHub Actions for automated builds
  • Pull request previews (PR #208 mentioned with preview URL)
  • Automated testing (implied but not detailed)

Continuous Deployment ​

  • Cloudflare Pages for web deployments
  • Self-hosted asset server for desktop/mobile builds
  • Expo OTA updates for mobile

Development Environment Setup ​

Prerequisites ​

  • Node.js (version TBD)
  • npm or yarn package manager
  • Git version control
  • Platform-specific tools:
    • Desktop: Tauri dependencies (Rust, system libraries)
    • Mobile: Expo CLI, iOS/Android development tools
    • Web: Modern browser for testing

Environment Variables ​

(Not detailed in available docs - likely includes:)

  • Backend API endpoint
  • Storage credentials (BackBlaze S3)
  • Expo configuration
  • Authentication secrets

Code Quality ​

Linting and Formatting ​

(Not detailed in available docs - likely includes:)

  • ESLint for JavaScript/TypeScript
  • Prettier for code formatting
  • Pre-commit hooks

Code Review Process ​

  • Pull request workflow via GitHub
  • Jira integration for issue tracking
  • PR previews for visual review
  • Example: PR #208 for dashboard redesign

Module Development ​

Module System Framework ​

From Module System architecture docs:

Creating a New Module ​

  1. Implement module interface (e.g., ConfigurableModule)
  2. Define module routes for navigation
  3. Set up key-value store for persistence
  4. Implement module-specific UI components
  5. Register module with core framework

Module Conventions ​

  • Code Location: Module-specific code outside core folder
  • Storage: Use agnostic KV store package
  • State Management: Redux-style with DevTools integration
  • UI Generation: Auto-generated with optional custom views

Developer Experience ​

  • Easy Integration: OpenTelemetry-style instrumentation pattern
  • Package: fullcircle for framework integration
  • Debugging: Redux DevTools for state inspection
  • Testing: Module-level unit tests

Deployment Contexts ​

Local-Browser Mode ​

  • MIDI always "ready" locally in browser
  • Local storage for user preferences
  • No server required for basic functionality

Raspberry Pi Mode ​

  • Pi acts as browser client OR cloud server replacement
  • MIDI integration for JamScribe hardware
  • Local network connectivity

Cloud Workspace Mode ​

  • Data saved in cloud workspace
  • Shared access based on membership
  • BackBlaze S3 storage backend

Self-Hosted Mode ​

  • User preferences in local storage
  • Guest access configuration required
  • Hybrid local/cloud functionality

Documentation ​

User Documentation ​

Developer Documentation ​

  • Module system architecture docs
  • API documentation (TBD)
  • Integration guides (TBD)

Debugging and Monitoring ​

Development Debugging ​

  • Redux DevTools: State inspection and time-travel debugging
  • Browser DevTools: Standard web debugging
  • React Developer Tools: Component inspection
  • KV Store Visibility: Key-value operations visible in dev tools

Production Monitoring ​

(Not detailed in current docs - future considerations:)

  • Error tracking (Sentry, etc.)
  • Performance monitoring
  • User analytics
  • Backend API monitoring

Getting Started ​

Quick Start (Desktop Development) ​

  1. Clone repository
  2. Install dependencies: npm install (or yarn install)
  3. Run development server: npm run dev
  4. Access at http://localhost:PORT

Quick Start (Mobile Development) ​

  1. Clone repository
  2. Install dependencies: npm install
  3. Install Expo CLI: npm install -g expo-cli
  4. Start Expo dev server: expo start
  5. Scan QR code with Expo Go app

Quick Start (Web Development) ​

  1. Clone repository
  2. Install dependencies: npm install
  3. Run development server: npm run dev
  4. Access at http://localhost:PORT

(Note: Specific commands may vary - refer to package.json scripts)

Contributing ​

Pull Request Process ​

  1. Create feature branch from main
  2. Implement changes with tests
  3. Submit pull request
  4. Link to related Jira issue
  5. Await code review
  6. Address feedback
  7. Merge after approval

Code Style ​

  • Follow existing code patterns
  • Use consistent naming conventions
  • Write clear commit messages
  • Add comments for complex logic

Testing Requirements ​

  • Add unit tests for new features
  • Ensure existing tests pass
  • Test cross-platform functionality
  • Document manual testing steps