# Domain Modules

This is the primary reference document — the one to return to when reasoning about or building any part of CommerceDex. It defines all 20 bounded modules: what each owns, the business-language concepts it's responsible for, what it depends on, and what events it publishes or consumes.

## Tier legend

- **[CORE]** — Transactional. Cannot be down. Sits on the synchronous checkout/request path.
- **[INTEL]** — Intelligence/Automation. Degrades gracefully. Runs asynchronously, as background jobs.
- **[SUPPORT]** — Supporting infrastructure. Underpins other modules (media, settings, users, notifications, search).

This tiering matters directly for the cost-conscious architecture in `03-reference-architecture.md`: INTEL modules run purely as background jobs in the same process. If the automation worker backs up or briefly stalls, checkout still works. CORE modules get the tightest reliability treatment even though everything shares one deployable.

---

### 1. Commerce Core `[CORE]`
The orchestration backbone that ties a storefront session to the merchant's business rules. Not a module with its own rich entity set so much as the shared kernel other Core modules plug into — store identity, currency/locale, and the checkout state machine live here.
**Key concepts:** Store, Storefront Session, Checkout Flow.
**Depends on:** Settings.
**Publishes:** Checkout lifecycle events, consumed by Orders, Payments, Marketing.

### 2. Catalog `[CORE]`
Owns what can be sold and how it's described and organized for merchandising.
**Key concepts:** Product, Variant, Category, Collection, Attribute, List Price.
**Depends on:** Media Manager (images), Search Engine (indexing).
**Publishes:** Product created/updated/deleted, consumed by Inventory, Search Engine, Analytics, Automation Engine (missing-image/duplicate detection).

### 3. Inventory `[CORE]`
Owns stock truth: how many units exist, where, and what's reserved.
**Key concepts:** Stock Level, Warehouse/Location, Reservation, Stock Movement, Reorder Point.
**Depends on:** Catalog (product/variant identity).
**Publishes:** Low-stock / out-of-stock / back-in-stock, consumed by Automation Engine, Notification Service, Merchant Health.

### 4. Orders `[CORE]`
Owns the transactional record of what a customer committed to buy and its fulfillment lifecycle.
**Key concepts:** Order, Order Line Item (an immutable snapshot at time of purchase), Order Status, Fulfillment, Return/Refund.
**Depends on:** Catalog, Inventory (reservation/decrement), Customers, Payments, Shipping, Tax, Discount Engine.
**Publishes:** Order placed/paid/fulfilled/cancelled/refunded — consumed by nearly every INTEL module, Notification Service, Analytics.

### 5. Customers `[CORE]`
Owns who is buying and their relationship history with the store.
**Key concepts:** Customer Profile, Address Book, Purchase History (reference), Segment/Tag, Wishlist.
**Depends on:** Orders (history), User Management (shared auth substrate, if customer accounts use common login infrastructure).
**Publishes:** Customer registered, wishlist item added — consumed by Automation Engine, Marketing.

### 6. Payments `[CORE]`
Owns the secure handling of payment capture, authorization, and reconciliation status. Deliberately thin: actual card handling is delegated to a payment gateway/processor integration; this module owns only the record and state machine. **This module never stores card data** — that constraint is load-bearing for keeping CommerceDex out of PCI scope (see `06-open-questions.md`).
**Key concepts:** Payment, Transaction, Authorization, Capture, Refund, Payment Method (a reference/token, not raw card data).
**Depends on:** Orders.
**Publishes:** Payment succeeded/failed/refunded — consumed by Orders, Notification Service, Merchant Health.

### 7. Shipping `[CORE]`
Owns how an order gets from merchant to customer, physically or digitally, and what that costs.
**Key concepts:** Shipping Method, Rate, Zone, Package, Tracking Number.
**Depends on:** Orders, Inventory (package contents), Tax (shipping taxability).
**Publishes:** Shipment created/delivered — consumed by Orders, Notification Service.

### 8. Tax `[CORE]`
Owns tax calculation and rule application at checkout. Classified Core because checkout cannot complete without a correct tax result, even though the underlying rules are closer to compliance data than merchandising logic. Per the resolved decision in `06-open-questions.md` (item 3), this module's public interface must be **provider-agnostic**: self-hosted rate tables ship as the default implementation, but the interface is designed so an external tax-rate provider can be swapped in later without reworking the module boundary.
**Key concepts:** Tax Rate, Tax Class, Tax Jurisdiction, Tax Exemption.
**Depends on:** Settings (merchant tax registration), Customers (exemption status).
**Publishes:** None typically — queried synchronously by Commerce Core/Orders during checkout.

### 9. Marketing `[INTEL]`
Owns outbound campaign definition and targeting logic — the "what to say and to whom" — distinct from the Automation Engine's "when to trigger it."
**Key concepts:** Campaign, Audience/Segment, Promotion, Coupon Code (definition), Email/SMS Template.
**Depends on:** Customers (segments), Discount Engine (promotion mechanics), Notification Service (delivery).
**Publishes:** Campaign sent — consumed by Analytics.

### 10. Discount Engine `[CORE]`
Owns the rules and math of price reduction. Classified Core (not Intel) because discount validity and application must be correct and synchronous at checkout, even though discount *suggestions* are an Intel concern owned by Automation Engine.
**Key concepts:** Discount Rule, Coupon, Bundle Price, Tiered Pricing, Eligibility Condition.
**Depends on:** Catalog (applicability), Customers (eligibility).
**Publishes:** Discount applied — consumed by Orders, Analytics.

### 11. Automation Engine `[INTEL]`
The rule-based commerce intelligence hub. Owns detection and recommendation generation across the store: abandoned cart, back-in-stock alerts, reorder reminders, low-stock/overstock/slow-mover/trending detection, frequently-bought-together, bundle/cross-sell suggestions, seasonal promo suggestions, and catalog data-quality detection (missing images, duplicates, incomplete products, broken categories).
**Key concepts:** Automation Rule, Trigger, Recommendation, Detection Job, Suggestion.
**Depends on:** Orders, Inventory, Catalog, Customers (as read models/event sources).
**Publishes:** Recommendation generated, alert raised — consumed by Notification Service, Merchant Health, Marketing.
**Note:** This module is the primary reason the Postgres-backed job queue decision matters (see `03-reference-architecture.md`) — every one of these behaviors is a scheduled or event-triggered background job, never a synchronous request-path dependency. See `06-open-questions.md` for a scope-creep risk flagged against this module.

### 12. Notification Service `[SUPPORT]`
Owns delivery of merchant- and customer-facing messages across channels. A reliable dispatcher, not a decision-maker — decisions about *what* to send come from Automation Engine, Marketing, or Orders.
**Key concepts:** Notification, Channel (email/SMS/push/in-app), Template, Delivery Status.
**Depends on:** Nothing upstream by business logic — it's a subscriber to events from Orders, Inventory, Automation Engine, Marketing.
**Publishes:** Delivery succeeded/failed — consumed by Merchant Health, Analytics.

### 13. Media Manager `[SUPPORT]`
Owns storage, processing, and serving of images and other assets. This is where automatic image compression, responsive variant generation, and alt-text generation live as a service other modules call into.
**Key concepts:** Asset, Image Variant, Alt Text, Storage Location.
**Depends on:** Nothing upstream.
**Publishes:** Asset processed — consumed by Catalog (to attach final URLs), Automation Engine (missing-image detection).

### 14. Content Manager `[SUPPORT]`
Owns non-catalog storefront content that a merchant edits directly, rather than data generated by transactions: pages, banners, announcements.
**Key concepts:** Page, Block, Banner, Page-level SEO Metadata.
**Depends on:** Media Manager.
**Publishes:** Content published — consumed by Search Engine (indexing) and caching layers.

### 15. Analytics `[INTEL]`
Owns raw event capture and metric computation — the numbers — distinct from Reporting (presentation) and Merchant Health (coaching).
**Key concepts:** Metric, Event Log, Funnel, Cohort.
**Depends on:** Subscribes to events from virtually every Core module (Orders, Payments, Customers, Catalog).
**Publishes:** Computed metric — consumed by Reporting, Merchant Health.

### 16. Reporting `[INTEL]`
Owns packaging Analytics' raw metrics into merchant-consumable reports. Deliberately separated from Analytics so "compute" and "present/schedule/export" can evolve independently, per the "actionable insights over raw analytics" principle.
**Key concepts:** Report, Report Schedule, Export, Dashboard Widget.
**Depends on:** Analytics.
**Publishes:** Report generated — consumed by Notification Service (scheduled report delivery).

### 17. Merchant Health `[INTEL]`
Owns the synthesized, opinionated Store Health Score and specific coaching recommendations. The signature "actionable insights over raw analytics" module, and the clearest expression of "automation before configuration."
**Key concepts:** Health Score, Health Signal, Recommendation, Coaching Tip.
**Depends on:** Analytics, Automation Engine (alerts feed into scoring), Inventory, Orders, Notification Service (delivery stats).
**Publishes:** Health score updated — consumed by Notification Service (merchant-facing digest).

### 18. User Management `[SUPPORT]`
Owns merchant staff accounts, roles, and permissions — distinct from Customers, which is shopper-facing.
**Key concepts:** Staff User, Role, Permission, Session, Audit Log Entry.
**Depends on:** Nothing upstream.
**Publishes:** User action — consumed by Analytics/audit trail.

### 19. Settings `[SUPPORT]`
Owns merchant-level configuration that other modules read: store identity, currency, locale, tax registration, feature toggles. The most-depended-upon leaf module.
**Key concepts:** Store Setting, Feature Flag, Locale/Currency Config.
**Depends on:** Nothing upstream.
**Publishes:** Setting changed — consumed by nearly all modules, for cache invalidation.

### 20. Search Engine `[SUPPORT]`
Owns query-time discovery across Catalog (and optionally Content Manager). A thin indexing/query layer over Postgres full-text search and trigram matching (see `03-reference-architecture.md`) — not a separate service.
**Key concepts:** Search Index, Query, Facet, Ranking.
**Depends on:** Catalog, Content Manager (indexes their published data).
**Publishes:** None typically — a query-side module invoked synchronously by the storefront.

---

## Summary table

| # | Module | Tier | Primary dependencies |
|---|---|---|---|
| 1 | Commerce Core | CORE | Settings |
| 2 | Catalog | CORE | Media Manager, Search Engine |
| 3 | Inventory | CORE | Catalog |
| 4 | Orders | CORE | Catalog, Inventory, Customers, Payments, Shipping, Tax, Discount Engine |
| 5 | Customers | CORE | Orders, User Management |
| 6 | Payments | CORE | Orders |
| 7 | Shipping | CORE | Orders, Inventory, Tax |
| 8 | Tax | CORE | Settings, Customers |
| 9 | Marketing | INTEL | Customers, Discount Engine, Notification Service |
| 10 | Discount Engine | CORE | Catalog, Customers |
| 11 | Automation Engine | INTEL | Orders, Inventory, Catalog, Customers |
| 12 | Notification Service | SUPPORT | (event subscriber only) |
| 13 | Media Manager | SUPPORT | — |
| 14 | Content Manager | SUPPORT | Media Manager |
| 15 | Analytics | INTEL | (event subscriber, all Core modules) |
| 16 | Reporting | INTEL | Analytics |
| 17 | Merchant Health | INTEL | Analytics, Automation Engine, Inventory, Orders, Notification Service |
| 18 | User Management | SUPPORT | — |
| 19 | Settings | SUPPORT | — |
| 20 | Search Engine | SUPPORT | Catalog, Content Manager |

**Tier totals:** 9 Core, 5 Intelligence/Automation, 6 Supporting.