> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartwpplugins.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> File map, storage model, and how the codebase is built

## File map

| Area | Files | Responsibility |
| - | - | - |
| Bootstrap | `unwan-for-woocommerce.php` | Constants, namespace loader, compatibility declarations, WooCommerce gate |
| Coordination | `includes/Plugin.php` | Wires up services, styles, translations, activation, once-per-version upgrade steps |
| Persistence | `includes/AddressRepository.php` | Unified storage, default swaps, duplicate detection, formatting |
| Settings | `includes/Admin/Settings.php` | Accounts & Privacy subsection, behavior, labels, appearance |
| Admin orders | `includes/Admin/OrderAddresses.php`, `assets/js/unwan-admin-order.js` | Saved-address dropdown on the admin order screen |
| My Account | `includes/AccountController.php`, `templates/myaccount/` | Endpoint, form handling, actions |
| Picker controller | `src/unwan-address-picker.js` | Shared standard-DOM markup and interaction |
| Picker styles | `assets/css/unwan.css` | Scoped reset and all visual presentation |
| Classic checkout | `includes/Checkout/ClassicCheckout.php` | Shortcode checkout adapter |
| Checkout Blocks | `includes/Checkout/BlocksController.php`, `BlocksIntegration.php`, `src/blocks/` | Blocks registration and Store API integration |
| Translations | `languages/`, `wpml-config.xml` | Bundled POT, ten locale catalogues, block script-translation JSON, label declarations for WPML and Polylang |
| Privacy | `includes/Privacy.php` | WordPress personal data exporter and eraser for saved addresses |
| Uninstall | `uninstall.php` | Opt-in settings and address cleanup |
| Tests | `tests/`, `phpunit.xml.dist` | Integration suite run against real WordPress + WooCommerce (development only) |

## No custom database tables

Unwan stores exactly one thing of its own: a single namespaced user-meta key, `_unwan_addresses`, holding every customer's additional (role-free) addresses as one serialized collection. The two profile defaults are read from WooCommerce's own billing/shipping user meta — Unwan never creates a second, competing copy of that data. There is nothing here for a host to migrate, index, or back up beyond what WooCommerce already manages.

## PSR-4 autoloading, without a Composer runtime dependency

Every PHP class lives under the `Unwan\AddressLibrary` namespace and is autoloaded via a small `spl_autoload_register` callback defined directly in `unwan-for-woocommerce.php` — mapping the namespace onto `includes/`. Composer's `vendor/autoload.php` is **never required in production**; Composer is used only for the project's own development tooling (WordPress Coding Standards, PHPCompatibility), and `vendor/` is excluded from every release archive.

> [!NOTE]
>
> Class files are named after their class (`AddressRepository.php`), not the legacy WordPress core `class-{name}.php` convention — a deliberate, documented choice to keep PSR-4 autoloading straightforward.

## Request-level caching

Building a customer's combined address book involves normalizing raw stored data and formatting display text — work that's identical whether it's needed for the billing selector, the shipping selector, or My Account on the same page load. `AddressRepository` caches its saved-address, profile-default, combined-book, and checkout-option lookups for the lifetime of the current request, and invalidates all of it immediately after any mutation. The practical effect: a checkout page rendering both selectors does the normalization work once, not twice.

## Translations

Unwan ships its own translations rather than waiting for volunteers on translate.wordpress.org. `languages/` holds the POT, ten locale catalogues as `.po` plus compiled `.mo`, and the script-translation JSON the block bundles need. Bundled locales, all left-to-right: `es_ES`, `fr_FR`, `de_DE`, `it_IT`, `pt_BR`, `nl_NL`, `pl_PL`, `ru_RU`, `sv_SE`, `ja`.

PHP and JavaScript resolve through different mechanisms, and their precedence runs in opposite directions:

| Side | Loaded by | Wins on conflict |
| - | - | - |
| PHP | `load_plugin_textdomain()` on `init` | `WP_LANG_DIR` — a community translation overrides the bundled copy |
| Block JS | `wp_set_script_translations()` with an explicit path | The bundled `languages/` copy, checked before `WP_LANG_DIR` |

The PHP loader is required, not vestigial. `WP_Textdomain_Registry` searches only `WP_LANG_DIR/plugins`, `WP_LANG_DIR/themes`, and paths registered through `load_plugin_textdomain()` — omit the call and the bundled catalogues are never found. It runs on `init` because WordPress 6.7 and later emit a `_doing_it_wrong()` notice for translations loaded earlier.

Script translations are keyed by a hash WordPress computes over the **built** script path (`build/blocks/frontend.js`), not the `src/` path the strings were extracted from, producing filenames like `unwan-for-woocommerce-fr_FR-<md5>.json`.

> [!NOTE]
>
> WordPress.org's Plugin Check reports `load_plugin_textdomain()` as a discouraged function. That rule assumes a plugin whose translations come only from translate.wordpress.org, which stopped applying once Unwan bundled its own — the finding is a warning, is expected, and removing the call would silently disable all ten locales.

## Coding standards

Every PHP file is checked against a WordPress Coding Standards ruleset (`WordPress-Extra` plus `PHPCompatibilityWP`, targeting PHP 7.4+) before release, with a small number of documented, narrowly-scoped exceptions (PSR-4 filenames, template-scope variables that PHPCS's static analysis can't see are request-local). JavaScript and CSS go through `wp-scripts`' standard lint configuration. None of this is visible to a store owner directly — it's why the plugin stays predictable to extend and unlikely to collide with other well-built plugins on the same site.

## Testing

Unwan is covered by 211 integration tests that boot a real WordPress install with WooCommerce active, using the WordPress core PHPUnit library. They are not unit tests against mocks: every assertion runs through actual `WC_Customer` objects, real user meta, and the real template stack, which is what makes them useful as a compatibility check against a new WordPress or WooCommerce release.

| Area | What is asserted |
| - | - |
| Storage | Where each address lives, field sanitization, how the two defaults and the shared extras combine into one book |
| Duplicates | That case, accents, and whitespace normalize away, and that a different name at the same street stays a separate entry |
| Default roles | That reassigning a default never loses the displaced address, even when the additional-address limit is already full |
| Checkout | Option shaping and ordering, cache invalidation, validation, and that an order-specific choice does not rewrite profile defaults — including virtual and local-pickup orders, and checkout updates that must never save the profile |
| Settings | Sanitization, label placeholders and fallbacks, and that every label setting is declared in `wpml-config.xml` |
| Privacy and upgrades | Personal data export and erasure, and the once-per-version rewrite refresh and label cleanup |
| Hooks | Every filter and action on the [Hooks Reference](https://docs.smartwpplugins.com/unwan/developers/hooks-reference.md), with its documented signature |
| My Account | Markup structure, output escaping, search visibility, and that one customer can never open another's address |
| Blocks | Block registration, the Store API extension schema, and that guests receive no address data |
| Uninstall | That cleanup stays opt-in and never touches WooCommerce's own profile fields |
| Admin orders | The dropdown's data and ordering, plain-text labels, the country filter, staff-only loading, the on/off setting, and that saving an admin order changes no customer address |

Two of the tests exist to catch drift rather than defects. One fails when a new setting is added without also adding it to the uninstall routine's option list — the failure mode it prevents is data left behind after a "full removal". The other fails when the plugin's `Tested up to` header falls behind the WordPress version the suite just ran on, which is what prompts a re-verification instead of letting the claim quietly go stale.

> [!NOTE]
>
> The suite is development tooling. `tests/` is excluded from the release archive, so nothing described here ships to a store.

## Compatibility declarations

Unwan declares compatibility with WooCommerce's High-Performance Order Storage (`custom_order_tables`) and Cart & Checkout Blocks (`cart_checkout_blocks`) features via `FeaturesUtil::declare_compatibility()`, registered on `before_woocommerce_init` — before WooCommerce's own feature system finishes initializing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.