Rewrite README for post-decoupling architecture

Document submodules, models, cross-app integration (event-driven
login adoption), and accurate directory structure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -1,36 +1,62 @@
-# Blog App
+# Blog App (Coop)
 
-Blog and content management application for the Rose Ash cooperative platform.
+Blog, authentication, and content management service for the Rose Ash cooperative platform. This is the primary "coop" app — it handles Ghost CMS integration, user auth, and admin settings.
 
-## Overview
+## Architecture
 
-This is the **blog** service extracted from the Rose Ash (Suma Browser) monolith.
-It handles:
+One of four Quart microservices sharing a single PostgreSQL database:
 
-- **Blog**: Ghost CMS integration for browsing, creating, and editing posts
-- **Auth**: Magic link authentication and user account management
-- **Admin/Settings**: Administrative interface and settings management
-- **Menu Items**: Navigation menu item management
-- **Snippets**: Reusable content snippet management
-- **Internal API**: Server-to-server endpoints for cross-app data sharing
+| 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 |
 
-## Tech Stack
+## Structure
 
-- **Quart** (async Flask) with HTMX
-- **SQLAlchemy 2.0** (async) with PostgreSQL
-- **Redis** for page caching
-- **Ghost CMS** for blog content
+```
+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, SumUp config
+models/                 # Blog-domain models
+  ghost_content.py      #   Post, Tag, PostTag
+  ghost_membership_entities.py  #   GhostNewsletter, UserNewsletter
+  user.py               #   Re-export of shared User model
+  magic_link.py         #   Re-export of shared MagicLink model
+  kv.py                 #   Re-export of shared KeyValue model
+  menu_item.py          #   MenuItem
+  snippet.py            #   Snippet
+  tag_group.py          #   TagGroup, TagGroupTag
+bp/                     # Blueprints
+  auth/                 #   Magic link login, account, newsletters
+  blog/                 #   Post listing, Ghost CMS sync
+  post/                 #   Single post view and admin
+  admin/                #   Settings admin interface
+  menu_items/           #   Navigation menu management
+  snippets/             #   Reusable content snippets
+  coop_api.py           #   Internal API (/internal/coop/*)
+templates/              # Jinja2 templates
+entrypoint.sh           # Docker entrypoint (runs alembic + starts server)
+Dockerfile
+shared/                 # Submodule → git.rose-ash.com/coop/shared.git
+glue/                   # Submodule → git.rose-ash.com/coop/glue.git
+```
+
+## Cross-App Integration
+
+- **Login adoption:** When a user logs in via magic link, `auth/routes.py` emits a `user.logged_in` domain event. The glue layer's `login_handlers.py` picks it up and adopts anonymous cart items + calendar entries.
+- **Cart widget:** Context processor fetches cart summary via `internal_api.get("cart", "/internal/cart/summary")`.
+- **Internal API:** `/internal/coop/` endpoints serve blog data to other apps.
 
 ## Running
 
 ```bash
-# Set environment variables (see .env.example)
-export APP_MODULE=app:app
+export DATABASE_URL_ASYNC=postgresql+asyncpg://user:pass@localhost/coop
+export REDIS_URL=redis://localhost:6379/0
+export SECRET_KEY=your-secret-key
 
-# Run migrations
-alembic upgrade head
-
-# Start the server
+alembic -c shared/alembic.ini upgrade head
 hypercorn app:app --bind 0.0.0.0:8000
 ```
 
@@ -40,21 +66,3 @@ hypercorn app:app --bind 0.0.0.0:8000
 docker build -t blog .
 docker run -p 8000:8000 --env-file .env blog
 ```
-
-## Directory Structure
-
-```
-app.py              # Application factory and entry point
-bp/                 # Blueprints
-  auth/             # Authentication (magic links, account)
-  blog/             # Blog listing, Ghost CMS integration
-  post/             # Individual post viewing and admin
-  admin/            # Settings admin interface
-  menu_items/       # Navigation menu management
-  snippets/         # Content snippet management
-  coop_api.py       # Internal API endpoints
-templates/          # Jinja2 templates
-  _types/           # Feature-specific templates
-entrypoint.sh       # Docker entrypoint (migrations + server start)
-Dockerfile          # Container build definition
-```