# hwamil/fairgame architecture

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

- Interactive diagram: https://gitdiagram.com/hwamil/fairgame
- Repository: https://github.com/hwamil/fairgame

## Overview

FairGame is an Amazon stock-monitoring and automated-purchasing bot. The main workflow starts at the CLI, loads product and account settings, checks configured ASIN groups sequentially against Amazon, and attempts checkout and order placement when an item meets configured conditions. Notifications provide a separate user-feedback path; CLI commands also support notification testing and endpoint diagnostics. The sampled sources establish the CLI, configuration, credential, notification, and Amazon components; some Amazon internals and CLI wiring are only partially shown, so uncertain links are omitted.

Main entry points: [`cli/cli.py`](https://github.com/hwamil/fairgame/blob/master/cli/cli.py) (CLI commands), [`common/globalconfig.py`](https://github.com/hwamil/fairgame/blob/master/common/globalconfig.py) (Global config), [`notifications/notifications.py`](https://github.com/hwamil/fairgame/blob/master/notifications/notifications.py) (Notification handler), [`stores/amazon.py`](https://github.com/hwamil/fairgame/blob/master/stores/amazon.py) (Amazon monitor and checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_app["App bootstrap<br/>[app.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_config["Configuration and credentials"]
  node_globalconfig["Global config<br/>[globalconfig.py]"]
  node_configfile["FairGame settings<br/>[fairgame.conf]"]
  node_productconfig["Amazon product settings"]
  node_credentials["Amazon credentials"]
  node_encryption["Credential encryption<br/>[encryption.py]"]
end

subgraph group_purchase["Amazon purchasing"]
  node_amazon["Amazon monitor and checkout<br/>[amazon.py]"]
end

subgraph group_feedback["Feedback and diagnostics"]
  node_notifications["Notification handler<br/>[notifications.py]"]
  node_appriseconfig["Apprise settings"]
  node_sounds["Notification sounds"]
  node_presence["Discord presence"]
  node_http["HTTP client utilities<br/>[http.py]"]
  node_dns["DNS endpoint diagnostics<br/>[cli.py]"]
end

node_user(("User"))
node_amazonservice{{"Amazon"}}
node_apprise{{"Apprise services"}}
node_discord{{"Discord"}}

node_user -->|"starts"| node_app
node_app -->|"dispatches"| node_cli
node_user -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_globalconfig
node_globalconfig -->|"reads"| node_configfile
node_globalconfig -->|"loads or creates"| node_credentials
node_globalconfig -->|"uses"| node_encryption
node_cli -->|"initializes"| node_notifications
node_cli -->|"starts monitoring"| node_amazon
node_cli -->|"loads Amazon settings"| node_globalconfig
node_globalconfig -->|"reads"| node_productconfig
node_amazon -->|"checks stock and orders"| node_amazonservice
node_amazon -->|"sends alerts"| node_notifications
node_cli -->|"tests notifications"| node_notifications
node_notifications -->|"loads"| node_appriseconfig
node_notifications -.->|"sends alerts"| node_apprise
node_notifications -->|"plays"| node_sounds
node_presence -.->|"updates status"| node_discord
node_cli -->|"runs diagnostics"| node_dns
node_dns -->|"uses utilities"| node_http

click node_app "https://github.com/hwamil/fairgame/blob/master/app.py"
click node_cli "https://github.com/hwamil/fairgame/blob/master/cli/cli.py"
click node_globalconfig "https://github.com/hwamil/fairgame/blob/master/common/globalconfig.py"
click node_configfile "https://github.com/hwamil/fairgame/blob/master/config/fairgame.conf"
click node_productconfig "https://github.com/hwamil/fairgame/blob/master/config/amazon_config.template_json"
click node_encryption "https://github.com/hwamil/fairgame/blob/master/utils/encryption.py"
click node_amazon "https://github.com/hwamil/fairgame/blob/master/stores/amazon.py"
click node_notifications "https://github.com/hwamil/fairgame/blob/master/notifications/notifications.py"
click node_appriseconfig "https://github.com/hwamil/fairgame/blob/master/config/apprise.conf_template"
click node_sounds "https://github.com/hwamil/fairgame/tree/master/notifications"
click node_presence "https://github.com/hwamil/fairgame/blob/master/utils/discord_presence.py"
click node_http "https://github.com/hwamil/fairgame/blob/master/utils/http.py"
click node_dns "https://github.com/hwamil/fairgame/blob/master/cli/cli.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_app,node_cli,node_user toneBlue
class node_globalconfig,node_configfile,node_productconfig,node_credentials,node_encryption toneAmber
class node_amazon toneMint
class node_notifications,node_appriseconfig,node_sounds,node_presence,node_http,node_dns toneRose
class node_amazonservice,node_apprise,node_discord toneIndigo
```

## Components

### Application entry

- [App bootstrap](https://github.com/hwamil/fairgame/blob/master/app.py): `app.py`
- [CLI commands](https://github.com/hwamil/fairgame/blob/master/cli/cli.py): `cli/cli.py`

### Configuration and credentials

- [Global config](https://github.com/hwamil/fairgame/blob/master/common/globalconfig.py): `common/globalconfig.py`
- [FairGame settings](https://github.com/hwamil/fairgame/blob/master/config/fairgame.conf): `config/fairgame.conf`
- [Amazon product settings](https://github.com/hwamil/fairgame/blob/master/config/amazon_config.template_json): `config/amazon_config.template_json`
- **Amazon credentials**
- [Credential encryption](https://github.com/hwamil/fairgame/blob/master/utils/encryption.py): `utils/encryption.py`

### Amazon purchasing

- [Amazon monitor and checkout](https://github.com/hwamil/fairgame/blob/master/stores/amazon.py): `stores/amazon.py`

### Feedback and diagnostics

- [Notification handler](https://github.com/hwamil/fairgame/blob/master/notifications/notifications.py): `notifications/notifications.py`
- [Apprise settings](https://github.com/hwamil/fairgame/blob/master/config/apprise.conf_template): `config/apprise.conf_template`
- [Notification sounds](https://github.com/hwamil/fairgame/tree/master/notifications): `notifications`
- [Discord presence](https://github.com/hwamil/fairgame/blob/master/utils/discord_presence.py): `utils/discord_presence.py`
- [HTTP client utilities](https://github.com/hwamil/fairgame/blob/master/utils/http.py): `utils/http.py`
- [DNS endpoint diagnostics](https://github.com/hwamil/fairgame/blob/master/cli/cli.py): `cli/cli.py`

### Other components

- **User**
- **Amazon**
- **Apprise services**
- **Discord**

## Connections

- User → App bootstrap: starts
- App bootstrap → CLI commands: dispatches
- User → CLI commands: runs commands
- CLI commands → Global config: loads settings
- Global config → FairGame settings: reads
- Global config → Amazon credentials: loads or creates
- Global config → Credential encryption: uses
- CLI commands → Notification handler: initializes
- CLI commands → Amazon monitor and checkout: starts monitoring
- CLI commands → Global config: loads Amazon settings
- Global config → Amazon product settings: reads
- Amazon monitor and checkout → Amazon: checks stock and orders
- Amazon monitor and checkout → Notification handler: sends alerts
- CLI commands → Notification handler: tests notifications
- Notification handler → Apprise settings: loads
- Notification handler → Apprise services: sends alerts
- Notification handler → Notification sounds: plays
- Discord presence → Discord: updates status
- CLI commands → DNS endpoint diagnostics: runs diagnostics
- DNS endpoint diagnostics → HTTP client utilities: uses utilities