# Architecture

## System boundary

WooCommerce remains the public storefront and payment channel. Coffee Manager is the operational system for wholesale/manual orders, production, purchasing, inventory, invoicing, shipping and reporting.

## Main data flow

```text
WooCommerce orders --\
Manual orders --------+--> Orders --> Invoices
Recurring templates --/       |
                              +--> Roast-day requirements --> Production batches
                              +--> Shipments

Suppliers --> Purchase orders --> Receipts --> Inventory movements
                                                |
Green-bean lots <-------------------------------+

Orders + invoices + stock movements --> Reports and reminders
```

## Integration rules

- WooCommerce IDs are unique external keys.
- Imports use upserts and can be safely repeated.
- Webhooks require an HMAC signature.
- Raw webhook payloads and import outcomes are recorded in `sync_events`.
- Operational statuses are maintained locally; storefront order status remains an integration concern rather than the production model.

## Next production milestones

1. Add edit screens and a complete order status history.
2. Add recipe consumption and lot selection when roast batches are completed.
3. Add payment recording and accounting-system export.
4. Connect a shipping provider for labels and tracking updates.
5. Add email delivery for invoices and reminders.
6. Add user administration and enforce role permissions at route level.