Architecture

15 min

Vue d'ensemble

Un OAV repose sur une architecture client/serveur. Elle se compose :

d'une application React pour la partie client ;

d'une application Express pour la partie serveur ;

d'une communication GraphQL entre le client et le serveur ;

d'un service dédié à la persistance des données.

Cette section présente les rôles de chacun de ces composants ainsi que les flux d'échange.

Composants

Client : application React

L'application React constitue l'interface utilisateur de l'OAV. Elle initie les interactions, déclenche les actions et effectue les appels GraphQL vers le serveur.

Elle est construite avec Vite et s'appuie sur Apollo Client pour le dialogue avec le serveur.

[info] Le client ne contient aucune règle de navigation : il déclenche une action et applique la vue que le serveur lui renvoie.

Serveur : application Express

L'application Express traite les requêtes GraphQL, exécute la logique métier et coordonne les appels vers le service de persistance des données.

Elle porte quatre responsabilités :

exposer le schéma GraphQL consommé par le client ;

résoudre les transitions entre les vues ;

lire et écrire les entités ;

exécuter les tâches asynchrones déclenchées par le parcours.

Service de persistance : OIP Headless

La persistance des données est assurée par le service OIP Headless qui expose une API REST. Le serveur Express interagit avec cette API pour créer, lire, mettre à jour ou supprimer des données.

OIP Headless est une application Elixir bâtie sur Phoenix, Ecto, PostgreSQL et Oban. Elle assure également :

l'historisation de toutes les écritures et leur annulation par transaction ;

la programmation des tâches et des workflows de tâches ;

l'application des règles RGPD de chiffrement au repos et de purge automatique ;

la publication d'évènements vers l'OAV via le protocole AMQP.

Services annexes

Service	Rôle
Service de sessions	Émet et valide les jetons de décrochage utilisés à l'entrée du parcours.
PostgreSQL	Stocke les données d'OIP Headless ainsi que les sessions HTTP de l'OAV.
RabbitMQ	Achemine les évènements entre OIP Headless et l'OAV, et diffuse les notifications aux clients.

Briques logicielles

L'OAV assemble plusieurs paquets distribués par l'OIP.

Brique	Paquet	Rôle
OIP Starter	—	Modèle de projet servant de point de départ à un OAV.
OIP Starter Utils	@fasstech/oip-starter-utils	Socle applicatif : application React, application Express, couche GraphQL, sessions, moteur de transitions et ordonnanceur de tâches.
OIP Core	@fasstech/oip-core	Bibliothèque d'accès aux données au-dessus de l'API OIP Headless.
OIP Tools	@fasstech/oip-tools	Interface en ligne de commande de configuration et de génération de code.
OIP Features	@fasstech/oip-features-<name>	Fonctionnalités métier réutilisables, installables à la demande.

Le socle s'appuie par ailleurs sur des utilitaires transverses : @fasstech/rabbitmq-helper pour AMQP, @fasstech/checkenv pour la validation des variables d'environnement, @fasstech/logger pour la journalisation et @fasstech/textit pour l'internationalisation.

Répartition des responsabilités

Savoir où s'exécute chaque traitement est déterminant pour concevoir un parcours correctement.

Traitement	Lieu d'exécution
Rendu de l'interface et interactions	Navigateur.
Résolution des transitions entre vues	Serveur Express.
Lecture et écriture des entités	Serveur Express, par appel à OIP Headless.
Exécution du code d'une tâche	Serveur Express, dans un processus dédié.
Programmation des tâches et des workflows	OIP Headless.
Historisation, purge et chiffrement	OIP Headless.

[warn] Les conditions de transition et les accès aux entités ne sont jamais évalués dans le navigateur. Les données du modèle ne sont exposées au client que par les resolvers GraphQL des vues.

Flux de communication

Transports

Liaison	Protocole
Navigateur → serveur Express	GraphQL sur HTTP pour les requêtes et les mutations, sur WebSocket pour les souscriptions.
Serveur Express → OIP Headless	REST sur HTTP, authentifié par clé d'API.
OIP Headless → serveur Express	AMQP, file <OAV_ID>.events pour les tâches et <OAV_ID>.entities pour les instantanés de projet.
Serveur Express → OIP Headless	AMQP, file oip.api.events pour la remontée des statuts de tâches.

Flux nominal

Le diagramme ci-dessous illustre les interactions entre les différents composants.

sequenceDiagram
    actor Alice
    Alice->>React App: User interaction
    React App->>Express App: GraphQL
    Express App->>API: REST
    API->>DB: CRUD operations

Résolution d'une transition

Lorsque l'utilisateur passe d'un écran au suivant, la décision est prise côté serveur, puis persistée dans le Process.

sequenceDiagram
    actor Alice
    Alice->>React App: Screen validation
    React App->>Express App: GraphQL, action mutation
    Express App->>Express App: Evaluation of view transitions
    Express App->>API: REST, Process update
    Express App-->>React App: Resolved view
    React App->>Alice: Navigation

Exécution d'une tâche asynchrone

Une tâche n'est jamais exécutée dans le fil de la requête : elle est programmée par OIP Headless, qui notifie l'OAV à échéance.

sequenceDiagram
    React App->>Express App: GraphQL, runTask mutation
    Express App->>API: REST, task scheduling
    API-->>Express App: AMQP, OAV_ID.events queue
    Express App->>Express App: Execution in a dedicated process
    Express App-->>API: AMQP, oip.api.events queue
    Express App-->>React App: GraphQL, subscription notification

État et persistance

L'état courant d'un OAV n'est pas conservé en mémoire par le serveur.

Le Process, qui porte le projet, la vue active et ses métadonnées, est persisté dans OIP Headless ; il survit à un rechargement de la page comme au redémarrage du serveur ;

les entités sont persistées dans OIP Headless, chaque écriture étant historisée et réversible ;

la session HTTP est stockée dans une table PostgreSQL dédiée, et non dans le processus Node ;

les notifications de tâches transitent par RabbitMQ, ce qui permet de servir plusieurs instances de l'OAV.

Déploiement

Un OAV en production mobilise cinq services :

l'OAV lui-même, distribué sous forme d'image Docker ;

le service de sessions et sa base de données ;

OIP Headless ;

PostgreSQL, hébergeant les données d'OIP Headless et les sessions de l'OAV ;

RabbitMQ.

Les migrations du modèle de données sont appliquées au démarrage du conteneur, avant le lancement du serveur. La configuration est entièrement portée par des variables d'environnement, validées au démarrage : un OAV mal configuré s'arrête immédiatement plutôt que de démarrer dans un état incohérent.

Résumé

Le client React porte l'interface, le serveur Express porte la logique et OIP Headless porte les données ;

les transitions, les accès aux entités et l'exécution des tâches ont lieu côté serveur ;

le client dialogue en GraphQL, le serveur en REST avec OIP Headless, et les évènements asynchrones circulent en AMQP ;

l'état de l'OAV est intégralement externalisé, ce qui rend le serveur reproductible et redémarrable.