LifeRPG_v2.0/docs/ARCHITECTURE.md

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:

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)