============
Architecture
============

MemGuard is organized into five layers.

.. code-block:: text

   memguard/
   ├── core/                  # Layer 1: Detection Engine
   │   ├── schema.py          # Pydantic data models
   │   ├── runner.py          # Async tool orchestrator + MemHint injection
   │   ├── parsers.py         # Unified parsers (XML, JSON, text → MemoryError)
   │   ├── symbolizers.py     # addr2line / llvm-symbolizer
   │   ├── visualizer.py      # Interactive HTML visualization (4 tabs)
   │   ├── hardening.py       # Binary security audit (8 checks)
   │   ├── timetravel.py      # rr/GDB recording, replay, AI commands
   │   ├── memhint.py         # Neuro-symbolic pipeline (LLM + Z3)
   │   ├── heaptrack.py       # KDE heaptrack integration
   │   └── taintflow.py       # Input taint flow tracker (6-phase)
   ├── ai/                    # Layer 2: AI Pipeline
   │   ├── client.py          # Ollama HTTP client + JSON escape fixer
   │   ├── analyzer.py        # 4-pass analysis + 3 validators + MemHint context
   │   └── explainability.py  # Reasoning chains, backtracking, 161 CVE database
   ├── pipeline/              # Layer 3: Orchestration
   │   └── orchestrator.py    # Scan pipeline coordinator
   ├── cli/main.py            # Layer 4: CLI (20+ Typer commands)
   └── api/                   # Layer 4: Web Dashboard
       ├── server.py          # FastAPI + WebSocket + HTML
       └── static/app.js      # Frontend (vanilla JS)

Data Flow
---------

.. code-block:: text

   Source/Binary
        │
   [MemHint: tree-sitter → LLM → Z3] → summaries.json
        │                                      │
   [Runner: Valgrind | Helgrind | Infer(+summaries) | cppcheck]
        │
   [Parsers: XML/JSON → MemoryError objects]
        │
   [AI: Triage → Deep → Fix → Steps] (+MemHint context)
        │
   [Validators: Fix | CWE | Z3]
        │
   [Taint Flow | CVE | Hardening | Viz | Relationships]
        │
   [CLI (Rich) | Web (FastAPI+WS) | HTML Viz]

Key Design Decisions
--------------------

- **Unified MemoryError schema** - all tools normalized to same Pydantic objects
- **Async pipeline** - tools run in parallel via asyncio with timeout protection
- **MemHint auto-injection** - summaries loaded from disk into both Infer and AI prompts
- **Fix validation pipeline** - pattern validator + CWE validator + Z3 verifier
- **Variable-level taint** - tracks taint at variable granularity with 5 edge types