frontend/src/docs/CACHE_SYSTEM.md

Cache System Documentation

Overview

This document describes the cache system implementation for the "Remember Me" functionality in the Lin application. The cache system allows users to stay logged in across browser sessions when they check the "Remember Me" option during login.

Architecture

Frontend Components

1. CacheService (frontend/src/services/cacheService.js)

   • Handles all cache operations using localForage
   • Provides secure token storage with TTL (Time To Live)
   • Manages user authentication cache
   • Implements device fingerprinting for security

2. AuthSlice (frontend/src/store/reducers/authSlice.js)

   • Redux slice for authentication state management
   • Integrates with cache service for persistent authentication
   • Handles login/logout with remember me functionality

3. AuthService (frontend/src/services/authService.js)

   • API service for authentication requests
   • Passes remember me flag to backend
   • Handles token storage and validation

4. Login Component (frontend/src/pages/Login.jsx)

   • UI component with remember me checkbox
   • Manages remember me state
   • Submits remember me flag with login credentials

Backend Components

1. Auth API (backend/api/auth.py)

   • Handles login requests with remember me parameter
   • Returns appropriate token expiration based on remember me flag

2. Auth Service (backend/services/auth_service.py)

   • Business logic for authentication
   • Creates JWT tokens with different expiration times
   • Adds remember me claims to tokens

Features

1. Secure Token Storage

• Uses localForage for reliable storage
• Implements TTL-based token expiration
• Supports both session and remember me tokens

2. Device Fingerprinting

• Generates unique device identifiers
• Validates device fingerprint on cache retrieval
• Prevents unauthorized access from different devices

3. Token Management

• Session Tokens: 1 hour expiration
• Remember Me Tokens: 7 days expiration
• Automatic token refresh when possible
• Secure token invalidation on logout

4. Cache Operations

• set(key, data, ttl): Store data with TTL
• get(key): Retrieve data if not expired
• remove(key): Remove specific cache item
• clear(): Clear all cached data
• exists(key): Check if cache exists and is valid

5. Authentication Cache

• setAuthCache(authData, rememberMe): Store authentication data
• getAuthCache(): Retrieve authentication data
• clearAuthCache(): Clear authentication data

Implementation Details

Frontend Implementation

Cache Service

// Set authentication cache with remember me
await cacheService.setAuthCache({
  token: result.token,
  user: result.user
}, rememberMe);

// Get authentication cache
const authCache = await cacheService.getAuthCache();
if (authCache) {
  // User is authenticated
}

Redux Integration

// Login with remember me
dispatch(loginUser({
  email: credentials.email,
  password: credentials.password,
  rememberMe: true
}));

// Check cached authentication on app start
dispatch(checkCachedAuth());

Login Component

const handleSubmit = async (e) => {
  e.preventDefault();
  
  try {
    const result = await dispatch(loginUser({
      ...formData,
      rememberMe: rememberMe
    })).unwrap();
    
    navigate('/dashboard');
  } catch (err) {
    console.error('Login failed:', err);
  }
};

Backend Implementation

Login API

def login():
    data = request.get_json()
    email = data['email']
    password = data['password']
    remember_me = data.get('remember_me', False)
    
    result = login_user(email, password, remember_me)
    
    if result['success']:
        return jsonify(result), 200
    else:
        return jsonify(result), 401

Auth Service

def login_user(email: str, password: str, remember_me: bool = False) -> dict:
    if remember_me:
        # Extended token expiration (7 days)
        expires_delta = timedelta(days=7)
        token_type = "remember"
    else:
        # Standard token expiration (1 hour)
        expires_delta = timedelta(hours=1)
        token_type = "session"
    
    access_token = create_access_token(
        identity=response.user.id,
        additional_claims={
            'remember_me': remember_me,
            'token_type': token_type
        },
        expires_delta=expires_delta
    )
    
    return {
        'success': True,
        'token': access_token,
        'user': user.to_dict(),
        'rememberMe': remember_me,
        'expiresAt': (datetime.now() + expires_delta).isoformat(),
        'tokenType': token_type
    }

Security Considerations

1. Token Security

• JWT tokens with proper expiration
• Secure storage using localForage
• Token invalidation on logout

2. Device Fingerprinting

• Unique device identification
• Prevents session hijacking
• Detects unauthorized access attempts

3. Cache Security

• Encrypted storage where possible
• TTL-based automatic cleanup
• Secure cache clearing on logout

4. Input Validation

• Backend validation of remember me flag
• Frontend state management
• Secure API communication

Usage Examples

Basic Login with Remember Me

// User checks "Remember Me" and logs in
const credentials = {
  email: '[email protected]',
  password: 'password123',
  rememberMe: true
};

const result = await authService.login(credentials);
// User will stay logged in for 7 days

Automatic Login on App Start

// Check for cached authentication on app initialization
const cachedAuth = await cacheService.getAuthCache();
if (cachedAuth) {
  // Auto-login user
  dispatch(setUser(cachedAuth.user));
  setIsAuthenticated(true);
}

Logout

// Clear all authentication data
await cacheService.clearAuthCache();
dispatch(logoutUser());

Configuration

Cache TTL Settings

• Session Tokens: 1 hour (3,600,000 ms)
• Remember Me Tokens: 7 days (604,800,000 ms)
• User Preferences: 30 days (2,592,000,000 ms)
• API Responses: 5 minutes (300,000 ms)

Storage Configuration

• Storage Driver: localForage (IndexedDB > WebSQL > localStorage)
• Storage Name: 'LinAppCache'
• Store Name: 'authCache'

Error Handling

Common Scenarios

1. Expired Tokens: Automatically cleared from cache
2. Invalid Tokens: Removed from storage, user redirected to login
3. Storage Errors: Fallback to localStorage, clear cache
4. Network Issues: Offline mode with cached data

Error Recovery

• Automatic token refresh when possible
• Graceful degradation to localStorage
• Clear error messages for users

Performance Considerations

Optimization

• Asynchronous cache operations
• Efficient storage usage
• Minimal memory footprint
• Background cache cleanup

Monitoring

• Cache hit/miss logging
• Storage usage tracking
• Performance metrics collection

Future Enhancements

Planned Features

1. Biometric Authentication: Integration with device biometrics
2. Multi-device Support: Sync authentication across devices
3. Advanced Security: Two-factor authentication integration
4. Offline Mode: Full offline functionality with cached data

Scalability

• Distributed caching support
• Cache sharding for large datasets
• Performance optimization for high traffic

Testing

Unit Tests

• Cache service functionality
• Authentication flow testing
• Error handling scenarios

Integration Tests

• Frontend-backend integration
• Cache persistence testing
• Security validation

End-to-End Tests

• Complete authentication flow
• Remember me functionality
• Logout and session cleanup

Troubleshooting

Common Issues

1. Cache Not Working: Check localForage availability
2. Token Expiration: Verify TTL settings
3. Storage Errors: Clear browser cache and data
4. Authentication Issues: Verify backend configuration

Debug Mode

Enable development logging for detailed debugging:

// In development mode
if (import.meta.env.VITE_NODE_ENV === 'development') {
  console.log('🗃️ [Cache]', cacheOperation);
}

Conclusion

The cache system implementation provides a robust, secure, and user-friendly authentication experience with the "Remember Me" functionality. It combines modern web technologies with best practices to ensure both security and usability.

For questions or issues, please refer to the troubleshooting section or contact the development team.