{"slug":"developers/INTEGRATION_HOOKS_GUIDE","title":"Integration Hooks Guide — Multi-App & Backend Connectivity","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/INTEGRATION_HOOKS_GUIDE.mdx","bytes":13197,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Overview\n\nThe `@integratewise/domain-shells` package now includes **7 comprehensive integration hooks** that connect:\n\n- **Multi-app Portfolio:** Cross-domain navigation between Revops, SalesOps, Admin, Personal, etc.\n- **Backend Services:** Spine (SSOT), Memory (conversations), Governance (approvals), Connected Apps\n- **Real-time Sync:** Automatic data synchronization with retry logic\n- **RBAC Integration:** Permission-based rendering and navigation\n- **Signal Detection:** Intelligence overlay powered by platform signals\n\nAll hooks are fully typed with TypeScript and follow React best practices.\n\n---\n\n## Hook Reference\n\n### 1. `useDomainNavigation()`\n\nCross-app navigation bridge for 12-app portfolio.\n\n```typescript\n\nfunction App() {\n  const { allDomains, accessibleDomains, navigateToDomain } = useDomainNavigation();\n\n  return (\n    <div>\n      \n      {accessibleDomains.map(domain => (\n        <button\n          key={domain.id}\n          onClick={() => navigateToDomain(domain.id)}\n        >\n          {domain.name}\n        </button>\n      ))}\n    </div>\n  );\n}\n```\n\n**Returns:**\n- `allDomains: DomainApp[]` — All 12 workbenches (unfiltered)\n- `accessibleDomains: DomainApp[]` — RBAC-filtered domains\n- `navigateToDomain(domainId: string)` — Navigate to domain\n\n**Domains Included:**\n- Account Success (`/workspace`)\n- RevOps (`/revops`)\n- SalesOps (`/salesops`)\n- Personal (`/personal`)\n- Admin (`/admin` - requires `admin` permission)\n\n---\n\n### 2. `useBackendSync(config?)`\n\nReal-time backend data synchronization with retry logic.\n\n```typescript\n\nfunction Dashboard() {\n  const { syncing, lastSync, performSync } = useBackendSync({\n    interval: 30000, // Sync every 30 seconds\n    retryAttempts: 3,\n    onSync: (data) => {\n      console.log('Synced data:', data);\n    },\n    onError: (error) => {\n      console.error('Sync failed:', error);\n    },\n  });\n\n  return (\n    <div>\n      {syncing && <p>Syncing...</p>}\n      {lastSync && <p>Last synced: {lastSync.toLocaleTimeString()}</p>}\n      <button onClick={performSync}>Sync Now</button>\n    </div>\n  );\n}\n```\n\n**Config:**\n- `interval?: number` — Milliseconds between syncs (default: 30000)\n- `retryAttempts?: number` — Number of retry attempts (default: 3)\n- `onSync?: (data) => void` — Callback on successful sync\n- `onError?: (error) => void` — Callback on sync failure\n\n**Returns:**\n- `syncing: boolean` — Is currently syncing\n- `lastSync: Date | null` — Last successful sync time\n- `performSync()` — Trigger manual sync\n\n---\n\n### 3. `useSpineData(entityType)`\n\nFetch and cache Spine SSOT entity data with TTL.\n\n```typescript\n\nfunction AccountsList() {\n  const { data: accounts, loading, error, refetch } = useSpineData('account');\n\n  if (loading) return <div>Loading...</div>;\n  if (error) return <div>Error: {error.message}</div>;\n\n  return (\n    <div>\n      {accounts.map(account => (\n        <div key={account.id}>{account.name}</div>\n      ))}\n      <button onClick={refetch}>Refresh</button>\n    </div>\n  );\n}\n```\n\n**Cache:**\n- 5-minute TTL per entity type\n- Automatic cache invalidation\n- Manual refetch available\n\n**Returns:**\n- `data: SpineEntity[]` — Array of entities from Spine\n- `loading: boolean` — Is loading\n- `error: Error | null` — Error if fetch failed\n- `refetch()` — Manual refresh\n\n---\n\n### 4. `useSignalDetection()`\n\nIntelligence signal detection and classification.\n\n```typescript\n\nfunction IntelligencePanel() {\n  const {\n    signals,\n    loading,\n    getSignalsByType,\n    getHighSeveritySignals,\n  } = useSignalDetection();\n\n  const risks = getSignalsByType('risk');\n  const criticalSignals = getHighSeveritySignals();\n\n  return (\n    <div>\n      <h3>Critical Signals ({criticalSignals.length})</h3>\n      {criticalSignals.map(signal => (\n        <div\n          key={signal.id}\n          className={`severity-${signal.severity}`}\n        >\n          {signal.title}\n        </div>\n      ))}\n\n      <h3>Risks ({risks.length})</h3>\n      {risks.map(risk => (\n        <div key={risk.id}>{risk.description}</div>\n      ))}\n    </div>\n  );\n}\n```\n\n**Signal Types:**\n- `risk` — High-risk signals requiring attention\n- `opportunity` — Growth opportunities\n- `insight` — Data insights\n- `action` — Recommended actions\n\n**Severity Levels:**\n- `critical` — Immediate action required\n- `high` — Should address soon\n- `medium` — Worth monitoring\n- `low` — Informational\n- `info` — Background info\n\n**Returns:**\n- `signals: Signal[]` — All detected signals\n- `loading: boolean` — Is loading\n- `filteredSignals: Signal[]` — Filtered results\n- `filterSignals(filters)` — Filter signals\n- `getSignalsByType(type)` — Get signals by type\n- `getHighSeveritySignals()` — Get critical + high\n\n---\n\n### 5. `useMemoryIntegration()`\n\nConversational memory persistence and retrieval.\n\n```typescript\n\nfunction ChatInterface() {\n  const { messages, loading, addMessage, reload } = useMemoryIntegration();\n\n  const handleSendMessage = (content: string) => {\n    addMessage({\n      role: 'user',\n      content,\n    });\n\n    // Chat logic here...\n  };\n\n  return (\n    <div>\n      {messages.map(msg => (\n        <div key={msg.id} className={`message-${msg.role}`}>\n          {msg.content}\n        </div>\n      ))}\n      <input\n        onKeyDown={(e) => {\n          if (e.key === 'Enter') {\n            handleSendMessage(e.currentTarget.value);\n          }\n        }}\n      />\n    </div>\n  );\n}\n```\n\n**Returns:**\n- `messages: ConversationMessage[]` — All messages in current session\n- `loading: boolean` — Is loading conversation history\n- `addMessage(message)` — Add message to memory\n- `reload()` — Reload conversation history\n\n---\n\n### 6. `useGovernanceIntegration()`\n\nGovernance approvals and workflows.\n\n```typescript\n\nfunction ApprovalCenter() {\n  const { workflows, loading, pendingApprovals, reload } = useGovernanceIntegration();\n\n  return (\n    <div>\n      <h3>Pending Approvals ({pendingApprovals.length})</h3>\n      {pendingApprovals.map(workflow => (\n        <div key={workflow.id}>\n          <p>{workflow.type}</p>\n          <p>Requested by: {workflow.requester}</p>\n          <p>Approvers: {workflow.approvers.join(', ')}</p>\n          <button>Review</button>\n        </div>\n      ))}\n      <button onClick={reload}>Refresh Approvals</button>\n    </div>\n  );\n}\n```\n\n**Workflow Statuses:**\n- `pending` — Awaiting approval\n- `approved` — Approved\n- `rejected` — Rejected\n- `cancelled` — Cancelled\n\n**Returns:**\n- `workflows: ApprovalWorkflow[]` — All workflows\n- `loading: boolean` — Is loading\n- `pendingApprovals()` — Only pending workflows\n- `reload()` — Refresh workflows\n\n---\n\n### 7. `useConnectedAppsSync()`\n\nExternal app data synchronization (ChatGPT, HubSpot, Slack, etc.).\n\n```typescript\n\nfunction ConnectedAppsPanel() {\n  const { apps, syncing, triggerSync } = useConnectedAppsSync();\n\n  return (\n    <div>\n      <h3>Connected Apps</h3>\n      {apps.map(app => (\n        <div key={app.id}>\n          <span>{app.name}</span>\n          <span className={`status-${app.status}`}>\n            {app.status}\n          </span>\n          <button\n            onClick={() => triggerSync(app.id)}\n            disabled={syncing}\n          >\n            {syncing ? 'Syncing...' : 'Sync'}\n          </button>\n        </div>\n      ))}\n      <button\n        onClick={() => triggerSync()}\n        disabled={syncing}\n      >\n        Sync All\n      </button>\n    </div>\n  );\n}\n```\n\n**App Statuses:**\n- `connected` — Connected and synced\n- `disconnected` — Not connected\n- `syncing` — Currently syncing\n- `error` — Sync error\n\n**Returns:**\n- `apps: ConnectedApp[]` — All connected apps\n- `syncing: boolean` — Is syncing\n- `triggerSync(appId?)` — Sync specific or all apps\n\n---\n\n## Usage Patterns\n\n### Pattern 1: Multi-Domain App Switcher\n\n```typescript\nfunction DomainSwitcher() {\n  const { accessibleDomains, navigateToDomain } = useDomainNavigation();\n\n  return (\n    <nav>\n      {accessibleDomains.map(domain => (\n        <button\n          key={domain.id}\n          onClick={() => navigateToDomain(domain.id)}\n        >\n          {domain.icon} {domain.name}\n        </button>\n      ))}\n    </nav>\n  );\n}\n```\n\n### Pattern 2: Real-time Dashboard\n\n```typescript\nfunction RealTimeDashboard() {\n  // Auto-sync every 30 seconds with error handling\n  useBackendSync({\n    interval: 30000,\n    onSync: (data) => console.log('Dashboard updated'),\n    onError: (error) => console.error('Sync failed, will retry'),\n  });\n\n  const accounts = useSpineData('account');\n  const signals = useSignalDetection();\n\n  return (\n    <div>\n      <Stats accounts={accounts.data} />\n      <Signals signals={signals.getHighSeveritySignals()} />\n    </div>\n  );\n}\n```\n\n### Pattern 3: Intelligence Overlay\n\n```typescript\nfunction IntelligenceOverlay() {\n  const signals = useSignalDetection();\n\n  return (\n    <aside>\n      <h3>Intelligence ({signals.signals.length})</h3>\n      \n      <section>\n        <h4>Risks</h4>\n        {signals.getSignalsByType('risk').map(risk => (\n          <Alert key={risk.id} signal={risk} />\n        ))}\n      </section>\n\n      <section>\n        <h4>Opportunities</h4>\n        {signals.getSignalsByType('opportunity').map(opp => (\n          <Opportunity key={opp.id} signal={opp} />\n        ))}\n      </section>\n    </aside>\n  );\n}\n```\n\n### Pattern 4: Integrated Workbench\n\n```typescript\nfunction AccountSuccessWorkbench() {\n  const { user } = usePlatform();\n  const { accessibleDomains } = useDomainNavigation();\n  const { syncing } = useBackendSync({ interval: 30000 });\n  const accounts = useSpineData('account');\n  const signals = useSignalDetection();\n\n  return (\n    <div>\n      <Sidebar domains={accessibleDomains} />\n      <Header user={user} syncing={syncing} />\n      <Dashboard\n        accounts={accounts.data}\n        signals={signals.signals}\n      />\n      <IntelligencePanel signals={signals.signals} />\n    </div>\n  );\n}\n```\n\n---\n\n## Type Definitions\n\nAll hooks are fully typed:\n\n```typescript\n// Signals\ntype SignalType = 'risk' | 'opportunity' | 'insight' | 'action';\ntype SignalSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';\n\ninterface Signal {\n  id: string;\n  type: SignalType;\n  severity: SignalSeverity;\n  title: string;\n  description: string;\n  source: string;\n  confidence: number; // 0-100\n  timestamp: Date;\n  metadata?: Record<string, any>;\n}\n\n// Spine Entities\ninterface SpineEntity {\n  id: string;\n  type: string;\n  name: string;\n  [key: string]: any;\n}\n\n// Domain Apps\ninterface DomainApp {\n  id: string;\n  name: string;\n  path: string;\n  icon: React.ReactNode;\n  requiresPermission?: string;\n}\n\n// Workflows\ninterface ApprovalWorkflow {\n  id: string;\n  type: string;\n  status: 'pending' | 'approved' | 'rejected' | 'cancelled';\n  requester: string;\n  approvers: string[];\n  createdAt: Date;\n  expiresAt?: Date;\n}\n\n// Connected Apps\ninterface ConnectedApp {\n  id: string;\n  name: string;\n  status: 'connected' | 'disconnected' | 'syncing' | 'error';\n  lastSync?: Date;\n  nextSync?: Date;\n}\n```\n\n---\n\n## Performance Considerations\n\n1. **Spine Data Caching:** 5-minute TTL prevents excessive API calls\n2. **Backend Sync Retry:** Automatic retry with exponential backoff\n3. **Memory Integration:** Lazy-loads conversation history\n4. **Signal Detection:** Filters signals client-side to minimize API calls\n5. **Connected Apps:** Batches sync operations\n\n---\n\n## Integrating with Your Backend\n\nAll hooks use the `useGateway()` SDK to call your backend. Wire them by:\n\n1. **Ensure Gateway SDK is installed:** `npm install @integratewise/gateway-sdk`\n2. **Configure backend endpoints** in `/api/gateway/*` routes\n3. **Test with real data** using the hooks in your workbench\n\nExample backend integration:\n\n```typescript\n// /api/gateway/entity/route.ts\nexport async function GET(req: Request) {\n  const { orgId, entityType } = req.nextUrl.searchParams;\n  \n  // Fetch from Spine SSOT\n  const data = await spine.getEntities(orgId, entityType);\n  return Response.json(data);\n}\n```\n\n---\n\n## Summary\n\nThese 7 hooks provide enterprise-grade integration:\n\n✅ Multi-app portfolio navigation\n✅ Real-time backend synchronization\n✅ Spine SSOT data caching\n✅ Intelligence signal detection\n✅ Conversational memory persistence\n✅ Governance workflow management\n✅ External app synchronization\n\nUse them to build seamless, production-ready workbenches across all 12+ frontend apps.\n"}