+
+
+
+ )
+}
+```
+
+**Deliverables:**
+- [ ] Back-End: Territory CRUD API
+- [ ] Back-End: PostGIS spatial queries
+- [ ] Front-End: Terra Draw integration
+- [ ] Front-End: Polygon/circle drawing modes
+- [ ] Front-End: Territory library UI
+- [ ] Front-End: Filter by territory
+- [ ] Testing: Spatial query accuracy
+
+---
+
+### Enhancement 4: Property Comparison View
+
+**Total Effort:** 3-4 days (24-32 hours)
+**Priority:** MEDIUM-HIGH
+**Dependencies:** Enhancement 1
+
+#### Back-End Requirements (20% of work - 5-6 hours)
+
+**API Endpoint:**
+```python
+@router.post("/properties/compare")
+async def compare_properties(
+ property_ids: List[UUID]
+):
+ """Get detailed comparison data for multiple properties"""
+
+ if len(property_ids) > 4:
+ raise HTTPException(400, "Maximum 4 properties for comparison")
+
+ # Fetch all properties with full product data
+ properties = await db.get_properties_with_products(property_ids)
+
+ # Calculate comparison metrics
+ comparison = {
+ 'properties': properties,
+ 'highlights': {
+ 'best_solar': max(properties, key=lambda p: p.solarfit.score),
+ 'worst_roof': min(properties, key=lambda p: roof_condition_score(p)),
+ 'lowest_cost': min(properties, key=lambda p: p.roofiq.cost_low)
+ }
+ }
+
+ return comparison
+```
+
+#### Front-End Requirements (80% of work - 19-26 hours)
+
+**Comparison UI:**
+```typescript
+// components/property/property-comparison.tsx
+export function PropertyComparison({ propertyIds }: { propertyIds: string[] }) {
+ const { data } = useCompareProperties(propertyIds)
+
+ return (
+ Draw Territory
+
+
+
+ {drawnTerritory && (
+
+ )}
+
+
+
+ )
+}
+```
+
+**Deliverables:**
+- [ ] Back-End: Comparison API endpoint
+- [ ] Front-End: Multi-select mode on map
+- [ ] Front-End: Comparison panel UI
+- [ ] Front-End: Highlight best/worst values
+- [ ] Front-End: PDF export
+
+---
+
+### Enhancement 8: Bulk Property Import
+
+**Total Effort:** 5-6 days (40-48 hours)
+**Priority:** MEDIUM
+**Dependencies:** Enhancement 1
+
+#### Back-End Requirements (65% of work - 26-31 hours)
+
+**File Upload Endpoint:**
+```python
+from fastapi import UploadFile
+
+@router.post("/properties/bulk-import")
+async def bulk_import_properties(
+ file: UploadFile,
+ background_tasks: BackgroundTasks
+):
+ """Upload CSV/Shapefile for bulk analysis"""
+
+ # Validate file type
+ if file.content_type not in ['text/csv', 'application/zip']:
+ raise HTTPException(400, "Only CSV and Shapefile supported")
+
+ # Save file temporarily
+ file_path = f"/tmp/{uuid4()}.{file.filename.split('.')[-1]}"
+ with open(file_path, 'wb') as f:
+ f.write(await file.read())
+
+ # Parse file
+ if file.content_type == 'text/csv':
+ addresses = parse_csv(file_path)
+ else:
+ geometries = parse_shapefile(file_path)
+
+ # Create background job
+ job_id = str(uuid4())
+ background_tasks.add_task(
+ process_bulk_import,
+ job_id=job_id,
+ addresses=addresses
+ )
+
+ return {'job_id': job_id, 'status': 'processing'}
+
+async def process_bulk_import(job_id: str, addresses: List[str]):
+ """Background task to geocode and analyze properties"""
+
+ total = len(addresses)
+ processed = 0
+
+ for address in addresses:
+ # Geocode
+ coords = await geocode_address(address)
+
+ # Check if property exists
+ property = await db.get_property_by_coords(coords)
+
+ if not property:
+ # Trigger analysis
+ property = await trigger_property_analysis(coords)
+
+ processed += 1
+
+ # Update progress
+ await cache.set(
+ f'bulk_import:{job_id}',
+ {'total': total, 'processed': processed},
+ expire=3600
+ )
+
+ await cache.set(f'bulk_import:{job_id}:complete', True, expire=3600)
+```
+
+**CSV Parsing:**
+```python
+import csv
+
+def parse_csv(file_path: str) -> List[str]:
+ """Parse CSV and extract addresses"""
+ addresses = []
+
+ with open(file_path, 'r') as f:
+ reader = csv.DictReader(f)
+
+ for row in reader:
+ # Flexible column detection
+ address = (
+ row.get('address') or
+ row.get('Address') or
+ row.get('street_address')
+ )
+ city = row.get('city') or row.get('City')
+ state = row.get('state') or row.get('State')
+ zip_code = row.get('zip') or row.get('Zip')
+
+ full_address = f"{address}, {city}, {state} {zip_code}"
+ addresses.append(full_address)
+
+ return addresses
+```
+
+#### Front-End Requirements (35% of work - 14-17 hours)
+
+**File Upload UI:**
+```typescript
+// components/import/bulk-import-dialog.tsx
+export function BulkImportDialog({ isOpen, onClose }: Props) {
+ const [file, setFile] = useState
+
+
+
+
+ Compare Properties
+ +
+ {data?.properties.map(property => (
+
+
+
+
+
+ ))}
+ {property.address}
+ +
+ p.roofiq.condition)}
+ highlightBest
+ />
+ p.solarfit.score)}
+ highlightBest
+ />
+ p.roofiq.cost_low)}
+ highlightBest={false}
+ />
+
+ 
-
-
-
-
-
-
-#### Videos
-
-Use the HTML video element for self-hosted video content:
-
-
-
-Embed YouTube videos using iframe elements:
-
-
-
-#### Tooltips
-
-Example of tooltip usage:
-
-
+
+
+
+ """)
+
+ return template.render(
+ search_name=search_name,
+ property_count=len(properties),
+ properties=properties,
+ search_id=search_id,
+ unsubscribe_token=unsubscribe_token,
+ base_url=settings.FRONTEND_URL,
+ app_name=settings.PROJECT_NAME
+ )
+
+ def _generate_alert_plain(self, search_name: str, properties: List[Dict[str, Any]]) -> str:
+ """Generate plain text email content for property alert"""
+ lines = [
+ f"New Properties Match Your Search: {search_name}",
+ "",
+ f"We found {len(properties)} new {'property' if len(properties) == 1 else 'properties'} matching your saved search:",
+ ""
+ ]
+
+ for prop in properties:
+ lines.append(f"- {prop['address']}")
+ lines.append(f" Type: {prop.get('property_type', 'N/A')}")
+ if prop.get('roofiq'):
+ lines.append(f" RoofIQ Score: {prop['roofiq']['score']}/100")
+ if prop.get('solarfit'):
+ lines.append(f" Solar Score: {prop['solarfit']['solar_score']}/100")
+ lines.append(f" View: {settings.FRONTEND_URL}/property/{prop['id']}")
+ lines.append("")
+
+ lines.extend([
+ f"View all results: {settings.FRONTEND_URL}/searches",
+ "",
+ f"You're receiving this email because you created a saved search on {settings.PROJECT_NAME}.",
+ f"Manage your email preferences: {settings.FRONTEND_URL}/settings/email"
+ ])
+
+ return "\n".join(lines)
+
+ async def send_test_alert(self, to_email: str, search_name: str) -> tuple[bool, Optional[str], Optional[str]]:
+ """Send a test alert email"""
+ try:
+ html_content = """
+
+
+
+
+
+ New Properties Match Your Search
+{{ search_name }}
+We found {{ property_count }} new {{ 'property' if property_count == 1 else 'properties' }} matching your saved search criteria:
+ + {% for property in properties %} +
+
+ {% endfor %}
+
+ {{ property.address }}
+
+
+ View Details
+ Type: {{ property.property_type }}
+ {% if property.roofiq %} +RoofIQ Score: {{ property.roofiq.score }}/100
+ {% endif %}
+ {% if property.solarfit %}
+ Solar Score: {{ property.solarfit.solar_score }}/100
+ {% endif %}
+ {% if property.drivewaypro %}
+ Driveway Score: {{ property.drivewaypro.condition_score }}/100
+ {% endif %}
+
+ View All Results
+
+
+
+ Test Alert
+This is a test alert for your saved search: {search_name}
+When properties match your search criteria, you'll receive an email similar to this with property details.
+ + + """.format(search_name=search_name) + + message = Mail( + from_email=self.from_email, + to_emails=To(to_email), + subject=f"Test Alert: {search_name}", + html_content=Content("text/html", html_content) + ) + + response = self.client.send(message) + + if response.status_code in [200, 202]: + message_id = response.headers.get('X-Message-Id') + return True, message_id, None + else: + return False, None, f"SendGrid returned status {response.status_code}" + + except Exception as e: + logger.error(f"Error sending test email: {str(e)}") + return False, None, str(e) + + +# Singleton instance +email_service = EmailService() diff --git a/backend/app/services/google_ads_service.py b/backend/app/services/google_ads_service.py new file mode 100644 index 0000000..f5d0a0d --- /dev/null +++ b/backend/app/services/google_ads_service.py @@ -0,0 +1,407 @@ +""" +Google Ads Service + +Service for integrating with Google Ads API and Customer Match. +""" +from typing import List, Dict, Any, Optional, Tuple +from datetime import datetime, timedelta +from google.ads.googleads.client import GoogleAdsClient +from google.ads.googleads.errors import GoogleAdsException +from google.auth.transport.requests import Request +from google.oauth2.credentials import Credentials +import hashlib +import logging + +from app.core.config import settings + +logger = logging.getLogger(__name__) + + +class GoogleAdsService: + """Service for Google Ads API interactions""" + + def __init__(self): + self.client_id = settings.GOOGLE_ADS_CLIENT_ID + self.client_secret = settings.GOOGLE_ADS_CLIENT_SECRET + self.developer_token = settings.GOOGLE_ADS_DEVELOPER_TOKEN + + def get_client( + self, + customer_id: str, + access_token: str, + refresh_token: str + ) -> GoogleAdsClient: + """ + Create Google Ads API client + + Args: + customer_id: Google Ads customer ID + access_token: OAuth access token + refresh_token: OAuth refresh token + + Returns: + Configured GoogleAdsClient + """ + credentials = Credentials( + token=access_token, + refresh_token=refresh_token, + client_id=self.client_id, + client_secret=self.client_secret, + token_uri="https://oauth2.googleapis.com/token" + ) + + config = { + "developer_token": self.developer_token, + "use_proto_plus": True, + "client_id": self.client_id, + "client_secret": self.client_secret, + "refresh_token": refresh_token, + "login_customer_id": customer_id, + } + + return GoogleAdsClient.load_from_dict(config) + + async def refresh_access_token( + self, + refresh_token: str + ) -> Tuple[str, datetime]: + """ + Refresh OAuth access token + + Args: + refresh_token: Refresh token + + Returns: + Tuple of (new_access_token, expires_at) + """ + try: + credentials = Credentials( + token=None, + refresh_token=refresh_token, + client_id=self.client_id, + client_secret=self.client_secret, + token_uri="https://oauth2.googleapis.com/token" + ) + + # Refresh the token + credentials.refresh(Request()) + + expires_at = datetime.utcnow() + timedelta(seconds=3600) # Usually 1 hour + + return credentials.token, expires_at + + except Exception as e: + logger.error(f"Failed to refresh access token: {str(e)}") + raise + + async def get_account_info( + self, + customer_id: str, + access_token: str, + refresh_token: str + ) -> Dict[str, Any]: + """ + Get Google Ads account information + + Args: + customer_id: Customer ID + access_token: Access token + refresh_token: Refresh token + + Returns: + Dict with account info + """ + try: + client = self.get_client(customer_id, access_token, refresh_token) + ga_service = client.get_service("GoogleAdsService") + + query = """ + SELECT + customer.id, + customer.descriptive_name, + customer.currency_code, + customer.time_zone + FROM customer + WHERE customer.id = '{customer_id}' + """.format(customer_id=customer_id) + + response = ga_service.search(customer_id=customer_id, query=query) + + for row in response: + return { + "customer_id": str(row.customer.id), + "account_name": row.customer.descriptive_name, + "currency_code": row.customer.currency_code, + "time_zone": row.customer.time_zone, + } + + raise ValueError(f"Customer {customer_id} not found") + + except GoogleAdsException as ex: + logger.error(f"Google Ads API error: {ex}") + raise + except Exception as e: + logger.error(f"Error getting account info: {str(e)}") + raise + + async def create_customer_match_user_list( + self, + customer_id: str, + access_token: str, + refresh_token: str, + name: str, + description: str = "", + membership_lifespan_days: int = 10000 + ) -> Tuple[str, str]: + """ + Create a Customer Match user list + + Args: + customer_id: Google Ads customer ID + access_token: OAuth access token + refresh_token: OAuth refresh token + name: User list name + description: User list description + membership_lifespan_days: How long users stay in list (max 10000) + + Returns: + Tuple of (resource_name, user_list_id) + """ + try: + client = self.get_client(customer_id, access_token, refresh_token) + user_list_service = client.get_service("UserListService") + + # Create user list operation + user_list_operation = client.get_type("UserListOperation") + user_list = user_list_operation.create + + user_list.name = name + user_list.description = description + user_list.membership_status = client.enums.UserListMembershipStatusEnum.OPEN + user_list.membership_life_span = membership_lifespan_days + + # Set as Customer Match list + user_list.crm_based_user_list.upload_key_type = ( + client.enums.CustomerMatchUploadKeyTypeEnum.CONTACT_INFO + ) + + # Create the user list + response = user_list_service.mutate_user_lists( + customer_id=customer_id, + operations=[user_list_operation] + ) + + resource_name = response.results[0].resource_name + user_list_id = resource_name.split("/")[-1] + + logger.info(f"Created user list: {resource_name}") + + return resource_name, user_list_id + + except GoogleAdsException as ex: + logger.error(f"Failed to create user list: {ex}") + for error in ex.failure.errors: + logger.error(f"Error: {error.message}") + raise + except Exception as e: + logger.error(f"Error creating user list: {str(e)}") + raise + + def _hash_email(self, email: str) -> str: + """Hash email for Customer Match (SHA256)""" + return hashlib.sha256(email.lower().strip().encode()).hexdigest() + + def _hash_phone(self, phone: str) -> str: + """Hash phone number for Customer Match (E.164 format, SHA256)""" + # Remove all non-digit characters + phone = ''.join(filter(str.isdigit, phone)) + # Add + prefix if not present + if not phone.startswith('+'): + phone = '+' + phone + return hashlib.sha256(phone.encode()).hexdigest() + + async def upload_customer_match_data( + self, + customer_id: str, + access_token: str, + refresh_token: str, + user_list_resource_name: str, + contacts: List[Dict[str, str]] + ) -> Dict[str, int]: + """ + Upload contact data to Customer Match user list + + Args: + customer_id: Google Ads customer ID + access_token: OAuth access token + refresh_token: OAuth refresh token + user_list_resource_name: User list resource name + contacts: List of contact dicts with 'email' and/or 'phone' + + Returns: + Dict with upload statistics + """ + try: + client = self.get_client(customer_id, access_token, refresh_token) + offline_user_data_job_service = client.get_service( + "OfflineUserDataJobService" + ) + + # Create offline user data job + job = client.get_type("OfflineUserDataJob") + job.type_ = client.enums.OfflineUserDataJobTypeEnum.CUSTOMER_MATCH_USER_LIST + job.customer_match_user_list_metadata.user_list = user_list_resource_name + + # Create the job + response = offline_user_data_job_service.create_offline_user_data_job( + customer_id=customer_id, + job=job + ) + + job_resource_name = response.resource_name + logger.info(f"Created offline user data job: {job_resource_name}") + + # Prepare operations (batch of contacts) + operations = [] + for contact in contacts: + operation = client.get_type("OfflineUserDataJobOperation") + user_data = operation.create + + # Add user identifiers + user_identifier_list = [] + + if contact.get("email"): + email_identifier = client.get_type("UserIdentifier") + email_identifier.hashed_email = self._hash_email(contact["email"]) + user_identifier_list.append(email_identifier) + + if contact.get("phone"): + phone_identifier = client.get_type("UserIdentifier") + phone_identifier.hashed_phone_number = self._hash_phone( + contact["phone"] + ) + user_identifier_list.append(phone_identifier) + + # Add address data if provided + if any(k in contact for k in ["first_name", "last_name", "country_code", "zip_code"]): + address_identifier = client.get_type("UserIdentifier") + address_info = address_identifier.address_info + + if contact.get("first_name"): + address_info.hashed_first_name = hashlib.sha256( + contact["first_name"].lower().strip().encode() + ).hexdigest() + + if contact.get("last_name"): + address_info.hashed_last_name = hashlib.sha256( + contact["last_name"].lower().strip().encode() + ).hexdigest() + + if contact.get("country_code"): + address_info.country_code = contact["country_code"] + + if contact.get("zip_code"): + address_info.postal_code = contact["zip_code"] + + user_identifier_list.append(address_identifier) + + user_data.user_identifiers.extend(user_identifier_list) + operations.append(operation) + + # Upload data in batches (API limit is 100k per request) + batch_size = 10000 + total_uploaded = 0 + + for i in range(0, len(operations), batch_size): + batch = operations[i:i + batch_size] + + offline_user_data_job_service.add_offline_user_data_job_operations( + resource_name=job_resource_name, + operations=batch, + enable_partial_failure=True + ) + + total_uploaded += len(batch) + logger.info(f"Uploaded batch {i // batch_size + 1}: {len(batch)} contacts") + + # Run the job + offline_user_data_job_service.run_offline_user_data_job( + resource_name=job_resource_name + ) + + logger.info(f"Started offline user data job: {job_resource_name}") + + return { + "total_uploaded": total_uploaded, + "job_resource_name": job_resource_name, + } + + except GoogleAdsException as ex: + logger.error(f"Failed to upload customer match data: {ex}") + for error in ex.failure.errors: + logger.error(f"Error: {error.message}") + raise + except Exception as e: + logger.error(f"Error uploading data: {str(e)}") + raise + + async def get_user_list_stats( + self, + customer_id: str, + access_token: str, + refresh_token: str, + user_list_resource_name: str + ) -> Dict[str, int]: + """ + Get statistics for a user list + + Args: + customer_id: Customer ID + access_token: Access token + refresh_token: Refresh token + user_list_resource_name: User list resource name + + Returns: + Dict with size_for_display and other stats + """ + try: + client = self.get_client(customer_id, access_token, refresh_token) + ga_service = client.get_service("GoogleAdsService") + + query = f""" + SELECT + user_list.id, + user_list.name, + user_list.size_for_display, + user_list.size_for_search, + user_list.match_rate_percentage + FROM user_list + WHERE user_list.resource_name = '{user_list_resource_name}' + """ + + response = ga_service.search(customer_id=customer_id, query=query) + + for row in response: + return { + "size_for_display": row.user_list.size_for_display, + "size_for_search": row.user_list.size_for_search, + "match_rate_percentage": row.user_list.match_rate_percentage, + } + + return { + "size_for_display": 0, + "size_for_search": 0, + "match_rate_percentage": 0, + } + + except Exception as e: + logger.error(f"Error getting user list stats: {str(e)}") + return { + "size_for_display": 0, + "size_for_search": 0, + "match_rate_percentage": 0, + } + + +# Singleton instance +google_ads_service = GoogleAdsService() diff --git a/backend/app/tasks/__init__.py b/backend/app/tasks/__init__.py new file mode 100644 index 0000000..0b97e37 --- /dev/null +++ b/backend/app/tasks/__init__.py @@ -0,0 +1 @@ +# Tasks package diff --git a/backend/app/tasks/alert_tasks.py b/backend/app/tasks/alert_tasks.py new file mode 100644 index 0000000..9ec4306 --- /dev/null +++ b/backend/app/tasks/alert_tasks.py @@ -0,0 +1,358 @@ +""" +Alert Tasks + +Celery tasks for processing saved search alerts. +""" +from datetime import datetime, timedelta +from typing import List, Dict, Any +from sqlalchemy import select, and_, or_ +from sqlalchemy.orm import joinedload +import logging + +from app.tasks.celery_app import celery_app +from app.core.database import AsyncSessionLocal +from app.models.saved_search import SavedSearch, SearchAlert, AlertFrequency +from app.models.property import Property +from app.services.email_service import email_service +from app.core.cache import cache + +logger = logging.getLogger(__name__) + + +@celery_app.task(name="app.tasks.alert_tasks.check_instant_alerts") +def check_instant_alerts(): + """Check and process instant alerts (every 5 minutes)""" + import asyncio + return asyncio.run(_check_instant_alerts()) + + +async def _check_instant_alerts(): + """Async implementation of instant alert checking""" + async with AsyncSessionLocal() as session: + try: + # Get all active saved searches with instant alerts + query = select(SavedSearch).where( + and_( + SavedSearch.is_active == True, + SavedSearch.alerts_enabled == True, + SavedSearch.alert_frequency == AlertFrequency.INSTANT + ) + ) + result = await session.execute(query) + searches = result.scalars().all() + + logger.info(f"Checking {len(searches)} instant alert searches") + + for search in searches: + await _process_search_alert(session, search) + + await session.commit() + return {"processed": len(searches)} + + except Exception as e: + logger.error(f"Error checking instant alerts: {str(e)}") + await session.rollback() + raise + + +@celery_app.task(name="app.tasks.alert_tasks.process_daily_alerts") +def process_daily_alerts(): + """Process daily alerts at configured times""" + import asyncio + return asyncio.run(_process_daily_alerts()) + + +async def _process_daily_alerts(): + """Async implementation of daily alert processing""" + async with AsyncSessionLocal() as session: + try: + current_hour = datetime.utcnow().hour + + # Get saved searches with daily alerts scheduled for this hour + query = select(SavedSearch).where( + and_( + SavedSearch.is_active == True, + SavedSearch.alerts_enabled == True, + SavedSearch.alert_frequency == AlertFrequency.DAILY, + SavedSearch.alert_time == current_hour + ) + ) + result = await session.execute(query) + searches = result.scalars().all() + + logger.info(f"Processing {len(searches)} daily alerts for hour {current_hour}") + + for search in searches: + await _process_search_alert(session, search) + + await session.commit() + return {"processed": len(searches), "hour": current_hour} + + except Exception as e: + logger.error(f"Error processing daily alerts: {str(e)}") + await session.rollback() + raise + + +@celery_app.task(name="app.tasks.alert_tasks.process_weekly_alerts") +def process_weekly_alerts(): + """Process weekly alerts on configured day""" + import asyncio + return asyncio.run(_process_weekly_alerts()) + + +async def _process_weekly_alerts(): + """Async implementation of weekly alert processing""" + async with AsyncSessionLocal() as session: + try: + current_day = datetime.utcnow().weekday() # 0=Monday + current_hour = datetime.utcnow().hour + + # Get saved searches with weekly alerts for this day/hour + query = select(SavedSearch).where( + and_( + SavedSearch.is_active == True, + SavedSearch.alerts_enabled == True, + SavedSearch.alert_frequency == AlertFrequency.WEEKLY, + SavedSearch.alert_day == current_day, + SavedSearch.alert_time == current_hour + ) + ) + result = await session.execute(query) + searches = result.scalars().all() + + logger.info(f"Processing {len(searches)} weekly alerts for day {current_day}") + + for search in searches: + await _process_search_alert(session, search) + + await session.commit() + return {"processed": len(searches), "day": current_day} + + except Exception as e: + logger.error(f"Error processing weekly alerts: {str(e)}") + await session.rollback() + raise + + +@celery_app.task(name="app.tasks.alert_tasks.process_monthly_alerts") +def process_monthly_alerts(): + """Process monthly alerts on configured day""" + import asyncio + return asyncio.run(_process_monthly_alerts()) + + +async def _process_monthly_alerts(): + """Async implementation of monthly alert processing""" + async with AsyncSessionLocal() as session: + try: + current_day = datetime.utcnow().day + current_hour = datetime.utcnow().hour + + # Get saved searches with monthly alerts for this day/hour + query = select(SavedSearch).where( + and_( + SavedSearch.is_active == True, + SavedSearch.alerts_enabled == True, + SavedSearch.alert_frequency == AlertFrequency.MONTHLY, + SavedSearch.alert_day == current_day, + SavedSearch.alert_time == current_hour + ) + ) + result = await session.execute(query) + searches = result.scalars().all() + + logger.info(f"Processing {len(searches)} monthly alerts for day {current_day}") + + for search in searches: + await _process_search_alert(session, search) + + await session.commit() + return {"processed": len(searches), "day": current_day} + + except Exception as e: + logger.error(f"Error processing monthly alerts: {str(e)}") + await session.rollback() + raise + + +async def _process_search_alert(session, search: SavedSearch): + """ + Process a single saved search alert + + Args: + session: Database session + search: SavedSearch instance to process + """ + try: + # Build property query from saved search filters + filters = search.filters + query = select(Property).options( + joinedload(Property.roofiq), + joinedload(Property.solarfit), + joinedload(Property.drivewaypro), + joinedload(Property.permitscope) + ) + + # Apply filters + conditions = [] + + # Location filters + if filters.get('city'): + conditions.append(Property.city == filters['city']) + if filters.get('state'): + conditions.append(Property.state == filters['state']) + if filters.get('zip_code'): + conditions.append(Property.zip_code == filters['zip_code']) + + # Bounding box filter + if filters.get('bounds'): + west, south, east, north = filters['bounds'] + conditions.append(and_( + Property.longitude >= west, + Property.longitude <= east, + Property.latitude >= south, + Property.latitude <= north + )) + + # Property type filter + if filters.get('property_type'): + conditions.append(Property.property_type.in_(filters['property_type'])) + + # Only get properties updated since last check + if search.last_checked_at: + conditions.append(Property.updated_at > search.last_checked_at) + + if conditions: + query = query.where(and_(*conditions)) + + # Execute query + result = await session.execute(query) + properties = result.unique().scalars().all() + + if not properties: + logger.info(f"No new properties found for search {search.id}") + search.last_checked_at = datetime.utcnow() + search.new_matches_since_last_alert = 0 + return + + # Prepare property data for email + property_data = [] + property_ids = [] + for prop in properties: + property_ids.append(str(prop.id)) + prop_dict = { + 'id': str(prop.id), + 'address': prop.address, + 'property_type': prop.property_type.value if prop.property_type else 'N/A', + } + if prop.roofiq: + prop_dict['roofiq'] = {'score': prop.roofiq.score} + if prop.solarfit: + prop_dict['solarfit'] = {'solar_score': prop.solarfit.solar_score} + if prop.drivewaypro: + prop_dict['drivewaypro'] = {'condition_score': prop.drivewaypro.condition_score} + + property_data.append(prop_dict) + + # Send email alert + success, message_id, error_msg = await email_service.send_property_alert( + to_email=search.alert_email, + search_name=search.name, + properties=property_data, + search_id=str(search.id), + unsubscribe_token=None # TODO: Get from user preferences + ) + + # Create alert record + alert = SearchAlert( + saved_search_id=search.id, + property_count=len(properties), + property_ids=property_ids, + email_sent=success, + sendgrid_message_id=message_id, + error_message=error_msg + ) + session.add(alert) + + # Update search statistics + search.last_checked_at = datetime.utcnow() + search.total_matches += len(properties) + search.new_matches_since_last_alert = len(properties) + + logger.info(f"Processed alert for search {search.id}: {len(properties)} properties, email_sent={success}") + + except Exception as e: + logger.error(f"Error processing search alert {search.id}: {str(e)}") + raise + + +@celery_app.task(name="app.tasks.alert_tasks.cleanup_old_alerts") +def cleanup_old_alerts(): + """Cleanup alert history older than 90 days""" + import asyncio + return asyncio.run(_cleanup_old_alerts()) + + +async def _cleanup_old_alerts(): + """Async implementation of alert cleanup""" + async with AsyncSessionLocal() as session: + try: + cutoff_date = datetime.utcnow() - timedelta(days=90) + + # Delete old alerts + from sqlalchemy import delete + stmt = delete(SearchAlert).where(SearchAlert.sent_at < cutoff_date) + result = await session.execute(stmt) + await session.commit() + + deleted_count = result.rowcount + logger.info(f"Cleaned up {deleted_count} old alerts") + + return {"deleted": deleted_count} + + except Exception as e: + logger.error(f"Error cleaning up old alerts: {str(e)}") + await session.rollback() + raise + + +@celery_app.task(name="app.tasks.alert_tasks.send_test_alert") +def send_test_alert(search_id: str, recipient_email: str = None): + """Send a test alert for a saved search""" + import asyncio + return asyncio.run(_send_test_alert(search_id, recipient_email)) + + +async def _send_test_alert(search_id: str, recipient_email: str = None): + """Async implementation of test alert""" + async with AsyncSessionLocal() as session: + try: + from uuid import UUID + + # Get saved search + query = select(SavedSearch).where(SavedSearch.id == UUID(search_id)) + result = await session.execute(query) + search = result.scalar_one_or_none() + + if not search: + return {"success": False, "error": "Search not found"} + + # Use provided email or search's configured email + email = recipient_email or search.alert_email + + # Send test email + success, message_id, error_msg = await email_service.send_test_alert( + to_email=email, + search_name=search.name + ) + + return { + "success": success, + "message_id": message_id, + "error": error_msg + } + + except Exception as e: + logger.error(f"Error sending test alert: {str(e)}") + return {"success": False, "error": str(e)} diff --git a/backend/app/tasks/celery_app.py b/backend/app/tasks/celery_app.py new file mode 100644 index 0000000..2016dde --- /dev/null +++ b/backend/app/tasks/celery_app.py @@ -0,0 +1,66 @@ +""" +Celery Application + +Background task queue configuration for processing saved search alerts. +""" +from celery import Celery +from celery.schedules import crontab +from app.core.config import settings + +# Create Celery app +celery_app = Celery( + "evoteli_tasks", + broker=settings.CELERY_BROKER_URL, + backend=settings.CELERY_RESULT_BACKEND +) + +# Celery configuration +celery_app.conf.update( + task_serializer="json", + accept_content=["json"], + result_serializer="json", + timezone="UTC", + enable_utc=True, + task_track_started=True, + task_time_limit=300, # 5 minutes + task_soft_time_limit=240, # 4 minutes + worker_prefetch_multiplier=4, + worker_max_tasks_per_child=1000, +) + +# Periodic task schedule +celery_app.conf.beat_schedule = { + # Check instant alerts every 5 minutes + "check-instant-alerts": { + "task": "app.tasks.alert_tasks.check_instant_alerts", + "schedule": crontab(minute="*/5"), + }, + # Process daily alerts at configured times (hourly check) + "process-daily-alerts": { + "task": "app.tasks.alert_tasks.process_daily_alerts", + "schedule": crontab(minute=0), # Every hour + }, + # Process weekly alerts on Monday at 9 AM UTC + "process-weekly-alerts": { + "task": "app.tasks.alert_tasks.process_weekly_alerts", + "schedule": crontab(hour=9, minute=0, day_of_week=1), + }, + # Process monthly alerts on 1st of month at 9 AM UTC + "process-monthly-alerts": { + "task": "app.tasks.alert_tasks.process_monthly_alerts", + "schedule": crontab(hour=9, minute=0, day_of_month=1), + }, + # Cleanup old alerts (keep last 90 days) + "cleanup-old-alerts": { + "task": "app.tasks.alert_tasks.cleanup_old_alerts", + "schedule": crontab(hour=2, minute=0), # Daily at 2 AM UTC + }, + # Process Google Ads auto-sync audiences every hour + "process-auto-sync-audiences": { + "task": "app.tasks.google_ads_tasks.process_auto_sync_audiences", + "schedule": crontab(minute=0), # Every hour + }, +} + +# Auto-discover tasks +celery_app.autodiscover_tasks(["app.tasks"]) diff --git a/backend/app/tasks/google_ads_tasks.py b/backend/app/tasks/google_ads_tasks.py new file mode 100644 index 0000000..d46d482 --- /dev/null +++ b/backend/app/tasks/google_ads_tasks.py @@ -0,0 +1,306 @@ +""" +Google Ads Background Tasks + +Celery tasks for syncing audiences to Google Ads Customer Match. +""" +from datetime import datetime, timedelta +from typing import Optional +from sqlalchemy import select, and_ +from sqlalchemy.orm import joinedload +import logging + +from app.tasks.celery_app import celery_app +from app.core.database import AsyncSessionLocal +from app.models.google_ads import ( + GoogleAdsAccount, + CustomerMatchAudience, + AudienceSyncHistory, + AudienceSyncStatus, +) +from app.models.property import Property +from app.services.google_ads_service import google_ads_service + +logger = logging.getLogger(__name__) + + +@celery_app.task(name="app.tasks.google_ads_tasks.sync_audience_to_google_ads") +def sync_audience_to_google_ads(audience_id: str, sync_id: Optional[str] = None): + """Sync audience to Google Ads Customer Match""" + import asyncio + return asyncio.run(_sync_audience_to_google_ads(audience_id, sync_id)) + + +async def _sync_audience_to_google_ads(audience_id: str, sync_id: Optional[str] = None): + """Async implementation of audience sync""" + async with AsyncSessionLocal() as session: + try: + from uuid import UUID + + # Get audience with account + query = ( + select(CustomerMatchAudience) + .where(CustomerMatchAudience.id == UUID(audience_id)) + .options(joinedload(CustomerMatchAudience.google_ads_account)) + ) + result = await session.execute(query) + audience = result.unique().scalar_one_or_none() + + if not audience: + logger.error(f"Audience {audience_id} not found") + return {"success": False, "error": "Audience not found"} + + account = audience.google_ads_account + + # Create or get sync record + if sync_id: + sync_query = select(AudienceSyncHistory).where( + AudienceSyncHistory.id == UUID(sync_id) + ) + sync_result = await session.execute(sync_query) + sync_record = sync_result.scalar_one_or_none() + else: + sync_record = AudienceSyncHistory( + audience_id=UUID(audience_id), + status=AudienceSyncStatus.PENDING, + triggered_by="auto_sync", + ) + session.add(sync_record) + await session.commit() + await session.refresh(sync_record) + + # Update status to in progress + sync_record.status = AudienceSyncStatus.IN_PROGRESS + audience.sync_status = AudienceSyncStatus.IN_PROGRESS + await session.commit() + + # Refresh access token if needed + if account.token_expires_at and account.token_expires_at < datetime.utcnow(): + try: + new_token, expires_at = await google_ads_service.refresh_access_token( + account.refresh_token + ) + account.access_token = new_token + account.token_expires_at = expires_at + await session.commit() + except Exception as e: + logger.error(f"Failed to refresh token: {str(e)}") + raise + + # Create user list in Google Ads if not exists + if not audience.user_list_resource_name: + try: + resource_name, user_list_id = await google_ads_service.create_customer_match_user_list( + customer_id=account.customer_id, + access_token=account.access_token, + refresh_token=account.refresh_token, + name=audience.name, + description=audience.description or "", + ) + + audience.user_list_resource_name = resource_name + audience.user_list_id = user_list_id + await session.commit() + + logger.info(f"Created user list {resource_name} for audience {audience_id}") + + except Exception as e: + logger.error(f"Failed to create user list: {str(e)}") + raise + + # Query properties based on filters + filters = audience.property_filters + prop_query = select(Property).options( + joinedload(Property.roofiq), + joinedload(Property.solarfit), + joinedload(Property.drivewaypro), + joinedload(Property.permitscope), + ) + + # Apply filters + conditions = [] + + if filters.get("city"): + conditions.append(Property.city == filters["city"]) + if filters.get("state"): + conditions.append(Property.state == filters["state"]) + if filters.get("zip_code"): + conditions.append(Property.zip_code == filters["zip_code"]) + + if filters.get("bounds"): + west, south, east, north = filters["bounds"] + conditions.append( + and_( + Property.longitude >= west, + Property.longitude <= east, + Property.latitude >= south, + Property.latitude <= north, + ) + ) + + if filters.get("property_type"): + conditions.append(Property.property_type.in_(filters["property_type"])) + + if conditions: + prop_query = prop_query.where(and_(*conditions)) + + # Limit to avoid memory issues + prop_query = prop_query.limit(50000) + + prop_result = await session.execute(prop_query) + properties = prop_result.unique().scalars().all() + + sync_record.properties_processed = len(properties) + audience.total_properties = len(properties) + + # Extract contact data + contacts = [] + seen_contacts = set() + + for prop in properties: + # Extract email and phone if available + # In production, these would come from property owner data + # For now, we'll generate sample data based on property ID + contact_key = f"{prop.id}" + + if contact_key not in seen_contacts: + seen_contacts.add(contact_key) + + contact = {} + + # In production, get from property.owner_email, property.owner_phone + # For demo, we'll skip actual contact upload + if prop.address: + # Generate demo email from address + email_local = prop.address.lower().replace(" ", ".")[:20] + contact["email"] = f"{email_local}@example.com" + + if prop.zip_code: + contact["zip_code"] = prop.zip_code + contact["country_code"] = "US" + + if contact.get("email"): + contacts.append(contact) + + sync_record.contacts_uploaded = len(contacts) + audience.total_contacts = len(contacts) + + # Upload contacts to Google Ads + if contacts: + try: + upload_result = await google_ads_service.upload_customer_match_data( + customer_id=account.customer_id, + access_token=account.access_token, + refresh_token=account.refresh_token, + user_list_resource_name=audience.user_list_resource_name, + contacts=contacts, + ) + + audience.uploaded_count = upload_result["total_uploaded"] + sync_record.contacts_uploaded = upload_result["total_uploaded"] + + logger.info( + f"Uploaded {upload_result['total_uploaded']} contacts for audience {audience_id}" + ) + + except Exception as e: + logger.error(f"Failed to upload contacts: {str(e)}") + raise + + # Wait a bit then get stats from Google Ads + import asyncio + await asyncio.sleep(5) + + try: + stats = await google_ads_service.get_user_list_stats( + customer_id=account.customer_id, + access_token=account.access_token, + refresh_token=account.refresh_token, + user_list_resource_name=audience.user_list_resource_name, + ) + + audience.matched_count = stats.get("size_for_display", 0) + audience.match_rate = stats.get("match_rate_percentage", 0) + sync_record.contacts_matched = stats.get("size_for_display", 0) + + except Exception as e: + logger.warning(f"Failed to get user list stats: {str(e)}") + + # Update sync record + sync_record.status = AudienceSyncStatus.COMPLETED + sync_record.completed_at = datetime.utcnow() + + # Update audience + audience.sync_status = AudienceSyncStatus.COMPLETED + audience.last_sync_at = datetime.utcnow() + + if audience.auto_sync_enabled: + audience.next_sync_at = datetime.utcnow() + timedelta( + hours=audience.sync_frequency_hours + ) + + # Update account last sync + account.last_sync_at = datetime.utcnow() + + await session.commit() + + logger.info(f"Successfully synced audience {audience_id}") + + return { + "success": True, + "audience_id": str(audience_id), + "contacts_uploaded": audience.uploaded_count, + "contacts_matched": audience.matched_count, + "match_rate": audience.match_rate, + } + + except Exception as e: + logger.error(f"Error syncing audience {audience_id}: {str(e)}") + + # Update sync record with error + if sync_record: + sync_record.status = AudienceSyncStatus.FAILED + sync_record.error_message = str(e) + sync_record.completed_at = datetime.utcnow() + + # Update audience + if audience: + audience.sync_status = AudienceSyncStatus.FAILED + audience.last_error = str(e) + + await session.commit() + + return {"success": False, "error": str(e)} + + +@celery_app.task(name="app.tasks.google_ads_tasks.process_auto_sync_audiences") +def process_auto_sync_audiences(): + """Process audiences with auto-sync enabled""" + import asyncio + return asyncio.run(_process_auto_sync_audiences()) + + +async def _process_auto_sync_audiences(): + """Async implementation of auto-sync processing""" + async with AsyncSessionLocal() as session: + try: + # Get audiences due for sync + query = select(CustomerMatchAudience).where( + and_( + CustomerMatchAudience.auto_sync_enabled == True, + CustomerMatchAudience.next_sync_at <= datetime.utcnow(), + ) + ) + result = await session.execute(query) + audiences = result.scalars().all() + + logger.info(f"Processing {len(audiences)} audiences for auto-sync") + + for audience in audiences: + # Queue sync task + sync_audience_to_google_ads.delay(str(audience.id)) + + return {"processed": len(audiences)} + + except Exception as e: + logger.error(f"Error processing auto-sync audiences: {str(e)}") + raise diff --git a/backend/requirements.txt b/backend/requirements.txt new file mode 100644 index 0000000..4e712d1 --- /dev/null +++ b/backend/requirements.txt @@ -0,0 +1,51 @@ +# FastAPI and server +fastapi==0.109.0 +uvicorn[standard]==0.27.0 +python-multipart==0.0.6 + +# Database +sqlalchemy==2.0.25 +asyncpg==0.29.0 +alembic==1.13.1 +geoalchemy2==0.14.3 + +# Caching +redis==5.0.1 +hiredis==2.3.2 + +# Authentication +python-jose[cryptography]==3.3.0 +passlib[bcrypt]==1.7.4 +python-multipart==0.0.6 + +# Email +sendgrid==6.11.0 +jinja2==3.1.3 + +# Google Ads +google-ads==23.1.0 +google-auth==2.27.0 +google-auth-oauthlib==1.2.0 +google-auth-httplib2==0.2.0 + +# Utilities +pydantic==2.5.3 +pydantic-settings==2.1.0 +python-dotenv==1.0.0 +httpx==0.26.0 +tenacity==8.2.3 + +# File processing +pandas==2.1.4 +openpyxl==3.1.2 + +# Task queue +celery==5.3.6 +flower==2.0.1 + +# Development +pytest==7.4.4 +pytest-asyncio==0.23.3 +black==24.1.1 +ruff==0.1.14 +mypy==1.8.0 diff --git a/commercial-safe-stack.mdx b/commercial-safe-stack.mdx new file mode 100644 index 0000000..eec8d1b --- /dev/null +++ b/commercial-safe-stack.mdx @@ -0,0 +1,487 @@ +--- +title: "Commercial-Safe Tech Stack" +description: "100% permissively-licensed technology stack for commercial SaaS products" +--- + +## Overview + +This is the **fully commercial-safe** technology stack using **only permissive licenses** (MIT, Apache 2.0, BSD). All AGPL/GPL/proprietary components have been replaced with battle-tested alternatives. + +**Legal Status:** ✅ Zero licensing risk for commercial SaaS +**Cost Impact:** $0 additional cost vs. original stack +**Migration Effort:** Minimal (drop-in replacements) + +--- + +## Complete Stack Summary + +| Layer | Component | License | Replacement For | +|-------|-----------|---------|-----------------| +| **Frontend** | React + TypeScript | MIT | - | +| **Map** | MapLibre GL JS | BSD 3-Clause | Google Maps | +| **Tiles** | Protomaps | BSD 3-Clause | Mapbox | +| **UI** | shadcn/ui | MIT | Material-UI | +| **API** | FastAPI | MIT | - | +| **Time-Series DB** | ClickHouse | Apache 2.0 | InfluxDB | +| **Geospatial DB** | PostGIS | PostgreSQL + GPL w/ exception | - | +| **Cache** | **Valkey** | BSD 3-Clause | Redis 7.x | +| **Object Storage** | **SeaweedFS** | Apache 2.0 | MinIO | +| **Detection** | **PP-YOLOE** | Apache 2.0 | YOLO11 | +| **Tracking** | ByteTrack | MIT | - | +| **Message Queue** | Apache Kafka | Apache 2.0 | - | +| **Stream Processing** | Apache Flink | Apache 2.0 | - | +| **Batch** | Apache Airflow | Apache 2.0 | - | +| **Dashboards** | **Apache Superset** | Apache 2.0 | Grafana | +| **Logging** | **OpenSearch** | Apache 2.0 | Loki | +| **Metrics** | Prometheus | Apache 2.0 | - | +| **Tracing** | Jaeger | Apache 2.0 | - | +| **Auth** | Keycloak | Apache 2.0 | - | + +--- + +## Critical Replacements Explained + +### 1. Object Detection: PP-YOLOE (Apache 2.0) + +**Replaces:** YOLO11 (AGPL v3) + +**Why PP-YOLOE:** +- ✅ **Better accuracy:** 48.9% AP vs 47.3% for YOLOv5 +- ✅ **Apache 2.0 license:** Fully commercial-safe +- ✅ **Production-ready:** Used by Baidu PaddlePaddle +- ✅ **Active development:** Regular updates + +**Installation:** +```bash +pip install paddlepaddle-gpu paddledet +``` + +**Inference:** +```python +from ppdet.engine import Trainer +from ppdet.core.workspace import load_config + +config = load_config('configs/ppyoloe/ppyoloe_crn_l_300e_coco.yml') +trainer = Trainer(config, mode='test') +trainer.load_weights('ppyoloe_crn_l_300e_coco.pdparams') + +# Inference +result = trainer.predict(images=['image.jpg']) +``` + +**Performance:** +- **Speed:** 78 FPS on V100 GPU +- **Accuracy:** 51.4% AP (large model) +- **Edge deployment:** ONNX export for Jetson + +**Alternative:** YOLOX (Apache 2.0, 47.3% AP, slightly faster) + +--- + +### 2. Cache: Valkey (BSD 3-Clause) + +**Replaces:** Redis 7.x (SSPL/RSALv2) + +**Why Valkey:** +- ✅ **Drop-in replacement:** 100% Redis 6.2 API compatible +- ✅ **Linux Foundation project:** Backed by AWS, Google, Oracle +- ✅ **BSD 3-Clause:** No commercial restrictions +- ✅ **Active development:** Monthly releases + +**Installation:** +```bash +# Docker +docker run -d --name valkey -p 6379:6379 valkey/valkey:latest + +# Or build from source +git clone https://github.com/valkey-io/valkey +cd valkey +make +make install +``` + +**Usage:** +```python +import valkey # Uses redis-py client + +r = valkey.Valkey(host='localhost', port=6379) +r.set('key', 'value') +r.get('key') # Returns b'value' +``` + +**Migration from Redis:** +- Zero code changes (same API) +- Compatible with redis-py, go-redis, ioredis +- Supports Redis 6.2 commands + +**Alternative:** KeyDB (BSD 3-Clause, multi-threaded, faster) + +--- + +### 3. Object Storage: SeaweedFS (Apache 2.0) + +**Replaces:** MinIO (AGPL v3) + +**Why SeaweedFS:** +- ✅ **S3-compatible API:** Drop-in replacement +- ✅ **Better performance:** Faster for small files +- ✅ **Apache 2.0:** Fully commercial-safe +- ✅ **Distributed:** Scales to billions of files + +**Installation:** +```bash +# Download binary +wget https://github.com/seaweedfs/seaweedfs/releases/download/3.60/linux_amd64.tar.gz +tar -xzf linux_amd64.tar.gz + +# Start master server +./weed master -defaultReplication=001 + +# Start volume server +./weed volume -mserver=localhost:9333 -port=8080 +``` + +**S3 Gateway:** +```bash +./weed s3 -filer=localhost:8888 +``` + +**Usage (AWS SDK):** +```python +import boto3 + +s3 = boto3.client( + 's3', + endpoint_url='http://localhost:8333', + aws_access_key_id='any', + aws_secret_access_key='any' +) + +# Upload file +s3.upload_file('local.jpg', 'bucket', 'remote.jpg') + +# Download file +s3.download_file('bucket', 'remote.jpg', 'local.jpg') +``` + +**Performance:** +- **Small files:** 10x faster than MinIO +- **Large files:** Similar to MinIO +- **Replication:** Configurable (000 to 111) + +**Alternative:** Cloudflare R2 (commercial, $0.015/GB, no egress fees) + +--- + +### 4. Dashboards: Apache Superset (Apache 2.0) + +**Replaces:** Grafana (AGPL v3) + +**Why Apache Superset:** +- ✅ **Modern BI tool:** Rich visualizations +- ✅ **SQL-based:** Works with ClickHouse, PostgreSQL +- ✅ **Apache 2.0:** Can embed in SaaS product +- ✅ **Active development:** Airbnb, Lyft, Netflix use it + +**Installation:** +```bash +pip install apache-superset + +# Initialize database +superset db upgrade + +# Create admin user +export FLASK_APP=superset +superset fab create-admin + +# Initialize +superset init + +# Start server +superset run -p 8088 --with-threads --reload +``` + +**Connect to ClickHouse:** +```python +# SQLAlchemy URI +clickhouse+native://default:@localhost:9000/default +``` + +**Create Dashboard:** +1. Add ClickHouse database +2. Create SQL query: `SELECT ts, AVG(value) FROM signals GROUP BY ts` +3. Add chart (line, bar, heat map, etc.) +4. Create dashboard, add charts + +**Embedding:** +```python +# Generate guest token for embedding +from superset.security.manager import SupersetSecurityManager + +token = SupersetSecurityManager.get_guest_token( + user={'username': 'guest'}, + resources=[{'type': 'dashboard', 'id': '1'}] +) + +# Embed URL +embed_url = f"http://localhost:8088/superset/dashboard/1/?standalone=true&guest_token={token}" +``` + +**Alternative:** Redash (BSD 2-Clause, simpler, less features) + +--- + +### 5. Logging: OpenSearch (Apache 2.0) + +**Replaces:** Loki (AGPL v3) + +**Why OpenSearch:** +- ✅ **Full-text search:** Better than Loki for log search +- ✅ **AWS-backed:** Active development, stable +- ✅ **Apache 2.0:** Fully commercial-safe +- ✅ **Elasticsearch fork:** Familiar APIs + +**Installation (Docker):** +```bash +docker run -d \ + --name opensearch \ + -p 9200:9200 -p 9600:9600 \ + -e "discovery.type=single-node" \ + opensearchproject/opensearch:latest +``` + +**Log Ingestion (Vector):** +```toml +# vector.toml +[sources.logs] +type = "file" +include = ["/var/log/*.log"] + +[sinks.opensearch] +type = "elasticsearch" +inputs = ["logs"] +endpoint = "http://localhost:9200" +bulk.index = "logs-%Y.%m.%d" +``` + +**Query Logs:** +```bash +curl -X GET "localhost:9200/logs-*/_search?q=error" +``` + +**Dashboards:** +- Use OpenSearch Dashboards (Apache 2.0) +- Or integrate with Superset + +**Alternative:** Vector + ClickHouse (MPL 2.0 + Apache 2.0, cheaper storage) + +--- + +## Migration Checklist + +### Pre-Launch (Critical) + ++ Property Intelligence Platform +
++ RoofIQ Analysis +
++ Solar Suitability +
++ Key Metrics +
+ ``` ++ This property has excellent solar potential with 2,450 sqft + of south-facing roof area. +
++ Last updated: November 8, 2025 +
+ ``` +
+ Content appears smoothly
+
+
+ /* CSS */
+ @keyframes fade-in {
+ from { opacity: 0; }
+ to { opacity: 1; }
+ }
+ .animate-fade-in {
+ animation: fade-in 250ms ease-out;
+ }
+ ```
+
+ Panel slides in from right
+
+
+ /* CSS */
+ @keyframes slide-in-right {
+ from {
+ transform: translateX(100%);
+ opacity: 0;
+ }
+ to {
+ transform: translateX(0);
+ opacity: 1;
+ }
+ }
+ .animate-slide-in-right {
+ animation: slide-in-right 350ms cubic-bezier(0.4, 0, 0.2, 1);
+ }
+ ```
+
+ Loading indicator
+
+
+ /* CSS */
+ @keyframes pulse {
+ 0%, 100% { opacity: 1; }
+ 50% { opacity: 0.5; }
+ }
+ .animate-pulse {
+ animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+ }
+ ```
+
+
+
+
+```
+
+### Cards
+
+```tsx
++ Enter a full address or coordinates +
+
+
+```
+
+### Badges
+
+```tsx
+/* Status Badge */
+
+ Excellent
+
+
+/* Count Badge */
+
+ 3
+
+```
+
+### Tooltips
+
+```tsx
+
+
+ + 123 Main Street +
++ Excellent solar potential • 2,450 sqft roof +
+
+
+
+
+
+
+
+```
+
+---
+
+## Layout Patterns
+
+### Page Layout
+
+```tsx
+
+ More information
+
+
+
+ {/* Header */}
+
+
+
+ {/* Main Content */}
+
+ {children}
+
+
+ {/* Footer */}
+
+
+```
+
+### Split Layout (Map + Panel)
+
+```tsx
+
+
+
+
+
+ {/* Map (takes remaining space) */}
+
+```
+
+### Grid Layout
+
+```tsx
+
+
+
+
+ {/* Side Panel (fixed width or resizable) */}
+
+
+ {properties.map(property => (
+
+```
+
+---
+
+## Responsive Design
+
+### Breakpoints
+
+```css
+/* Mobile First */
+--screen-sm: 640px; /* Tablet */
+--screen-md: 768px; /* Desktop */
+--screen-lg: 1024px; /* Large Desktop */
+--screen-xl: 1280px; /* Extra Large */
+--screen-2xl: 1536px; /* Ultra Wide */
+```
+
+### Responsive Utilities
+
+```tsx
+/* Hide on mobile, show on desktop */
+
+ Desktop only content
+
+
+/* Full width on mobile, fixed width on desktop */
+
+ Responsive width
+
+
+/* Stack on mobile, side-by-side on desktop */
+
+
+```
+
+---
+
+## Accessibility
+
+### WCAG 2.1 AA Compliance
+
+**Color Contrast:**
+- Text (normal): 4.5:1 minimum
+- Text (large): 3:1 minimum
+- UI components: 3:1 minimum
+
+**Keyboard Navigation:**
+- All interactive elements must be keyboard accessible
+- Focus indicators must be visible
+- Skip links for main content
+
+**Screen Readers:**
+- Semantic HTML (`Left
+ Right
+