164 lines
7.6 KiB
Markdown
164 lines
7.6 KiB
Markdown
# 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:
|
||
|
||
```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.
|