From: Edward Delaporte <edward@delaporte.us>
Date: Sun, 5 Apr 2026 14:44:25 +0000 (-0500)
Subject: Add README
X-Git-Url: https://apps.delaporte.us/gitweb/matrix-shop-bot.git/commitdiff_plain/18cd16d493680714ecf51c1ec3fd411788776a76?ds=sidebyside

Add README
---

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb3a4b5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+## About
+
+A matrix bot that tracks shopping lists.
+
+
+Add the bot to your Matrix room, and start telling it your shopping list.
+
+Then add stores, and assign your items to one or moreany stores where you would shop for that item.
+
+Matrix shop bot can then list back your shopping list for any given store.
+
+This bot works well with, and is included in [Cadbury, the many purpose Matrix bot](https://codeberg.org/EdTheDev/matrix-cadbury).
+
+## Privacy
+
+This bot exists because most modern shopping tools have no respect for our privacy.
+
+All data is stored locally in a sqlite database on the host where you run the bot.
+
+Shop bot contains no trackers of any kind.
+
+## Usage
+
+Configure the necessary environment variables, and run with `make serve`.
+
+Invite the bot to a Matrix channel, and it will accept automatically, if it can.
+
+Use `!shop help`, to get started.
+
+> Tip: Additional setup is required to add a Matrix bot to an encrypted channel.
+
+```
+ Prefix: !shop
+
+    Synax:
+      !shop COMMAND ARGS
+
+    Commands:
+      help - show this help
+      add  - add an item to shop for
+      add-store - add a store
+      assign-item-to-store ITEM_ID STORE_ID - plan to shop for at store for item
+      assign ITEM_ID - assign item to last used store id
+      buy - mark item as purchased
+      ...etc...
+```  
+
+This bot can also be invoked from the commande line with `invoke`.
+
+    ```sh
+    git clone https://codeberg.org/EdTheDev/matrix-shop-bot.git
+    cd matrix-shop-bot
+    make .venv
+    source .venv/bin/activate
+    invoke --list
+    ```
+
+## TODO List
+
+- [ ] add PurchaseRecord table to track how often an item is purchased at a given store
+- [ ] add a `quick.list` command that populates a store shopping list with the most commonly shopped items at that store from the PurchaseRecord table in the database
+
+## Data Sources
+
+|Data Store|Data Type|Sensitivity|Notes|
+|----------|---------|-----------|-----|
+| Local SQLite Database | Shopping Lists | Personal | Filename is shop.db |
+
+By design, Shop bot does not store any data except as described in the above table.
+
+## Endpoint Connections
+
+|Endpoint|Purpose|Access|Contact|
+|--------|-------|------|-------|
+| Your Matrix Server | Connect as a chat bot | Read/Write | Matrix server administrator |
+
+By design, Shop bot does not transmit any data except as described in the above table.
+
+## Support
+
+As of the last update to this README, the expected End-of-Life date of this product is October 2028.
+
+End-of-Life was decided upon based on these dependencies:
+
+    - Python 3.12 (October 2028)