# Open Questions & Risks These are flagged for explicit stakeholder awareness and sign-off before Phase 2 (Information Architecture & UX Flows) begins. None of them block Phase 1 — they're deliberate trade-offs or decisions deferred to a later phase, documented here so they're a known choice rather than a surprise discovered mid-build. ## 1. Opinionated simplicity vs. module extensibility — RESOLVED The domain architecture (`04-domain-modules.md`) deliberately keeps 20 modules with clean boundaries, partly *for future extensibility* — swapping Postgres search for something else later, or extracting the Automation Engine into a separate worker fleet. This could look like it fights "opinionated defaults over endless customization" (`02-principles-and-tradeoffs.md`). **Resolution stated in `02-principles-and-tradeoffs.md`:** internal architecture can be modular for the people building it; the merchant-facing product surface must still feel like one coherent, opinionated system — never a set of togglable modules or a settings screen per module. **Decision (2026-07-09):** Confirmed as a **hard constraint** for Phase 2. Information architecture must be organized around merchant goals and workflows, never around the internal 20-module map — no per-module settings screens, no exposed module names anywhere in the merchant-facing product. ## 2. Boundary enforcement is documentation-only until Phase 3 The module interaction rules in `05-module-interaction-model.md` (no cross-module joins, no shared tables, interface/event-only communication) are currently enforced by convention and code review, not by tooling. If that discipline erodes during implementation — a developer takes a shortcut and joins across module tables "because it's all one database anyway" — the future extraction path quietly disappears and the codebase becomes a true single monolith with no real seams. **Needs a decision in Phase 3:** pick an enforcement mechanism (schema-per-module at the database level, a dependency-boundary linter, or both) before implementation scales past a couple of modules. ## 3. Tax module: fully in-house vs. pluggable provider — RESOLVED Tax is classified `[CORE]` because checkout can't complete without a correct calculation, but tax logic is arguably the least "commerce-native" module — it's compliance data more than merchandising logic, and many real-world systems eventually delegate to an external tax-rate API/service (rates and jurisdictions change; keeping them current in-house is a maintenance burden, not a feature). **Decision (2026-07-09):** Design the Tax module's public interface to be **provider-agnostic from the start**. Self-hosted rate tables ship as the default implementation behind that interface, but the interface itself must not assume in-house logic, so an external tax-rate API/provider can be swapped in later without reworking the module boundary. This constraint carries into Phase 3's interface design for Tax. ## 4. Payments and PCI scope Payments (`04-domain-modules.md`, module 6) is modeled as deliberately thin: it owns the payment record and state machine, and delegates actual card handling to a gateway/processor integration. **This module must never store raw card data.** This is the right call for a self-hosted product — it keeps the merchant/product operator out of full PCI-DSS scope. But it needs to be stated as a **hard constraint**, not an implicit assumption, so that Phase 3's schema design and any future payment-gateway integration work doesn't accidentally introduce card-data storage (e.g., "just cache the card number for retry logic" is exactly the kind of shortcut this constraint rules out). ## 5. Search Engine ceiling Postgres full-text search plus trigram matching (`03-reference-architecture.md`) is a deliberate, accepted trade-off — it covers the large majority of single-store catalog search needs cheaply, but it is measurably less capable than a tuned Elasticsearch for very large catalogs with heavy faceting or advanced typo-tolerant fuzzy search at scale. **Documented threshold:** this is expected to hold comfortably for catalogs up to roughly 10,000 SKUs with moderate faceting. Beyond that, or for merchants with unusually demanding search/discovery requirements, revisiting this decision (e.g., an optional Elasticsearch/OpenSearch backend behind the same Search Engine module interface) is reasonable and anticipated — not a sign the original decision was wrong. ## 6. Automation Engine scope risk — RESOLVED (deferred) The Automation Engine (`04-domain-modules.md`, module 11) is the single busiest module — 12+ distinct behaviors spanning recovery/re-engagement, inventory intelligence, merchandising intelligence, and catalog quality detection (see `01-product-vision.md`'s automation catalog). It is the module most likely to balloon in scope and the most likely to violate its own bounded-context discipline by becoming a dumping ground for "anything vaguely automated." **Recommendation for Phase 3:** even while staying one module/tier at the domain-architecture level, plan for clear internal sub-organization within Automation Engine — e.g., detection jobs, recommendation generation, and trigger/campaign execution as distinct internal concerns with their own code boundaries — so the module doesn't become unmaintainable as behaviors are added. **Decision (2026-07-09):** Explicitly deferred to Phase 3. Phase 1 stays at the module-boundary level (one module, one tier, as documented above) — no internal sub-structure is sketched here. Phase 3 should treat this note as a flag to address early when System Architecture & Database Design reaches this module, not as something already designed. ## 7. Defining "commercial-grade" without multi-tenancy — RESOLVED CommerceDex is confirmed single-tenant-per-install (`01-product-vision.md`), so "commercial-grade" cannot mean SaaS-scale concerns like tenant isolation or noisy-neighbor protection — those don't apply here. **Decision (2026-07-09):** Confirmed and locked in. "Commercial-grade" for CommerceDex means reliability, data integrity, and a solid backup/restore story for a *single store's* data — the bar a merchant depends their business on, not the bar a multi-tenant platform operator depends on. Phase 3 must not over-engineer for multi-tenancy concerns that were explicitly ruled out in Phase 1. --- **Status (updated 2026-07-09):** Items 1, 3, 6, and 7 are resolved per the decisions recorded above. Item 4 (Payments/PCI) is settled as a hard constraint, not a genuine open choice. Items 2 (boundary enforcement mechanism) and 5 (Search Engine ceiling) remain open, informational trade-offs to revisit in Phase 3 — item 2 needs an actual enforcement decision (schema-per-module + linter, or both) before implementation scales past a couple of modules; item 5 is an accepted trade-off with a documented ~10,000-SKU threshold, not a blocker. Nothing remains outstanding for Phase 2 to begin.