🧙♂️ Transform LifeRPG into The Wizard's Grimoire - Production-Ready Application
✨ Major Features Added: - Complete magical theming and rebranding from LifeRPG to The Wizard's Grimoire - Production-grade React frontend with Tailwind CSS v4 and magical aesthetics - Comprehensive analytics dashboard with Recharts integration (ScryingPortal) - Push notifications system with PWA service worker support - Drag & drop functionality using @dnd-kit for habit reordering - Social features with friends system and leaderboards - Performance optimization tools and monitoring - Mobile app enhancement with PWA installation support 🏗️ Technical Infrastructure: - Advanced service worker with offline support and background sync - Zustand state management for scalable application state - Production-ready UI component system with enhanced Button, Card, Input - Progressive Web App (PWA) with manifest and app installation - FastAPI backend with comprehensive API endpoints - Docker containerization and CI/CD pipeline setup 📱 Progressive Web App Features: - Offline functionality with intelligent caching - Push notification support for habit reminders - App installation on mobile and desktop platforms - Background sync for offline data management - Performance monitoring and optimization tools 🎨 User Experience: - Magical wizard/grimoire theming throughout application - Responsive design optimized for all device sizes - Drag & drop habit management with smooth animations - Interactive analytics with multiple chart types - Social connectivity with friends and competitive features - Comprehensive notification and performance settings 🔧 Developer Experience: - Modern development stack with Vite and React - Comprehensive testing setup and CI/CD pipelines - Code quality tools with pre-commit hooks - Docker development environment - Detailed documentation and implementation guides This represents a complete transformation from prototype to production-ready application with enterprise-grade features and magical user experience.
This commit is contained in:
TLimoges33
@@ -0,0 +1,225 @@
|
||||
# Telemetry System Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
LifeRPG includes an optional telemetry system designed to help improve the application through anonymous usage analytics. The system is built with privacy-first principles and user control.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Opt-in Only**: Users must explicitly consent to telemetry collection
|
||||
- **Anonymous**: No personal information or habit content is collected
|
||||
- **Transparent**: Users can see exactly what data is collected
|
||||
- **Administrative Control**: Can be disabled globally by administrators
|
||||
- **GDPR Compliant**: Respects user privacy and data protection regulations
|
||||
|
||||
## Architecture
|
||||
|
||||
### Backend Components
|
||||
|
||||
1. **`telemetry.py`** - Core telemetry engine
|
||||
- Consent management
|
||||
- Event recording and sanitization
|
||||
- Pre-defined event helpers
|
||||
- Analytics aggregation
|
||||
|
||||
2. **Database Models**
|
||||
- `TelemetryEvent` - Stores anonymous event data
|
||||
- `Profile` - Stores user consent preferences
|
||||
|
||||
3. **API Endpoints**
|
||||
- `POST /api/v1/telemetry/consent` - Set user consent
|
||||
- `GET /api/v1/telemetry/consent` - Get consent status
|
||||
- `POST /api/v1/telemetry/event` - Record custom events
|
||||
- `GET /api/v1/admin/telemetry/stats` - Admin analytics
|
||||
|
||||
### Frontend Components
|
||||
|
||||
1. **`TelemetrySettings.jsx`** - User consent management UI
|
||||
2. **`AdminTelemetryDashboard.jsx`** - Administrative analytics dashboard
|
||||
3. **`useTelemetry.js`** - React hook for event tracking
|
||||
|
||||
## Data Collection
|
||||
|
||||
### What We Collect
|
||||
|
||||
- **Feature Usage**: Which features are accessed and how often
|
||||
- **Performance Metrics**: Error rates and system performance
|
||||
- **Aggregated Behavior**: Usage patterns and trends
|
||||
- **Gamification Events**: XP earnings, level-ups, achievements
|
||||
|
||||
### What We Don't Collect
|
||||
|
||||
- Personal information (names, emails, etc.)
|
||||
- Habit titles or descriptions
|
||||
- User notes or content
|
||||
- Location data
|
||||
- Device identifiers
|
||||
- IP addresses
|
||||
|
||||
### Event Types
|
||||
|
||||
```javascript
|
||||
// User actions
|
||||
habit_created: { habit_difficulty, habit_cadence }
|
||||
habit_completed: { habit_difficulty, xp_awarded }
|
||||
achievement_earned: { achievement_type, xp_awarded }
|
||||
level_up: { old_level, new_level }
|
||||
|
||||
// Feature usage
|
||||
analytics_heatmap: { feature_used: 'analytics_heatmap' }
|
||||
analytics_trends: { feature_used: 'analytics_trends' }
|
||||
feature_used: { feature_used: 'feature_name', duration? }
|
||||
|
||||
// Technical events
|
||||
error_occurred: { error_type, context? }
|
||||
page_view: { page }
|
||||
user_interaction: { action, category?, label? }
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Enable/disable telemetry globally
|
||||
TELEMETRY_ENABLED=true # default: true
|
||||
```
|
||||
|
||||
### User Consent
|
||||
|
||||
Users can opt-in/out at any time through:
|
||||
1. Settings page in the UI
|
||||
2. API endpoint
|
||||
3. Automatic consent prompts
|
||||
|
||||
## Privacy Compliance
|
||||
|
||||
### GDPR Compliance
|
||||
|
||||
- **Lawful Basis**: Legitimate interest with opt-out capability
|
||||
- **Data Minimization**: Only collect necessary anonymous data
|
||||
- **Purpose Limitation**: Data used only for application improvement
|
||||
- **Transparency**: Clear disclosure of what data is collected
|
||||
- **User Control**: Easy opt-out mechanism
|
||||
|
||||
### Data Retention
|
||||
|
||||
- Events are stored indefinitely for analytics
|
||||
- User consent can be withdrawn at any time
|
||||
- No personal data is stored in telemetry events
|
||||
|
||||
## Implementation Examples
|
||||
|
||||
### Backend Integration
|
||||
|
||||
```python
|
||||
from .telemetry import record_habit_completion
|
||||
|
||||
# In habit completion endpoint
|
||||
result = gamification.process_habit_completion(db, user.id, habit_id)
|
||||
|
||||
# Record telemetry
|
||||
record_habit_completion(db, user.id, habit.difficulty, result.get('xp_awarded', 0))
|
||||
```
|
||||
|
||||
### Frontend Integration
|
||||
|
||||
```javascript
|
||||
import { useTelemetry } from '../hooks/useTelemetry';
|
||||
|
||||
const MyComponent = () => {
|
||||
const { trackFeatureUsage, trackInteraction } = useTelemetry();
|
||||
|
||||
const handleAnalyticsView = () => {
|
||||
trackFeatureUsage('analytics_dashboard');
|
||||
};
|
||||
|
||||
const handleButtonClick = () => {
|
||||
trackInteraction('button_click', 'navigation', 'analytics');
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Data Sanitization
|
||||
|
||||
All event properties are sanitized to remove:
|
||||
- Strings longer than 100 characters
|
||||
- Non-whitelisted property keys
|
||||
- Potentially identifying information
|
||||
|
||||
### Access Control
|
||||
|
||||
- User events require authentication
|
||||
- Admin analytics require admin role
|
||||
- Anonymous events allowed for error reporting
|
||||
|
||||
## Monitoring and Analytics
|
||||
|
||||
### Admin Dashboard
|
||||
|
||||
Administrators can view:
|
||||
- Total events and unique users
|
||||
- Event type distribution
|
||||
- Usage trends over time
|
||||
- Performance insights
|
||||
|
||||
### Metrics Available
|
||||
|
||||
- Daily/weekly/monthly active users
|
||||
- Feature adoption rates
|
||||
- Error rates and types
|
||||
- User engagement patterns
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Telemetry not recording**
|
||||
- Check `TELEMETRY_ENABLED` environment variable
|
||||
- Verify user has given consent
|
||||
- Check database connectivity
|
||||
|
||||
2. **Admin dashboard empty**
|
||||
- Verify admin role permissions
|
||||
- Check if telemetry is globally enabled
|
||||
- Ensure events are being recorded
|
||||
|
||||
3. **Consent not saving**
|
||||
- Check authentication token
|
||||
- Verify database write permissions
|
||||
- Check API endpoint configuration
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Real-time event streaming
|
||||
- Advanced user behavior analytics
|
||||
- A/B testing framework integration
|
||||
- Performance monitoring dashboard
|
||||
- Automated privacy compliance reports
|
||||
|
||||
## API Reference
|
||||
|
||||
### Endpoints
|
||||
|
||||
```
|
||||
POST /api/v1/telemetry/consent
|
||||
GET /api/v1/telemetry/consent
|
||||
POST /api/v1/telemetry/event
|
||||
GET /api/v1/admin/telemetry/stats
|
||||
```
|
||||
|
||||
### Event Recording Functions
|
||||
|
||||
```python
|
||||
# Direct event recording
|
||||
record_event(db, user_id, event_name, properties)
|
||||
|
||||
# Convenience functions
|
||||
record_habit_completion(db, user_id, difficulty, xp_awarded)
|
||||
record_achievement_earned(db, user_id, achievement_type, xp_awarded)
|
||||
record_level_up(db, user_id, old_level, new_level)
|
||||
record_feature_usage(db, user_id, feature, duration)
|
||||
record_error(db, user_id, error_type, context)
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
# Admin operations guide
|
||||
|
||||
This page summarizes admin/ops capabilities and where to find them.
|
||||
|
||||
API endpoints (all under /api/v1):
|
||||
- GET /admin/orchestration — current in-flight counts, queue depths, effective provider caps, and RQ queue length.
|
||||
- GET/POST /admin/provider_caps — view/update per-provider concurrency caps (persisted); reflected in metrics and enqueue logic.
|
||||
- GET /admin/hooks/schema — JSON schema and examples for hooks configuration to aid validation.
|
||||
- POST /admin/hooks/validate — validate a hooks object server-side before saving.
|
||||
- GET /admin/email/health — show email transport config and attempt an SMTP handshake when enabled.
|
||||
- POST /admin/email/test — send a test email to verify delivery.
|
||||
|
||||
Frontend UI:
|
||||
- Integrations page includes:
|
||||
- Provider caps editor (view/edit) and orchestration summary with manual refresh, auto-refresh, sorting, and cap utilization badges.
|
||||
- Hooks editor with example prefill and server-side validation, showing inline errors.
|
||||
- Admin settings controls for integration close mode and default sync interval.
|
||||
|
||||
Metrics to watch (Prometheus):
|
||||
- sync_inflight, sync_queue_depth, sync_provider_cap, rq_queue_length
|
||||
- sync_enqueue_skips_total{reason}
|
||||
- sync_job_duration_seconds (histogram by provider,result)
|
||||
|
||||
Alerts (Prometheus examples in ops/prometheus-alerts.yaml):
|
||||
- Provider at cap for sustained periods
|
||||
- Queue depth increasing
|
||||
- RQ queue backlog sustained
|
||||
- Slow syncs (p95 duration) exceeding threshold
|
||||
@@ -0,0 +1,26 @@
|
||||
# Email transport
|
||||
|
||||
The notifier supports three transports controlled by environment variables:
|
||||
|
||||
- LIFERPG_EMAIL_TRANSPORT: `console` (default), `smtp`, or `disabled`.
|
||||
- SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_USE_TLS, SMTP_FROM
|
||||
|
||||
Behavior:
|
||||
- console: logs an `email_console` event (no email sent).
|
||||
- smtp: sends via SMTP with optional STARTTLS and auth.
|
||||
- disabled: logs an `email_disabled` event and does nothing.
|
||||
|
||||
Example `.env`:
|
||||
```
|
||||
LIFERPG_EMAIL_TRANSPORT=smtp
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=smtp-user
|
||||
SMTP_PASSWORD=s3cr3t
|
||||
SMTP_USE_TLS=true
|
||||
SMTP_FROM=LifeRPG <noreply@example.com>
|
||||
```
|
||||
|
||||
Troubleshooting:
|
||||
- If SMTP_HOST is missing, it falls back to console behavior.
|
||||
- Errors are logged as `email_fail` job events; they don’t raise to the caller.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Hooks configuration
|
||||
|
||||
You can configure pre- and post-sync hooks per integration via `Integration.config.hooks`.
|
||||
|
||||
Config shape (stored as JSON in `integrations.config`):
|
||||
|
||||
```
|
||||
{
|
||||
"hooks": {
|
||||
"pre_sync": [
|
||||
{ "type": "slack", "text": "Sync starting for {provider}" },
|
||||
{ "type": "webhook", "url": "https://example.com/hook", "template": "{provider} sync started" }
|
||||
],
|
||||
"post_sync": [
|
||||
{ "type": "slack", "on": "success" },
|
||||
{ "type": "slack", "on": "fail" },
|
||||
{ "type": "email", "to": "ops@example.com", "subject": "Sync {event}", "body": "{provider} finished with count={count}" },
|
||||
{ "type": "webhook", "url": "https://example.com/notify", "headers": {"X-Token": "abc"}, "template": "{provider} done: {count}" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `pre_sync` runs before adapter execution.
|
||||
- `post_sync` supports `on`: `success`, `fail`, or `always` (default).
|
||||
- Slack hook reuses the Slack notifier. Add a Slack integration with an incoming webhook for messages to deliver.
|
||||
- Webhook hook posts JSON to the given `url`. If `template` is provided, `{context}` values are formatted into a `text` field.
|
||||
- Email hook uses the notifier email transport. See `docs/email.md`.
|
||||
|
||||
Context variables available to templates:
|
||||
- `provider`: provider name (e.g., `todoist`)
|
||||
- `count`: items processed (when available)
|
||||
|
||||
Caveats:
|
||||
- Hooks execute best-effort. Failures are logged and do not block the sync.
|
||||
- Keep templates simple; invalid placeholders are ignored and the raw context is sent.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Legacy import (AHK) plan
|
||||
|
||||
The classic LifeRPG AHK app can export data (habits, projects, logs). This document outlines a basic import approach for the modern backend.
|
||||
|
||||
Scope (phase 1):
|
||||
- Accept a JSON export shaped as:
|
||||
```json
|
||||
{ "habits": [{"title":"...","notes":"...","cadence":"once","status":"active"}],
|
||||
"projects": [{"title":"...","description":"..."}],
|
||||
"logs": [{"habit_title":"...","action":"completed","timestamp":"2025-08-28T12:00:00Z"}] }
|
||||
```
|
||||
- Map to current schema: create Projects, Habits, and Logs for the authenticated user.
|
||||
- Provide an admin endpoint to upload and import.
|
||||
|
||||
Future:
|
||||
- Write a converter for AHK-specific export formats (CSV/INI) into the JSON shape above.
|
||||
- Support incremental merge with duplicate detection by title + timestamps.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Public API tokens (read-only)
|
||||
|
||||
Create lightweight tokens to embed read-only widgets without a full login.
|
||||
|
||||
Endpoints:
|
||||
- POST /api/v1/tokens — create a token (returns plaintext once)
|
||||
- GET /api/v1/tokens — list your tokens
|
||||
- DELETE /api/v1/tokens/{id} — revoke
|
||||
- GET /api/v1/public/widgets/status?token=... — public read-only status JSON
|
||||
|
||||
Security notes:
|
||||
- Tokens are one-way hashed in DB with a server-side pepper; only shown at creation.
|
||||
- Scope is currently `read:widgets` only.
|
||||
- Treat tokens like secrets; rotate regularly.
|
||||
Reference in New Issue
Block a user