feat(ui): add animated architecture flow and 'How It Works' tab

app.py

@@ -15,6 +15,7 @@ from verification_service import calculate_symbolic_score
 from consensus_fusion import evaluate_consensus
 from report_module import generate_mvm2_report, export_to_pdf
 from image_enhancing import ImageEnhancer
+from flow_module import generate_flow_html
 
 # Initialize Engines
 ocr_engine = MVM2OCREngine()
@@ -91,6 +92,9 @@ def process_mvm2_pipeline(image, auto_enhance):
     latex_text = ocr_results['latex_output']
     ocr_conf = ocr_results['weighted_confidence']
     
+    # Update flow for current state (Visual sync)
+    flow_html = generate_flow_html("reasoning") # Transitioning to reasoning
+    
     # 3. Multi-Agent Reasoning
     agent_responses = run_agent_orchestrator(latex_text)
     
@@ -144,7 +148,9 @@ def process_mvm2_pipeline(image, auto_enhance):
     pdf_path = os.path.join(tempfile.gettempdir(), f'MVM2_Report_{reports["report_id"]}.pdf')
     export_to_pdf(json.loads(reports['json']), pdf_path)
     
-    return preview_img, latex_text, gauges_html, conf_bar, md_report, pdf_path
+    final_flow = generate_flow_html("success")
+    
+    return preview_img, latex_text, gauges_html, conf_bar, md_report, pdf_path, final_flow
 
 # Build Interface
 with gr.Blocks(css=css_content, title="MVM²: Senior UI AI Dashboard") as demo:
@@ -171,13 +177,29 @@ with gr.Blocks(css=css_content, title="MVM²: Senior UI AI Dashboard") as demo:
 
         # --- CENTER STAGE: Canvas ---
         with gr.Column(scale=2):
-            gr.Markdown("### 🎨 MVM² Verification Canvas")
-            with gr.Group(elem_classes="glass-card"):
-                canvas_latex = gr.Textbox(label="Canonical LaTeX Transcription", lines=2, interactive=False, elem_classes="monospace")
-                calib_bar_html = gr.HTML()
-            
-            gr.Markdown("### 🪜 Dynamic Reasoning Trace")
-            trace_html = gr.HTML()
+            with gr.Tabs():
+                with gr.TabItem("Solver Visualization"):
+                    gr.Markdown("### 🎨 MVM² Verification Canvas")
+                    with gr.Group(elem_classes="glass-card"):
+                        canvas_latex = gr.Textbox(label="Canonical LaTeX Transcription", lines=2, interactive=False, elem_classes="monospace")
+                        calib_bar_html = gr.HTML()
+                    
+                    gr.Markdown("### 🪜 Dynamic Reasoning Trace")
+                    trace_html = gr.HTML()
+
+                with gr.TabItem("How It Works (Architecture Flow)"):
+                    gr.Markdown("### 🚀 Real-Time Pipeline Visualization")
+                    flow_view = gr.HTML(generate_flow_html("idle"))
+                    gr.Markdown(
+                        """
+                        **Pipeline Phases:**
+                        1. **Enhance:** CLAHE & Gaussian Blur noise reduction.
+                        2. **OCR:** Pix2Text LaTeX structure reconstruction.
+                        3. **Reasoning:** Quad-agent parallel logic processing.
+                        4. **Verification:** SymPy deterministic symbolic check.
+                        5. **Consensus:** Multi-signal weighted confidence fusion.
+                        """
+                    )
 
         # --- RIGHT PANEL: Signal Intel ---
         with gr.Column(scale=1, variant="panel"):
@@ -201,7 +223,7 @@ with gr.Blocks(css=css_content, title="MVM²: Senior UI AI Dashboard") as demo:
     run_btn.click(
         fn=process_mvm2_pipeline,
         inputs=[input_img, enhance_toggle],
-        outputs=[preview_output, canvas_latex, signal_gauges, calib_bar_html, trace_html, download_btn]
+        outputs=[preview_output, canvas_latex, signal_gauges, calib_bar_html, trace_html, download_btn, flow_view]
     )
 
 if __name__ == "__main__":

flow_module.py

@@ -0,0 +1,85 @@
+def generate_flow_html(active_phase="idle"):
+    """
+    Generates animated SVG for the MVM² Architecture Flow.
+    Phases: 'idle', 'enhance', 'ocr', 'reasoning', 'verification', 'consensus', 'success'
+    """
+    
+    # Define colors
+    bg_color = "#1e293b"
+    accent = "#6366f1"
+    success = "#10b981"
+    text = "#94a3b8"
+    
+    # Pulse animation logic
+    def get_pulse(phase):
+        return 'active-pulse' if active_phase == phase else ''
+
+    def get_node_style(phase):
+        if active_phase == 'success': return 'stroke: #10b981; filter: drop-shadow(0 0 8px #10b981);'
+        if active_phase == phase: return f'stroke: {accent}; filter: drop-shadow(0 0 8px {accent});'
+        return 'stroke: rgba(255,255,255,0.1);'
+
+    html = f"""
+    <div class="glass-card" style="width: 100%; height: 400px; display: flex; justify-content: center; align-items: center; overflow: hidden; position: relative;">
+        <svg width="800" height="350" viewBox="0 0 800 350" preserveAspectRatio="xMidYMid meet">
+            <!-- Definitions for markers and gradients -->
+            <defs>
+                <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="0" refY="3.5" orient="auto">
+                    <polygon points="0 0, 10 3.5, 0 7" fill="{text}" />
+                </marker>
+                <linearGradient id="pulse-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+                    <stop offset="0%" stop-color="transparent" />
+                    <stop offset="50%" stop-color="{accent}" />
+                    <stop offset="100%" stop-color="transparent" />
+                </linearGradient>
+            </defs>
+
+            <!-- CONNECTIONS -->
+            <!-- Enhance to OCR -->
+            <path d="M100 175 H200" class="flow-line {get_pulse('enhance')}" stroke="{text}" stroke-width="2" marker-end="url(#arrowhead)" />
+            
+            <!-- OCR to Reasoning -->
+            <path d="M300 175 H400" class="flow-line {get_pulse('ocr')}" stroke="{text}" stroke-width="2" marker-end="url(#arrowhead)" />
+            
+            <!-- Reasoning to Consensus (4 Parallel) -->
+            <path d="M500 100 Q 550 175 600 175" class="flow-line {get_pulse('reasoning')}" stroke="{text}" stroke-width="1.5" />
+            <path d="M500 150 Q 550 175 600 175" class="flow-line {get_pulse('reasoning')}" stroke="{text}" stroke-width="1.5" />
+            <path d="M500 200 Q 550 175 600 175" class="flow-line {get_pulse('reasoning')}" stroke="{text}" stroke-width="1.5" />
+            <path d="M500 250 Q 550 175 600 175" class="flow-line {get_pulse('reasoning')}" stroke="{text}" stroke-width="1.5" />
+
+            <!-- Symbolic Bridge -->
+            <path d="M450 300 Q 450 250 450 250" class="flow-line {get_pulse('verification')}" stroke="{success}" stroke-width="3" stroke-dasharray="5,5" />
+
+            <!-- NODES -->
+            <!-- 1. Input/Enhance -->
+            <rect x="20" y="140" width="80" height="70" rx="10" fill="{bg_color}" style="{get_node_style('enhance')}" />
+            <text x="60" y="180" text-anchor="middle" fill="white" font-size="12">ENHANCE</text>
+            
+            <!-- 2. OCR Module -->
+            <circle cx="250" cy="175" r="45" fill="{bg_color}" style="{get_node_style('ocr')}" />
+            <text x="250" y="180" text-anchor="middle" fill="white" font-size="12">OCR</text>
+
+            <!-- 3. Reasoning Agents (Parallel) -->
+            <g class="{'thinking' if active_phase == 'reasoning' else ''}">
+                <circle cx="450" cy="80" r="25" fill="{bg_color}" style="{get_node_style('reasoning')}" />
+                <circle cx="450" cy="140" r="25" fill="{bg_color}" style="{get_node_style('reasoning')}" />
+                <circle cx="450" cy="200" r="25" fill="{bg_color}" style="{get_node_style('reasoning')}" />
+                <circle cx="450" cy="260" r="25" fill="{bg_color}" style="{get_node_style('reasoning')}" />
+                <text x="450" y="45" text-anchor="middle" fill="{text}" font-size="10">REASONING</text>
+            </g>
+
+            <!-- 4. Verification Bridge (SymPy) -->
+            <rect x="400" y="300" width="100" height="40" rx="5" fill="{bg_color}" style="{get_node_style('verification')}" />
+            <text x="450" y="325" text-anchor="middle" fill="{success}" font-size="10" font-weight="bold">SYMPY CORE</text>
+
+            <!-- 5. Consensus -->
+            <polygon points="650,125 750,175 650,225" fill="{bg_color}" style="{get_node_style('consensus')}" />
+            <text x="680" y="180" text-anchor="middle" fill="white" font-size="12">CONSENSUS</text>
+        </svg>
+        
+        <div style="position: absolute; bottom: 20px; left: 50%; transform: translateX(-50%); font-size: 0.8em; color: {text};">
+            Current Stage: <span style="color: {accent if active_phase != 'success' else success}; font-weight: bold; text-transform: uppercase;">{active_phase}</span>
+        </div>
+    </div>
+    """
+    return html

theme.css

@@ -118,6 +118,39 @@ h2 { font-weight: 600; color: var(--text-main); }
     border-left: 4px solid var(--primary) !important;
 }
 
+/* Architecture Flow Animations */
+.flow-line {
+    stroke-dasharray: 1000;
+    stroke-dashoffset: 1000;
+    animation: none;
+}
+
+.active-pulse {
+    stroke-dashoffset: 0;
+    animation: pulse-flow 2s infinite linear;
+    stroke: var(--primary) !important;
+    opacity: 1;
+}
+
+@keyframes pulse-flow {
+    0% { stroke-dashoffset: 1000; opacity: 0.3; }
+    50% { opacity: 1; }
+    100% { stroke-dashoffset: 0; opacity: 0.3; }
+}
+
+.thinking circle {
+    animation: thinking-pulse 1.5s infinite ease-in-out;
+}
+
+@keyframes thinking-pulse {
+    0%, 100% { transform: scale(1); opacity: 0.8; }
+    50% { transform: scale(1.1); opacity: 1; filter: brightness(1.2); }
+}
+
+.thinking {
+    transform-origin: 450px 175px;
+}
+
 /* Gradio Overrides */
 .stButton button { border-radius: 10px !important; }
 .stMarkdown { color: var(--text-main) !important; }