From a29612ffa434c470e1b41276de4894443da7a8e1 Mon Sep 17 00:00:00 2001
From: giles <giles.bradshaw@sigyl.com>
Date: Sat, 14 Feb 2026 19:28:56 +0000
Subject: [PATCH] Rewrite README for post-decoupling architecture

Fix microservice count (4 not 3), document submodules, models,
scraper, all blueprints including bp/cart/, and cross-app integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 112 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 62 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 7887579..aa43fff 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,79 @@
 # Market App
 
-Product browsing and marketplace application for the Rose Ash cooperative.
-
-## Overview
-
-The Market app is one of three microservices split from the original coop monolith:
-
-- **coop** (:8000) - Blog, calendar, auth, settings
-- **market** (:8001) - Product browsing, categories, product detail
-- **cart** (:8002) - Shopping cart, orders, payments
+Product browsing and marketplace service for the Rose Ash cooperative. Displays products scraped from Suma Wholesale.
 
 ## Architecture
 
-- **Framework:** Quart (async Flask)
-- **Database:** PostgreSQL 16 with SQLAlchemy 2.0 (async)
-- **Cache:** Redis (tag-based page cache)
-- **Frontend:** HTMX + Jinja2 + Tailwind CSS
-- **Data:** Products scraped from Suma Wholesale
+One of four Quart microservices sharing a single PostgreSQL database:
 
-## Blueprints
+| App | Port | Domain |
+|-----|------|--------|
+| blog (coop) | 8000 | Auth, blog, admin, menus, snippets |
+| **market** | 8001 | Product browsing, Suma scraping |
+| cart | 8002 | Shopping cart, checkout, orders |
+| events | 8003 | Calendars, bookings, tickets |
 
-- `bp/market/` - Market root (navigation, category listing)
-- `bp/browse/` - Product browsing with filters and infinite scroll
-- `bp/product/` - Product detail pages
-- `bp/api/` - Product sync API (used by scraper)
+## Structure
 
-## Development
+```
+app.py                  # Application factory (create_base_app + blueprints)
+path_setup.py           # Adds project root + app dir to sys.path
+config/app-config.yaml  # App URLs, feature flags
+models/                 # Market-domain models
+  market.py             #   Product, Category, CartItem
+  market_place.py       #   MarketPlace (page-scoped marketplace)
+bp/                     # Blueprints
+  market/               #   Market root, navigation, category listing
+  browse/               #   Product browsing with filters and infinite scroll
+  product/              #   Product detail pages
+  cart/                 #   Page-scoped cart views
+  api/                  #   Product sync API (used by scraper)
+scrape/                 # Suma Wholesale scraper
+  get_auth.py           #   Authentication
+  listings.py           #   Product listing pages
+  nav.py                #   Category navigation
+  product/              #   Individual product scraping
+  build_snapshot/       #   Build product snapshots
+  persist_snapshot/     #   Save snapshots to DB
+  persist_api/          #   Save via API
+templates/              # Jinja2 templates
+entrypoint.sh           # Docker entrypoint
+Dockerfile
+shared/                 # Submodule → git.rose-ash.com/coop/shared.git
+glue/                   # Submodule → git.rose-ash.com/coop/glue.git
+```
 
-    # Install dependencies
-    pip install -r requirements.txt
+## Cross-App Integration
 
-    # Set environment variables
-    export $(grep -v '^#' .env | xargs)
-
-    # Run migrations
-    alembic upgrade head
-
-    # Scrape products
-    bash scrape.sh
-
-    # Run the dev server
-    hypercorn app:app --reload --bind 0.0.0.0:8001
+- **Cart:** "Add to cart" posts to cart app. Cart widget fetched via internal API.
+- **Blog:** Post/page data fetched via internal API for page-scoped marketplaces.
+- **Glue:** MarketPlace uses generic containers (`container_type + container_id`) to attach to pages without FK coupling.
 
 ## Scraping
 
-    # Full scrape (max 50 pages, 200k products, 8 concurrent)
-    bash scrape.sh
+```bash
+# Full scrape (Suma Wholesale catalogue)
+bash scrape.sh
 
-    # Test scraping
-    bash scrape-test.sh
+# Test scraping (limited)
+bash scrape-test.sh
+```
+
+## Running
+
+```bash
+export DATABASE_URL_ASYNC=postgresql+asyncpg://user:pass@localhost/coop
+export REDIS_URL=redis://localhost:6379/0
+export SECRET_KEY=your-secret-key
+export SUMA_USER=your-suma-username
+export SUMA_PASSWORD=your-suma-password
+
+hypercorn app:app --reload --bind 0.0.0.0:8001
+```
 
 ## Docker
 
-    docker build -t market .
-    docker run -p 8001:8000 --env-file .env market
-
-## Environment Variables
-
-    DATABASE_URL_ASYNC=postgresql+asyncpg://user:pass@localhost/coop
-    REDIS_URL=redis://localhost:6379/0
-    SECRET_KEY=your-secret-key
-    SUMA_USER=your-suma-username
-    SUMA_PASSWORD=your-suma-password
-    APP_URL_COOP=http://localhost:8000
-    APP_URL_MARKET=http://localhost:8001
-    APP_URL_CART=http://localhost:8002
+```bash
+docker build -t market .
+docker run -p 8001:8000 --env-file .env market
+```