Documentation Navigation V2¶

Status¶

Proposed Documentation Navigation Architecture

Purpose¶

This document defines the target MkDocs navigation architecture for CMonChoix Platform.

It does not change mkdocs.yml.

It defines the navigation structure that should eventually become official after validation.

The target navigation must:

help a new reader understand the Platform progressively;
give developers direct access to the official component references;
give architects stable access to normative architecture and ADR;
give operators task-oriented access to runtime, CLI and operations material;
keep contributors aligned on where new documentation belongs;
limit navigation depth to three levels;
avoid duplicated entry points;
preserve useful annexes and legacy material without polluting first-level reading paths.

Top-Level Information Model¶

The target documentation is organized by understanding, not by filesystem layout.

The top-level sections are:

Start Here
Governance
Architecture
Business Domains
Target Design
Platform References
Runtime And Operations
Migration
ADR
Annexes

Section Roles¶

Start Here¶

Role:

onboarding;
orientation;
vocabulary entry;
first reading path.

Audience:

new developer;
contributor;
occasional reader.

Governance¶

Role:

define documentary governance;
define project governance entry points;
keep official standards and constitution visible.

Audience:

contributor;
architect;
documentation owner.

Architecture¶

Role:

explain why the Platform is designed the way it is;
expose the normative architecture path;
host architecture review and remediation material.

Audience:

architect;
senior developer;
contributor.

Business Domains¶

Role:

expose business capabilities as concepts, not technical layers;
explain what the Platform models before explaining how it is implemented.

Audience:

developer;
architect;
product-minded contributor.

Target Design¶

Role:

explain the target responsibilities of major components;
show what each component should become.

Audience:

developer;
architect.

Platform References¶

Role:

host the stable detailed references required after orientation;
keep contracts, domain references and component references accessible without overloading top-level onboarding.

Audience:

developer;
architect;
advanced contributor.

Runtime And Operations¶

Role:

group task-oriented runtime, read-only, CLI, database and operations documentation;
optimize for observability, validation and execution.

Audience:

operator;
developer;
production support.

Migration¶

Role:

preserve transformation strategy;
keep historical-to-target transition visible;
avoid mixing migration narrative with normative architecture.

Audience:

architect;
contributor;
migration owner.

ADR¶

Role:

keep architectural decisions findable and auditable;
provide one stable official decision area.

Audience:

architect;
contributor;
reviewer.

Annexes¶

Role:

preserve useful but secondary documents;
retain bridge pages, stubs, narrow side topics and transitional assets without polluting the primary understanding path.

Audience:

advanced reader;
contributor;
maintainer.

nav:
  - Start Here:
      - Home: index.md
      - Foundation: foundation/index.md
      - Platform Foundation: foundation/platform-foundation.md
      - Architecture Overview: architecture/overview.md
      - FAQ: architecture/faq.md
      - Glossary:
          - Index: glossary/index.md
          - Canonical Identity: glossary/canonical-identity.md
          - Projection: glossary/projection.md
          - Resolver: glossary/resolver.md

  - Governance:
      - Governance Overview: governance.md
      - Governance Index: governance/index.md
      - Documentation Constitution: governance/constitution.md
      - Documentation Standards: governance/documentation-standards.md
      - Documentation Roadmap: governance/documentation-roadmap.md
      - Documentation Architecture Review: governance/documentation-architecture-review.md
      - Namespace Convergence Plan: governance/namespace-convergence-plan.md
      - Repository Classification: governance/repository-classification.md

  - Architecture:
      - Overview: architecture/overview.md
      - Platform Blueprint: architecture/blueprint.md
      - Vision: architecture/vision.md
      - Principles: architecture/principes.md
      - Invariants: architecture/invariants.md
      - Dependencies: architecture/dependances.md
      - Boundary Architecture: architecture/boundary-architecture.md
      - Identifier First: architecture/identifier-first.md
      - Canonical Identity: architecture/canonical-identity.md
      - Component Map: architecture/component-map.md
      - Roadmap: architecture/roadmap.md
      - Platform:
          - Overview: architecture/platform/index.md
          - Reference: architecture/platform/reference.md
      - Review And Remediation:
          - Architecture Review Report: architecture/architecture-review-report.md
          - Architecture Remediation Plan: architecture/architecture-remediation-plan.md
          - Industrial Quality Gates: architecture/governance/industrial-quality-gates.md
      - Documentation Architecture:
          - Documentation Information Architecture: architecture/documentation-information-architecture.md
          - Documentation Navigation V2: architecture/documentation-navigation-v2.md
          - Documentation Navigation Migration Plan: architecture/documentation-navigation-migration-plan.md

  - Business Domains:
      - Product:
          - Index: business-domains/product/index.md
          - Vision: business-domains/product/vision.md
          - Ubiquitous Language: business-domains/product/ubiquitous-language.md
          - Aggregate: business-domains/product/aggregate.md
          - Invariants: business-domains/product/invariants.md
          - Value Objects: business-domains/product/value-objects.md
          - Entities: business-domains/product/entities.md
          - Events: business-domains/product/events.md
          - Policies: business-domains/product/policies.md
          - Specifications: business-domains/product/specifications.md
          - Contracts: business-domains/product/contracts.md
          - Repository Contract: business-domains/product/repository-contract.md
          - Persistence Boundary: business-domains/product/persistence-boundary.md
          - Factory: business-domains/product/factory.md
          - Queries: business-domains/product/queries.md
          - Projections: business-domains/product/projections.md
          - Domain Services: business-domains/product/domain-services.md
          - Testing Strategy: business-domains/product/testing-strategy.md
      - Catalog:
          - Index: business-domains/catalog/index.md
          - Projection Engine: business-domains/catalog/projection-engine.md
          - Runtime Synchronization Layer: business-domains/catalog/runtime-sync-layer.md

  - Target Design:
      - Design Rules:
          - Guidelines: design/design-guidelines.md
          - Design Principles: design/design-principles.md
          - Template: design/template.md
      - Domain Core: design/domain-core.md
      - Vertical Modules: design/vertical-modules.md
      - Read Services: design/read-services.md
      - Write Services: design/write-services.md
      - Pipeline: design/pipeline.md
      - Runtime: design/runtime.md
      - Infrastructure: design/infrastructure.md
      - Interfaces: design/interfaces.md
      - Governance: design/governance.md
      - Frontend: design/frontend.md

  - Platform References:
      - Domain Core:
          - Overview: domain-core/overview.md
          - Identifiers: domain-core/identifiers.md
          - Candidate: domain-core/candidate.md
          - Canonical Identity: domain-core/canonical-identity.md
          - Resolver: domain-core/resolver.md
          - Projection: domain-core/projection.md
          - Quality: domain-core/quality.md
          - Health: domain-core/health.md
          - Promotions: domain-core/promotions.md
          - Helpers: domain-core/helpers.md
      - Contracts:
          - Overview: contracts/overview.md
          - Platform Core Contract V1: contracts/platform-core-contract-v1.md
          - Identity Resolver Contract: contracts/identity-resolver.md
          - Conflict Policy Contract: contracts/conflict-policy.md
          - Projection Builder Contract: contracts/projection-builder.md
          - Quality Scorer Contract: contracts/quality-scorer.md
          - Write Service Contract: contracts/write-service.md
      - Domain Engine:
          - Overview: domain-engine/overview.md
          - Identity Engine: architecture/engines/identity-engine.md
          - Global Event Model: domain-engine/global-event-model.md
          - Global Consistency Contract: domain-engine/global-consistency-contract.md
          - Event Store And Replay Engine: domain-engine/event-store-and-replay-engine.md
      - Vertical Modules:
          - Overview: vertical-modules/overview.md
          - Guide: vertical-modules/guide.md
          - Smartphone: vertical-modules/smartphone.md
          - Photo: vertical-modules/photo.md
          - Photo Validation: vertical-modules/photo-validation.md
          - Roadmap: vertical-modules/roadmap.md

  - Runtime And Operations:
      - Application Engine:
          - Overview: application-engine/overview.md
          - Pipeline: pipeline/overview.md
          - Runtime: runtime/overview.md
          - Read Services: read-services/overview.md
          - Write Services: write-services/overview.md
      - Read Services:
          - Audits: read-services/audit.md
          - Simulations: read-services/simulation.md
          - Comparisons: read-services/comparison.md
          - Dumps: read-services/dump.md
          - Preview: read-services/preview.md
          - Health: read-services/health.md
          - Validation Reports: read-services/validation-reports.md
          - Real Sample Comparison: read-services/real-sample-comparison.md
          - Difference Family Audit: read-services/difference-family-audit.md
          - Remaining Audit: read-services/remaining-audit.md
          - Resolution Status Audit: read-services/resolution-status-audit.md
          - Virtual Candidates Dump: read-services/virtual-candidates-dump.md
          - Virtual Patch: read-services/virtual-patch.md
      - Pipeline:
          - Feed Ingestion: pipeline/feed-ingestion.md
          - Stage: pipeline/stage.md
          - Normalisation: pipeline/normalisation.md
          - Enrichment: pipeline/enrichment.md
          - Persistence: pipeline/persistence.md
          - Monitoring: pipeline/monitoring.md
      - Runtime:
          - Orchestration: runtime/orchestration.md
          - Batchs: runtime/batchs.md
          - Monitoring: runtime/monitoring.md
          - Runtime Pipeline Bridge: runtime/pipeline.md
      - Frontend And Adapters:
          - Frontend Overview: frontend/overview.md
          - Frontend Projections: frontend/projections.md
          - Adapters Overview: adapters/overview.md
          - WordPress Adapter: adapters/wordpress.md
      - CLI And Operations:
          - CLI Overview: cli/overview.md
          - CLI Reference: cli/reference.md
          - ccx-ops: cli/ccx-ops.md
          - Commands: cli/commands.md
          - Audits: cli/audits.md
          - Synchronization Commands: cli/sync.md
          - Feed Inspector: cli/feed-inspector.md
          - Candidate Dump: cli/candidate-dump.md
          - Catalog Audit: cli/catalog-audit.md
          - Difference Family Audit: cli/difference-family-audit.md
          - Real Sample Comparison: cli/real-sample-comparison.md
          - Remaining Audit: cli/remaining-audit.md
          - Resolution Status Audit: cli/resolution-status-audit.md
          - Simulation: cli/simulation.md
          - Validation Report: cli/validation-report.md
          - Virtual Candidates Dump: cli/virtual-candidates-dump.md
          - Virtual Patch: cli/virtual-patch.md
      - Database And Operations:
          - Database Overview: database/overview.md
          - Database Architecture: database/architecture.md
          - Database Lifecycle: database/lifecycle.md
          - Database Tables: database/tables.md
          - Database Persistence: database/persistence.md
          - Database Projections: database/projections.md
          - Operations Overview: operations/overview.md
          - Deployment: operations/deployment.md
          - Monitoring: operations/monitoring.md
          - Incidents: operations/incidents.md
          - Recovery: operations/recovery.md
          - Backups: operations/backups.md
          - Checklists: operations/checklists.md

  - Migration:
      - Overview: migration/overview.md
      - Methodology: migration/methodology.md
      - Migration Plan: migration/migration-plan.md
      - Component Classification: migration/component-classification.md
      - Repository Cleanup Phase 1: migration/repository-cleanup-phase-1.md
      - Architecture Atlas: migration/architecture-atlas.md
      - Legacy Plugin Inventory: migration/legacy-plugin-inventory.md

  - ADR:
      - Index: adr/index.md
      - ADR 0001 - Identifier First: adr/0001-identifier-first.md
      - ADR 0002 - Domain Core Independent: adr/0002-domain-core-independent.md
      - ADR 0003 - Read-only Before Runtime: adr/0003-readonly-before-runtime.md
      - ADR 004 - Identity Domain Service: architecture/adr/adr-004-identity-domain-service.md
      - ADR 005 - Conflict Policy Extraction: architecture/adr/adr-005-conflict-policy-extraction.md
      - ADR 006 - Domain without WordPress: architecture/adr/adr-006-domain-without-wordpress.md

  - Annexes:
      - Knowledge Architecture: knowledge/architecture.md
      - Frontend SEO: frontend/seo.md
      - Frontend Performance: frontend/performance.md
      - CLI feed-sync: cli/feed-sync.md
      - CLI rebuild-navigation: cli/rebuild-navigation.md
      - CLI rebuild-projections: cli/rebuild-projections.md
      - Write Services Backfill: write-services/backfill.md
      - Write Services Cleanup: write-services/cleanup.md
      - Write Services Migration: write-services/migration.md
      - Write Services Reclassification: write-services/reclassification.md
      - Write Services Repair: write-services/repair.md
      - Vertical Gaming: vertical-modules/gaming.md
      - Vertical GPU: vertical-modules/gpu.md
      - Vertical Mobility: vertical-modules/mobility.md
      - Vertical Printer: vertical-modules/printer.md
      - Vertical Toys: vertical-modules/toys.md
      - Vertical TV: vertical-modules/tv.md
      - Vertical Wellness: vertical-modules/wellness.md

New Developer¶

Path:

Start Here -> Architecture -> Business Domains -> Target Design -> Platform References

Architect¶

Path:

Architecture -> ADR -> Target Design -> Migration

Operator¶

Path:

Runtime And Operations -> CLI And Operations -> Database And Operations -> Read Services

Contributor¶

Path:

Start Here -> Governance -> Architecture / Documentation Architecture -> Annexes when needed

Stability Rules¶

The target navigation is designed to remain stable over multiple years.

The following rules preserve stability:

top-level sections change rarely;
a page enters the main path only if it owns a durable responsibility;
stubs and narrow bridge pages remain outside the primary path;
navigation never duplicates the same conceptual entry point in multiple top-level sections;
detailed references are grouped below stable indexes instead of being promoted prematurely.

Rejected because it reflects storage, not understanding.

Rejected because it destroys onboarding and increases noise.

Rejected because the same document often serves multiple readers.

The navigation should support personas through reading paths, not by duplicating the tree.

Rejected because some bridge or legacy pages still provide value and should be preserved in annexes.

Quality Gate Check¶

maximum depth: three levels;
no primary navigation duplication for the same responsibility;
useful annexes preserved;
onboarding path explicit;
architecture path explicit;
operations path explicit;
contributor path explicit.

Future Evolution¶

This navigation may evolve gradually.

Its section logic and reader-oriented structure should remain stable.

Documentation Navigation V2¶

Status¶

Purpose¶

Navigation Goals¶

Top-Level Information Model¶

Section Roles¶

Start Here¶

Governance¶

Architecture¶

Business Domains¶

Target Design¶

Platform References¶

Runtime And Operations¶

Migration¶

ADR¶

Annexes¶

Target Navigation Tree¶

Reader Paths Supported By This Navigation¶

New Developer¶

Architect¶

Operator¶

Contributor¶

Stability Rules¶

Rejected Navigation Patterns¶

Folder Mirror Navigation¶

Everything In Top-Level Navigation¶

Strict Persona-Based Top Navigation¶

Deleting Narrow Documents From The Navigation Model¶

Quality Gate Check¶

Future Evolution¶

Documentation Navigation V2¶

Status¶

Purpose¶

Navigation Goals¶

Top-Level Information Model¶

Section Roles¶

Start Here¶

Governance¶

Architecture¶

Business Domains¶

Target Design¶

Platform References¶

Runtime And Operations¶

Migration¶

ADR¶

Annexes¶

Target Navigation Tree¶

Reader Paths Supported By This Navigation¶

New Developer¶

Architect¶

Operator¶

Contributor¶

Stability Rules¶

Rejected Navigation Patterns¶

Folder Mirror Navigation¶

Everything In Top-Level Navigation¶

Strict Persona-Based Top Navigation¶

Deleting Narrow Documents From The Navigation Model¶

Quality Gate Check¶

Related Documents¶

Future Evolution¶