# Architecture

The auditor is built as a deterministic browser evidence pipeline. A real Chromium session captures what the customer and ad pixels actually experience, then deterministic analyzers score the page. The optional LLM path is deliberately narrow and auditable.

## System Diagram

```mermaid
flowchart TD
    CLI["CLI: run_audit.py --url"] --> Capture["Playwright CaptureRunner"]

    Capture --> Browser["Real Chromium Session"]
    Browser --> Network["Request / Response / Failure Hooks"]
    Browser --> Console["Console + Page Errors"]
    Browser --> DOM["DOM Snapshot Before/After"]
    Browser --> Interaction["Primary Interaction: Add to Cart when safe"]
    Browser --> Artifacts["Screenshots, HAR, Trace, Raw JSON"]

    Network --> Tracking["Tracking Classifier"]
    DOM --> Ecommerce["Shopify / Ecommerce Adapter"]
    Interaction --> Ecommerce

    Tracking --> Analyzer["Deterministic Analyzer"]
    Ecommerce --> Analyzer
    Artifacts --> Analyzer

    Analyzer --> Findings["Findings + Verdict"]
    Analyzer --> Timeline["Event Timeline"]
    Analyzer --> Payloads["Payload Correspondence"]

    Findings --> Report["HTML + JSON Report"]
    Timeline --> Report
    Payloads --> Report

    Analyzer -->|Optional WATCH duplicates only| LLM["Groq Duplicate Judge"]
    LLM --> Log["judgment_log.jsonl"]
    LLM --> Findings
```

## Pipeline

1. **CLI validation**
   - Accepts an absolute `http` or `https` URL.
   - Creates a timestamped run ID.
   - Wires optional Groq duplicate classification only when `--llm-duplicates` is passed.

2. **Browser capture**
   - Launches Chromium through Playwright.
   - Captures requests, responses, failed requests, console messages, page errors, full-page screenshots, HAR, Playwright trace, and DOM snapshots.
   - Stimulates the page with scrolling before extracting product context.
   - Attempts the primary ecommerce action when a recognizable Add-to-Cart control exists.

3. **Tracking classification**
   - Classifies known providers including GTM, GA4, Google Ads, Google Merchant, Meta, TikTok, Shopify/Trekkie/Monorail, WebEngage, Clarity, Criteo, Snapchat, and Taboola.
   - Extracts event names and normalized fields such as value, currency, product id, variant id/title, item name, and SKU.
   - Preserves raw request evidence in the run artifacts.

4. **Ecommerce correspondence**
   - Uses Shopify product JSON, JSON-LD Product schema, visible DOM prices, cart forms, selected variant, SKU, and cart state.
   - Compares detected product truth against tracking payloads.
   - Handles Shopify minor units such as `319900` paise/cents becoming `3199.00`.

5. **Readiness scoring**
   - Emits findings with `BLOCKER`, `HIGH RISK`, `WATCH`, `PASS`, or `UNVERIFIED`.
   - Produces one of `READY`, `READY WITH CAUTION`, or `NOT READY`.
   - Does not pretend when product/cart structure is absent; non-ecommerce pages receive universal checks plus `UNVERIFIED` ecommerce correspondence.

6. **Report generation**
   - Generates an HTML report for stakeholders and a JSON summary for technical review.
   - Copies report screenshots beside HTML so tracked sample reports are portable.

## Key Files

- `auditor/capture.py` - Playwright browser capture and interaction
- `auditor/tracking.py` - provider/event/payload classification
- `auditor/ecommerce.py` - product/cart truth extraction
- `auditor/analyze.py` - deterministic findings and verdicts
- `auditor/llm.py` - optional Groq duplicate judge
- `auditor/report.py` - report rendering and portable screenshot assets
- `auditor/templates/report.html.j2` - stakeholder HTML report template
- `tests/` - regression tests for tracking, ecommerce, analyzer, and LLM boundaries

## Trust Boundaries

- Deterministic checks decide all hard facts: request presence, status, payload values, product truth, duplicate timing, and verdict.
- Groq is optional and only classifies ambiguous duplicate intent after deterministic evidence has already identified a repeated event.
- Server-side conversion APIs and ad-platform account diagnostics are outside local browser visibility and are documented as limitations.