# matttimms/coles_vs_woolies architecture

> Architecture diagram of the GitHub repository matttimms/coles_vs_woolies, 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/matttimms/coles_vs_woolies
- Repository: https://github.com/matttimms/coles_vs_woolies

## Overview

This Python CLI compares grocery offers from Coles, IGA, and Woolworths, with search results available for display or as weekly email deals. The main flow is CLI request → concurrent merchant searches → normalized and similarity-ranked offers → optional email rendering and MailerSend delivery. Supporting layers provide cached HTTP sessions, product display, and date calculations. The README also documents cache clearing and scheduled weekly use. Edges are limited to relationships shown in excerpts, the source index, or README; unsampled details are not inferred.

Main entry points: [`coles_vs_woolies/search.py`](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/search.py) (Product search), [`coles_vs_woolies/merchants/base.py`](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/base.py) (Merchant models), [`coles_vs_woolies/__main__.py`](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/__main__.py) (CLI commands), [`coles_vs_woolies/merchants/__init__.py`](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/__init__.py) (Merchant registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and search"]
  node_cli["CLI commands<br/>[__main__.py]"]
  node_search["Product search<br/>[search.py]"]
end

subgraph group_merchants["Merchant search"]
  node_merchant_registry["Merchant registry<br/>[__init__.py]"]
  node_merchant_base["Merchant models<br/>[base.py]"]
  node_coles["Coles adapter<br/>[coles.py]"]
  node_iga["IGA adapter<br/>[iga.py]"]
  node_woolworths["Woolworths adapter<br/>[woolworths.py]"]
end

subgraph group_email["Weekly email"]
  node_email_flow["Email workflow<br/>[emails.py]"]
  node_email_template["Email rendering<br/>[main.py]"]
  node_mailer["MailerSend client<br/>[mailer_send.py]"]
end

subgraph group_support["Shared utilities"]
  node_session["Cached HTTP session<br/>[session.py]"]
  node_wednesday["Week date helpers<br/>[wednesday.py]"]
  node_similarity["Product similarity<br/>[similarity.py]"]
  node_display["Result display<br/>[display.py]"]
end

node_user(("CLI user"))
node_coles_api{{"Coles API"}}
node_iga_api{{"IGA API"}}
node_woolworths_api{{"Woolworths API"}}
node_mailersend_service{{"MailerSend"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"runs search"| node_search
node_cli -->|"clears cache"| node_session
node_cli -->|"runs email"| node_email_flow
node_search -->|"dispatches searches"| node_merchant_registry
node_search -->|"creates session"| node_session
node_search -->|"renders results"| node_display
node_merchant_registry -->|"registers"| node_coles
node_merchant_registry -->|"registers"| node_iga
node_merchant_registry -->|"registers"| node_woolworths
node_coles -->|"extends models"| node_merchant_base
node_iga -->|"extends models"| node_merchant_base
node_woolworths -->|"extends models"| node_merchant_base
node_coles -->|"queries"| node_coles_api
node_iga -->|"queries"| node_iga_api
node_woolworths -->|"queries"| node_woolworths_api
node_merchant_base -->|"scores matches"| node_similarity
node_merchant_base -->|"renders page"| node_display
node_email_flow -->|"runs bulk search"| node_search
node_email_flow -->|"generates HTML"| node_email_template
node_email_flow -->|"sends email"| node_mailer
node_mailer -->|"delivers message"| node_mailersend_service
node_mailer -->|"sets subject"| node_wednesday
node_session -->|"sets expiry"| node_wednesday

click node_cli "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/__main__.py"
click node_search "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/search.py"
click node_merchant_registry "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/__init__.py"
click node_merchant_base "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/base.py"
click node_coles "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/coles.py"
click node_iga "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/iga.py"
click node_woolworths "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/woolworths.py"
click node_email_flow "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/emails.py"
click node_email_template "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/templates/main.py"
click node_mailer "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/providers/mailer_send.py"
click node_session "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/session.py"
click node_wednesday "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/wednesday.py"
click node_similarity "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/similarity.py"
click node_display "https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/display.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_cli,node_search,node_user toneBlue
class node_merchant_registry,node_merchant_base,node_coles,node_iga,node_woolworths toneAmber
class node_email_flow,node_email_template,node_mailer,node_coles_api,node_iga_api,node_woolworths_api toneMint
class node_session,node_wednesday,node_similarity,node_display toneRose
class node_mailersend_service toneIndigo
```

## Components

### CLI and search

- [CLI commands](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/__main__.py): `coles_vs_woolies/__main__.py`
- [Product search](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/search.py): `coles_vs_woolies/search.py`

### Merchant search

- [Merchant registry](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/__init__.py): `coles_vs_woolies/merchants/__init__.py`
- [Merchant models](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/base.py): `coles_vs_woolies/merchants/base.py`
- [Coles adapter](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/coles.py): `coles_vs_woolies/merchants/coles.py`
- [IGA adapter](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/iga.py): `coles_vs_woolies/merchants/iga.py`
- [Woolworths adapter](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/merchants/woolworths.py): `coles_vs_woolies/merchants/woolworths.py`

### Weekly email

- [Email workflow](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/emails.py): `coles_vs_woolies/emails/emails.py`
- [Email rendering](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/templates/main.py): `coles_vs_woolies/emails/templates/main.py`
- [MailerSend client](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/emails/providers/mailer_send.py): `coles_vs_woolies/emails/providers/mailer_send.py`

### Shared utilities

- [Cached HTTP session](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/session.py): `coles_vs_woolies/utils/session.py`
- [Week date helpers](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/wednesday.py): `coles_vs_woolies/utils/wednesday.py`
- [Product similarity](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/similarity.py): `coles_vs_woolies/utils/similarity.py`
- [Result display](https://github.com/matttimms/coles_vs_woolies/blob/main/coles_vs_woolies/utils/display.py): `coles_vs_woolies/utils/display.py`

### Other components

- **CLI user**
- **Coles API**
- **IGA API**
- **Woolworths API**
- **MailerSend**

## Connections

- CLI user → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Product search: runs search (evidence: `coles_vs_woolies/__main__.py`)
- CLI commands → Cached HTTP session: clears cache (evidence: `coles_vs_woolies/__main__.py`)
- CLI commands → Email workflow: runs email (evidence: `README.md`)
- Product search → Merchant registry: dispatches searches (evidence: `coles_vs_woolies/search.py`)
- Product search → Cached HTTP session: creates session (evidence: `coles_vs_woolies/search.py`)
- Product search → Result display: renders results (evidence: `coles_vs_woolies/search.py`)
- Merchant registry → Coles adapter: registers (evidence: `coles_vs_woolies/merchants/__init__.py`)
- Merchant registry → IGA adapter: registers (evidence: `coles_vs_woolies/merchants/__init__.py`)
- Merchant registry → Woolworths adapter: registers (evidence: `coles_vs_woolies/merchants/__init__.py`)
- Coles adapter → Merchant models: extends models (evidence: `coles_vs_woolies/merchants/coles.py`)
- IGA adapter → Merchant models: extends models (evidence: `coles_vs_woolies/merchants/iga.py`)
- Woolworths adapter → Merchant models: extends models (evidence: `coles_vs_woolies/merchants/woolworths.py`)
- Coles adapter → Coles API: queries (evidence: `coles_vs_woolies/merchants/coles.py`)
- IGA adapter → IGA API: queries (evidence: `coles_vs_woolies/merchants/iga.py`)
- Woolworths adapter → Woolworths API: queries (evidence: `coles_vs_woolies/merchants/woolworths.py`)
- Merchant models → Product similarity: scores matches (evidence: `coles_vs_woolies/merchants/base.py`)
- Merchant models → Result display: renders page (evidence: `coles_vs_woolies/merchants/base.py`)
- Email workflow → Product search: runs bulk search (evidence: `coles_vs_woolies/emails/emails.py`)
- Email workflow → Email rendering: generates HTML (evidence: `coles_vs_woolies/emails/emails.py`)
- Email workflow → MailerSend client: sends email (evidence: `coles_vs_woolies/emails/emails.py`)
- MailerSend client → MailerSend: delivers message (evidence: `coles_vs_woolies/emails/providers/mailer_send.py`)
- MailerSend client → Week date helpers: sets subject (evidence: `coles_vs_woolies/emails/providers/mailer_send.py`)
- Cached HTTP session → Week date helpers: sets expiry (evidence: `coles_vs_woolies/utils/session.py`)
