🏗️ Architecture: How to handle the two-phase proactive analysis (instant rule...

Date: 2026-03-24
Time: 15:17:18 UTC
Session: gspace1-263.3
Agent: angular
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How to handle the two-phase proactive analysis (instant rules + async LLM) without blocking the UI?

Task: Not specified

🎯 Decision Made

Chosen:

Phase A (rule scan) runs synchronously in <100ms on the frontend using the SuggestionRuleEngine. Ambient dots and preliminary chat summary appear instantly. Phase B (LLM deep scan) fires parallel Haiku calls via backend PVI endpoints, results merge with Phase A via SuggestionMergeEngine, and dots/summary update in place.

Options Considered:

1. LLM-only analysis (slow, no instant feedback)
2. Rules-only analysis (misses nuanced suggestions)
3. Streaming partial results via SSE (more complex, marginal UX benefit over two-phase)

💭 Reasoning

Users need immediate feedback after generation completes. Waiting 2-4s for LLM analysis would feel broken. The rule engine has ~20 deterministic rules that catch 60-70% of suggestions (missing SDK components, hardcoded colors, missing composables). LLM enrichment adds nuanced, context-aware suggestions (card layouts, status badges) that rules can't detect. Merging via SuggestionMergeEngine uses Levenshtein similarity to deduplicate overlapping rule+LLM suggestions. This two-phase approach mirrors how VS Code IntelliSense works: instant prefix completions + async LSP completions that merge in.

📁 Files Involved

• libs/libs-structural/vitto-studio/src/lib/services/pvi-proactive-analysis.service.ts
• libs/libs-ai/proactive-visual-intelligence/src/lib/engines/suggestion-rule-engine.ts
• libs/libs-ai/proactive-visual-intelligence/src/lib/engines/suggestion-merge-engine.ts

🔗 Related

• Decision ID: dev_1774365438616_0xklpgm
• Session: 263
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation