# Principles & Tradeoffs

These 8 principles are non-negotiable. Every architecture, UX, and feature decision throughout the project must be checked against them. When a decision seems to serve one principle at the expense of another, resolve the conflict using the guidance below — don't silently pick one.

## The principles, and what each rules out

1. **Simplicity before flexibility.**
   Rules out: configuration options that exist "just in case," pluggable systems where a single opinionated default would do, and any feature that requires the merchant to make a decision the software could make for them.

2. **Automation before configuration.**
   Rules out: manual setup steps for anything the system can detect or infer (e.g., asking a merchant to tag "low stock" thresholds one product at a time instead of computing a sensible default and letting them override it).

3. **Workflow before settings.**
   Rules out: dumping raw settings screens on merchants. Every configurable behavior should be reachable through the workflow it affects, not a separate settings maze.

4. **Business language before technical language.**
   Rules out: exposing internal architecture concepts (modules, events, jobs, schemas) anywhere in the merchant-facing product. A merchant should never see the word "Automation Engine" — they see "Abandoned Cart Recovery."

5. **Opinionated defaults over endless customization.**
   Rules out: a plugin marketplace model, theme systems with unlimited configuration surfaces, and "build it yourself" extensibility as a primary product offering.

6. **Actionable insights over raw analytics.**
   Rules out: dashboards that are just charts. Every metric surfaced to a merchant should come with a specific recommendation or next action, not just a number.

7. **Consistency over feature quantity.**
   Rules out: shipping a feature that behaves differently from the rest of the product just because it was faster to build that way, or matching a competitor's feature checklist at the cost of a coherent experience.

8. **Merchant productivity over developer convenience.**
   Rules out: making an architectural or product choice because it's easier to build, when it costs the merchant time or clarity. When engineering convenience and merchant experience conflict, the merchant wins.

## Resolving conflicts between principles

**Simplicity/opinionated-defaults vs. the module architecture's internal extensibility.** The domain architecture (`04-domain-modules.md`) deliberately keeps 20 modules with clean boundaries — partly so that individual pieces (like Search or the Automation Engine) can be swapped or scaled later without a rewrite. This looks like it fights "simplicity before flexibility" and "opinionated defaults over endless customization." It doesn't, because these principles govern the **merchant-facing product surface**, not the internal codebase structure. Internally, engineers get modular boundaries for maintainability and future headroom. Externally, the merchant sees one coherent, opinionated system — never a set of togglable modules or a settings screen per module. If a UX decision in Phase 2 is tempted to expose "20 modules" as 20 separate configuration areas, that's principle 3 and 5 being violated by an architecture detail leaking into the product. Don't let it.

**Automation before configuration vs. merchant trust.** Fully automated decisions (auto-applying a discount, auto-reordering stock) can feel like a loss of control if a merchant doesn't understand why something happened. The resolution is not "add a setting to disable it" by default — it's "make the automation's reasoning visible and reversible" (e.g., Merchant Health explains *why* it flagged something, and every automated suggestion is a suggestion the merchant can accept or dismiss, not a silent irreversible action on Core commerce data like pricing or orders). Automation owns detection and recommendation; the merchant retains the final say on anything that touches money or customer-facing content, unless they've explicitly configured otherwise.

**Consistency over feature quantity vs. the breadth of the automation catalog.** The built-in automation list (`01-product-vision.md`) is large. Consistency doesn't mean cutting scope — it means every one of those behaviors should look and feel like it came from the same design system and follows the same interaction pattern (a detected issue, a plain-language explanation, a suggested action), so the platform doesn't feel like a bag of unrelated features bolted together.