Water Tracker PWA - AI Assistant Guide Skill

This skill converts the comprehensive CLAUDE.md file from the Water Tracker PWA v2.0 project into a structured knowledge base for AI assistants working on PWA development.

What This Skill Does

This skill provides complete project context for the Water Tracker PWA, a Progressive Web App built with vanilla JavaScript that demonstrates:

Project Overview

Technology Stack

Key Features

Instructions for AI Assistants

When working with this codebase, follow these guidelines:

1. Understanding the Architecture

**Single Class Design**: The entire app is encapsulated in the `WaterTracker` class (app.js). All state management, data persistence, and UI updates flow through this single instance.

**Key architectural patterns**:

**Critical files**:

2. Code Conventions to Follow

**JavaScript**:

**CSS**:

**HTML**:

3. Making Changes

**When adding features**:

1. Update `CONSTANTS` if adding configurable values

2. Add UI elements to `index.html` with ARIA labels

3. Add styles to `styles.css` using CSS variables

4. Add event listeners in `setupEventListeners()`

5. Create handler method with JSDoc

6. Update `saveData()`/`loadData()` for persistence

7. Add error handling with try-catch

8. Test manually and check console

**When modifying Service Worker**:

1. Update `CACHE_NAME` version in `sw.js` (line 1)

2. Update cache busting params in `index.html`

3. Unregister old SW in DevTools

4. Hard refresh browser

**When updating styles**:

4. State Management

**All state lives in WaterTracker instance**:

```javascript

{

currentGlasses: 0,

dailyGoal: 8,

maxGoal: 10,

historicalData: {},

currentPeriod: 'week',

currentOffset: 0

}

```

**Storage keys**:

**Data flow**:

User Action → Event Listener → Action Method → Update State → Save to localStorage → Update Display → Render to DOM

5. Error Handling

**Always provide user-friendly messages**:

6. Performance Optimizations

7. Accessibility Requirements

8. Security Best Practices

Common Tasks

Adding a New Feature

1. Identify where it fits in the class structure

2. Add constants if needed

3. Add UI with accessibility

4. Wire up event listeners

5. Implement logic with error handling

6. Update persistence layer

7. Test offline functionality

Debugging Service Worker

1. Check DevTools → Application → Service Workers

2. Verify cache version matches code

3. Unregister and hard refresh if needed

4. Check Network tab for cache hits/misses

Updating Historical Data Structure

1. Modify schema in `loadData()` and `saveData()`

2. Add migration logic for existing data

3. Update rendering in `updateHistory()`

4. Test with existing localStorage data

Key Code Locations

**Constants**: `app.js:8-18`

**Event Listeners**: `app.js:88-188`

**Data Loading**: `app.js:351-387`

**Data Saving**: `app.js:389-405`

**Display Updates**: `app.js:243-287`

**History Rendering**: `app.js:429-483`

**Settings Modal**: `app.js:678-822`

**Service Worker Registration**: `index.html:169-298`

**CSS Variables**: `styles.css:1-44`

**Caching Strategy**: `sw.js:28-81`

Testing Checklist

When making changes, verify:

Best Practices Summary

1. **No frameworks**: Pure vanilla JavaScript

2. **Offline-first**: Service worker caching for all resources

3. **Accessibility-first**: ARIA labels and keyboard support

4. **Security-hardened**: CSP and safe data handling

5. **Performance-optimized**: Change detection and CSS animations

6. **Error-resilient**: Try-catch and user-friendly messages

7. **Convention-driven**: Consistent naming and organization

8. **Static-only**: No build process required

Additional Resources