Development Guide - NateEaton/mind-pwa GitHub Wiki

Contributing to the MIND Diet Tracker

This guide provides information for developers who want to contribute to or modify the MIND Diet Tracker PWA.

Development Environment Setup

Prerequisites

  • Git for version control
  • Node.js (version 18 or higher) for both client and server development
  • Modern web browser with developer tools (Chrome, Firefox, Safari, Edge)
  • Text editor or IDE (VS Code recommended)
  • Docker and Docker Compose (optional, for container-based development)

Initial Setup

  1. Clone the repository

    git clone https://github.com/NateEaton/mind-pwa.git
cd mind-pwa

  2. Set up Git hooks (recommended)

    cp scripts/pre-commit.example .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

    The pre-commit hook automatically updates version.json with commit information.

  3. Install dependencies

    # Install root dependencies
npm install

# Install server dependencies (if working on cloud sync features)
cd server
npm install
cd ..

  4. Generate version file

    npm run generate-version

Development Modes

Choose the appropriate development mode based on what you're working on:

Client-Only Development (Recommended for most changes)

Best for UI work, tracking logic, themes, and import/export features:

# Configure environment
echo "VITE_SERVER_FEATURES_ENABLED=false" > .env
echo "VITE_DEV_MODE=true" >> .env

# Start development server
cd client
npm run dev

Access at: http://localhost:5173

Full-Stack Development (For cloud sync features)

Required when working on cloud synchronization, OAuth flows, or server components:

# Configure environment
echo "VITE_SERVER_FEATURES_ENABLED=true" > .env
echo "VITE_DEV_MODE=true" >> .env
echo "APP_BASE_URL=http://localhost:8080" >> .env

# Start OAuth server (Terminal 1)
cd server
npm run dev

# Start client development server (Terminal 2)  
cd client
npm run dev

Access at: http://localhost:8080

For environment variable details and OAuth provider setup, see the Installation Guide.

Project Structure

For detailed information about the codebase architecture and module organization, see the Technical Documentation.

Key Development Areas

Client Core (client/src/core/):

  • stateManager.js - Application state and data flow
  • dataService.js - Local storage and data persistence
  • trackingEngine.js - Date handling and tracking logic
  • setupWizard.js - First-time user experience

User Interface (client/src/ui/):

  • renderer.js - UI rendering and state updates
  • components.js - Reusable UI components
  • templates.js - HTML template system

Cloud Sync (client/src/cloudSync/):

  • cloudSync.js - Main synchronization coordinator
  • mergeStrategies.js - Conflict resolution logic
  • Cloud provider implementations in cloudProviders/

Server (server/):

Development Workflow

Feature Development

  1. Create a feature branch

    git checkout -b feature/description-of-change

  2. Make focused commits

    • Keep commits small and focused on a single change
    • Write descriptive commit messages
    • The pre-commit hook will automatically update version information

  3. Test thoroughly

    • Test across multiple browsers (Chrome, Firefox, Safari, Edge)
    • Test PWA installation behavior
    • Test offline functionality
    • For cloud sync changes, test OAuth flows with both providers
    • Test both deployment modes if your changes affect feature gating

  4. Create a pull request

    • Include a clear description of changes
    • Document any new dependencies or breaking changes
    • Note which deployment modes you've tested

Code Standards

JavaScript Style:

  • Use ES6+ features while maintaining browser compatibility
  • Follow existing naming conventions and module patterns
  • Add JSDoc comments for functions and classes
  • Use feature gating (if (__SERVER_FEATURES_ENABLED__)) for cloud sync code

Module Organization:

  • Follow the established module structure
  • Keep modules focused on single responsibilities
  • Use explicit imports and exports
  • Maintain clear dependencies between modules

Error Handling:

  • Add appropriate logging using the logger system
  • Handle both online and offline scenarios
  • Provide graceful fallbacks for optional features

Testing Strategy

Client-Side Testing:

  • Test core functionality without internet connection
  • Verify state persistence across browser sessions
  • Test date transitions using developer tools
  • Validate PWA installation and offline behavior

Cloud Sync Testing:

  • Test authentication flows with both providers
  • Verify conflict resolution with multiple devices
  • Test network constraint scenarios (Wi-Fi only mode)
  • Validate sync behavior with various data states

Cross-Browser Testing:

  • Chrome/Chromium (primary development target)
  • Firefox (secondary target)
  • Safari (iOS/macOS compatibility)
  • Edge (Windows compatibility)

Developer Tools and Debugging

Built-in Developer Tools

The application includes debugging tools accessible through the About dialog when developer mode is enabled.

Enabling Developer Mode

  1. Set VITE_DEV_MODE=true in your .env file, or
  2. In the browser console: localStorage.setItem('devMode', 'true')
  3. Refresh the application
  4. Open the About dialog to access developer controls

Test Date Override

Simulate date transitions for testing:

  1. Open About dialog → Developer Controls
  2. Set a custom test date
  3. App will use the test date instead of system date
  4. Reset by clearing the override

Use cases:

  • Testing day/week boundary transitions
  • Validating reset and archival logic
  • Testing historical data scenarios

Cloud Sync Debugging

For cloud sync development:

  • Use multiple browser profiles or incognito windows to simulate multiple devices
  • Monitor network requests in browser developer tools
  • Check server logs for OAuth and token refresh issues
  • Use the sync status indicators in Settings dialog

Browser Developer Tools

Console Debugging:

  • The logger system provides module-based debug output
  • Use stateManager.getState() to inspect current application state
  • Check for errors in the console during state transitions

Storage Inspection:

  • localStorage: Current state, preferences, and settings
  • IndexedDB: Historical weekly data and large datasets
  • Clear storage to test fresh installation scenarios

Network Monitoring:

  • Monitor OAuth flows and token refresh requests
  • Check for proper CORS handling
  • Validate API request/response formats

Server Development

Development Commands

# Start server with auto-restart
cd server
npm run dev

# Start server without auto-restart
npm start

# Check server logs (if using Docker)
docker-compose logs server

OAuth Testing

Testing Authentication Flows:

  1. Configure OAuth redirect URIs in cloud provider consoles for development URLs
  2. Test complete auth flow through setup wizard or settings
  3. Verify token refresh operations work correctly
  4. Monitor server logs for authentication issues

For OAuth architecture details, see Technical Documentation.

Common Development Tasks

Adding New Food Groups

Food groups are defined in client/src/app.js. For the complete data structure and requirements, see Technical Documentation.

Steps:

  1. Add the new food group to the foodGroups array
  2. Update UI templates if needed for layout
  3. Test with existing user data to ensure compatibility
  4. Update color coding logic if required

Modifying Tracking Logic

The core tracking logic is in trackingEngine.js and stateManager.js. For architecture details, see Technical Documentation.

Development Considerations:

  • Modify checkDateAndReset() for new transition behaviors
  • Update week calculation logic if changing week definitions
  • Test edge cases like timezone changes and system clock adjustments
  • Add new action types to ACTION_TYPES if needed
  • Update state schema version if changing data structure

Extending Cloud Sync

For cloud sync architecture details, see Technical Documentation.

Adding New Providers:

  1. Create provider class in client/src/cloudProviders/
  2. Implement the required interface methods
  3. Add OAuth endpoints to server/server.js
  4. Update setup wizard and settings UI
  5. Test complete authentication and sync flows

Modifying Sync Logic:

  • Update merge strategies in mergeStrategies.js
  • Modify conflict resolution rules
  • Add new sync metadata fields if needed
  • Test across multiple devices and network conditions

UI and Theme Development

Component Development:

  • Follow existing component patterns in components.js
  • Use the template system in templates.js
  • Test responsive behavior across device sizes

Theme System:

  • Theme logic is in themeManager.js
  • CSS variables are defined in style.css
  • Test light, dark, and auto theme modes

Debugging Common Issues

Client-Side Issues

State Management Problems:

  • Check state structure matches expected schema
  • Verify action dispatching and reducer logic
  • Use stateManager.getState() to inspect current state

Date Transition Issues:

  • Use test date override to simulate specific scenarios
  • Check trackingEngine.js logic for edge cases
  • Verify timezone handling and date string formatting

Storage Issues:

  • Clear browser storage to test fresh installations
  • Check for storage quota limitations
  • Verify localStorage and IndexedDB operations

Server-Side Issues

OAuth Flow Problems:

  • Verify redirect URIs match cloud provider configuration
  • Check environment variables are correctly set
  • Monitor server logs for authentication errors
  • Test with different browsers and incognito mode

Token Management Issues:

  • Check token refresh logic in server code
  • Verify client secret configuration
  • Monitor network requests for token operations

CORS Configuration:

  • Ensure proper origin configuration in server
  • Check for preflight request handling
  • Verify CORS headers in responses

Environment Issues

Build Problems:

  • Check environment variable configuration
  • Verify feature gating is working correctly
  • Ensure all dependencies are installed

Development Server Issues:

  • Check port conflicts (client: 5173, server: 3000)
  • Verify proxy configuration for full-stack mode
  • Clear browser cache and restart servers

Building and Testing

Development Builds

For development purposes, you can build manually to test specific configurations:

# Development build - client-only
cd client
VITE_SERVER_FEATURES_ENABLED=false npm run build

# Development build - server-enabled  
cd client
VITE_SERVER_FEATURES_ENABLED=true npm run build

Note: For production deployment, use the deployment scripts documented in the Installation Guide rather than manual builds.

Testing Deployments

Before submitting changes that affect deployment:

  1. Test both deployment modes

    • Build and test client-only deployment
    • Build and test server-enabled deployment

  2. Verify feature gating

    • Ensure cloud sync code is excluded from client-only builds
    • Test that features are properly disabled/hidden

  3. Test PWA functionality

    • Verify installation works correctly
    • Test offline behavior
    • Check service worker caching

For complete deployment instructions, see the Installation Guide.

Contributing Guidelines

Code Review Process

  • All changes should go through pull request review
  • Include testing notes and affected deployment modes
  • Document any new dependencies or configuration requirements
  • Update relevant documentation for user-facing changes

Documentation Updates

When making changes that affect:

Version Management

  • The pre-commit hook automatically updates version.json
  • Version information is displayed in the About dialog
  • Build timestamp and commit hash are included for debugging

Issue Reporting

When reporting issues:

  • Include browser and device information
  • Note which deployment mode you're using
  • Provide steps to reproduce the issue
  • Include relevant console errors or logs