LACRM Contact Sync SOP

graph LR
  A[Contact Index Build] --> B[Meeting Data Aggregation]
  B --> C[Touch Frequency Analysis]
  C --> D[Metrics Calculation]
  D --> E[LACRM Field Updates]
  E --> F[Schema Validation]
  F --> G[Push Updates]
  G --> H[Audit Log]

1 Purpose

Maintain LACRM as the authoritative contact database by automatically synchronizing meeting data, email touch frequency, and computed client metrics from all integrated platforms.

2 Triggers

• Automated: Every 4 hours via cron schedule
• Manual: uv run scripts/sync/run_lacrm_refresh.sh execution
• Event-driven: New meeting bookings, email interactions, contact additions

3 Inputs

• Contact index from Google Contacts, Gmail, LACRM API
• Meeting data from Cal.com, Calendly, TidyCal booking platforms
• Email interaction data from Gmail API (message metadata only)
• Existing LACRM contact records and custom fields

4 Steps

1. Build Contact Index (build_contact_index.py)
   • Download LACRM contacts via API pagination
   • Extract email addresses from Google Contacts and Gmail
   • Create unified email-to-contact-id mapping
   • Store index in data/model/contacts_index.json
2. Aggregate Meeting Data (build_lacrm_metrics.py)
   • Process Cal.com bookings via API with cursor pagination
   • Import Calendly and TidyCal CSV exports if available
   • Normalize meeting data across platforms (attendees, duration, type)
   • Calculate meeting frequency, last meeting date, portfolio review flags
3. Analyze Email Touches (update_gmail_touch_table.py)
   • Query Gmail API for message metadata (no content)
   • Match sender/recipient emails to contact index
   • Calculate touch frequency, last contact date, response patterns
   • Generate touch metrics per contact
4. Compute Client Metrics (aggregation logic)
   • Meeting frequency (meetings per quarter)
   • Portfolio review status (last formal review date)
   • Communication recency (days since last email)
   • Engagement score (composite metric)
5. Schema Validation (apply_lacrm_schema.py)
   • Validate field mappings against current LACRM schema
   • Check custom field existence and data types
   • Flag any schema drift or missing fields
6. Push Updates (push_lacrm_contact_updates.py)
   • Generate contact updates batch (respects API rate limits)
   • Update custom fields: last_meeting, meeting_frequency, email_touch_count
   • Handle API errors and retry logic
   • Log successful updates and failures

5 Exceptions

• API Rate Limit: Exponential backoff, resume from last successful batch
• Contact Not Found: Log orphaned meeting/email data for manual review
• Schema Mismatch: Alert ops team, halt updates until fields created
• Authentication Failure: Retry with token refresh, escalate if persistent

6 Owner Handoffs

• Data Engineering → Client Experience for contact assignment corrections
• Client Experience → Compliance for data quality issues requiring audit
• Ops → Engineering for persistent API failures or schema changes

7 SLAs

• Automated Sync: Complete within 30 minutes of scheduled execution
• Manual Sync: Complete within 15 minutes of operator initiation
• Error Recovery: Automatic retry within 1 hour, manual escalation at 4 hours

8 Controls

• Data Validation: Email address format validation, duplicate contact detection
• Rate Limiting: Maximum 10 requests/second to LACRM API
• Audit Logging: All contact updates logged with timestamp and source data
• Schema Enforcement: Updates blocked if target fields don’t exist in LACRM

9 Audit Artifacts

• Contact update logs in logs/lacrm_contact_updates_YYYYMMDD.json
• Meeting aggregation summaries in data/model/lacrm_contact_metrics.parquet
• Email touch frequency reports in data/model/contact_email_touches.parquet
• Sync execution logs with success/failure counts and timing

10 Vendor Nuances

• LACRM: API pagination requires page parameter, rate limit 1000/hour
• Cal.com: Uses cursor-based pagination, requires Bearer token authentication
• Google APIs: OAuth refresh tokens expire, automated renewal implemented
• Calendly/TidyCal: CSV export only, manual file placement required

11 Technical Dependencies

• Contact Index: Foundation for all contact matching across platforms
• DuckDB Catalog: Local data warehouse for metrics calculation and validation
• OAuth Token Management: Google services authentication renewal
• Parquet Storage: Efficient columnar format for historical metrics analysis

12 Monitoring & Alerts

• Success Metrics: Contacts updated, meetings processed, emails analyzed
• Error Conditions: API failures, schema mismatches, data quality issues
• Performance: Sync duration, API response times, batch processing efficiency

13 FAQs

What happens if a contact exists in multiple booking platforms? The contact index deduplicates by email address. Meetings from all platforms are aggregated under the single LACRM contact record.

How are email touches counted without reading message content? Gmail API metadata provides sender/recipient information and timestamps. Only headers are processed - message content is never accessed.

Can the sync be run manually during business hours? Yes, but avoid concurrent execution with automated runs. The script includes file locking to prevent conflicts.