glue/README.md

Glue Layer

The glue layer sits between the four domain apps (blog, market, cart, events) and encapsulates all cross-domain logic — the code that would otherwise create tight coupling between services.

Each app includes glue/ as a git submodule. All apps share one PostgreSQL database, so glue services operate within the caller's existing DB transaction.

Architecture

blog ──┐
market ─┤
cart ───┤──→ glue (services, handlers, models)
events ─┘

Rule: Apps never import models or write data belonging to another domain directly. Instead they call a glue service or emit a domain event.

Models

ContainerRelation (models/container_relation.py)

Generic parent/child relationship between any two entities.

• parent_type + parent_id → child_type + child_id
• Soft-deletable (deleted_at), ordered (sort_order)
• Unique constraint on (parent_type, parent_id, child_type, child_id)

Used to attach calendars to pages, markets to pages, etc. without FK coupling.

MenuNode (models/menu_node.py)

Navigation tree nodes, scoped to a container (container_type + container_id).

• Self-referential (parent_id), ordered (sort_order), with depth
• Stores label, slug, href, icon, feature_image

Services

services/relationships.py — Container Relations

Function	Description
attach_child()	Create or revive a ContainerRelation (upsert). Emits container.child_attached.
get_children()	Query children of a container, optionally filtered by child_type.
detach_child()	Soft-delete a ContainerRelation. Emits container.child_detached.

services/order_lifecycle.py — Order ↔ Calendar Bridging

Cross-domain writes between cart and events domains. These run in the same transaction as the caller (not event-driven) because order creation and payment require immediate consistency.

Function	Description
claim_entries_for_order()	Mark pending CalendarEntries as "ordered" and set order_id. Called from checkout.
confirm_entries_for_order()	Mark ordered CalendarEntries as "provisional". Called when payment confirms.
get_entries_for_order()	Return CalendarEntries for an order. Replaces the old Order.calendar_entries relationship.

services/cart_adoption.py — Login Adoption

Function	Description
adopt_session_for_user()	Adopt anonymous CartItems + CalendarEntries for a logged-in user. Soft-deletes any existing user cart/entries first.

services/navigation.py — Navigation

Function	Description
get_navigation_tree()	Return top-level MenuNodes ordered by sort_order.
rebuild_navigation()	Placeholder for syncing ContainerRelations → MenuNodes.

Event Handlers

Handlers are registered at import time via shared.events.register_handler(). They're imported in setup.py → register_glue_handlers(), which each app calls at startup.

handlers/container_handlers.py

Event	Handler
container.child_attached	Triggers rebuild_navigation()
container.child_detached	Triggers rebuild_navigation()

handlers/login_handlers.py

Event	Handler
user.logged_in	Calls adopt_session_for_user() to adopt anonymous cart/entries

handlers/order_handlers.py

Event	Handler
order.created	Logging (placeholder for future workflows)
order.paid	Logging (placeholder for future workflows)

Event Flow Diagrams

Checkout

cart/checkout.py
  ├─ create order + order items (cart domain)
  ├─ glue: claim_entries_for_order()     ← cross-domain write (same txn)
  └─ emit: order.created                 ← observability

Payment Confirmation

cart/check_sumup_status.py
  ├─ update order.status = "paid"        (cart domain)
  ├─ glue: confirm_entries_for_order()   ← cross-domain write (same txn)
  └─ emit: order.paid                    ← observability

Login Adoption

blog/auth/routes.py
  └─ emit: user.logged_in               ← event (in last_login_at txn)
        ↓ (EventProcessor)
glue/handlers/login_handlers.py
  └─ glue: adopt_session_for_user()      ← cross-domain write (handler txn)

Remaining Cross-Domain Reads (Pragmatic Exceptions)

These stay in the app code (not in glue) because they're read-only queries against the shared DB. Moving them to glue would be pure churn:

• cart/bp/cart/services/checkout.py → resolve_page_config() reads Calendar + MarketPlace
• cart/bp/cart/api.py → /summary reads CalendarEntry + Calendar + MarketPlace
• cart/bp/cart/ → calendar_cart.py, page_cart.py read CalendarEntry/Calendar for display

Adding New Cross-Domain Logic

1. Cross-domain write? → Add a function in glue/services/. Call it from the app code within the existing transaction.
2. Eventually consistent? → Emit a domain event from the originating app. Add a handler in glue/handlers/.
3. Cross-domain read? → If it's a simple query against the shared DB, keep it in the app. Only move to glue if multiple apps need the same query.