SchemaCommerce

React 19 + TypeScript SPA storefront scaffold.

Scripts

• npm run dev – start dev server
• npm run build – schema registry generation + typecheck + production build
• npm run typecheck – TypeScript project build (no emit)
• npm run lint – ESLint
• npm run format – Prettier
• npm run test – Vitest

Requirements overview (consolidated)

This project implements a schema.org registry-driven storefront with mixed-type commerce flows. The requirements below consolidate functional, non-functional, and constraint-driven expectations.

Functional requirements

FR-SCHEMA-001 – Deterministic schema.org registry

• Ingest a pinned schema.org release at build time.
• Generate a deterministic registry with types, properties, and datatypes.
• Preserve multiple inheritance and hosted sections (core, pending, attic).
• Include release metadata and deterministic hash.

FR-CATALOG-001 – Registry-driven catalogue

• Provide a type gallery and type detail view that are driven by the local registry.
• Allow search and filtering across type name/id/description, hosted section, and term status.
• Ensure stable sorting in gallery and deterministic ordering in UI lists.

FR-COMMERCE-001 – Mixed-type commerce flows

• Items are schema.org-driven and may represent Products, Recipes, or other types.
• Sellability is offers-driven (presence of valid offer with availability).
• Generic item rendering must support composite decomposition hints when present.

FR-BASKET-001 – Basket intent

• Basket intent is the only client-persisted data.
• Basket flows must support add/update/remove items and compute totals via pricing port.

FR-CHECKOUT-001 – Checkout & order placement

• Revalidate pricing, inventory, promotions, tax, and shipping before placing order.
• Block order placement if deltas are detected.
• Use idempotency keys for order placement.

FR-INTEGRATION-001 – Ports/adapters

• All external capabilities must be accessed via domain ports.
• Demo uses deterministic stubs with fault injection (timeouts, 500s, partial).
• All adapters must be time-bounded and cancellable via AbortController.

FR-CONFIG-001 – Runtime configuration

• Configuration is treated as untrusted input and validated before use.
• Runtime navigation is loaded from configuration with feature gating.

Non-functional requirements

Performance & budgets

• Enforce bundle and interaction latency budgets in CI.
• Type Gallery must be responsive with virtualization.
• Core Web Vitals targets are tracked in CI (LCP/INP/CLS).

Reliability

• Adapter calls use timeouts, cancellation, and bounded retries/backoff.
• Resilient error states for partial failures and offline behavior.

Security

• CSP and secure headers required for hosting.
• Configuration and content are sanitized; no secrets in bundle.
• No raw card data handled or persisted client-side.

Privacy

• Data minimization; no PII persisted client-side.
• Analytics gated by consent and uses synthetic data only.

Accessibility

• WCAG 2.2 AA intent.
• Automated checks in CI and accessible virtualized lists.

Observability

• Telemetry without PII; session/correlation IDs via infra.

Compatibility

• Latest Chromium/Firefox/WebKit.

Constraints

• React 19 + TypeScript 5+, Vite, React Router.
• Route-level code splitting.
• Schema.org multiple inheritance and hosted sections must be preserved.
• External capabilities abstracted via ports/adapters.
• Client persistence limited to basket intent.
• Runtime config validated before use.
• SPA hosting supports deep links and runtime config caching.

Routes (current)

• / Home
• /types Type Gallery
• /datatypes DataTypes
• /catalogue Catalogue (stub)
• /item/:type/:id Item detail (stub)
• /basket Basket (stub)
• /checkout Checkout (stub)
• /orders Orders (stub)
• /orders/confirmation/:orderId Order confirmation (stub)
• /account Account (stub; gated by navigation feature flag)
• /config Runtime config editor/validation

CI evidence expectations

• Deterministic schema registry generation tests.
• Domain port contract tests.
• Runtime config validation tests.
• Performance budget and Web Vitals gating (to be wired into CI).
• End-to-end smoke via Playwright (pending).

Architecture

See docs/architecture/hexagonal.md for hexagonal layering, registry usage, and integration contracts.