gdpr/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Information

- **Git Repository**: ssh://git@kode.naiv.no:2222/olemd/gdpr.git
- **Forgejo Server**: https://kode.naiv.no
- **Owner**: olemd

## Project Overview

This is a GDPR-compliant optional tracking solution that provides a privacy-first approach to website analytics. The core concept is "minimal tracking by default, enhanced tracking by consent" - users start with privacy-protected minimal tracking and can opt-in to enhanced features. **Features comprehensive i18n support for Norwegian and English.**

## Architecture

### Core Components

**GDPRTrackingConsent Class** (`index.html`)
- Main JavaScript class that manages consent state and UI interactions
- Handles localStorage persistence with key 'gdpr-tracking-consent'
- Integrates with Google Analytics consent modes (`analytics_storage`, `ad_storage`, `personalization_storage`)
- Manages cookie cleanup for tracking cookies (`_ga`, `_gid`, `_gat`, `_fbp`, `_fbc`)
- Fires custom events (`trackingModeChanged`) for external integrations

**Internationalization System**
- Complete translation system supporting Norwegian (Bokmål) and English
- Language preference persisted with key 'gdpr-language' in localStorage
- Real-time translation updates without page reload
- Language toggle button (EN/NO) in top-right corner
- All UI text, modal content, and notifications fully localized

**Two-Mode System**
- **Minimal Mode**: Essential cookies only, anonymized analytics, consent denied by default
- **Enhanced Mode**: Full tracking enabled only after explicit user consent

### Key Files

- `index.html` - Complete demo with hero section, feature explanations, live status indicator, and i18n support
- `integration-example.js` - Production-ready integration examples for React, Vue, WordPress, and vanilla JS
- `README.md` - Documentation covering API, customization, i18n, and legal compliance
- `favicon.svg`, `favicon.ico` - Privacy-themed favicon with shield and lock design

## Development Commands

### Repository Operations
```bash
# Clone the repository
git clone ssh://git@kode.naiv.no:2222/olemd/gdpr.git

# Use fj (Forgejo CLI) for repository management
fj repo view olemd/gdpr
fj issue list
fj pr list
```

### Testing the Demo
```bash
# Open the demo in your browser
open index.html
# or
python3 -m http.server 8000  # Then visit http://localhost:8000
```

### Git Workflow
```bash
# Standard git operations work with the Forgejo server
git push origin main
git pull origin main
```

### Integration Testing
The solution integrates with Google Analytics via consent modes:
```javascript
// Check current consent status
localStorage.getItem('gdpr-tracking-consent') === 'true'

// Check current language
localStorage.getItem('gdpr-language') || 'en'

// Listen for mode changes
document.addEventListener('trackingModeChanged', (e) => {
  console.log('Mode:', e.detail.mode); // 'minimal' or 'enhanced'
});

// Set language programmatically
setLanguage('no'); // Norwegian
setLanguage('en'); // English
```

## Key Implementation Details

### Consent Flow
1. Page loads with minimal tracking (GDPR compliant by default)
2. User sees "Plz trac me!" button in bottom-right
3. Clicking shows consent modal with clear explanation
4. User can enable enhanced tracking or dismiss
5. Status persisted in localStorage, toggleable anytime

### Google Analytics Integration
The solution expects Google Analytics to be initialized with consent mode:
```javascript
gtag('consent', 'default', {
  'analytics_storage': 'denied',
  'ad_storage': 'denied',
  'personalization_storage': 'denied'
});
```

The button automatically calls `gtag('consent', 'update', {...})` when user changes preferences.

### Cookie Management
- Automatically cleans up tracking cookies when switching to minimal mode
- Uses domain-aware cookie deletion for cross-subdomain cleanup
- Preserves essential functionality cookies (`functionality_storage: 'granted'`)

## Customization Points

### UI Customization
- Button styling via CSS classes `.tracking-consent-btn` and `.tracking-consent-btn.enabled`
- Modal content in `.consent-modal-content`
- Status indicator in `.tracking-status`
- Language toggle styling via `.language-toggle` and `.lang-btn`

### Behavioral Customization
- Change storage key by modifying `this.storageKey` in constructor
- Customize consent message in modal HTML
- Add additional tracking services in `enableEnhancedTracking()` method

### Internationalization Customization
- Add new languages to `translations` object with all required keys
- Modify Norwegian translations for local variants (e.g., Nynorsk)
- Add language detection based on browser locale
- Customize language button labels and positioning

### Framework Integration
The `integration-example.js` contains complete examples for:
- WordPress (functions.php and shortcode approaches)
- React (hooks-based component)
- Vue.js (composition API)
- Minified standalone snippet for any website

## Legal Compliance Notes

This implementation addresses technical requirements for:
- GDPR Article 7 (explicit consent)
- ePrivacy Directive cookie requirements
- CCPA transparency requirements

However, legal compliance requires consultation with legal experts for specific jurisdictions and use cases.