# Cart App

Shopping cart, checkout, and order management service for the Rose Ash cooperative.

## Architecture

One of five Quart microservices sharing a single PostgreSQL database:

| 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 |
| federation | 8004 | ActivityPub, fediverse social |

## Structure

```
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, SumUp config
models/                 # Cart-domain models (Order, OrderItem, PageConfig)
bp/
  cart/                 # Cart blueprint
    global_routes.py    #   Add to cart, checkout, webhooks, return page
    page_routes.py      #   Page-scoped cart and checkout
    overview_routes.py  #   Cart overview / summary page
    services/           #   Business logic
      checkout.py       #     Order creation, SumUp integration
      check_sumup_status.py  #  Payment status polling
      calendar_cart.py  #     Calendar entry cart queries
      page_cart.py      #     Page-scoped cart queries
      get_cart.py       #     Cart item queries
      identity.py       #     Cart identity (user_id / session_id)
      total.py          #     Price calculations
      clear_cart_for_order.py  # Soft-delete cart after checkout
  order/                # Single order detail view
  orders/               # Order listing view
services/               # register_domain_services() — wires cart + calendar + market
shared/                 # Submodule -> git.rose-ash.com/coop/shared.git
```

## Cross-Domain Communication

- `services.calendar.*` — claim/confirm entries for orders, adopt on login
- `services.market.*` — marketplace queries for page-scoped carts
- `services.blog.*` — post lookup for page context
- `shared.services.navigation` — site navigation tree

## Domain Events

- `checkout.py` emits `order.created` via `shared.events.emit_event`
- `check_sumup_status.py` emits `order.paid` via `shared.events.emit_event`

## Checkout Flow

```
1. User clicks "Checkout"
2. create_order_from_cart() creates Order + OrderItems
3. services.calendar.claim_entries_for_order() marks entries as "ordered"
4. emit: order.created event
5. SumUp hosted checkout created, user redirected
6. SumUp webhook / return page triggers check_sumup_status()
7. If PAID: services.calendar.confirm_entries_for_order(), emit: order.paid
```

## 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

hypercorn app:app --bind 0.0.0.0:8002
```