From 7d20f67d991e1ab2709c17e1dd9f5f9b489bdfe9 Mon Sep 17 00:00:00 2001 From: giles Date: Sat, 14 Feb 2026 19:28:50 +0000 Subject: [PATCH] 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 --- README.md | 88 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index f247d86..522faa1 100644 --- a/README.md +++ b/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 -```