4.7 KiB

Raw Blame History

Architecture Decisions

This document records key architectural decisions made during the development of TimeSafari.

Platform Service Architecture: Mixins over Composables

Date: July 2, 2025
Status: Accepted
Context: Need for consistent platform service access across Vue components

Decision

Use Vue mixins for platform service access instead of Vue 3 Composition API composables.

Rationale

Why Mixins Were Chosen

Existing Architecture Consistency
- The entire codebase uses class-based components with vue-facing-decorator
- All components follow the established pattern of extending Vue class
- Mixins integrate seamlessly with the existing architecture
Performance Benefits
- Caching Layer: PlatformServiceMixin provides smart TTL-based caching
- Ultra-Concise Methods: Short methods like $db(), $exec(), $one() reduce boilerplate
- Settings Shortcuts: $saveSettings(), $saveMySettings() eliminate 90% of update boilerplate
- Memory Management: WeakMap-based caching prevents memory leaks
Developer Experience
- Familiar Pattern: Mixins are well-understood by the team
- Type Safety: Full TypeScript support with proper interfaces
- Error Handling: Centralized error handling across components
- Code Reduction: Reduces database code by up to 80%
Production Readiness
- Mature Implementation: PlatformServiceMixin is actively used and tested
- Comprehensive Features: Includes transaction support, cache management, settings shortcuts
- Security: Proper input validation and error handling

Why Composables Were Rejected

Architecture Mismatch
- Would require rewriting all components to use Composition API
- Breaks consistency with existing class-based component pattern
- Requires significant refactoring effort
Limited Features
- Basic platform service access without caching
- No settings management shortcuts
- No ultra-concise database methods
- Would require additional development to match mixin capabilities
Performance Considerations
- No built-in caching layer
- Would require manual implementation of performance optimizations
- More verbose for common operations

Implementation

Current Usage

// Component implementation
@Component({
  mixins: [PlatformServiceMixin],
})
export default class HomeView extends Vue {
  async mounted() {
    // Ultra-concise cached settings loading
    const settings = await this.$settings({
      apiServer: "",
      activeDid: "",
      isRegistered: false,
    });
    
    // Cached contacts loading
    this.allContacts = await this.$contacts();
    
    // Settings update with automatic cache invalidation
    await this.$saveMySettings({ isRegistered: true });
  }
}

Key Features

Cached Database Operations: $contacts(), $settings(), $accountSettings()
Settings Shortcuts: $saveSettings(), $saveMySettings(), $saveUserSettings()
Ultra-Concise Methods: $db(), $exec(), $one(), $query(), $first()
Cache Management: $refreshSettings(), $clearAllCaches()
Transaction Support: $withTransaction() with automatic rollback

Consequences

Positive

Consistent Architecture: All components follow the same pattern
High Performance: Smart caching reduces database calls by 80%+
Developer Productivity: Ultra-concise methods reduce boilerplate by 90%
Type Safety: Full TypeScript support with proper interfaces
Memory Safety: WeakMap-based caching prevents memory leaks

Negative

Vue 2 Pattern: Uses older mixin pattern instead of modern Composition API
Tight Coupling: Components are coupled to the mixin implementation
Testing Complexity: Mixins can make unit testing more complex

Future Considerations

Migration Path: If Vue 4 or future versions deprecate mixins, we may need to migrate
Performance Monitoring: Continue monitoring caching performance and adjust TTL values
Feature Expansion: Add new ultra-concise methods as needed
Testing Strategy: Develop comprehensive testing strategies for mixin-based components

This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.

4.7 KiB Raw Blame History