# popcsev/ecommercetools architecture

> Architecture diagram of the GitHub repository popcsev/ecommercetools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/popcsev/ecommercetools
- Repository: https://github.com/popcsev/ecommercetools

## Overview

EcommerceTools is a Python toolkit for ecommerce analytics, marketing, and technical SEO. Users prepare transaction-item data for product, customer, and reporting analysis, or query web and analytics sources for specialist reports; GA4 supports multi-country properties. A separate intelligence capability collects weekly GA4 snapshots and produces analysis and narrative reports. The graph preserves the README’s advertised domains, including capabilities whose implementations were not sampled. Edges are limited to documented calls and visible imports; several unsampled subsystems therefore have no asserted connections.

Main entry points: [`ecommercetools/transactions/transactions.py`](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/transactions/transactions.py) (Transactions), [`ecommercetools/seo/google_search.py`](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_search.py) (Search Research), [`ecommercetools/products/products.py`](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/products/products.py) (Product Analysis), [`ecommercetools/customers/customers.py`](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/customers/customers.py) (Customer Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commerce["Commerce Analysis"]
  node_transactions["Transactions<br/>[transactions.py]"]
  node_products["Product Analysis<br/>[products.py]"]
  node_customers["Customer Analysis<br/>[customers.py]"]
  node_ops["Operations<br/>[operations.py]"]
  node_reports["Commerce Reports<br/>[reports.py]"]
end

subgraph group_growth["Marketing and SEO"]
  node_advertising["Advertising<br/>[advertising.py]"]
  node_marketing["Marketing and Basket<br/>[marketing.py]"]
  node_nlp["NLP<br/>[nlp.py]"]
  node_seo_search["Search Research<br/>[google_search.py]"]
  node_search_console["Search Console"]
  node_autocomplete["Autocomplete"]
  node_pagespeed["PageSpeed"]
  node_seo_other["SEO Utilities"]
  node_seo_testing["SEO Testing<br/>[testing.py]"]
end

subgraph group_analytics["Analytics and Intelligence"]
  node_ga4["Multi-country GA4<br/>[ga4.py]"]
  node_ga_reports["GA4 Reports<br/>[reports.py]"]
  node_snapshots[("Weekly Snapshots<br/>[snapshots.py]")]
  node_analyst["Snapshot Analyst<br/>[analyst.py]"]
  node_narrator["Narrator<br/>[narrator.py]"]
  node_reporter["Reporter<br/>[reporter.py]"]
end

subgraph group_foundations["Data Foundations"]
  node_tools["Data Tools<br/>[tools.py]"]
  node_http["HTTP Fetching<br/>[http.py]"]
end

node_user(("Analyst"))
node_google{{"Google Services"}}

node_user -->|"analyzes data"| node_transactions
node_user -->|"analyzes data"| node_products
node_user -->|"analyzes data"| node_customers
node_user -->|"uses tools"| node_advertising
node_user -->|"analyzes baskets"| node_marketing
node_user -->|"uses tools"| node_nlp
node_user -->|"researches search"| node_seo_search
node_user -->|"queries metrics"| node_search_console
node_user -->|"checks performance"| node_pagespeed
node_user -->|"requests reports"| node_ga_reports
node_reports -->|"aggregates via"| node_transactions
node_customers -->|"uses"| node_transactions
node_transactions -->|"counts with"| node_tools
node_products -->|"uses"| node_tools
node_ga_reports -->|"queries"| node_ga4
node_snapshots -->|"queries"| node_ga4
node_analyst -->|"reads"| node_snapshots
node_seo_search -->|"fetches through"| node_http
node_autocomplete -->|"fetches through"| node_http
node_seo_search -->|"scrapes results"| node_google
node_search_console -->|"queries API"| node_google
node_pagespeed -.->|"queries service"| node_google

click node_transactions "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/transactions/transactions.py"
click node_products "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/products/products.py"
click node_customers "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/customers/customers.py"
click node_ops "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/operations/operations.py"
click node_reports "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/reports/reports.py"
click node_advertising "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/advertising/advertising.py"
click node_marketing "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/marketing/marketing.py"
click node_nlp "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/nlp/nlp.py"
click node_seo_search "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_search.py"
click node_search_console "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_search_console.py"
click node_autocomplete "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_autocomplete.py"
click node_pagespeed "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_pagespeed_insights.py"
click node_seo_other "https://github.com/popcsev/ecommercetools/tree/master/ecommercetools/seo"
click node_seo_testing "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/testing.py"
click node_ga4 "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/analytics/ga4.py"
click node_ga_reports "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/analytics/reports.py"
click node_snapshots "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/snapshots.py"
click node_analyst "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/analyst.py"
click node_narrator "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/narrator.py"
click node_reporter "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/reporter.py"
click node_tools "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/utilities/tools.py"
click node_http "https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/utilities/http.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_transactions,node_products,node_customers,node_ops,node_reports toneBlue
class node_advertising,node_marketing,node_nlp,node_seo_search,node_search_console,node_autocomplete,node_pagespeed,node_seo_other,node_seo_testing toneAmber
class node_ga4,node_ga_reports,node_snapshots,node_analyst,node_narrator,node_reporter toneMint
class node_tools,node_http toneRose
class node_user,node_google toneIndigo
```

## Components

### Commerce Analysis

- [Transactions](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/transactions/transactions.py): `ecommercetools/transactions/transactions.py`
- [Product Analysis](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/products/products.py): `ecommercetools/products/products.py`
- [Customer Analysis](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/customers/customers.py): `ecommercetools/customers/customers.py`
- [Operations](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/operations/operations.py): `ecommercetools/operations/operations.py`
- [Commerce Reports](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/reports/reports.py): `ecommercetools/reports/reports.py`

### Marketing and SEO

- [Advertising](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/advertising/advertising.py): `ecommercetools/advertising/advertising.py`
- [Marketing and Basket](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/marketing/marketing.py): `ecommercetools/marketing/marketing.py`
- [NLP](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/nlp/nlp.py): `ecommercetools/nlp/nlp.py`
- [Search Research](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_search.py): `ecommercetools/seo/google_search.py`
- [Search Console](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_search_console.py): `ecommercetools/seo/google_search_console.py`
- [Autocomplete](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_autocomplete.py): `ecommercetools/seo/google_autocomplete.py`
- [PageSpeed](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/google_pagespeed_insights.py): `ecommercetools/seo/google_pagespeed_insights.py`
- [SEO Utilities](https://github.com/popcsev/ecommercetools/tree/master/ecommercetools/seo): `ecommercetools/seo`
- [SEO Testing](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/seo/testing.py): `ecommercetools/seo/testing.py`

### Analytics and Intelligence

- [Multi-country GA4](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/analytics/ga4.py): `ecommercetools/analytics/ga4.py`
- [GA4 Reports](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/analytics/reports.py): `ecommercetools/analytics/reports.py`
- [Weekly Snapshots](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/snapshots.py): `ecommercetools/intelligence/snapshots.py`
- [Snapshot Analyst](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/analyst.py): `ecommercetools/intelligence/analyst.py`
- [Narrator](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/narrator.py): `ecommercetools/intelligence/narrator.py`
- [Reporter](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/intelligence/reporter.py): `ecommercetools/intelligence/reporter.py`

### Data Foundations

- [Data Tools](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/utilities/tools.py): `ecommercetools/utilities/tools.py`
- [HTTP Fetching](https://github.com/popcsev/ecommercetools/blob/master/ecommercetools/utilities/http.py): `ecommercetools/utilities/http.py`

### Other components

- **Analyst**
- **Google Services**

## Connections

- Analyst → Transactions: analyzes data
- Analyst → Product Analysis: analyzes data
- Analyst → Customer Analysis: analyzes data
- Analyst → Advertising: uses tools
- Analyst → Marketing and Basket: analyzes baskets
- Analyst → NLP: uses tools
- Analyst → Search Research: researches search
- Analyst → Search Console: queries metrics
- Analyst → PageSpeed: checks performance
- Analyst → GA4 Reports: requests reports
- Commerce Reports → Transactions: aggregates via (evidence: `ecommercetools/reports/reports.py`)
- Customer Analysis → Transactions: uses (evidence: `ecommercetools/customers/customers.py`)
- Transactions → Data Tools: counts with (evidence: `ecommercetools/transactions/transactions.py`)
- Product Analysis → Data Tools: uses (evidence: `ecommercetools/products/products.py`)
- GA4 Reports → Multi-country GA4: queries (evidence: `ecommercetools/analytics/reports.py`)
- Weekly Snapshots → Multi-country GA4: queries (evidence: `ecommercetools/intelligence/snapshots.py`)
- Snapshot Analyst → Weekly Snapshots: reads (evidence: `ecommercetools/intelligence/analyst.py`)
- Search Research → HTTP Fetching: fetches through (evidence: `ecommercetools/seo/google_search.py`)
- Autocomplete → HTTP Fetching: fetches through (evidence: `ecommercetools/seo/google_autocomplete.py`)
- Search Research → Google Services: scrapes results (evidence: `ecommercetools/seo/google_search.py`)
- Search Console → Google Services: queries API (evidence: `ecommercetools/seo/google_search_console.py`)
- PageSpeed → Google Services: queries service
