Public navigation architecture¶

Purpose¶

This document defines how CMonChoix public navigation must be understood and diagnosed.

The critical distinction is between:

the long-term public navigation architecture declared in code;
the runtime-visible navigation, which is derived from that architecture and the public catalogue data currently available;
database taxonomy/cache tables, which are runtime materializations or projections and are not the canonical definition of the navigation tree.

Do not infer the intended public taxonomy from a database table alone.

Canonical source of truth¶

The canonical long-term navigation registry is:

plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php

Function:

ccx_navigation_architecture_registry(): array

The file explicitly declares itself the single source of truth for the long-term public navigation architecture.

A registry entry can exist even when no current offer backs it. This is intentional: future leaves remain declared so the product/navigation contract is stable while catalogue coverage grows.

Runtime may expose a leaf only when its contract is backed by public offers/models, unless the leaf is explicitly configured as always_visible.

Consequently:

navigation-architecture.php
        │
        │ category/group/leaf contracts
        │ verticals
        │ accessory_types
        │ exclude_accessory_types
        ▼
runtime navigation resolution
        │
        │ evaluates current public catalogue coverage
        ▼
runtime taxonomy / navigation projections
        │
        ▼
public categories actually visible on CMonChoix

Registry contract¶

The registry is hierarchical:

category
  └── group
        └── leaf

A leaf can constrain catalogue eligibility with:

verticals
accessory_types
exclude_accessory_types
always_visible when explicitly supported by the runtime contract

Example conceptually:

'bagues-connectees' => [
    'label' => 'Bagues connectées',
    'verticals' => ['smartwatch'],
    'accessory_types' => ['bague_connectee'],
]

This means the navigation leaf belongs to the public architecture even if no matching public catalogue row currently exists.

Canonical top-level categories¶

At the current registry state, the long-term public architecture declares these top-level categories, in sort_order order:

Smartphones & Objets connectés
Informatique
TV & Audio
Électroménager
Maison & Habitat
Gaming
Photo & Vidéo
Mobilité
Beauté & Santé
Jeux & Jouets

The registry intentionally excludes jardin, mobilier, robots tondeuses and arrosage.

For the exact groups, leaves and matching contracts, read navigation-architecture.php; do not duplicate the full registry into SQL or maintain a second hand-written taxonomy as an authority.

Runtime data is not the architecture authority¶

Tables such as:

ccx_navigation_taxonomy_v1
ccx_catalog_nav_cache_v1

must not be described as the source of truth for the intended navigation architecture.

They can legitimately contain only a subset of the registry because runtime visibility depends on current catalogue coverage. They can also expose historical/stale/materialized states while a projection has not yet been rebuilt.

Therefore an empty lookup for a future leaf such as Bagues connectées, Robots aspirateurs, Trottinettes électriques or Jeux de société does not prove that the leaf is absent from the CMonChoix architecture. Check the registry first.

Similarly, rows found in a cache do not by themselves prove that a path belongs to the current canonical architecture.

Relationship with category routing¶

Do not confuse public navigation architecture with feed category routing.

includes/mapping/common/category-routing.php and its delegated modules classify incoming catalogue rows into vertical/spec/accessory semantics. They are classification infrastructure.

navigation-architecture.php defines how those semantics map into the long-term public navigation tree.

The two layers are related through values such as vertical_id and accessory type, but neither should be substituted for the other.

In simplified form:

merchant/feed row
      │
      ▼
category routing / classification
      │
      ├── vertical_id
      ├── spec_type
      └── accessory_type
      │
      ▼
normalized offers / product models
      │
      ▼
navigation architecture contracts
      │
      ▼
runtime-visible navigation

Correct server database access¶

For direct MariaDB diagnostics on the VPS, the verified container command is:

docker exec -it ccx-mariadb mariadb -u root -proot ccx

For non-interactive diagnostics:

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "SELECT 1;"

WP-CLI can also query the database from the worker container, but never hard-code the WordPress table prefix.

Verified prefix discovery:

PREFIX="$(docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db prefix | tr -d '\r')"

echo "$PREFIX"

Then build physical table names from the discovered prefix:

NAV_TABLE="${PREFIX}ccx_navigation_taxonomy_v1"
CACHE_TABLE="${PREFIX}ccx_catalog_nav_cache_v1"

Example:

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query \
  "SELECT COUNT(*) FROM ${NAV_TABLE};"

The observed VPS prefix may currently be wp_3888956, but it is an environment detail, not a stable application contract.

Why `wp_ccx_*` was wrong¶

A command such as:

SELECT * FROM wp_ccx_navigation_taxonomy_v1;

is invalid on an installation whose actual WordPress prefix is not wp_.

The observed physical table name was:

wp_3888956ccx_navigation_taxonomy_v1

The correct operational rule is therefore:

discover the prefix first, then compose the table name.

Application PHP should continue to use $wpdb->prefix; shell diagnostics should discover the prefix dynamically or use the verified MariaDB physical schema after checking it.

Diagnostic procedure for a missing menu/category¶

When a category expected from the product design is missing from the site, inspect the system in this order:

Registry — confirm that the category/group/leaf exists in navigation-architecture.php and record its verticals, accessory_types and exclusions.
Normalized catalogue — check whether public/eligible offers exist with the required classification contract.
Product models — check whether the relevant model projection exists when runtime navigation requires model backing.
Runtime taxonomy/projection — inspect ccx_navigation_taxonomy_v1 only as a runtime materialization, not as the design authority.
Navigation cache — inspect ccx_catalog_nav_cache_v1 for the actual offer/path projection and stale or legacy paths.
Rebuild/invalidation path — only after the upstream contract is understood, investigate why the runtime projection was not refreshed or exposed.

This ordering prevents a missing database row from being mistaken for a missing architecture declaration.

Useful discovery queries¶

Start by discovering the prefix and relevant physical tables:

PREFIX="$(docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db prefix | tr -d '\r')"

printf 'PREFIX=%s\n' "$PREFIX"

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query \
  "SHOW TABLES LIKE '%navigation%'; SHOW TABLES LIKE '%taxonomy%';"

Inspect the materialized taxonomy:

TABLE="${PREFIX}ccx_navigation_taxonomy_v1"

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query "
SELECT nav_category, nav_group, nav_subcategory
FROM ${TABLE}
WHERE is_active = 1
GROUP BY nav_category, nav_group, nav_subcategory
ORDER BY MIN(sort_order), nav_category, nav_group, nav_subcategory;
"

Inspect the catalogue navigation cache:

CACHE="${PREFIX}ccx_catalog_nav_cache_v1"

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query "
SELECT nav_category, nav_group, nav_subcategory, seo_path_norm_nav
FROM ${CACHE}
GROUP BY nav_category, nav_group, nav_subcategory, seo_path_norm_nav
ORDER BY nav_category, nav_group, nav_subcategory;
"

These queries answer what is currently materialized. They do not replace inspection of the canonical registry when answering what categories CMonChoix is designed to have.

Maintenance rules¶

When changing public navigation:

edit the canonical registry rather than hand-editing a cache/table as the design source;
keep category/group/leaf slugs stable unless a migration explicitly changes public URLs;
keep vertical/accessory contracts explicit;
distinguish future declared leaves from currently runtime-visible leaves;
rebuild or invalidate the appropriate runtime projection after architecture/classification changes;
verify both the registry and the materialized runtime result;
update documentation whenever the authority or runtime contract changes.

When changing category classification:

preserve category-routing.php first-match-wins semantics;
keep its Runtime boundary tests passing;
verify that resulting vertical_id/accessory semantics still satisfy the intended navigation leaf contracts.

Key rule¶

Architecture answers what CMonChoix is designed to expose. Runtime projections answer what the current catalogue can expose now.

Never use one as a silent substitute for the other.