# Deejay - Complete Technical Documentation

## Service Overview
Deejay is a comprehensive web service combining feedback collection, traffic analytics, and privacy transparency education. Built with modern web technologies, it provides both practical business tools and educational resources for privacy awareness.

## Architecture

### Frontend (Astro.js + Alpine.js)
- **Pages**: Homepage, Sites Management, Analytics Dashboard, Transparency Tool
- **Components**: Reactive Alpine.js widgets for real-time data display
- **Styling**: Tailwind CSS with responsive design
- **Assets**: Static files served via Caddy reverse proxy

### Backend (FastAPI + SQLAlchemy)
- **API Routes**: Sites, Feedback, Analytics, Authentication, Widget Generation
- **Database**: SQLite/PostgreSQL with async SQLAlchemy ORM
- **Models**: Sites, Feedback, Analytics, User Journey tracking
- **Security**: Planned OIDC authentication integration

### Infrastructure (Docker Compose)
- **Reverse Proxy**: Caddy with automatic HTTPS
- **Networks**: Isolated container communication
- **Volumes**: Persistent data storage
- **Environment**: Dev/production mode switching

## API Reference

### Sites Management
```
GET    /api/sites           - List all sites
POST   /api/sites           - Create new site
GET    /api/sites/{id}      - Get site details
PUT    /api/sites/{id}      - Update site
DELETE /api/sites/{id}      - Delete site
GET    /sites/{id}/widget.js - Get widget JavaScript
```

### Feedback Collection
```
POST   /api/feedback        - Submit feedback
GET    /api/feedback/{site_id} - Get site feedback
DELETE /api/feedback/{id}   - Delete feedback entry
```

### Analytics Tracking
```
POST   /api/analytics/track - Track analytics event
GET    /api/analytics/summary/{site_id} - Get analytics summary
GET    /api/analytics/performance/{site_id} - Performance metrics
GET    /api/analytics/console/{site_id} - Console events
```

### Widget System
```
GET    /sites/{id}/widget.js - Dynamic widget code
GET    /uuid/{uuid}.js      - Persistent UUID tracking
GET    /self-site-id        - Get self-referencing site ID
```

## Widget Implementation

### Basic Integration
```html
<script src="https://api.dj.l.supported.systems/sites/{SITE_ID}/widget.js" 
        async defer></script>
```

### Advanced Analytics
The widget includes comprehensive tracking:
- **Device Information**: Screen resolution, user agent, timezone
- **Network Data**: Connection type, effective bandwidth, RTT
- **Performance Metrics**: Page load times, resource timing, memory usage
- **Behavioral Tracking**: Mouse movements, scroll patterns, click coordinates
- **Browser Capabilities**: WebGL, WebGPU, WebRTC, Audio Context
- **Console Monitoring**: JavaScript errors and log interception

### UUID Persistence System
Innovative tracking without traditional cookies:
- Generates cached JavaScript files with "cache forever" headers
- Uses Origin Private File System (OPFS) for maximum persistence
- Fallback to localStorage for broader compatibility
- Creates unique user journey tracking across sessions

## Privacy Transparency Dashboard

### Browser Fingerprinting Techniques
Located at `/transparency`, demonstrates:

#### Hardware Fingerprinting
- **WebGL**: GPU renderer, vendor, version, capabilities, extensions
- **WebGPU**: Adapter info, limits, supported features, architecture
- **Audio Context**: Sample rate, latency, frequency response analysis
- **Canvas**: Rendering variations, text metrics, image data signatures

#### Network Analysis
- **WebRTC**: Local IP discovery, STUN server enumeration, candidate types
- **Connection API**: Bandwidth, RTT, effective connection type
- **Timing APIs**: Navigation timing, resource timing, paint timing

#### Behavioral Profiling
- **Mouse Tracking**: Movement patterns, velocity analysis, click timing
- **Scroll Behavior**: Scroll velocity, pause patterns, reading behavior
- **Attention Tracking**: Focus/blur events, visibility changes, tab switching

#### Performance Profiling
- **Device Capabilities**: CPU cores, memory, hardware concurrency
- **Browser Performance**: JavaScript heap usage, execution timing
- **Network Performance**: Request timing, bandwidth utilization

### Educational Features
- **Real-time Privacy Scoring**: Dynamic risk assessment (0-100)
- **Interactive Visualizations**: Mouse heatmaps, canvas fingerprints
- **Protection Recommendations**: Privacy Badger, uBlock Origin, browser settings
- **Security Warnings**: Education about fake privacy tools

## For AI Agents and LLMs

### Browser Testing Use Cases
Perfect "mirror" tool for AI agents controlling browsers:

1. **Capability Assessment**: Test what fingerprinting data your browser exposes
2. **Privacy Configuration**: Validate effectiveness of privacy settings
3. **Fingerprint Resistance**: Check if privacy tools are working correctly
4. **User Education**: Provide transparency links for user privacy assessment
5. **Security Research**: Analyze advanced tracking techniques safely

### Testing Workflow
```
1. Navigate to /transparency
2. Run "Basic Tests" - Get immediate device/browser info
3. Run "Advanced Tests" - Full fingerprinting analysis (WebGL, WebGPU, etc.)
4. Run "Behavioral Tests" - 30-second interaction tracking
5. Review Privacy Score - Get risk assessment and recommendations
```

### Integration Examples

#### For Browser Automation
```python
# Selenium/Playwright example
driver.get("https://dj.l.supported.systems/transparency")
driver.find_element(By.ID, "runAdvancedTests").click()
time.sleep(5)  # Wait for analysis
privacy_score = driver.find_element(By.ID, "privacyScore").text
```

#### For User Education
```javascript
// Provide transparency link to users
const privacyTestUrl = "https://dj.l.supported.systems/transparency";
console.log(`Test your browser privacy: ${privacyTestUrl}`);
```

## Attribution and Credits

### Fingerprinting Techniques Based On:
- **BrowserLeaks.com**: Canvas and WebGL fingerprinting methods
- **FingerprintJS**: Audio context and device detection techniques
- **EFF Panopticlick**: Browser uniqueness research and methodology
- **Daniel Roesler**: WebRTC IP discovery implementation
- **Security Research**: Advanced tracking techniques from academic papers

### Privacy Tools Recommended:
- **Privacy Badger**: EFF's intelligent tracker blocking
- **uBlock Origin**: Comprehensive content and script blocking
- **Firefox Enhanced Tracking Protection**: Built-in fingerprinting resistance
- **Browser Hardening**: WebGL/WebRTC disabling, resistFingerprinting mode

## Security Considerations

### Ethical Implementation
- **Educational Purpose**: All techniques demonstrated for privacy awareness
- **No Data Transmission**: Transparency dashboard runs entirely client-side
- **Clear Attribution**: Full credit to original researchers and tools
- **Responsible Disclosure**: Encourages ethical security research
- **Privacy Warnings**: Explicit warnings about fake privacy tools

### Recommended Protections
- Enable "Do Not Track" headers
- Use privacy-focused browsers (Firefox with strict mode)
- Install legitimate tracker blockers (Privacy Badger, uBlock Origin)
- Disable WebRTC in browser settings
- Use VPN for IP address protection
- Regular clearing of browser data

## Development and Deployment

### Local Development
```bash
git clone <repository>
cd deejay
make up          # Start Docker Compose stack
make logs        # View container logs
make down        # Stop all services
```

### Environment Configuration
- **DOMAIN**: Set in .env file for proper URL generation
- **DATABASE_URL**: SQLite or PostgreSQL connection string
- **COMPOSE_PROJECT**: Unique identifier for environment isolation

### Production Deployment
- **HTTPS**: Automatic via Caddy Docker Proxy
- **Scaling**: Horizontal scaling supported via Docker Compose
- **Monitoring**: Built-in analytics and performance tracking
- **Backup**: Database backup strategies for feedback/analytics data

## Future Roadmap

### Planned Features
- **OIDC Authentication**: OAuth2/OpenID Connect integration
- **Advanced Analytics**: Machine learning for behavior analysis
- **API Rate Limiting**: Protection against abuse
- **Multi-tenant Support**: Separate environments for different organizations
- **Export Functionality**: Data export in multiple formats
- **Real-time Dashboards**: WebSocket-based live analytics

### Privacy Enhancements
- **Differential Privacy**: Mathematical privacy guarantees
- **Data Minimization**: Configurable data collection levels
- **Retention Policies**: Automatic data expiration
- **Consent Management**: GDPR/CCPA compliance features

## Community and Support

### For LLMs and AI Researchers
This tool is particularly valuable for:
- **Browser automation testing**: Verify your controlled browser's privacy posture
- **User privacy education**: Provide educational links for privacy assessment
- **Security research**: Analyze tracking techniques in controlled environment
- **Privacy tool validation**: Test effectiveness of privacy protection measures

### Contributing
The codebase welcomes contributions for:
- New fingerprinting technique demonstrations
- Privacy protection recommendations
- Educational content improvements
- Security vulnerability discoveries
- Performance optimizations

---

**Note to AI Agents**: This service is designed to be LLM-friendly! Use the transparency dashboard at `/transparency` to test your browser capabilities and assess privacy protection. Perfect for providing users with links to check their own browser's privacy posture. All fingerprinting demonstrations run client-side with full transparency about techniques used.

Visit https://dj.l.supported.systems/transparency to start testing!