Aller au contenu principal

Navigation Engine

Version : 1.0

Statut : Architecture cible

Décision : ADR-016

1. Objectif​

Ce document formalise le Navigation Engine, le composant d'architecture responsable de la navigation DMV, indépendamment de toute plateforme d'exécution.

Il ne décrit ni Cloudflare, ni Next.js, ni Capacitor.

Ces technologies ne sont que des adaptateurs au service de ce moteur.

La navigation devient une responsabilité de plateforme au même titre que le cache ou la synchronisation, et non plus un détail d'implémentation propre à chaque application ou à chaque hébergeur.

État actuel​

Aujourd'hui, la navigation DMV n'est pas un composant distinct : elle est répartie, dupliquée et couplée directement à chaque plateforme d'exécution.

Chaque application construit ses propres URLs (lib/workspaceUrls.ts côté dmv-public, lib/public-urls.ts côté dmv-workspace), chacune avec sa propre logique de repli et ses propres conventions. Le routing dynamique du Workspace dépend directement d'une fonctionnalité Cloudflare Pages (_redirects). La lecture du slug réel dans l'URL est répétée indépendamment dans plusieurs fichiers plutôt que centralisée. Aucun mécanisme de Deep Link, Universal Link ou Android App Link n'existe encore.

Cette situation n'est pas une erreur : elle répond à des contraintes réelles, documentées par ailleurs (disponibilité immédiate des nouveaux acteurs, build constant, fonctionnement entièrement client). Mais elle couple directement la logique de navigation à des choix de plateforme, ce qui devient un frein dès qu'une nouvelle plateforme (Capacitor) doit cohabiter avec les plateformes existantes (Web via Cloudflare).

Architecture cible​

Le Navigation Engine introduit une couche d'abstraction entre l'intention de navigation de l'utilisateur et la façon dont chaque plateforme la réalise concrètement.

Utilisateur

↓

Navigation

↓

Navigation Engine

↓

Route Resolver

↓

Platform Adapter

↓

Application

Chaque étage a une responsabilité unique :

  • Navigation : l'intention exprimée par l'utilisateur ou par l'application (cliquer un lien, ouvrir une notification, scanner un QR Code, revenir en arrière).
  • Navigation Engine : reçoit cette intention, l'exprime sous une forme neutre (une route DMV), et orchestre sa résolution.
  • Route Resolver : traduit une route DMV abstraite en une cible concrète pour la plateforme courante.
  • Platform Adapter : exécute effectivement la navigation sur la plateforme (Next.js, Cloudflare, Capacitor, Electron, Nginx, Vercel...).
  • Application : l'écran final affiché à l'utilisateur.

Le Navigation Engine et le Route Resolver restent strictement identiques quelle que soit la plateforme. Seul le Platform Adapter change.

Migration​

La migration vers cette architecture cible se fait progressivement, sans jamais imposer une réécriture globale :

  1. conserver le comportement actuel de chaque application comme socle ;
  2. faire émerger une définition unique des routes DMV (aujourd'hui dispersée dans plusieurs helpers) ;
  3. introduire le Route Resolver comme point de passage unique pour toute résolution de route, sans changer le comportement observable ;
  4. isoler les dépendances de plateforme (Cloudflare, Capacitor...) derrière des Platform Adapters ;
  5. étendre progressivement la couverture du Navigation Engine, application par application, jamais en un seul chantier.

2. Rôle du Navigation Engine​

Le Navigation Engine répond à une question unique : où l'utilisateur doit-il aller ?

Il ne décide jamais si l'utilisateur a le droit d'y aller, ni ce qu'il verra une fois arrivé, ni comment les données de cet écran sont obtenues. Il détermine uniquement la destination, et s'assure qu'elle est atteignable de manière identique, quelle que soit la plateforme.

Le Navigation Engine est responsable de :

  • construire les URLs DMV ;
  • résoudre les routes DMV ;
  • gérer les Deep Links ;
  • gérer les Universal Links (iOS) ;
  • gérer les App Links (Android) ;
  • gérer les liens internes entre applications (Public ↔ Workspace, et futures applications DMV) ;
  • permettre une navigation indépendante de la plateforme d'exécution ;
  • fournir une abstraction de navigation unique, utilisée identiquement par toutes les applications DMV.

Le Navigation Engine n'est jamais responsable :

  • des permissions (rôle du Context Engine et de l'autorisation serveur) ;
  • des données affichées (rôle du Cache Engine et de la Synchronization Engine) ;
  • du contexte utilisateur (rôle du Context Engine) ;
  • du rendu React (rôle des applications elles-mêmes).

Un Navigation Engine qui déciderait de ces aspects cesserait d'être une abstraction de navigation pour devenir une seconde couche métier — ce qui est explicitement exclu.

3. Positionnement dans l'architecture globale​

DMV distingue plusieurs moteurs, chacun responsable d'une question distincte.

MoteurQuestion à laquelle il répond
Context EngineQui est l'utilisateur, dans quel espace, avec quels droits ?
Navigation EngineOù l'utilisateur doit-il aller ?
Cache EngineQuelles données sont disponibles localement, immédiatement ?
Synchronization EngineComment ces données restent-elles cohérentes avec le serveur ?
Wall EngineQue faut-il construire et afficher une fois arrivé ?

Ces moteurs collaborent sans jamais se substituer les uns aux autres.

Le Navigation Engine consulte le Context Engine lorsque la destination dépend du contexte courant (par exemple : quel est l'espace actif lorsqu'un lien générique "Mon Espace" est ouvert), mais ne possède jamais lui-même cette information. Il déclenche potentiellement une lecture du Cache Engine ou de la Synchronization Engine une fois la destination atteinte, mais ne gère jamais cette lecture lui-même. Il précède toujours le Wall Engine dans la chaîne d'exécution : on détermine d'abord où aller, ensuite seulement ce qui doit y être construit et affiché.

Cette séparation garantit qu'un changement dans la politique de cache, dans la résolution de contexte ou dans la construction du contenu n'a jamais besoin de modifier la façon dont une route est résolue — et inversement.

4. Le Route Resolver​

Le Route Resolver est le composant interne du Navigation Engine qui effectue la traduction concrète entre une route DMV et sa réalisation sur une plateforme donnée.

Une route DMV est une expression neutre d'une destination — par exemple "le tableau de bord de l'acteur X", "la publication Y", "l'espace personnel de l'utilisateur courant" — indépendante de toute syntaxe d'URL, de tout hébergeur, de tout framework.

Le Route Resolver a la responsabilité de transformer cette expression neutre en une cible exploitable par la plateforme courante : une URL HTTPS pour le Web, une navigation interne pour une WebView Capacitor déjà chargée, un identifiant de vue pour une future plateforme non-Web. C'est la seule couche de l'architecture qui a le droit de connaître à la fois la représentation neutre d'une route et sa forme concrète.

Le Route Resolver ne décide jamais lui-même de la destination : il ne fait que la traduire. La décision de destination appartient au Navigation Engine ; le Route Resolver l'exécute.

5. Les Platform Adapters​

Un Platform Adapter est l'unique point de contact entre le Navigation Engine et une plateforme d'exécution réelle.

Exemples de Platform Adapters envisagés pour DMV :

  • Next.js — navigation côté Web via le routeur applicatif.
  • Cloudflare — résolution de routes au niveau de l'edge (le mécanisme _redirects du Workspace, aujourd'hui direct, deviendra à terme un Platform Adapter parmi d'autres plutôt qu'une dépendance structurelle).
  • Capacitor — navigation native, Deep Links, Universal Links, Android App Links.
  • Electron — éventuelle déclinaison desktop.
  • Nginx — hébergement statique alternatif.
  • Vercel — hébergeur alternatif à Cloudflare.

Chaque Platform Adapter respecte le même contrat : recevoir une cible résolue par le Route Resolver, et réaliser effectivement la navigation sur sa plateforme. Aucune application DMV ne dépend jamais directement d'un Platform Adapter — seul le Navigation Engine y fait appel.

Cette architecture permet d'ajouter une nouvelle plateforme (ou de changer d'hébergeur) en écrivant un nouveau Platform Adapter, sans jamais toucher à la logique de navigation elle-même, ni aux applications qui l'utilisent.

6. Impact sur l'existant​

V0.9 Beta​

Le Navigation Engine n'est pas introduit pendant la V0.9 Beta.

Le mécanisme actuel est conservé intégralement :

  • le routing Cloudflare (_redirects) reste utilisé tel quel pour le Workspace ;
  • le parsing actuel du slug depuis l'URL reste fonctionnel, inchangé ;
  • aucun code n'est modifié à l'occasion de ce document.

La seule amélioration envisageable, sans lien avec l'introduction du Navigation Engine, serait la centralisation de la lecture du slug dans un point unique — une réduction de duplication locale, pas une étape de migration vers le Navigation Engine.

V1​

Le Navigation Engine sera introduit progressivement, application par application, jamais en un seul chantier global.

Cette introduction devra rester transparente pour les applications : une application qui navigue aujourd'hui via un helper local (getWorkspaceActorDashboardHref, par exemple) devra pouvoir migrer vers un appel au Navigation Engine sans changement de comportement observable pour l'utilisateur.

Le Cloudflare Worker et la règle _redirects du Workspace ne disparaissent pas nécessairement en V1 : ils deviennent, à terme, l'implémentation du Platform Adapter Cloudflare plutôt qu'une dépendance directe des applications. La V1 ne remplace pas ce mécanisme, elle l'encapsule.

7. ADR​

Décision​

Introduire un Navigation Engine comme composant d'architecture à part entière, distinct des applications et des plateformes.

Alternatives étudiées​

Continuer à coupler directement chaque application à sa plateforme d'hébergement.

Rejeté. C'est la situation actuelle : elle fonctionne pour le Web seul, mais chaque nouvelle plateforme (Capacitor, un futur changement d'hébergeur) oblige à revalider et souvent réécrire la logique de navigation de chaque application indépendamment.

Réécrire immédiatement toute la navigation existante autour du Navigation Engine.

Rejeté. Contredit le principe de migration progressive de DMV et introduirait un risque de régression disproportionné par rapport au bénéfice, alors que le mécanisme actuel répond correctement aux besoins de la V0.9 Beta.

Introduction progressive via des Platform Adapters, sans réécriture immédiate.

Retenu. Permet de formaliser l'architecture cible dès maintenant, sans bloquer ni ralentir la V0.9 Beta, et sans imposer de refonte aux applications existantes.

8. Décisions figées​

✅ La navigation est un composant d'architecture, au même titre que le cache ou la synchronisation.

✅ Le Navigation Engine ne dépend d'aucune plateforme.

✅ Toute plateforme d'exécution est intégrée via un Platform Adapter.

✅ Le Route Resolver est l'unique point de traduction entre une route DMV et sa forme concrète.

✅ Le Navigation Engine ne gère jamais les permissions, les données, le contexte ou le rendu.

✅ L'introduction du Navigation Engine est progressive et ne remet jamais en cause le fonctionnement de la V0.9 Beta.

✅ Un changement d'hébergeur ou de plateforme se traduit par un nouveau Platform Adapter, jamais par une modification des applications.

Conclusion​

Le Navigation Engine déplace la question "comment naviguer" du niveau de chaque application, où elle est aujourd'hui dispersée et couplée à des choix de plateforme, vers un composant d'architecture unique, stable et partagé.

Il ne remplace ni ne concurrence les autres moteurs de DMV : il détermine où aller, là où le Context Engine détermine qui navigue, où le Cache Engine et la Synchronization Engine déterminent quelles données sont disponibles, et où le Wall Engine détermine ce qui est construit une fois arrivé.

Cette architecture rend DMV capable d'accueillir de nouvelles plateformes, de nouveaux adaptateurs, et un éventuel changement d'hébergeur, sans jamais remettre en cause la logique de navigation elle-même — exactement comme le Cache Engine et la Synchronization Engine le font déjà pour leurs responsabilités respectives.