pyplaykit 1.20.0__tar.gz → 1.20.2__tar.gz

{pyplaykit-1.20.0 → pyplaykit-1.20.2}/CHANGELOG.md

@@ -11,6 +11,26 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.20.2] — 2026-08-19
+
+### Documentation
+
+- **Comprehensive architecture documentation** — added `docs/ARCHITECTURE.md`, a living multi-view reference with 9 Mermaid diagrams (layered overview, runtime fixture lifecycle, test/page/resilience flow, config & multi-project resolution, DB stack & data-comparison, plugins/orchestration/observability/integrations, MCP server, security posture, repository map).
+- **Regenerated architecture SVGs to match the current implementation** — `docs/diagrams/architecture_overview.svg` now shows the real 9-layer dependency stack plus the plugins/orchestration/resilience cross-cutting layers, the MCP read-only sidecar, and a security & governance rail; dropped the unsupported "Mobile/Desktop" target. `docs/diagrams/data_comparison_flow.svg` was re-laid-out to remove overlapping boxes/labels and corrected to the real `ComparisonProfile` fields.
+- **New security posture diagram** — `docs/diagrams/security_posture.svg` documents defense-in-depth: runtime secrets/masking/auth controls plus the bandit / pip-audit / gitleaks CI scanning pipeline (with `security_plugin.py` shown honestly as a stub/extension point).
+- **Fixed SVG rendering** — escaped raw `&` characters that caused `xmlParseEntityRef` parse errors when opening the SVGs in a browser.
+- **README diagram embeds for PyPI** — added inline PNG previews (rendered via new `scripts/svg_to_png.py`) that display on the PyPI page and link to the crisp SVG sources.
+
+---
+
+## [1.20.1] — 2026-08-17
+
+### Fixed
+
+- **`BasePage.wait_for_url_contains()` no longer raises `value must be a string or regular expression`** — it previously called `expect(page).to_have_url(lambda url: url_part in url)`, but Playwright's `to_have_url()` only accepts a string or regex, not a predicate. It now uses Playwright's native `page.wait_for_url(f"**{url_part}**")` glob pattern, which matches the partial path regardless of scheme, host, or trailing query string.
+
+---
+
 ## [1.20.0] — 2026-08-14
 
 ### Added

{pyplaykit-1.20.0/pyplaykit.egg-info → pyplaykit-1.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyplaykit
-Version: 1.20.0
+Version: 1.20.2
 Summary: Enterprise Python + Playwright automation framework
 Author-email: Shan Konduru <shankonduru@gmail.com>
 License: MIT
@@ -207,6 +207,22 @@ tests/
 8. **Resilience Layer** (`resilience/`) - Self-healing locator resolution
 9. **Integration Layer** (`integrations/`) - Jira and test management adapters
 
+### Architecture Diagrams
+
+**Architecture Overview** — the full layered dependency stack, cross-cutting layers (plugins, orchestration, resilience), the MCP read-only sidecar, and the security & governance rail:
+
+[![PyPlayKit Architecture Overview](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/architecture_overview.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/architecture_overview.svg)
+
+**Data Comparison Flow** — config-driven Excel / CSV / DB comparison: sources → loader → comparison engine → result + HTML report:
+
+[![Data Comparison Flow](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/data_comparison_flow.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/data_comparison_flow.svg)
+
+**Security Posture** — defense-in-depth: runtime secrets/masking/auth controls plus the bandit / pip-audit / gitleaks CI scanning pipeline:
+
+[![Security Posture](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/security_posture.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/security_posture.svg)
+
+> Each image is a PNG (renders inline on PyPI and GitHub) and links to the crisp, zoomable **SVG** source. See also the **[Full Architecture Reference](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/ARCHITECTURE.md)** — 9 Mermaid views covering layers, runtime lifecycle, config resolution, data engineering, plugins/observability, MCP, and security. Regenerate PNGs after editing an SVG with `python scripts/svg_to_png.py`.
+
 ---
 
 ## Project Structure

{pyplaykit-1.20.0 → pyplaykit-1.20.2}/README.md

@@ -110,6 +110,22 @@ tests/
 8. **Resilience Layer** (`resilience/`) - Self-healing locator resolution
 9. **Integration Layer** (`integrations/`) - Jira and test management adapters
 
+### Architecture Diagrams
+
+**Architecture Overview** — the full layered dependency stack, cross-cutting layers (plugins, orchestration, resilience), the MCP read-only sidecar, and the security & governance rail:
+
+[![PyPlayKit Architecture Overview](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/architecture_overview.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/architecture_overview.svg)
+
+**Data Comparison Flow** — config-driven Excel / CSV / DB comparison: sources → loader → comparison engine → result + HTML report:
+
+[![Data Comparison Flow](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/data_comparison_flow.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/data_comparison_flow.svg)
+
+**Security Posture** — defense-in-depth: runtime secrets/masking/auth controls plus the bandit / pip-audit / gitleaks CI scanning pipeline:
+
+[![Security Posture](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/security_posture.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/security_posture.svg)
+
+> Each image is a PNG (renders inline on PyPI and GitHub) and links to the crisp, zoomable **SVG** source. See also the **[Full Architecture Reference](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/ARCHITECTURE.md)** — 9 Mermaid views covering layers, runtime lifecycle, config resolution, data engineering, plugins/observability, MCP, and security. Regenerate PNGs after editing an SVG with `python scripts/svg_to_png.py`.
+
 ---
 
 ## Project Structure

{pyplaykit-1.20.0 → pyplaykit-1.20.2}/core/base_page.py

@@ -23,8 +23,15 @@ class BasePage:
         self.page.goto(url, wait_until="domcontentloaded")
 
     def wait_for_url_contains(self, url_part: str) -> None:
-        """Wait until current page URL contains expected partial value."""
-        expect(self.page).to_have_url(lambda current_url: url_part in current_url)
+        """Wait until the current page URL contains ``url_part``.
+
+        Uses Playwright's native :meth:`Page.wait_for_url` with a glob pattern.
+        ``to_have_url`` only accepts a string or regex — passing a predicate
+        raises ``value must be a string or regular expression`` — so we wrap
+        ``url_part`` in ``**`` wildcards to match any surrounding URL segments
+        (scheme, host, trailing query string, etc.).
+        """
+        self.page.wait_for_url(f"**{url_part}**")
 
     def wait_for_visible(
         self,

pyplaykit-1.20.2/docs/ARCHITECTURE.md

@@ -0,0 +1,457 @@
+# PyPlayKit — Architecture
+
+> Comprehensive architecture reference for the PyPlayKit enterprise test‑automation framework.
+> Diagrams are authored in [Mermaid](https://mermaid.js.org/) and render natively on GitHub.
+> Keep this file in sync with the code — it is the living architecture document.
+
+**Contents**
+
+1. [Layered Architecture Overview](#1-layered-architecture-overview)
+2. [Runtime Fixture Lifecycle](#2-runtime-fixture-lifecycle)
+3. [Test → Page → Resilience Execution Flow](#3-test--page--resilience-execution-flow)
+4. [Configuration & Multi‑Project Resolution](#4-configuration--multi-project-resolution)
+5. [Data Engineering: DB Stack & Data Comparison](#5-data-engineering-db-stack--data-comparison)
+6. [Plugins, Orchestration, Observability & Integrations](#6-plugins-orchestration-observability--integrations)
+7. [MCP Server & CLI](#7-mcp-server--cli)
+8. [Security Posture](#8-security-posture)
+9. [Repository Map](#9-repository-map)
+
+---
+
+## 1. Layered Architecture Overview
+
+The framework enforces a strict layered architecture. Higher layers depend downward only;
+cross‑cutting concerns (plugins, resilience, observability, integrations) attach to the core flow.
+
+```mermaid
+flowchart TB
+    subgraph AUT["Applications Under Test"]
+        direction LR
+        SD["SauceDemo"]
+        OHRM["OrangeHRM"]
+        PROJ["Multi-project apps<br/>(customers_modernization,<br/>dispatcho, timelyquote)"]
+    end
+
+    subgraph TEST["1 · Test Layer — tests/"]
+        direction LR
+        TF["functional / integration"]
+        TP["projects/*"]
+        TU["unit/*"]
+    end
+
+    subgraph PAGE["2 · Page Object & Component Layer — pages/ · components/"]
+        direction LR
+        PO["Page Objects<br/>login, dashboard, inventory…"]
+        COMP["Reusable Components<br/>data_table, form_field, modal"]
+    end
+
+    subgraph CORE["3 · Core Engine Layer — core/"]
+        direction LR
+        PM["PlaywrightManager<br/>(session)"]
+        BF["BrowserFactory<br/>(per test)"]
+        BP["BasePage / BaseTest"]
+    end
+
+    subgraph UTIL["4 · Utilities Layer — utils/"]
+        direction LR
+        UAPI["API/GraphQL/SOAP clients"]
+        UDB["DB stack + comparison"]
+        UDATA["data_loader · tdm · validators"]
+        UOBS["logger · observability · screenshots"]
+    end
+
+    subgraph CONF["5 · Configuration Layer — config/"]
+        direction LR
+        CY["config.yaml"]
+        CE["environments.yaml"]
+        CP["projects/*  ·  comparison_profiles"]
+    end
+
+    subgraph XCUT["Cross-Cutting Layers"]
+        direction LR
+        PLUG["6 · Plugins<br/>plugins/"]
+        ORCH["7 · Orchestration<br/>orchestration/"]
+        RES["8 · Resilience<br/>resilience/"]
+        INTG["9 · Integrations<br/>integrations/"]
+        MCP["MCP Server<br/>mcp_server/"]
+    end
+
+    AUT --> TEST
+    TEST --> PAGE
+    PAGE --> CORE
+    PAGE --> COMP
+    CORE --> UTIL
+    TEST --> UTIL
+    UTIL --> CONF
+    CORE --> CONF
+
+    PLUG -. hooks .-> TEST
+    ORCH -. suite planning .-> TEST
+    RES  -. self-healing .-> CORE
+    INTG -. export .-> UOBS
+    MCP  -. read-only introspection .-> CONF
+    MCP  -. read-only introspection .-> TEST
+
+    classDef aut fill:#fef3c7,stroke:#d97706,color:#78350f;
+    classDef test fill:#dbeafe,stroke:#2563eb,color:#1e3a8a;
+    classDef page fill:#e0e7ff,stroke:#4f46e5,color:#312e81;
+    classDef core fill:#dcfce7,stroke:#16a34a,color:#14532d;
+    classDef util fill:#f1f5f9,stroke:#475569,color:#0f172a;
+    classDef conf fill:#fae8ff,stroke:#a21caf,color:#701a75;
+    classDef xcut fill:#ffe4e6,stroke:#e11d48,color:#881337;
+    class SD,OHRM,PROJ aut;
+    class TF,TP,TU test;
+    class PO,COMP page;
+    class PM,BF,BP core;
+    class UAPI,UDB,UDATA,UOBS util;
+    class CY,CE,CP conf;
+    class PLUG,ORCH,RES,INTG,MCP xcut;
+```
+
+---
+
+## 2. Runtime Fixture Lifecycle
+
+`conftest.py` wires the entire runtime. This sequence shows session start → per‑test execution → session teardown,
+including how the plugin registry and observability tracker are stashed on the pytest `config` object.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant CLI as pytest CLI<br/>(--pyplaykit-*)
+    participant CF as conftest.py
+    participant RO as runtime_options
+    participant PR as PluginRegistry
+    participant OT as ObservabilityTracker
+    participant PM as PlaywrightManager
+    participant T as Test Function
+    participant BF as BrowserFactory
+    participant PG as Page Object
+
+    Note over CLI,CF: Session start (session-scoped fixtures)
+    CLI->>CF: pytest_addoption / collection
+    CF->>RO: resolve config + CLI overrides<br/>(env, browser, base_url, tdm_policy,<br/>resilience_policy)
+    CF->>PR: build & on_session_start()
+    CF->>OT: create tracker (setattr on config)
+    CF->>PM: launch Playwright runtime
+
+    loop Each test
+        Note over CF,PG: Function-scoped fixtures
+        CF->>BF: create browser (per test)
+        BF->>BF: new isolated context
+        BF->>PG: new page
+        CF->>T: inject page, runtime_options,<br/>db_client, auth_token, logger…
+        T->>PG: high-level page actions
+        PG-->>T: results / assertions
+        CF->>CF: pytest_runtest_makereport
+        CF->>OT: record outcome + classify failure
+        CF->>PR: on_test_result(hook)
+        alt failure
+            CF->>CF: capture_artifacts_on_failure<br/>(screenshot / video)
+        end
+    end
+
+    Note over CF,OT: Session teardown
+    CF->>PR: on_session_finish()
+    CF->>OT: write observability + KPI + persona reports
+    CF->>PM: stop Playwright
+```
+
+---
+
+## 3. Test → Page → Resilience Execution Flow
+
+How a test action flows through `BasePage` into Playwright, with the optional self‑healing locator path
+(disabled by default; enabled via `resilience.enabled`).
+
+```mermaid
+flowchart TB
+    T["Test calls page method<br/>e.g. login_page.login(user, pass)"] --> BP["BasePage action<br/>click / fill / text / wait_for_visible"]
+    BP --> POL{"resilience_policy<br/>enabled?"}
+
+    POL -- No --> DIRECT["Direct Playwright locator<br/>page.locator(selector)"]
+    POL -- Yes --> RES["resolve_visible_locator()"]
+
+    RES --> P1["Try primary selector"]
+    P1 --> OK1{"visible?"}
+    OK1 -- Yes --> DONE["Return locator<br/>confidence = 1.0"]
+    OK1 -- No --> FB["Iterate fallback_selectors<br/>(confidence decays per hop)"]
+    FB --> RETRY["DOM retry loop<br/>(dom_retry_count)"]
+    RETRY --> OK2{"resolved?"}
+    OK2 -- Yes --> AUDIT["Write recovery_audit.jsonl<br/>+ decayed confidence"]
+    OK2 -- No --> FAIL["Raise / timeout"]
+    AUDIT --> DONE
+
+    DIRECT --> ACT["Perform action"]
+    DONE --> ACT
+    ACT --> ASSERT["Assertions via<br/>utils/assertion_helper"]
+
+    classDef start fill:#dbeafe,stroke:#2563eb;
+    classDef res fill:#ffe4e6,stroke:#e11d48;
+    classDef ok fill:#dcfce7,stroke:#16a34a;
+    class T,BP start;
+    class RES,P1,FB,RETRY,AUDIT res;
+    class DONE,ACT,ASSERT ok;
+```
+
+---
+
+## 4. Configuration & Multi‑Project Resolution
+
+Config is layered and CLI‑overridable. Multi‑project support lets one framework instance target
+several applications, each with its own pages, test data, and environment config.
+
+```mermaid
+flowchart LR
+    subgraph SRC["Config Sources (lowest → highest precedence)"]
+        direction TB
+        D["config/config.yaml<br/>framework defaults"]
+        E["config/environments.yaml<br/>per-env URLs & settings"]
+        P["config/projects/*<br/>per-project overrides"]
+        ENV["Environment variables<br/>${PYPLAYKIT_*} credentials"]
+        CLI["CLI flags<br/>--pyplaykit-env / -browser /<br/>-base-url / -headed"]
+    end
+
+    D --> RO["runtime_options fixture<br/>(resolved config)"]
+    E --> RO
+    P --> RO
+    ENV --> RO
+    CLI --> RO
+
+    RO --> CR["ConfigReader<br/>(env-aware .get())"]
+    RO --> Test["Tests & Pages"]
+
+    subgraph PROJECTS["Multi-Project Fan-out"]
+        direction TB
+        PGD["pages/{customers_modernization,<br/>dispatcho, timelyquote}"]
+        TDD["test_data/{...}"]
+        TPD["tests/projects/*"]
+    end
+    CR --> PROJECTS
+
+    classDef src fill:#fae8ff,stroke:#a21caf;
+    class D,E,P,ENV,CLI src;
+```
+
+---
+
+## 5. Data Engineering: DB Stack & Data Comparison
+
+PyPlayKit ships a multi‑engine database stack plus a data‑comparison engine used for
+data‑migration / ETL validation (Excel ↔ CSV ↔ DB in any direction), driven by declarative profiles.
+
+### 5a. Database stack
+
+```mermaid
+flowchart TB
+    FIX["db_pool / db_client fixtures<br/>(conftest.py)"] --> POOL["DbConnectionPool<br/>utils/db_pool.py"]
+    POOL --> FACT["DbClientFactory<br/>utils/db_factory.py"]
+    FACT --> DRV["utils/db_drivers/*<br/>(lazy-imported)"]
+
+    DRV --> PG["postgresql · psycopg2"]
+    DRV --> SL["sqlite · stdlib"]
+    DRV --> MY["mysql"]
+    DRV --> MS["sqlserver · pyodbc"]
+    DRV --> OR["oracle"]
+    DRV --> D2["db2"]
+    DRV --> IN["informix"]
+    DRV --> SN["snowflake"]
+
+    FIX --> TX["db_transaction / db_seed / db_clean<br/>(test data lifecycle)"]
+
+    classDef db fill:#dcfce7,stroke:#16a34a;
+    class PG,SL,MY,MS,OR,D2,IN,SN db;
+```
+
+### 5b. Data comparison & validation flow
+
+```mermaid
+flowchart LR
+    subgraph SOURCES["Data Sources — utils/data_source.py"]
+        XL["Excel"]
+        CSV["CSV"]
+        DB["Database"]
+    end
+
+    PROF["Comparison Profile<br/>config/data_comparison_profiles.yaml<br/>→ comparison_config_loader"] --> CMP
+
+    subgraph CMP["data_comparison_utils.py"]
+        direction TB
+        MAP["_apply_column_mapping"]
+        KEY["_build_row_key (key columns)"]
+        COMPARE["compare_* (excel/csv/db,<br/>any direction) → ComparisonResult"]
+    end
+
+    SOURCES --> CMP
+    MAP --> KEY --> COMPARE
+
+    COMPARE --> TV["TransformationValidator<br/>ColumnSpec / RowRule / PairRule"]
+    COMPARE --> UIDB["UIDbValidator<br/>(UI ↔ DB reconciliation)"]
+    COMPARE --> RPT["data_comparison_report<br/>+ tolerances → HTML/JSON report"]
+
+    classDef s fill:#fef3c7,stroke:#d97706;
+    class XL,CSV,DB s;
+```
+
+---
+
+## 6. Plugins, Orchestration, Observability & Integrations
+
+The cross‑cutting layers that wrap the test session. All are config‑gated and disabled by default.
+
+```mermaid
+flowchart TB
+    subgraph PLUGINS["Plugin Layer — plugins/"]
+        REG["PluginRegistry<br/>BUILTIN_PLUGIN_FACTORIES"]
+        API["api_plugin"]
+        DATA["data_plugin"]
+        SEC["security_plugin"]
+        REG --> API & DATA & SEC
+    end
+
+    subgraph HOOKS["Lifecycle Hooks (FrameworkPlugin)"]
+        H1["on_session_start"]
+        H2["on_test_result"]
+        H3["on_session_finish"]
+    end
+    REG --> HOOKS
+
+    subgraph ORCH["Orchestration — orchestration/"]
+        PLAN["planner.build_orchestration_plan()<br/>dependency graph + cycle detection"]
+        ENF["enforcer<br/>stage-based execution constraints"]
+        PLAN --> ENF
+    end
+
+    subgraph OBS["Observability — utils/observability*"]
+        TRK["ObservabilityTracker<br/>outcomes · duration · failure class"]
+        FLAKY["flaky detection"]
+        PERS["persona reports:<br/>engineering / qa / leadership"]
+        TRK --> FLAKY --> PERS
+    end
+
+    subgraph INTG["Integrations — integrations/adapters.py"]
+        JIRA["Jira adapter"]
+        TMS["Test management adapter"]
+    end
+
+    HOOKS --> TRK
+    PERS --> INTG
+    PERS --> REPORTS["reports/observability/*.json"]
+    JIRA & TMS --> IEXP["reports/integrations/*.json"]
+
+    classDef p fill:#ffe4e6,stroke:#e11d48;
+    class REG,API,DATA,SEC,PLAN,ENF,TRK,FLAKY,PERS,JIRA,TMS p;
+```
+
+---
+
+## 7. MCP Server & CLI
+
+`mcp_server/` exposes 11 read‑only introspection tools over the Model Context Protocol for AI assistants,
+each also available as a `pyplaykit-mcp` CLI subcommand. Tools are grouped into three categories.
+
+```mermaid
+flowchart LR
+    AI["AI Assistant<br/>(Claude / Copilot)"] -->|MCP| SRV["mcp_server/server.py"]
+    TERM["Terminal / AI IDE"] -->|subcommand| CLIe["mcp_server/cli.py"]
+    SRV --> TOOLS
+    CLIe --> TOOLS
+
+    subgraph TOOLS["mcp_server/tools/"]
+        direction TB
+        subgraph PD["package_discovery"]
+            T1["list_utilities"]
+            T2["get_module_api"]
+            T3["search_methods"]
+            T4["get_base_page_api"]
+        end
+        subgraph PI["project_introspection"]
+            T5["summarize_project"]
+            T6["list_tests"]
+            T7["list_pages"]
+        end
+        subgraph PS["project_state"]
+            T8["get_test_results"]
+            T9["get_config"]
+            T10["check_environment_readiness"]
+            T11["get_comparison_profiles"]
+        end
+    end
+
+    PD -. reads .-> CODE["source + AST<br/>(_ast_utils)"]
+    PI -. reads .-> PROJ["pages / tests"]
+    PS -. reads .-> STATE["config · reports ·<br/>live HTTP check"]
+
+    classDef mcp fill:#e0e7ff,stroke:#4f46e5;
+    class T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11 mcp;
+```
+
+---
+
+## 8. Security Posture
+
+Security is **cross-cutting** — it is not a single module but a set of controls that touch config, runtime,
+and CI. See also the rendered diagram: [`docs/diagrams/security_posture.svg`](diagrams/security_posture.svg).
+
+```mermaid
+flowchart TB
+    subgraph RUNTIME["Runtime security — every test session"]
+        direction LR
+        SEC["1 · Secrets & Config<br/>env-var creds only ·<br/>${ENV_VAR} placeholders ·<br/>no hardcoded secrets"]
+        DP["2 · Data Protection<br/>tdm.mask_value/mask_record<br/>(full · partial) · masking_rules ·<br/>deterministic synthetic data"]
+        AUTH["3 · Authentication<br/>AuthTokenManager · Bearer<br/>lazy fetch + cache ·<br/>401 auto-refresh"]
+    end
+
+    subgraph CI["Static & supply-chain scanning — CI / on-demand"]
+        direction LR
+        BANDIT["bandit — Python SAST"]
+        AUDIT["pip-audit — dependency CVEs"]
+        LEAKS["gitleaks — secrets (dir + git history)"]
+    end
+
+    RUN["scripts/run_security_reports.{sh,bat}<br/>(self-bootstrapping venv)"] --> CI
+    BANDIT & AUDIT & LEAKS --> RPT["Consolidated HTML + per-tool json<br/>reports/secutiry_reports/"]
+    RPT --> GATE["Triage & gate:<br/>remediate / suppress ·<br/>block release on high severity"]
+
+    EXT["plugins/security_plugin.py<br/>(lifecycle-hook stub — extension point)"] -. wire via PluginRegistry .-> RUNTIME
+
+    classDef sec fill:#fef2f2,stroke:#dc2626,color:#7f1d1d;
+    classDef scan fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d;
+    class SEC,DP,AUTH sec;
+    class BANDIT,AUDIT,LEAKS scan;
+```
+
+> **Honest scope note:** `plugins/security_plugin.py` is currently a registered *extension point* (a stub),
+> not a working scanner. The active scanning is the bandit / pip-audit / gitleaks pipeline above. DAST,
+> auth fuzzing, and in-run security assertions are not implemented — wire them through the plugin hook if needed.
+
+---
+
+## 9. Repository Map
+
+```mermaid
+flowchart LR
+    ROOT["pyplaykit/"] --> C["core/ — Playwright lifecycle, BasePage/BaseTest"]
+    ROOT --> PG["pages/ — page objects (+ per-project subdirs)"]
+    ROOT --> CO["components/ — reusable UI components"]
+    ROOT --> U["utils/ — clients, DB stack, comparison, tdm, observability"]
+    ROOT --> CFG["config/ — config.yaml, environments.yaml, projects/, profiles"]
+    ROOT --> PL["plugins/ — registry + api/data/security plugins"]
+    ROOT --> OR["orchestration/ — planner + enforcer"]
+    ROOT --> RE["resilience/ — locator_recovery"]
+    ROOT --> IN["integrations/ — Jira / TMS adapters"]
+    ROOT --> MC["mcp_server/ — server, cli, tools/"]
+    ROOT --> TE["tests/ — functional, integration, projects, unit"]
+    ROOT --> TD["test_data/ — fixtures (+ per-project subdirs)"]
+    ROOT --> DO["docs/ — guides + diagrams/"]
+    ROOT --> RP["reports/ — coverage, observability, screenshots, videos"]
+    ROOT --> CT["conftest.py — fixture wiring & pytest hooks"]
+```
+
+---
+
+### Diagram maintenance
+
+- **Source of truth:** this file. When you add a layer, plugin, driver, or MCP tool, update the relevant diagram here.
+- **Rendering:** GitHub, VS Code (Mermaid preview), and most IDEs render these blocks inline.
+- **Legacy SVGs:** `docs/diagrams/architecture_overview.svg` and `docs/diagrams/data_comparison_flow.svg` remain for slide/README embedding.

{pyplaykit-1.20.0 → pyplaykit-1.20.2/pyplaykit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyplaykit
-Version: 1.20.0
+Version: 1.20.2
 Summary: Enterprise Python + Playwright automation framework
 Author-email: Shan Konduru <shankonduru@gmail.com>
 License: MIT
@@ -207,6 +207,22 @@ tests/
 8. **Resilience Layer** (`resilience/`) - Self-healing locator resolution
 9. **Integration Layer** (`integrations/`) - Jira and test management adapters
 
+### Architecture Diagrams
+
+**Architecture Overview** — the full layered dependency stack, cross-cutting layers (plugins, orchestration, resilience), the MCP read-only sidecar, and the security & governance rail:
+
+[![PyPlayKit Architecture Overview](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/architecture_overview.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/architecture_overview.svg)
+
+**Data Comparison Flow** — config-driven Excel / CSV / DB comparison: sources → loader → comparison engine → result + HTML report:
+
+[![Data Comparison Flow](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/data_comparison_flow.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/data_comparison_flow.svg)
+
+**Security Posture** — defense-in-depth: runtime secrets/masking/auth controls plus the bandit / pip-audit / gitleaks CI scanning pipeline:
+
+[![Security Posture](https://raw.githubusercontent.com/ShanKonduru/pyplaykit/master/docs/diagrams/security_posture.png)](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/diagrams/security_posture.svg)
+
+> Each image is a PNG (renders inline on PyPI and GitHub) and links to the crisp, zoomable **SVG** source. See also the **[Full Architecture Reference](https://github.com/ShanKonduru/pyplaykit/blob/master/docs/ARCHITECTURE.md)** — 9 Mermaid views covering layers, runtime lifecycle, config resolution, data engineering, plugins/observability, MCP, and security. Regenerate PNGs after editing an SVG with `python scripts/svg_to_png.py`.
+
 ---
 
 ## Project Structure

{pyplaykit-1.20.0 → pyplaykit-1.20.2}/pyplaykit.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ demo/functional/database/postgres_src_tgt/README.md
 dist_pkg/__init__.py
 dist_pkg/distribution.py
 docs/API_TESTING_GUIDE.md
+docs/ARCHITECTURE.md
 docs/CLI_REFERENCE.md
 docs/COMPETITIVE_ANALYSIS.md
 docs/COVERAGE_IMPROVEMENTS.md

{pyplaykit-1.20.0 → pyplaykit-1.20.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyplaykit"
-version = "1.20.0"
+version = "1.20.2"
 description = "Enterprise Python + Playwright automation framework"
 readme = "README.md"
 license = { text = "MIT" }