system-prompts-and-models-of-ai-tools/salesflow-saas/docs/governance/connector-standard.md

Connector Governance Standard — Track 6

Parent: MASTER_OPERATING_PROMPT.md
Plane: Data | Version: 1.0

---

Objective

Every integration connector in Dealix follows a standard interface. No direct vendor bindings from agents. All connectors are governed, monitored, and auditable.

---

Connector Contract

Every connector MUST implement:

class ConnectorContract:
    """Standard interface for all Dealix connectors."""
    
    # Identity
    connector_key: str          # e.g. "whatsapp", "salesforce"
    display_name: str           # English
    display_name_ar: str        # Arabic
    version: str                # Semantic version
    
    # Governance
    approval_policy: str        # "auto" | "approval_required"
    audit_mapping: str          # Which audit event types
    data_classification: str    # "public" | "internal" | "confidential" | "restricted"
    
    # Reliability
    retry_policy: RetryPolicy   # max_retries, backoff, timeout
    timeout_ms: int             # Max wait per call
    idempotency: bool           # Supports idempotent calls
    
    # Observability
    health_check(): HealthResult
    metrics(): ConnectorMetrics
    
    # Lifecycle
    initialize(): void
    execute(payload): Result
    compensate(payload): void   # Rollback action
    shutdown(): void

---

Required Metadata Per Connector

Field	Description	Example
connector_key	Unique identifier	whatsapp
display_name	Human name (EN)	WhatsApp Business API
display_name_ar	Human name (AR)	واتساب بيزنس
version	Current version	2026.4.1
contract_url	API docs reference	Meta Developer docs URL
retry_max	Max retry attempts	3
retry_backoff_ms	Backoff between retries	1000, 2000, 4000
timeout_ms	Call timeout	30000
idempotent	Supports idempotency	true
approval_policy	Policy class	B (approval required)
data_classification	Sensitivity level	confidential
audit_events	Logged event types	message_sent, message_failed

---

Current Connectors

Connector	Key	Standard?	Health Check?	Retry?	Audit?
WhatsApp	whatsapp	Partial	No live probe	Partial	Yes (messages)
Salesforce	salesforce	Partial	No live probe	Partial	Partial
Stripe	stripe	Partial	No live probe	Yes (webhook)	Yes (payments)
Voice (Twilio)	voice	Pilot	No	Partial	Partial
Contract Intel	contract_intel	Pilot	No	No	No
Email (SMTP)	email	Partial	No live probe	Yes	Yes (messages)
Cal.com	cal	Pilot	No	No	No

---

Connector Health Board

The Connector Governance Board (/api/v1/connectors/governance) shows:

Column	Source
Connector name (AR/EN)	KNOWN_CONNECTORS in connector_governance.py
Status (ok/degraded/error)	IntegrationSyncState model
Last success	last_success_at field
Last attempt	last_attempt_at field
Last error	last_error field
Registered	Whether tenant has configured it

---

Semantic Metrics Layer

Purpose

Prevent multiple conflicting definitions of the same metric.

Metric Dictionary (mandatory)

Metric	Definition	Source	Owner
revenue_actual	Sum of closed-won deal values in period	deals table WHERE status='won'	Revenue Track
pipeline_value	Sum of open deal values	deals table WHERE status IN ('open', 'negotiating')	Revenue Track
win_rate	Won deals / total closed deals	deals table	Revenue Track
cac	Total acquisition cost / new customers in period	commissions + marketing spend	Revenue Track
consent_coverage	Leads with active consent / total leads	consents + leads tables	Compliance Track
approval_sla_compliance	Approvals within SLA / total approvals	approval_requests table	Trust Track
connector_health	Connectors with status=ok / total connectors	integration_sync_states table	Operations Track

Rule

No two services may define the same metric differently. The metric dictionary above is canonical. Any service computing these metrics MUST use the definition above.

---

Radar Additions

Airbyte (Connector Orchestration)

Status: Watch
Why: 600+ pre-built connectors, MCP server, agent engine
Adopt when: 5+ external data sources need governed ingestion
Spike: Prototype with one CRM source (HubSpot or Salesforce)

Unstructured (Document Extraction)

Status: Watch
Why: Extract contracts, CIMs, PDFs for DD workstreams
Adopt when: M&A DD workflow goes live
Spike: Prototype with sample contract extraction

Great Expectations (Data Quality)

Status: Watch
Why: Production-grade data quality checks
Adopt when: Data pipeline exceeds 5 sources
Spike: Quality suite for leads and deals tables

---

Gate: Data & Connector Closure

• Metric dictionary published and enforced
• Connector facade standard documented
• Health board shows real status for all active connectors
• No direct vendor bindings from agents (all via facade)
• At least one connector has full contract metadata