hemn/mataba

Fork 0

Files

T

XShop f11e1d650d chore: complete M1.1 runtime QA and release packaging

2026-09-13 19:04:41 +03:30

7.6 KiB

Raw Blame History

XShop – Architecture (v1.0.0)

1. Overview

repo/
  docs/                 # product specs & ADRs
  xshop-theme/          # presentation layer
  xshop-core/           # companion plugin
  release/              # built zips (not committed)
  tools/                # build / QA scripts

Two installable artifacts: theme (xshop) + plugin (xshop-core). Theme never stores business logic that outlives theme activation (wishlist/compare/Q&A/banners live in plugin).

2. Theme – `xshop-theme`

2.1 File map (M1)

xshop-theme/
  style.css             # WP header
  functions.php         # thin loader (requires inc/setup/* only)
  screenshot.png        # placeholder until final artwork
  rtl.css               # WP RTL flag; logical props used, not duplicated stylesheet
  header.php            # <html> + skip link + xshop-header wrapper + breadcrumbs
  footer.php            # </main> + footer + wp_footer
  index.php / front-page.php / single.php / page.php / archive.php / search.php / 404.php / sidebar.php / comments.php
  inc/
    setup/              # theme-support, menus, sidebars, body-classes, assets
    helpers/            # sanitize, template (xshop_get_setting, xshop_svg, xshop_is_dark_mode, xshop_has_woocommerce, branding fallback)
    customization/      # options (xshop_settings) — full UI in M6
    compatibility/      # gutenberg, elementor (no hard dep)
    woocommerce/        # wrappers + dequeued WC styles + notice compat
    performance/        # defer for xshop.js
  assets/
    css/                # tokens, base, layout, components, utilities
    js/                 # theme.js (mobile nav + dark toggle + focus trap)
    images/ fonts/
  template-parts/components/
    site-header.php, site-footer.php,
    breadcrumbs.php, pagination.php, search-form.php, post-card.php,
    empty-state.php, loading.php, section-heading.php, hero.php, promo-banner.php
  woocommerce/          # empty in M1 — overrides only when justified (documented)
  languages/

2.2 Bootstrap

functions.php is a thin loader:

require_once __DIR__ . '/inc/setup/theme-support.php';
require_once __DIR__ . '/inc/setup/menus.php';
// ... each file exposes a single setup function hooked appropriately

No giant functions.php. Each inc/* file is namespaced or prefixed xshop_.

2.3 Namespacing & Prefixing

Text domain: xshop
PHP functions/options/actions/meta: xshop_ prefix.
Classes: XShop\Theme\... and XShop\Core\... (PSR-4 style even if manual require).

2.4 Hook Strategy

Use after_setup_theme for theme support, init for CPT/taxonomy (only banners/Q&A).
Use wp_enqueue_scripts with conditional loading.
Use WC hooks for pricing, badges, loops – avoid overriding templates unless necessary.

3. Plugin – `xshop-core`

xshop-core/
  xshop-core.php        # plugin header + loader
  includes/
    Core/               # plugin bootstrap, constants
    Modules/
      Wishlist/
      Compare/
      QA/
      Search/
      Filter/
      Banners/
      Badges/
      DemoImport/
      SetupWizard/
      SystemStatus/
      Widgets/
    Admin/              # menu, dashboard, settings pages
    REST/               # REST endpoints (search/filter/wishlist/compare/QA)
    Compatibility/
  assets/ css/ js/
  languages/
  templates/            # wishlist, compare, banners front-end fragments

Plugin owns persistence for wishlist/compare/Q&A/banners. Theme only renders.

4. Data Ownership

WC: products, variations, orders, customers, coupons, shipping, payment, taxes, cart, checkout.
WP: users, posts, pages, media, menus, comments.
Custom: banners (CPT xshop_banner), Q&A (CPT or comments extension – see DATABASE-MODEL.md), wishlist/compare (user meta + cookie + transient for guests), theme settings (single option xshop_settings + mods).

Avoid custom tables in v1; revisit via ADR if scale demands.

5. Design System (M1)

CSS custom properties in assets/css/tokens.css — full token set: primary/secondary/bg/surface/card/text/muted/border/input/focus/link/success/warning/danger (+ bg variants), typography (xs–4xl, weights 400/500/700, leading tight/normal/relaxed), spacing (1–16), container/narrow, radius (sm/md/lg/full), shadow (sm/md/lg), z, transition (fast/normal/slow). Dark mode semantic swap on [data-theme="dark"]. Layering: tokens→base→layout→components→utilities→style.css via inc/setup/assets.php:1.

Logical properties (margin-inline, padding-inline, inset-inline, inset-block, inline-size) throughout; zero left/right in theme CSS. Components consume tokens, never hardcode colours.

6. Asset Strategy (M1)

No jQuery for new code (vanilla JS; theme.js:1 is deferred). WC jQuery remains for its handlers.
Enqueue: tokens→base→layout→components→utilities→style.css chain in inc/setup/assets.php:1 with version XSHOP_VERSION; style.css declares rtl replace. WC styles dequeued (woocommerce_enqueue_styles → __return_empty_array) to avoid duplication — theme provides compat in components.css:1.
Conditional: feature modules (search/filter/wishlist) will be enqueued per-template in M5; M1 only loads theme.js.
Localized xshopData (restUrl, nonce, isRtl, i18n) on xshop handle.
Build: no build step required to activate; release minify via tools/build-release.ps1.

7. AJAX / REST

Prefer WP REST API for search/filter/Q&A (cacheable, nonce via X-WP-Nonce), fallback to admin-ajax for cart/mini-cart where WC expects it. All endpoints: sanitize → validate → capability check → nonce → escaped output.

8. Security Model

See SECURITY.md. TL;DR: sanitize in, escape out, nonces, capability checks, prepared statements, no unserialize, no open redirects.

9. Performance Model

See PERFORMANCE.md. Conditional assets, lazy-load, transients for expensive queries, no N+1, wp_cache.

10. i18n / RTL

All strings via __(), _e(), esc_html__() with text domain xshop.
Logical CSS, dir attribute toggling, is_rtl() branching only where logical props insufficient.
Persian typography tokens, lang="fa" support, mixed LTR numbers handled via unicode-bidi where needed.

11. Templating (M1)

header.php:1 renders site-header.php:1 + breadcrumbs:1 (except front/404); footer.php:1 renders site-footer.php:1. All content templates (index.php:1, front-page.php:1, single.php:1, page.php:1, archive.php:1, search.php:1, 404.php:1) use Loop + get_template_part() + comments_template() / dynamic_sidebar() where appropriate. Reusable components: breadcrumbs, pagination, search-form, post-card, empty-state, loading, section-heading, hero, promo-banner. No markup duplication. front-page.php:1 is section-based (hero, category grid, product grid via wc_get_products, promo, latest posts) — extensible via xshop_front_hero_args filter.

WC overrides: none in M1; wrappers via woocommerce_before_main_content/after_main_content in inc/woocommerce/setup.php:1. Future overrides documented in docs/woocommerce.md with version map.

12. Decision Records

ADRs in docs/ADR/ – one per major decision (e.g., “No custom tables for Q&A in v1”).

13. Release

release/xshop.zip + release/xshop-core.zip built via tools/build-release.ps1. Excludes .git, node_modules, .env, logs, temp.

14. Versioning

SemVer 1.0.0. CHANGELOG.md follows Keep a Changelog.

15. Risks & Mitigations

WC API churn → pin tested versions, monitor template versions, use hooks not overrides.
RTL regressions → logical props + visual regression checklist.
Demo import timeouts → chunked importer with resume.

7.6 KiB Raw Blame History Unescape Escape