7fe4ae5365
✨ 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.
434 lines
18 KiB
Markdown
434 lines
18 KiB
Markdown
# LifeRPG Architecture Guide
|
|
|
|
This document outlines the architecture of the LifeRPG modern application, explaining key design decisions, component interactions, and technical implementation details.
|
|
|
|
## System Architecture Overview
|
|
|
|
LifeRPG follows a modern microservices-inspired architecture with clear separation of concerns:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Client Applications │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Web Frontend │ │ Mobile App │ │ Public API │ │
|
|
│ │ (React/Vite) │ │ (React Native)│ │ Consumers │ │
|
|
│ └──────┬───────┘ └───────┬──────┘ └───────┬──────┘ │
|
|
└──────────┼──────────────────────┼────────────────────┼──────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|
│ REST API Gateway │
|
|
│ │
|
|
│ (FastAPI with JWT auth, rate limiting, CORS) │
|
|
└────────────┬───────────────────┬───────────────────┬─────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────┐ ┌────────────────┐ ┌───────────────────────┐
|
|
│ Core Services │ │ Integrations │ │ Auxiliary Services │
|
|
│ │ │ │ │ │
|
|
│ - Auth Service │ │ - Todoist │ │ - Telemetry Service │
|
|
│ - Habit Service │ │ - GitHub │ │ - Analytics Service │
|
|
│ - User Service │ │ - Google Cal │ │ - Gamification │
|
|
│ - Project Service│ │ - Slack │ │ - Notification Service│
|
|
└────────┬─────────┘ └───────┬────────┘ └────────┬──────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|
│ Data Layer │
|
|
│ │
|
|
│ ┌──────────────┐ ┌───────────────┐ ┌────────────────────┐ │
|
|
│ │ PostgreSQL │ │ Redis Cache & │ │ Background Workers │ │
|
|
│ │ (SQLAlchemy)│ │ Queue (RQ) │ │ (Integration Sync) │ │
|
|
│ └──────────────┘ └───────────────┘ └────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|
│ Observability │
|
|
│ │
|
|
│ ┌──────────────┐ ┌───────────────┐ ┌────────────────────┐ │
|
|
│ │ Prometheus │ │ Grafana │ │ Structured Logging │ │
|
|
│ │ Metrics │ │ Dashboards │ │ (JSON, Loki) │ │
|
|
│ └──────────────┘ └───────────────┘ └────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### 1. Backend API (FastAPI)
|
|
|
|
The backend uses FastAPI to provide a modern, high-performance API with automatic OpenAPI documentation, data validation, and asynchronous request handling.
|
|
|
|
**Key Design Patterns:**
|
|
|
|
- **Repository Pattern**: Separates data access logic from business logic
|
|
- **Dependency Injection**: Clean dependency management via FastAPI's dependency system
|
|
- **Service Layer**: Business logic encapsulated in service classes
|
|
- **Unit of Work**: Transactions and session management
|
|
- **CQRS-inspired**: Separation of command and query responsibilities
|
|
|
|
**Security Features:**
|
|
|
|
- JWT authentication with proper token rotation
|
|
- OAuth2/OIDC integration with PKCE
|
|
- 2FA with TOTP
|
|
- Rate limiting
|
|
- CSRF protection
|
|
- Security headers (CSP, HSTS)
|
|
|
|
**Code Structure:**
|
|
|
|
```
|
|
backend/
|
|
├── api/ # API routes and endpoints
|
|
│ ├── v1/ # API version 1
|
|
│ │ ├── auth.py # Authentication endpoints
|
|
│ │ ├── habits.py # Habit management endpoints
|
|
│ │ ├── projects.py # Project management endpoints
|
|
│ │ ├── analytics.py # Analytics endpoints
|
|
│ │ └── ...
|
|
├── core/ # Core application components
|
|
│ ├── config.py # Application configuration
|
|
│ ├── security.py # Security utilities
|
|
│ ├── exceptions.py # Custom exceptions
|
|
│ └── dependencies.py # FastAPI dependencies
|
|
├── db/ # Database components
|
|
│ ├── base.py # Base database functionality
|
|
│ ├── session.py # Database session management
|
|
│ └── repositories/ # Repository implementations
|
|
├── models/ # SQLAlchemy models
|
|
├── schemas/ # Pydantic schemas
|
|
├── services/ # Business logic services
|
|
├── utils/ # Utility functions
|
|
├── workers/ # Background workers
|
|
└── main.py # Application entry point
|
|
```
|
|
|
|
### 2. Frontend (React + Vite)
|
|
|
|
The frontend is built with React and Vite for a fast, modern web experience with responsive design and component-based architecture.
|
|
|
|
**Key Design Patterns:**
|
|
|
|
- **Component Composition**: UI built from reusable components
|
|
- **Custom Hooks**: Encapsulating reusable logic
|
|
- **Context API**: State management for shared state
|
|
- **Suspense & Error Boundaries**: For loading states and error handling
|
|
- **React Query**: For data fetching, caching, and synchronization
|
|
|
|
**Code Structure:**
|
|
|
|
```
|
|
frontend/
|
|
├── public/ # Static assets
|
|
├── src/
|
|
│ ├── components/ # Reusable UI components
|
|
│ │ ├── ui/ # Basic UI components (Button, Card, etc.)
|
|
│ │ ├── habits/ # Habit-related components
|
|
│ │ ├── analytics/ # Analytics components
|
|
│ │ └── ...
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── contexts/ # React context providers
|
|
│ ├── pages/ # Page components
|
|
│ ├── services/ # API service functions
|
|
│ ├── utils/ # Utility functions
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ ├── App.jsx # Main App component
|
|
│ └── main.jsx # Application entry point
|
|
├── index.html # HTML template
|
|
└── vite.config.js # Vite configuration
|
|
```
|
|
|
|
### 3. Mobile App (React Native / Expo)
|
|
|
|
The mobile app uses React Native with Expo for cross-platform (iOS/Android) development with a focus on offline-first and sync capabilities.
|
|
|
|
**Key Features:**
|
|
|
|
- **Offline-First**: Local SQLite database
|
|
- **Background Sync**: Push/pull with conflict resolution
|
|
- **Deep Linking**: For OIDC authentication
|
|
- **Secure Storage**: For sensitive data (tokens)
|
|
- **Push Notifications**: For reminders and updates
|
|
|
|
**Code Structure:**
|
|
|
|
```
|
|
mobile/
|
|
├── app/ # Expo Router screens
|
|
├── assets/ # App assets (images, fonts)
|
|
├── components/ # Reusable components
|
|
├── hooks/ # Custom hooks
|
|
├── services/ # API and local services
|
|
├── store/ # State management
|
|
├── utils/ # Utility functions
|
|
├── App.tsx # Main App component
|
|
└── app.json # Expo configuration
|
|
```
|
|
|
|
### 4. Data Models
|
|
|
|
#### Core Entities
|
|
|
|
- **User**: Authentication and profile information
|
|
- **Habit**: Recurring actions to track
|
|
- **Project**: Grouping of related habits
|
|
- **HabitLog**: Record of habit completions
|
|
- **Achievement**: Gamification rewards
|
|
|
|
#### Entity Relationships
|
|
|
|
```
|
|
User 1──* Project
|
|
│
|
|
│
|
|
├───1──* Habit
|
|
│ │
|
|
│ │
|
|
│ └───1──* HabitLog
|
|
│
|
|
└───1──* Achievement
|
|
│
|
|
└───1──* Integration
|
|
│
|
|
└───1──* IntegrationItem
|
|
```
|
|
|
|
### 5. Integration System
|
|
|
|
The integration system connects with external services like Todoist, GitHub, and Google Calendar using a pluggable adapter pattern.
|
|
|
|
**Key Components:**
|
|
|
|
- **Provider Interface**: Common interface for all integrations
|
|
- **Adapter Pattern**: Specific implementations for each provider
|
|
- **OAuth Flow**: Secure token handling and refresh
|
|
- **Webhook Receivers**: For real-time updates
|
|
- **Background Sync**: Periodic syncing with rate limiting and backoff
|
|
|
|
### 6. Gamification Engine
|
|
|
|
The gamification engine motivates users through RPG-like progression mechanics.
|
|
|
|
**Key Features:**
|
|
|
|
- **XP System**: Points for completing habits
|
|
- **Leveling**: Progression based on accumulated XP
|
|
- **Achievements**: Special rewards for milestones
|
|
- **Streaks**: Consecutive completion tracking
|
|
- **Leaderboards**: Optional social comparison
|
|
|
|
**Implementation:**
|
|
|
|
```python
|
|
class GamificationService:
|
|
async def award_xp(self, user_id: int, amount: int, source: str) -> dict:
|
|
"""Award XP to a user and handle level ups and achievements."""
|
|
|
|
async def check_achievements(self, user_id: int, action: str, metadata: dict) -> list:
|
|
"""Check if an action triggers any achievements."""
|
|
|
|
async def update_streak(self, user_id: int, habit_id: int) -> dict:
|
|
"""Update streak counters for a habit."""
|
|
```
|
|
|
|
## Architectural Decisions
|
|
|
|
### Database Choice: PostgreSQL (Production) / SQLite (Development)
|
|
|
|
**Rationale**:
|
|
- **PostgreSQL**: Robust, ACID-compliant, supports complex queries and indexes
|
|
- **SQLite**: Simple setup for development and testing
|
|
- **SQLAlchemy**: ORM abstraction allows for easy switching between databases
|
|
|
|
### Authentication: JWT + OAuth2/OIDC
|
|
|
|
**Rationale**:
|
|
- **JWT**: Stateless authentication with low overhead
|
|
- **OAuth2/OIDC**: Secure delegation, no password storage, multi-provider support
|
|
- **PKCE**: Enhanced security for mobile and SPA clients
|
|
|
|
### Background Processing: Redis + RQ
|
|
|
|
**Rationale**:
|
|
- **Redis**: Fast, reliable queue with persistence options
|
|
- **RQ**: Simple Python interface with good monitoring
|
|
- **Worker Resilience**: Retries, backoff, and concurrency management
|
|
|
|
### Caching Strategy: Multi-level
|
|
|
|
**Rationale**:
|
|
- **Browser Cache**: Static assets with appropriate cache headers
|
|
- **Redis Cache**: API responses and computation results
|
|
- **Memory Cache**: Frequent lookups (e.g., user permissions)
|
|
|
|
### API Versioning
|
|
|
|
**Rationale**:
|
|
- **URL-based Versioning**: Clear, explicit API versions (e.g., `/api/v1/`)
|
|
- **Backwards Compatibility**: Maintain older versions during transitions
|
|
- **API Deprecation Policy**: Clear communication about deprecated endpoints
|
|
|
|
## Performance Considerations
|
|
|
|
### 1. Database Optimization
|
|
|
|
- **Indexes**: Strategic indexes on frequently queried fields
|
|
- **Connection Pooling**: Reuse database connections
|
|
- **Query Optimization**: Minimize N+1 queries using proper joins
|
|
- **Pagination**: For large result sets
|
|
|
|
### 2. Caching Strategy
|
|
|
|
- **Cache Headers**: HTTP caching for static assets
|
|
- **API Response Caching**: Cache common API responses
|
|
- **Computed Values**: Cache expensive calculations
|
|
|
|
### 3. Frontend Performance
|
|
|
|
- **Code Splitting**: Load only needed code
|
|
- **Tree Shaking**: Eliminate unused code
|
|
- **Lazy Loading**: Defer loading of non-critical components
|
|
- **Image Optimization**: Proper formats and sizes
|
|
|
|
## Security Architecture
|
|
|
|
### 1. Authentication & Authorization
|
|
|
|
- **JWT**: Secure, short-lived tokens
|
|
- **Refresh Tokens**: For session persistence
|
|
- **RBAC**: Role-based access control
|
|
- **2FA**: Additional security layer
|
|
|
|
### 2. Data Protection
|
|
|
|
- **HTTPS**: All traffic encrypted
|
|
- **Encrypted Storage**: Sensitive data encrypted at rest
|
|
- **Input Validation**: Prevent injection attacks
|
|
- **Output Encoding**: Prevent XSS
|
|
|
|
### 3. API Security
|
|
|
|
- **Rate Limiting**: Prevent abuse
|
|
- **CORS**: Restrict origins
|
|
- **CSRF Protection**: Prevent cross-site request forgery
|
|
- **Security Headers**: CSP, HSTS, etc.
|
|
|
|
## Observability & Monitoring
|
|
|
|
### 1. Metrics
|
|
|
|
- **Application Metrics**: Request rates, error rates, response times
|
|
- **Business Metrics**: User activity, habit completions, achievements
|
|
- **System Metrics**: CPU, memory, disk usage
|
|
|
|
### 2. Logging
|
|
|
|
- **Structured Logging**: JSON format for machine parsing
|
|
- **Log Levels**: Error, warning, info, debug
|
|
- **Context Enrichment**: User ID, request ID, etc.
|
|
|
|
### 3. Alerting
|
|
|
|
- **SLO-based Alerts**: Alert on service level objective violations
|
|
- **Error Rate Thresholds**: Alert on elevated error rates
|
|
- **Custom Business Alerts**: Unusual patterns in user behavior
|
|
|
|
## Future Architecture Considerations
|
|
|
|
### 1. Microservices Evolution
|
|
|
|
As the system grows, consider splitting into true microservices:
|
|
- **Auth Service**: Handle authentication and authorization
|
|
- **Habit Service**: Core habit tracking functionality
|
|
- **Integration Service**: Manage external integrations
|
|
- **Gamification Service**: Handle XP, levels, and achievements
|
|
|
|
### 2. Event-Driven Architecture
|
|
|
|
Introduce event sourcing and CQRS for complex domains:
|
|
- **Event Bus**: Publish domain events
|
|
- **Event Sourcing**: Store state changes as events
|
|
- **CQRS**: Separate read and write models
|
|
|
|
### 3. Serverless Components
|
|
|
|
For appropriate workloads:
|
|
- **API Lambdas**: Serverless API endpoints
|
|
- **Event Processors**: Serverless event handlers
|
|
- **Scheduled Tasks**: Serverless cron jobs
|
|
|
|
## Plugin System Design (Planned)
|
|
|
|
The planned plugin system will allow extending LifeRPG with custom functionality:
|
|
|
|
### 1. Plugin Architecture
|
|
|
|
- **WASM-based Sandbox**: Secure execution environment
|
|
- **Plugin Manifest**: Metadata, permissions, and dependencies
|
|
- **Lifecycle Hooks**: Initialize, execute, and clean up
|
|
- **Versioning**: Plugin and API version compatibility
|
|
|
|
### 2. Extension Points
|
|
|
|
- **Custom Visualizations**: Add new charts and views
|
|
- **Integration Adapters**: Connect to additional services
|
|
- **Habit Templates**: Predefined habit configurations
|
|
- **Achievement Rules**: Custom achievement conditions
|
|
|
|
### 3. Security Model
|
|
|
|
- **Permission System**: Granular permissions for plugins
|
|
- **Resource Limits**: Memory, CPU, and network constraints
|
|
- **Approval Process**: Optional plugin verification
|
|
|
|
## Conclusion
|
|
|
|
The LifeRPG architecture is designed for scalability, maintainability, and security while providing a rich user experience. This guide serves as a living document that will evolve with the project.
|
|
|
|
---
|
|
|
|
## Appendix: Technology Stack
|
|
|
|
### Backend
|
|
- **Language**: Python 3.10+
|
|
- **Framework**: FastAPI
|
|
- **ORM**: SQLAlchemy
|
|
- **Migration**: Alembic
|
|
- **Authentication**: JWT, OAuth2/OIDC
|
|
- **Background Jobs**: Redis + RQ
|
|
- **Testing**: Pytest
|
|
|
|
### Frontend
|
|
- **Framework**: React 18+
|
|
- **Build Tool**: Vite
|
|
- **Styling**: TailwindCSS
|
|
- **State Management**: React Context + React Query
|
|
- **UI Components**: Custom component library
|
|
- **Charts**: Recharts
|
|
- **Testing**: Vitest + React Testing Library
|
|
|
|
### Mobile
|
|
- **Framework**: React Native / Expo
|
|
- **Navigation**: React Navigation
|
|
- **Local Storage**: Expo SQLite
|
|
- **Authentication**: react-native-app-auth
|
|
- **Secure Storage**: expo-secure-store
|
|
- **Background Tasks**: expo-background-fetch
|
|
|
|
### Infrastructure
|
|
- **Database**: PostgreSQL (production), SQLite (development)
|
|
- **Caching**: Redis
|
|
- **Observability**: Prometheus, Grafana, Loki
|
|
- **CI/CD**: GitHub Actions
|
|
- **Containerization**: Docker
|
|
|
|
### Development Tools
|
|
- **Linting**: ESLint, Flake8
|
|
- **Formatting**: Prettier, Black
|
|
- **Documentation**: OpenAPI, MkDocs
|
|
- **Dependency Management**: Poetry (Python), npm (JS/TS)
|