Venruk E2E Architectural Workflow

flowchart TB
    %% Styling Definitions
    classDef surface fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#4c1d95;
    classDef pipeline fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0369a1;
    classDef store fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f;
    classDef intelligence fill:#ccfbf1,stroke:#0d9488,stroke-width:2px,color:#134e4a;
    classDef reasoning fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
    classDef ai fill:#fce7f3,stroke:#db2777,stroke-width:2px,color:#be185d;
    classDef legend fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,color:#374151;

    %% 1. Product Surface (CLI & Dashboard UI)
    subgraph SURFACE ["1. Product Surface & Entry Points"]
        cli_scan["CLI Entry Points
(venruk scan / watch / review-pr / sbom)"]:::surface
        web_dash["Web Dashboard UI
(FastAPI Backend Server & Next.js UI)"]:::surface
        ide_ext["IDE Extensions & MCP Server
(workspace/ide.py & mcp_server.py)"]:::surface
        git_hooks["Git Hooks & CI/CD Gateways
(ci_gateway.py & github_app)"]:::surface
    end

    %% 2. Ingest & Core Scan Pipeline
    subgraph PIPELINE ["2. Core Ingest & 6-Stage Scan Pipeline"]
        stages_disc["Stage 1: Discovery
(discovery.py: file filtering & globbing)"]:::pipeline
        stages_scan["Stage 2: Scanners
(scanning.py: SAST, Secrets, Quality, Deps)"]:::pipeline
        stages_corr["Stage 3: Correlation
(correlation.py: finding clustering & de-duplication)"]:::pipeline
        stages_graph["Stage 4: Graph Analysis
(graph.py & reachability_analyzer.py)"]:::pipeline
        stages_enrich["Stage 5: Enrichment
(enrichment.py: CWE, CVSS & Threat Intel)"]:::pipeline
        stages_risk["Stage 6: Risk Attribution
(risk.py: ScoreCard & ScanResult build)"]:::pipeline
        
        stages_disc --> stages_scan --> stages_corr --> stages_graph --> stages_enrich --> stages_risk
    end

    %% 3. Persistence Layer
    subgraph STORAGE ["3. Persistence & Append-Only Stores"]
        fs_store[("FilesystemStore
(JSONL ScanResult storage)")]:::store
        mem_store[("EngineeringMemoryStore
(Decision history & fingerprints)")]:::store
        rem_store[("RemediationStore
(RemediationRecords & patches)")]:::store
        pol_store[("PolicyStore
(CompiledPolicy configurations)")]:::store
        ai_store[("AIUsageTracker
(All router LLM call logs)")]:::store
    end

    %% 4. Workspace & Projection Engine
    subgraph WORKSPACE ["4. Dynamic Workspace & BFF Projection Layer"]
        ws_build["Workspace Builder
(builder.py: build Workspace object)"]:::intelligence
        ws_proj["Workspace Projection
(engineering_projection.py: user views)"]:::intelligence
        tier_gate["TierFeatureGate
(controls Static/Adaptive modes accessibility)"]:::intelligence
        comp_eng["Experience Engine / Composition
(dashboard.py: widget prioritization)"]:::intelligence
        
        ws_build --> ws_proj --> comp_eng
        tier_gate --> ws_proj
    end

    %% 5. Reasoning & Remediation Engine
    subgraph REASONING ["5. Reasoning, Policy & Remediation Platform"]
        explain_eng["Explainability Engine
(explainability.py: snapshot paths)"]:::reasoning
        predict_eng["Prediction Engine
(prediction_engine.py: risk forecasts)"]:::reasoning
        decision_eng["Decision Intelligence
(decision_intelligence.py: fix_roi_score)"]:::reasoning
        policy_compiler["Policy Compiler & Engine
(standards.py: compiles NL policy)"]:::reasoning
        rem_eng["Autonomous Remediation Engine
(engine.py: autofix patches validation)"]:::reasoning
        
        explain_eng --> decision_eng
        predict_eng --> decision_eng
        rem_eng --> decision_eng
        policy_compiler --> explain_eng
    end

    %% 6. Copilot & GenAI Engine
    subgraph COPILOT ["6. Copilot & Multi-Model AI Router"]
        router["AI Model Router
(ModelRouter: selects economy/premium)"]:::ai
        cop_kernel["Copilot Kernel & Planner
(kernel.py & planner.py: sessions)"]:::ai
        skills_reg["Skill Registry
(skills/: maps specialist prompt tools)"]:::ai
        provider_int["LLM Providers
(Ollama / DeepSeek / OpenAI / Anthropic)"]:::ai
        
        cop_kernel --> skills_reg --> router --> provider_int
    end

    %% DATA FLOWS (Represented by solid arrows)
    cli_scan -->|Initiates Scan Task| stages_disc
    git_hooks -->|Triggers PR Scan Event| stages_disc
    stages_risk -->|Serializes and Saves| fs_store
    fs_store -->|Reads latest ScanResult| ws_build
    ws_build -->|Provides IntelligenceBundle| ws_proj
    ws_proj -->|Feeds 65 WidgetDTOs with badges| web_dash
    
    web_dash -->|Requests Layout Composition| comp_eng
    ide_ext <-->|Queries active WorkspaceProjection| ws_proj
    
    %% EVENT FLOWS (Represented by dotted arrows)
    stages_corr -.->|Saves fingerprint signatures| mem_store
    stages_enrich -.->|Triggers fingerprint engine| mem_store
    
    ws_proj -.->|Requests ScoredPrediction| predict_eng
    ws_proj -.->|Requests Explainability Trace| explain_eng
    ws_proj -.->|Queries Decision Intelligence Queue| decision_eng
    
    web_dash -.->|Authorizes Auto-Fix Patch| rem_eng
    rem_eng -.->|Appends RemediationRecord| rem_store
    web_dash -.->|Requests Policy Compilation| policy_compiler
    policy_compiler -.->|Saves CompiledPolicy| pol_store
    
    web_dash -.->|Queries Conversational AI| cop_kernel
    ide_ext -.->|Sends prompt message| cop_kernel
    
    router -.->|Logs usage record| ai_store
    
    decision_eng -.->|Ranks and selects fixes| rem_eng
    rem_eng -.->|Applies codebase fix patch| ws_build

    %% Legend Definition
    subgraph LEGEND ["Diagram Legend & Color Key"]
        l_surf["Surface / UX Points"]:::surface
        l_pipe["Core Ingestion Pipeline"]:::pipeline
        l_store["Persistence Tier"]:::store
        l_intel["Workspace & BFF Projections"]:::intelligence
        l_reas["Reasoning & Decision Systems"]:::reasoning
        l_ai["AI Routing & Copilot Layer"]:::ai
        l_dataflow["Data Flow (Solid)"]:::legend
        l_eventflow["Event Flow (Dashed)"]:::legend
    end