---
title: Architecture
slug: oip-next/v4/architecture
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-07T11:51:43.000Z
---

# 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.

:::BlockQuote
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 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.                              |

:::BlockQuote
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.

```mermaid
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`.

```mermaid
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.

```mermaid
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.
