# 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 # + skip link + xshop-header wrapper + breadcrumbs footer.php # + 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: ```php 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.