Extend Firebase Service with Trend Operations

[Haydart]

Task 002: Firebase Service Extensions

Description

Extend SimpleFirebaseService with READ, WRITE, and WATCH methods for trend operations, including transaction-based duplicate prevention and real-time collection monitoring.

Acceptance Criteria

• Add POTENTIAL_TRENDS_COLLECTION = "potential_trends" constant
• Add CONFIRMED_TRENDS_COLLECTION = "confirmed_trends" constant
• Implement get_all_trends(include_potential=True, include_confirmed=True) READ method
• Implement find_trend_by_name(trend_name: str) READ method
• Implement watch_collection(collection_name: str, callback: Callable) for real-time updates (CRITICAL)
• Implement create_trend_with_retry(trend_name, trend_description, initial_memecoin, max_retries=3) WRITE method
• Implement _create_trend_transactional() with @firestore.transactional decorator
• Implement append_memecoin_to_trend(trend_id, memecoin, collection_name=None) using ArrayUnion and Increment
• Implement check_and_promote_trend(trend_id) for auto-promotion at threshold (5 memecoins)
• All methods properly async with error handling
• Transaction logic includes locked read → decision → atomic write pattern

Technical Details

• Location: src/services/simple_firebase_service.py

WATCH Method (NEW - CRITICAL):

• watch_collection(collection_name, callback) - Real-time collection monitoring
• Uses Firestore's on_snapshot() for push-based updates
• Callback fired on: ADD, MODIFY, DELETE events
• No polling, no TTL, always fresh data
• Pattern: collection_ref.on_snapshot(lambda snapshot: callback(self._parse_snapshot(snapshot)))

READ Methods:

• Use @firestore.transactional decorator for _create_trend_transactional
• Query by trend_name within transaction for duplicate check
• Return existing trend_id if duplicate found (no write)

WRITE Methods:

• Use ArrayUnion for atomic memecoin append
• Use Increment for atomic memecoin_count update
• Promotion threshold: env var TREND_PROMOTION_THRESHOLD (default 5)
• Move from potential_trends to confirmed_trends collection atomically

Effort Estimate

• Size: M
• Hours: 10-14 (increased for watch_collection implementation)
• Parallel: false (depends on Task 001 for models)