Architecture
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.
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 du chiffrement au repos et de la 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. |
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 operationsRé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: NavigationExé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.