system-prompts-and-models-of-ai-tools/salesflow-saas/docs/governance/executive-surface-closure.md

Executive Surface Closure Plan — Track 9

Parent: executive-board-os.md
Plane: Decision | Version: 1.0

---

Objective

Transform executive surfaces from placeholder UIs into real-data-driven decision tools used weekly by at least one stakeholder.

---

Surface Inventory & Wiring Status

Surface	Frontend	API	Real Data?	Priority
Executive Room	executive-room.tsx	executive_room.py	Placeholder	P1
Approval Center	approval-center.tsx	approval_center.py	Placeholder	P1
Evidence Pack Viewer	evidence-pack-viewer.tsx	evidence_packs.py	Placeholder	P2
Saudi Compliance Dashboard	saudi-compliance-dashboard.tsx	saudi_compliance.py	Seed data	P1
Actual vs Forecast	actual-vs-forecast-dashboard.tsx	forecast_control.py	Placeholder	P2
Risk Heatmap	risk-heatmap.tsx	Aggregated	No data	P2
Policy Violations Board	policy-violations-board.tsx	From contradictions	No data	P2
Connector Governance Board	connector-governance-board.tsx	connector_governance.py	Known connectors	P1
Partner Pipeline Board	partner-pipeline-board.tsx	From strategic_deals	Partial	P2

---

Wiring Plan: Executive Room (P1)

The Executive Room API (GET /api/v1/executive-room/snapshot) needs to aggregate from real services:

# Target implementation for executive_room.py
async def build_snapshot(db: AsyncSession, tenant_id: str):
    return {
        "revenue": await analytics_service.get_revenue_summary(db, tenant_id),
        "approvals": await count_approval_status(db, tenant_id),
        "connectors": await connector_governance.get_health_summary(db, tenant_id),
        "compliance": await saudi_compliance_matrix.get_posture(db, tenant_id),
        "contradictions": await contradiction_engine.get_stats(db, tenant_id),
        "strategic_deals": await count_strategic_deals(db, tenant_id),
        "evidence_packs": await count_evidence_packs(db, tenant_id),
    }

Data Source Mapping

Section	Query	Table(s)
Revenue actual	SUM(deals.value) WHERE status='won'	deals
Pipeline value	SUM(deals.value) WHERE status IN ('open','negotiating')	deals
Win rate	COUNT(won) / COUNT(closed)	deals
Pending approvals	COUNT WHERE status='pending'	approval_requests
SLA warning	COUNT WHERE deadline < now+4h AND status='pending'	approval_requests
Connector health	GROUP BY status	integration_sync_states
Compliance posture	FROM saudi_compliance_matrix.get_posture()	compliance_controls
Active contradictions	COUNT WHERE status IN ('detected','reviewing')	contradictions
Strategic deals	COUNT WHERE status='active'	strategic_deals
Evidence packs ready	COUNT WHERE status='ready'	evidence_packs

---

Wiring Plan: Approval Center (P1)

The Approval Center needs to query real ApprovalRequest records:

# Target query
SELECT * FROM approval_requests
WHERE tenant_id = :tid AND status = 'pending'
ORDER BY
    CASE priority
        WHEN 'critical' THEN 1
        WHEN 'high' THEN 2
        WHEN 'normal' THEN 3
        WHEN 'low' THEN 4
    END,
    created_at ASC

Required Model Enhancement

Add to ApprovalRequest in models/operations.py:

• sla_deadline_at (DateTime) — when approval must be completed
• escalation_level (Integer, default 0) — current escalation
• category (String) — deal, message, integration, billing, compliance
• priority (String) — critical, high, normal, low

---

Wiring Plan: Connector Governance Board (P1)

Already partially wired:

• ConnectorGovernanceService returns known connectors + registered states
• Needs: live health probes for active connectors (WhatsApp API check, Stripe status, etc.)

---

Wiring Plan: Saudi Compliance Dashboard (P1)

Already partially wired:

• SaudiComplianceMatrix seeds default controls
• Needs: live checks that update control status from real service results
• Example: PDPL-C01 should query consent coverage from real consents table

---

Board-Ready Export Path

Requirements

1. Any executive surface can export to JSON
2. Evidence packs export to PDF (via WeasyPrint with Arabic RTL)
3. Board pack combines multiple surfaces into single PDF

Implementation

• JSON export: Already supported (API returns JSON)
• PDF export: Use invoice_generator.py pattern (WeasyPrint)
• Board pack: New service that calls all surfaces and renders combined PDF

---

Gate: Executive Surface Closure

• Executive Room shows real revenue, approvals, compliance data
• Approval Center queries real ApprovalRequest records
• Saudi Compliance Dashboard runs real checks
• Connector Governance Board shows actual connector status
• At least one surface used in a real weekly review
• Board-ready export path works for at least one surface