{"slug":"business/CODEBASE_ALIGNMENT","title":"IntegrateWise Codebase Alignment Plan","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/CODEBASE_ALIGNMENT.mdx","bytes":5719,"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## Strategic Direction\n\nUser feedback: \"Capabilities should be directly executable in our workspace. The AI should be proactive—not waiting for context, but surfacing relevant capabilities based on what the user is viewing. Support inline operations: viewing contacts, updating fields, marking leads active. Mix fields from multiple tools (e.g., Website Manager shows visitor count from analytics + blog content from CMS).\"\n\n## Current State vs. Desired State\n\n### Current (Discovery-Only)\n- Capability Dashboard shows available capabilities\n- User manually invokes from dedicated page\n- No workspace context awareness\n- No inline execution\n- No field composition from multiple sources\n\n### Desired (Execution-in-Workspace)\n- User views entity (e.g., Lead \"Acme Corp\")\n- Proactive AI suggests relevant capabilities (Mark as Active, Send Email, Create Task)\n- User clicks → capability executes inline in current view\n- Fields show composite data: name (Salesforce) + website visits (Analytics) + content tags (CMS)\n- Sync options: real-time to connected tools OR deferred sync\n- Capability context flows from workspace to Twin\n\n## Implementation Roadmap\n\n### Phase 1: Workspace Context Awareness (Current Task)\n- Build Entity Detail View component\n- Connect to Spine for entity data\n- Display composite fields from multiple tools\n- Track current viewing context\n\n### Phase 2: Proactive Capability Surfacing\n- Create Capability Context Engine\n- Analyze current entity + user role → suggest capabilities\n- Surface top 3-5 relevant capabilities in entity sidebar\n- Prioritize by: role, entity type, frequency\n\n### Phase 3: Inline Capability Execution\n- Build Inline Capability Executor (mini UI vs. full modal)\n- Handle form inputs within entity view\n- Execute with real-time OR deferred sync option\n- Show execution status inline\n\n### Phase 4: Composite Field Views\n- Create FieldComposer component\n- Accept field definitions from multiple connectors\n- Display composite (e.g., \"Website Visitors: 4,221 (from Google Analytics) + Blog: 12 posts (from Contentful)\")\n- Enable field-level governance (show source, confidence)\n\n### Phase 5: Twin Integration\n- Twin watches workspace context (entity_id, viewing_user_id)\n- Generates proactive capability recommendations\n- Creates morning briefing with relevant workspace capabilities\n- Learns which capabilities user approves most often\n\n## File Structure Needed\n\n```\npackages/core/\n├── workspace-context/\n│   ├── context-provider.ts      # Track current entity/workspace\n│   ├── types.ts                 # Context shape\n│   └── index.ts\n\napps/web/components/\n├── entity-detail/\n│   ├── entity-detail.tsx        # Main entity view wrapper\n│   ├── composite-fields.tsx     # Field composition UI\n│   ├── field-viewer.tsx         # Single field with sources\n│   └── index.ts\n├── proactive-capabilities/\n│   ├── capability-suggester.tsx # AI suggestions sidebar\n│   ├── capability-card.tsx      # Mini capability card\n│   └── index.ts\n├── inline-executor/\n│   ├── inline-executor.tsx      # Embedded capability execution\n│   ├── capability-form.tsx      # Compact form input\n│   ├── sync-options.tsx         # Real-time vs. deferred\n│   └── index.ts\n└── workspace-layout/\n    ├── workspace-with-context.tsx # Root wrapper\n    └── index.ts\n```\n\n## Key Contracts\n\n### WorkspaceContext\n```typescript\ninterface WorkspaceContext {\n  tenant_id: string;\n  workspace_id: string;\n  user_id: string;\n  current_entity_id?: string;        // What user is viewing\n  current_entity_type?: string;      // e.g., \"lead\", \"account\"\n  viewing_role: string;              // User role\n  last_action?: { timestamp, action_name, entity_id };\n}\n```\n\n### CompositeField\n```typescript\ninterface CompositeField {\n  name: string;\n  values: {\n    source: string;              // e.g., \"salesforce\", \"analytics\", \"contentful\"\n    value: any;\n    confidence?: number;\n    last_updated?: ISO8601;\n  }[];\n}\n```\n\n### ProactiveCapability\n```typescript\ninterface ProactiveCapability {\n  capability_id: string;\n  relevance_score: number;       // 0-100, why this capability is relevant\n  reason: string;                // \"Based on lead status\" / \"You use this 3x/week\"\n  suggested_inputs?: Record<string, any>;\n  quick_actions: boolean;        // Can execute in < 2 seconds\n}\n```\n\n## Integration Points\n\n1. **Workspace Route** → Wraps with WorkspaceContext Provider\n2. **Entity Detail Page** → Queries Spine, displays CompositeFields, surfaces ProactiveCapabilities\n3. **Inline Executor** → Uses existing CapabilityEngine but with compact UI\n4. **Twin** → Consumes WorkspaceContext to generate smarter recommendations\n5. **Governance** → Sync options (real-time to tools vs. deferred) respect approval thresholds\n\n## Success Criteria\n\n- [ ] User views entity → sees composite fields from 2+ sources\n- [ ] User views entity → sees 3-5 proactive capability suggestions\n- [ ] User clicks capability → executes inline without page navigation\n- [ ] Execution completes → shows sync status (real-time synced / deferred pending approval)\n- [ ] Twin receives context → generates role-specific morning briefing\n- [ ] Workspace switching → Twin maintains continuity (Continuity Bridge)\n\n---\n\n**Next Steps**: Start Phase 1 - Build Entity Detail View and composite field infrastructure.\n"}