Documentation Navigation V2.1

Status

Proposed Documentation Navigation Architecture — validated against the current 306-document corpus.

Purpose

This document supersedes the earlier Navigation V2 proposal as the working target for the CMonChoix Platform documentation site.

It is based on the current documentation corpus rather than on an older partial inventory.

Observed corpus at design time:

• 306 Markdown documents on disk;
• 191 real documents covered by Navigation V2;
• 115 real documents absent from Navigation V2;
• 3 relative references inside the V2 design document that are not valid docs-root paths.

The purpose of V2.1 is not to expose every Markdown file directly in the menu. It is to guarantee that every useful document has an explicit documentary role and a reachable home without turning the primary navigation into a filesystem mirror.

Core Rules

V2.1 preserves the normative Documentation Information Architecture rules:

• reader understanding over folder layout;
• progressive disclosure;
• one primary responsibility per page;
• no useful document left unreachable;
• current architecture separated from implementation detail and history;
• maximum practical navigation depth of three levels;
• historical evidence preserved but never allowed to define current architecture.

Top-Level Navigation

The target top-level structure is:

1. Accueil
2. Architecture
3. Domaines métier
4. Moteurs & services
5. Pipeline & ingestion
6. Verticales produit
7. Frontend & navigation
8. Base de données
9. Runtime & infrastructure
10. Exploitation
11. CLI
12. Engineering & gouvernance
13. Design cible
14. Migration & évolution
15. Historique, audits & certifications

This organization is intentionally broader than V2 because the current repository now contains mature material in Engineering, Feed, Projections, Frontend, Operations and certification/audit areas that V2 did not cover.

1. Accueil

Role:

• orientation;
• first reading path;
• documentation map;
• glossary entry.

Primary pages:

• index.md
• foundation/index.md
• foundation/platform-foundation.md
• architecture/overview.md
• architecture/faq.md
• glossary/index.md
• glossary/canonical-identity.md
• glossary/projection.md
• glossary/resolver.md

Notes:

• short entry pages may remain if they act as indexes;
• index pages must be enriched later when too weak to orient a reader;
• README.md is repository documentation and is not a public navigation entry.

2. Architecture

Role:

• explain why the Platform is structured as it is;
• expose current normative architecture;
• keep canonical responsibility boundaries easy to find.

Primary pages:

• architecture/overview.md
• architecture/blueprint.md
• architecture/vision.md
• architecture/principes.md
• architecture/invariants.md
• architecture/dependances.md
• architecture/boundary-architecture.md
• architecture/application-infrastructure-contract.md
• architecture/identifier-first.md
• architecture/canonical-identity.md
• architecture/component-map.md
• architecture/wordpress-boundary.md
• architecture/pipeline.md
• architecture/02-database.md
• architecture/navigation-architecture.md
• architecture/media-quality-engine.md
• architecture/platform/index.md
• architecture/platform/reference.md
• architecture/roadmap.md

Review/governance pages:

• architecture/architecture-review-report.md
• architecture/architecture-remediation-plan.md
• architecture/governance/industrial-quality-gates.md
• architecture/documentation-information-architecture.md
• architecture/documentation-navigation-v2.md
• architecture/documentation-navigation-v2.1.md
• architecture/documentation-navigation-migration-plan.md

Compatibility/reference pages:

• architecture/00-overview.md
• architecture/01-data-pipeline.md
• architecture/03-bootstrap.md
• architecture/04-services.md
• architecture/05-debugging.md

These compatibility pages remain reachable but should not compete with the canonical overview pages where responsibilities overlap.

3. Domaines métier

Role:

• explain business capabilities before implementation layers;
• preserve Domain First.

Product

All current business-domains/product/*.md pages remain in this section.

Catalog

• business-domains/catalog/index.md
• business-domains/catalog/projection-engine.md
• business-domains/catalog/runtime-sync-layer.md

Feed

Navigation V2.1 explicitly adds the Feed domain, which was absent from V2:

• business-domains/feed/index.md
• business-domains/feed/invariants.md
• business-domains/feed/value-objects.md

4. Moteurs & services

Role:

• provide stable technical reference after conceptual orientation;
• group domain engines, contracts, projections and application/read/write boundaries.

Domain Core

All domain-core/*.md reference pages.

Domain Engine

• domain-engine/overview.md
• architecture/engines/identity-engine.md
• domain-engine/global-event-model.md
• domain-engine/global-consistency-contract.md
• domain-engine/event-store-and-replay-engine.md

Application Engine

• application-engine/overview.md
• apps/overview.md

Contracts

All contracts/*.md pages.

Read Services

All read-services/*.md pages, with short placeholder/bridge pages kept secondary until enriched.

Write Services

• write-services/overview.md
• write-services/business-repairs.md
• narrow write-service pages remain secondary/reference until enriched.

Projections

Navigation V2.1 promotes the projection reference family:

• projections/overview.md
• projections/homepage-projection.md
• projections/navigation-projection.md
• projections/offer-projection.md
• projections/product-projection.md

Adapters

• adapters/overview.md
• adapters/wordpress.md

5. Pipeline & ingestion

Role:

• explain current catalogue flow;
• separate canonical pipeline concepts from implementation/refactor notes.

Primary operational/conceptual pages:

• pipeline/overview.md
• pipeline/feed-ingestion.md
• pipeline/stage.md
• pipeline/normalisation.md
• pipeline/enrichment.md
• pipeline/persistence.md
• pipeline/monitoring.md

Detailed architecture/reference pages:

• architecture/feed-normalization-rules.md
• architecture/category-routing.md
• architecture/category-map-normalization.md
• architecture/gaming-normalization.md
• architecture/gaming-locks-normalization.md
• architecture/image-quality-normalization.md
• architecture/photo-normalization.md
• architecture/printer-normalization.md
• architecture/offers-norm-orchestrator.md
• architecture/pipeline-flush.md
• architecture/pipeline-stage-insert.md
• architecture/row-final-builder.md
• architecture/row-to-item-mapping.md
• architecture/sync-one-helpers.md

These detailed pages are reference material, not onboarding pages.

6. Verticales produit

Role:

• explain mature vertical behavior and industrialization status;
• keep future/placeholder verticals secondary until mature.

Primary pages:

• vertical-industrialization.md
• vertical-modules/overview.md
• vertical-modules/guide.md
• vertical-modules/smartphone.md
• vertical-modules/photo.md
• vertical-modules/photo-validation.md
• vertical-modules/roadmap.md
• verticals/smartphones.md
• verticals/laptops.md

Secondary/placeholder vertical pages:

• vertical-modules/gaming.md
• vertical-modules/gpu.md
• vertical-modules/mobility.md
• vertical-modules/printer.md
• vertical-modules/toys.md
• vertical-modules/tv.md
• vertical-modules/wellness.md

Short placeholder pages remain reachable but should not be promoted as mature references until enriched.

7. Frontend & navigation

Role:

• explain public rendering, routing and navigation architecture;
• make the canonical public navigation source easy to find.

Primary pages:

• frontend/overview.md
• frontend/projections.md
• frontend/public-information-architecture.md
• frontend/public-navigation-tree.md
• architecture/navigation-architecture.md
• architecture/frontend/industrialization-status.md
• architecture/frontend/product-models-responsibility-map.md
• architecture/frontend/refactoring-product-models.md
• frontend/seo.md
• frontend/performance.md

Obsolete page:

• frontend/navigation-runtime.md

frontend/navigation-runtime.md is explicitly obsolete/superseded and must not appear in the current primary reader path. It may remain reachable from a historical/compatibility index until removal is proven safe.

8. Base de données

Role:

• provide the complete current database reference and safe diagnostic path.

Primary pages:

• database/overview.md
• database/architecture.md
• database/tables.md
• database/persistence.md
• database/projections.md
• database/lifecycle.md
• database/consistency.md
• database/invariants.md
• database/dependencies.md
• database/evolution.md
• database/schema-evolution.md
• database/best-practices.md
• database/guidelines.md

Short placeholders:

• database/flows.md
• database/kpi.md

These placeholders should not be promoted as first-class references until they are enriched or merged.

The operational architecture diagnostic page architecture/02-database.md remains in Architecture and can cross-link here.

9. Runtime & infrastructure

Role:

• explain current execution topology and runtime contracts.

Primary pages:

• runtime/overview.md
• infrastructure/overview.md
• operations/runtime-current-state.md
• operations/containers.md

Secondary runtime pages:

• runtime/orchestration.md
• runtime/batchs.md
• runtime/monitoring.md
• runtime/pipeline.md

Short runtime bridge pages remain secondary until enriched.

10. Exploitation

Role:

• group task-oriented production procedures.

Primary pages:

• operations/overview.md
• operations/deployment.md
• operations/monitoring.md
• operations/backup-restore.md
• operations/backups.md
• operations/recovery.md
• operations/maintenance.md
• operations/performance.md
• operations/troubleshooting.md
• operations/checklists.md
• operations/merchant-daily-sync-playbook.md
• operations/samsung-daily-sync.md
• operations/rebuild-models.md
• operations/rebuild-specs.md
• operations/rebuild-gallery.md
• operations/write-inventory-current-state.md
• operations/technical-write-inventory-current-state.md

Incidents:

• operations/incidents.md
• incidents/laptop-ram-parser.md
• incidents/orphan-models.md
• incidents/samsung-hard-lock.md
• debugging/samsung-galaxy-buds-smartphone-false-positive-2026-07-23.md

Support/reference:

• operations/best-practices.md
• operations/media-quality-branch-recovery.md
• debugging/ENVIRONMENT.md
• architecture/05-debugging.md

11. CLI

Role:

• expose operator/developer commands by task.

Primary pages:

• cli/overview.md
• cli/reference.md
• cli/commands.md
• cli/ccx-ops.md
• cli/audits.md
• cli/sync.md
• cli/feed-inspector.md
• existing audit/simulation/dump/report pages.

Documentation tooling:

• cli/common-library.md
• cli/docs-check.md
• cli/docs-deploy.md
• cli/docs-report.md

Short bridge commands:

• cli/feed-sync.md
• cli/rebuild-navigation.md
• cli/rebuild-projections.md

Short bridge pages stay secondary until enriched or merged into the command reference.

12. Engineering & gouvernance

Role:

• make engineering standards and documentation governance first-class;
• expose the rules used to evolve the repository safely.

Engineering:

• engineering/README.md
• engineering/engineering-standard.md
• engineering/definition-of-done.md
• engineering/component-registry.md
• engineering/master-plan.md
• engineering/roadmap.md
• engineering/technical-debt.md
• engineering/adr/ADR-000-project-principles.md

Documentation governance:

• governance.md
• governance/index.md
• governance/constitution.md
• governance/documentation-standards.md
• governance/documentation-roadmap.md
• governance/documentation-architecture-review.md
• governance/namespace-convergence-plan.md
• governance/repository-classification.md

Draft status must remain visible where documents are still draft-level.

13. Design cible

Role:

• describe target responsibilities, not necessarily current runtime state.

All current design/*.md pages remain grouped here:

• design guidelines;
• design principles;
• template;
• Domain Core;
• Vertical Modules;
• Read Services;
• Write Services;
• Pipeline;
• Runtime;
• Infrastructure;
• Interfaces;
• Governance;
• Frontend.

The section must clearly state that target design and current implementation are different documentary categories.

14. Migration & évolution

Role:

• preserve transition strategy and refactoring context without allowing it to define current architecture.

Primary pages:

• migration/overview.md
• migration/methodology.md
• migration/migration-plan.md
• migration/component-classification.md
• migration/repository-cleanup-phase-1.md
• migration/architecture-atlas.md
• migration/legacy-plugin-inventory.md

Implementation/refactoring documents that are still useful should be linked from this area or from component-specific indexes rather than placed in the primary architecture path.

15. Historique, audits & certifications

Role:

• preserve evidence;
• keep certifications and BC audit trails findable;
• prevent historical reports from polluting the current architecture path.

Certification

• certification/overview.md
• engineering/certification-matrix.md
• pipeline/awin-feed-ingestion-certification.md

Engineering audits

• engineering/audit/README.md

BC-064

• architecture/bc-064a-projection-application-boundary-audit.md
• architecture/bc-064d-feed-projection-contract-audit.md
• architecture/bc-064e-legacy-application-audit.md

BC-065

• architecture/bc-065a-eventplatform-realtime-audit.md
• architecture/bc-065b-eventbridge-persistence-boundary.md
• architecture/bc-065c-eventplatform-m12-consolidation.md
• architecture/bc-065d-projection-realtime-boundary.md
• architecture/bc-065e-final-certification.md

BC-066

• architecture/bc-066a-catalog-intelligence-audit.md
• architecture/bc-066b-catalog-intelligence-boundary.md
• architecture/bc-066c-dormant-projection-realtime-rationalization.md
• architecture/bc-066d-dormant-orchestration-decision.md
• architecture/bc-066e-final-certification.md

BC-067

• architecture/bc-067a-runtime-activation-design.md
• architecture/bc-067b-dormant-runtime-retirement-decision.md
• architecture/bc-067c-dormant-runtime-reduction.md
• architecture/bc-067d-reference-core-final-certification.md

BC-068

• operations/bc-068a-worktree-consolidation-audit.md
• operations/bc-068b-cleanup-audit.md
• operations/bc-068c-test-manifest-consolidation.md
• operations/bc-068d-documentation-consolidation.md
• operations/bc-068e-final-worktree-certification.md

Checkpoints and recovery evidence

• operations/media-quality-realignment-checkpoint.md

Historical pages remain evidence. They do not supersede current architecture, runtime state or operational documentation.

ADR Policy

The current corpus contains ADR in both docs/adr/ and docs/architecture/adr/.

V2.1 exposes them through one visible ADR navigation group while preserving physical locations until a later migration safely consolidates them.

The ADR group must include:

• adr/index.md
• adr/0001-identifier-first.md
• adr/0002-domain-core-independent.md
• adr/0003-readonly-before-runtime.md
• adr/0004-canonical-public-url-strategy.md
• architecture/adr/adr-004-identity-domain-service.md
• architecture/adr/adr-005-conflict-policy-extraction.md
• architecture/adr/adr-006-domain-without-wordpress.md

No physical ADR move is part of this navigation change.

Short Page Policy

A short page is not automatically obsolete.

A short page can be:

• a valid index;
• a bridge preserving a stable URL;
• a stub awaiting maturation;
• a compatibility reference.

However, short pages must not be presented as mature first-class references solely because they exist.

V2.1 therefore keeps weak pages reachable but secondary until one of these decisions is made:

• IMPROVE;
• MERGE;
• REPLACE;
• ARCHIVE.

Obsolete Page Policy

Pages explicitly marked obsolete or superseded are removed from current primary navigation.

They may remain reachable from a historical/compatibility index while links or audit value still justify retention.

Example:

• frontend/navigation-runtime.md — obsolete/superseded; not a current frontend reference.

Coverage Rule

The final MkDocs implementation must satisfy both of these conditions:

1. every current/canonical document needed for daily development or operations is directly navigable;
2. every useful secondary/historical document is reachable from a navigable index or archive section.

The goal is not 306 menu items.

The goal is 306 classified documents with no unexplained orphan.

Validation Gates

Before V2.1 replaces the current MkDocs navigation:

• every referenced path must exist;
• no docs-root-invalid relative path may be introduced;
• no explicitly obsolete page may appear in the current primary path;
• canonical pages added since V2 must be represented;
• Feed, Engineering, Projections, Frontend navigation and current Operations must be represented;
• BC audit/certification material must remain reachable but historical;
• mkdocs build --clean must succeed;
• canonical documentation audit must pass;
• the rendered navigation must remain usable on desktop and mobile;
• site deployment must record the exact Git commit in site/.ccx-docs-commit only after a successful build.

Migration Sequence

Implement V2.1 in controlled steps:

1. commit this V2.1 design document;
2. update mkdocs.yml only after review of this structure;
3. build MkDocs locally with .venv-docs/bin/mkdocs;
4. inspect all build warnings;
5. add reachable archive/index paths where useful documents remain outside direct navigation;
6. run bash tools/audit/run.sh;
7. validate desktop/mobile rendering;
8. only then integrate into the main refactor branch and deploy the generated site.

Related Documents

• Documentation Information Architecture
• Documentation Navigation V2
• Documentation Navigation Migration Plan
• Documentation Architecture Review

Decision

Navigation V2.1 is the working target because it reflects the current documentation corpus and preserves the distinction between:

• current architecture;
• business domains;
• stable technical references;
• implementation details;
• operations;
• target design;
• migration context;
• historical audit evidence.

No existing document is deleted by this decision.