# Open Questions & Risks — Phase 3

Flagged for awareness before Phase 4 (Design System & UI Framework) and implementation (Phase 5+) begin. None block Phase 3.

## 1. `system.job` / `system.event` retention and partitioning

Both tables are append-only and grow forever by design. No retention policy is specified here — a nightly abandoned-cart scan alone could generate a meaningful number of `system.job` rows per year for an active store.

**Needs a decision before production release (Phase 12):** partition `system.job` and `system.event` by month, and define a retention window for `succeeded` jobs (e.g., archive or delete after 90 days) while keeping `failed` jobs and the `system.event` log itself (the audit trail of what happened) for longer, since Analytics and Merchant Health may reference historical events.

## 2. `analytics.event_log` vs. `system.event` overlap

`02-module-schemas.md` gives Analytics its own `event_log` table, distinct from the shared `system.event` log in `03-event-and-job-system.md`. Analytics' worker subscribes to relevant `system.event` rows (via a `system.job` of type `analytics.record_event`) and writes its own copy into `analytics.event_log` — this looks like duplication.

**Clarification for Phase 5 implementation:** this is intentional, not redundant. `system.event` is dispatch-plumbing (transient-ish, subject to the retention policy in #1) and not queryable by business intent; `analytics.event_log` is the durable, business-shaped record Reporting and Merchant Health actually query against, structured for analysis rather than dispatch. Worth restating clearly in code comments/onboarding docs so a future contributor doesn't "simplify" this into one table and break the module boundary between system plumbing and business-owned data.

## 3. Eventual consistency of search index and customer segments

`search.search_index_document` and `customers.customer_segment_member` are both maintained by background jobs reacting to events, not updated synchronously with the write that triggers them (`02-module-schemas.md`). A merchant who edits a product and immediately searches for it, or adds a customer to a segment's qualifying criteria and immediately checks Marketing's audience count, may see stale results for a brief window.

**Needs a decision before Phase 4 finalizes the Products/Marketing screens:** whether this lag is acceptable as-is (likely fine — sub-second to low-seconds with `SKIP LOCKED` polling at reasonable intervals) or whether specific actions (e.g., saving a product) should sychronously update the search index inline as an exception to the general async pattern, accepting the added coupling for a better-feeling save experience.

## 4. Customer data deletion across module boundaries

`orders.order` references `customer_id`, and order data is retained indefinitely for business/accounting reasons (`02-module-schemas.md`). If a customer's data must be deleted or anonymized (a data-subject deletion request), `customers.customer` can be anonymized directly, but historical orders still reference that `customer_id` — and unlike product line items, no customer-detail snapshot is currently specified on the order.

**Needs a decision before Phase 12 (Security & Compliance):** define whether Orders should store a minimal frozen snapshot of customer contact info at time of purchase (mirroring the `*_snapshot` pattern already used for products on line items), so that anonymizing `customers.customer` doesn't silently corrupt historical order records the merchant needs for accounting/tax purposes.

## 5. ULID storage type

`01-database-design-principles.md` specifies ULID primary keys but doesn't commit to a storage representation (native Postgres type via extension, vs. plain `text`/`char(26)`).

**Deferred to implementation (Phase 5):** not an architecture-level decision — pick based on the final language/framework's ecosystem support when that's chosen.

## 6. Permission model and future third-party integrations

`06-permissions-model.md` designs permissions for staff accounts only. It does not address how a future API key or third-party app integration (webhooks, a mobile companion app, etc.) would authenticate and what it could access — that concept doesn't exist yet in this architecture.

**Not a Phase 3 gap** — no such integration surface has been scoped anywhere in Phases 1–3, and per "simplicity before flexibility," it should not be speculatively designed now. Flagged only so that if/when a future phase introduces API access, it reuses the `permission_key` vocabulary from `06-permissions-model.md` rather than inventing a parallel scheme.

---

**Status:** Item 4 is the one worth resolving soonest — it affects the Orders schema (`02-module-schemas.md`) and is easiest to build in from the start rather than retrofit. Items 1 and 3 are implementation-detail decisions with low risk either way. Items 2, 5, and 6 are clarifications/deferrals, not open decisions.