# vuongdiensharing-performance/google-ads-performance-skills architecture

> Architecture diagram of the GitHub repository vuongdiensharing-performance/google-ads-performance-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vuongdiensharing-performance/google-ads-performance-skills
- Repository: https://github.com/vuongdiensharing-performance/google-ads-performance-skills

## Overview

Google Ads Performance Skills is a model-agnostic collection of auditable marketing workflows, domain knowledge, and evidence-based decision rules. A principal workflow selects a registered Skill, evaluates its related Rules against account context, and produces findings that a Skill’s output contract classifies and prioritizes. A separate GA4 path governs allowlisted query requests, obtains read-only MCP results, and wraps them as provenance-bearing evidence. The README documents the GA4 layering, but the excerpts do not establish a live connection from that integration into Rule Engine decisions; that future link is shown as unverified.

Main entry points: [`integrations/google_analytics/adapter.py`](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/adapter.py) (Read-only adapter), [`scripts/skill_runtime.py`](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/scripts/skill_runtime.py) (Skill runtime), [`integrations/google_analytics/client.py`](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/client.py) (MCP client), [`rules`](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/rules) (Decision Rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Skills and runtime"]
  node_skill_docs["Skill workflows"]
  node_skill_registry["Skill registry<br/>[registry.yaml]"]
  node_runtime["Skill runtime<br/>[skill_runtime.py]"]
  node_rule_engine["Rule Engine<br/>[rule_engine.py]"]
end

subgraph group_decision["Decision assets"]
  node_rules["Decision Rules"]
  node_knowledge["Domain knowledge"]
  node_output_contract["Output contracts"]
end

subgraph group_ga4_policy["GA4 evidence policy"]
  node_boundary_contract["Boundary contract"]
  node_evidence_contract["Evidence contract"]
  node_identity_linkage["Identity and linkage"]
  node_query_contract["Query contracts"]
  node_provider_policy["Provider policy"]
end

subgraph group_ga4_integration["GA4 integration"]
  node_ga4_adapter["Read-only adapter<br/>[adapter.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
  node_ga4_evidence["Approved GA4 evidence<br/>[adapter.py]"]
end

node_user(("Agent or user"))
node_mcp_server{{"Google Analytics MCP"}}

node_user -->|"runs skill"| node_runtime
node_runtime -->|"reads registry"| node_skill_registry
node_runtime -->|"evaluates rules"| node_rule_engine
node_runtime -->|"loads rules"| node_rules
node_skill_docs -->|"defines output"| node_output_contract
node_rules -->|"grounded by"| node_knowledge
node_user -.->|"requests evidence"| node_ga4_adapter
node_ga4_adapter -->|"calls tool"| node_mcp_client
node_mcp_client -->|"sends MCP request"| node_mcp_server
node_mcp_server -.->|"returns result"| node_mcp_client
node_ga4_adapter -->|"wraps result"| node_ga4_evidence
node_query_contract -->|"constrains requests"| node_ga4_adapter
node_provider_policy -->|"limits tools"| node_ga4_adapter
node_boundary_contract -->|"precedes"| node_evidence_contract
node_evidence_contract -->|"precedes"| node_identity_linkage
node_identity_linkage -->|"precedes"| node_ga4_adapter
node_ga4_adapter -->|"checks registered query"| node_query_contract
node_ga4_evidence -.->|"may inform decisions"| node_rule_engine

click node_skill_docs "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/skills"
click node_skill_registry "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/skills/registry.yaml"
click node_runtime "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/scripts/skill_runtime.py"
click node_rule_engine "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/scripts/rule_engine.py"
click node_rules "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/rules"
click node_knowledge "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/knowledge"
click node_output_contract "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/templates"
click node_boundary_contract "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/schemas/boundary-contract.json"
click node_evidence_contract "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/schemas/ga4-evidence-contract.json"
click node_identity_linkage "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/docs/GA4_MCP_INTEGRATION.md"
click node_query_contract "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/queries/google_analytics"
click node_provider_policy "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/providers/google_analytics.yaml"
click node_ga4_adapter "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/adapter.py"
click node_mcp_client "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/client.py"
click node_ga4_evidence "https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/adapter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_docs,node_skill_registry,node_runtime,node_rule_engine,node_user toneBlue
class node_rules,node_knowledge,node_output_contract toneAmber
class node_boundary_contract,node_evidence_contract,node_identity_linkage,node_query_contract,node_provider_policy toneMint
class node_ga4_adapter,node_mcp_client,node_ga4_evidence toneRose
class node_mcp_server toneIndigo
```

## Components

### Skills and runtime

- [Skill workflows](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/skills): `skills`
- [Skill registry](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/skills/registry.yaml): `skills/registry.yaml`
- [Skill runtime](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/scripts/skill_runtime.py): `scripts/skill_runtime.py`
- [Rule Engine](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/scripts/rule_engine.py): `scripts/rule_engine.py`

### Decision assets

- [Decision Rules](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/rules): `rules`
- [Domain knowledge](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/knowledge): `knowledge`
- [Output contracts](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/templates): `templates`

### GA4 evidence policy

- [Boundary contract](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/schemas/boundary-contract.json): `schemas/boundary-contract.json`
- [Evidence contract](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/schemas/ga4-evidence-contract.json): `schemas/ga4-evidence-contract.json`
- [Identity and linkage](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/docs/GA4_MCP_INTEGRATION.md): `docs/GA4_MCP_INTEGRATION.md`
- [Query contracts](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/tree/main/queries/google_analytics): `queries/google_analytics`
- [Provider policy](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/providers/google_analytics.yaml): `providers/google_analytics.yaml`

### GA4 integration

- [Read-only adapter](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/adapter.py): `integrations/google_analytics/adapter.py`
- [MCP client](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/client.py): `integrations/google_analytics/client.py`
- [Approved GA4 evidence](https://github.com/vuongdiensharing-performance/google-ads-performance-skills/blob/main/integrations/google_analytics/adapter.py): `integrations/google_analytics/adapter.py`

### Other components

- **Agent or user**
- **Google Analytics MCP**

## Connections

- Agent or user → Skill runtime: runs skill (evidence: `scripts/skill_runtime.py`)
- Skill runtime → Skill registry: reads registry (evidence: `scripts/skill_runtime.py`)
- Skill runtime → Rule Engine: evaluates rules (evidence: `scripts/skill_runtime.py`)
- Skill runtime → Decision Rules: loads rules (evidence: `scripts/skill_runtime.py`)
- Skill workflows → Output contracts: defines output (evidence: `README.md`)
- Decision Rules → Domain knowledge: grounded by (evidence: `README.md`)
- Agent or user → Read-only adapter: requests evidence
- Read-only adapter → MCP client: calls tool (evidence: `integrations/google_analytics/adapter.py`)
- MCP client → Google Analytics MCP: sends MCP request (evidence: `integrations/google_analytics/client.py`)
- Google Analytics MCP → MCP client: returns result
- Read-only adapter → Approved GA4 evidence: wraps result (evidence: `integrations/google_analytics/adapter.py`)
- Query contracts → Read-only adapter: constrains requests (evidence: `README.md`)
- Provider policy → Read-only adapter: limits tools (evidence: `README.md`)
- Boundary contract → Evidence contract: precedes (evidence: `README.md`)
- Evidence contract → Identity and linkage: precedes (evidence: `README.md`)
- Identity and linkage → Read-only adapter: precedes (evidence: `README.md`)
- Read-only adapter → Query contracts: checks registered query (evidence: `README.md`)
- Approved GA4 evidence → Rule Engine: may inform decisions
