---
title: Arborescence des fichiers
slug: oip-next/QxRZ-str
icon: {"lucideIcon":"📘"}
createdAt: 2025-12-03T14:25:02.000Z
---

# Vue d'ensemble

Un projet OAV utilise une arborescence normalisée. L'outillage s'appuie sur ces emplacements pour lire la configuration et produire le code : ils ne sont pas paramétrables au cas par cas.

L'arborescence se lit selon trois catégories :

| Catégorie                 | Répertoires                                 | Règle                                              |
| ------------------------- | ------------------------------------------- | -------------------------------------------------- |
| Configuration déclarative | `config/`                                   | Écrite par le projet, lue par l'outillage.         |
| Code généré               | `entities/`, `migrations/`, `views/`        | Produit par l'outillage, jamais modifié à la main. |
| Code de projet            | `app/`, `server/`, `tasks/`, `transitions/` | Écrit et maintenu par le projet.                   |

# Arborescence complète

```none
Project Root/
├── app/
│   ├── css/
│   │   └── main.css
│   ├── graphql/
│   │   └── fragments/
│   │       └── process.js
│   ├── locales/
│   │   └── common.js
│   ├── App.jsx
│   └── index.jsx
├── config/
│   ├── entities/
│   │   └── entities.openapi.yml
│   ├── tasks/
│   └── views/
│       ├── 00-home.yml
│       └── 01-customer.yml
├── entities/
│   ├── Project/
│   │   ├── enums/
│   │   │   └── index.mjs
│   │   └── index.mjs
│   └── entities.mjs
├── migrations/
│   └── 0000000000000_migration.js
├── mocks/
│   └── context.mjs
├── public/
├── scripts/
│   └── run-migrations.sh
├── server/
│   ├── graphql/
│   │   └── types/
│   │       └── extended-process-type.mjs
│   ├── lib/
│   │   └── version.js
│   ├── process/
│   │   └── extend-process.mjs
│   ├── index.mjs
│   └── logger.mjs
├── tasks/
│   └── my_task.mjs
├── transitions/
│   ├── customer.mjs
│   └── home.mjs
├── views/
│   ├── _common/
│   ├── home/
│   │   ├── client/
│   │   └── server/
│   └── views.mjs
├── .env
├── .env.dist
├── docker-compose.yml
├── env-vars.yml
├── index.html
├── package.json
└── vite.config.js
```

# Répertoires

| Répertoire         | Contenu                                                           | Généré | Modifiable                     |
| ------------------ | ----------------------------------------------------------------- | ------ | ------------------------------ |
| `app/`             | Code de l'application React.                                      | Non    | Oui                            |
| `config/entities/` | Fichier de configuration du modèle de données.                    | Non    | Oui                            |
| `config/tasks/`    | Déclaration des tâches asynchrones, lorsque le projet en utilise. | Non    | Oui                            |
| `config/views/`    | Fichiers de configuration YAML des vues.                          | Non    | Oui                            |
| `entities/`        | Code d'accès aux entités.                                         | Oui    | Non                            |
| `migrations/`      | Migrations SQL du modèle de données.                              | Oui    | Non                            |
| `mocks/`           | Contextes simulés utilisés en développement.                      | Non    | Oui                            |
| `public/`          | Fichiers statiques servis par le serveur Express.                 | Non    | Oui                            |
| `scripts/`         | Scripts utilitaires, dont l'exécution des migrations.             | Non    | Oui                            |
| `server/`          | Code de l'application Express.                                    | Non    | Oui                            |
| `tasks/`           | Code des tâches asynchrones.                                      | Non    | Oui                            |
| `transitions/`     | Règles d'enchaînement entre les vues.                             | Non    | Oui                            |
| `views/`           | Code client et serveur des vues.                                  | Oui    | Fichiers squelettes uniquement |

:::BlockQuote
**\[warn]** Les répertoires `entities/`, `migrations/` et `views/` sont produits par l'outillage. Les fichiers portant l'en-tête `// Code generated by gen. DO NOT EDIT.` sont réécrits intégralement à chaque génération.
:::

# Application React

| Fichier                            | Rôle                                                                                                                 |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `app/index.jsx`                    | Point d'entrée de l'application React. Il appelle la fonction `start` exposée par `@fasstech/oip-starter-utils/app`. |
| `app/App.jsx`                      | Composant principal. Il contient l'appel au routeur : `<Router views={views} />`.                                    |
| `app/css/main.css`                 | Point d'entrée des définitions de style.                                                                             |
| `app/graphql/fragments/process.js` | Fragment GraphQL de l'objet `Process`.                                                                               |
| `app/locales/common.js`            | Point d'entrée des traductions.                                                                                      |

:::BlockQuote
**\[info]** Toute modification du fragment `process.js` doit être répercutée dans `server/graphql/types/extended-process-type.mjs` et `server/process/extend-process.mjs`. Ces trois fichiers décrivent la même structure, respectivement côté client, côté schéma GraphQL et côté résolution.
:::

# Application Express

| Fichier                                          | Rôle                                                                                                                                                       |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server/index.mjs`                               | Point d'entrée du serveur. Il porte la configuration passée à `start` (dont les trois fonctions de décrochage) et l'enregistrement des consommateurs AMQP. |
| `server/logger.mjs`                              | Implémentation du *logger* du projet : niveaux disponibles et format des messages.                                                                         |
| `server/graphql/types/extended-process-type.mjs` | Type GraphQL de l'objet `Process` étendu.                                                                                                                  |
| `server/process/extend-process.mjs`              | Résolution des propriétés personnalisées de l'objet `Process`.                                                                                             |
| `server/lib/version.js`                          | Affichage du numéro de version et de la date du projet au démarrage. Ce fichier n'a pas vocation à être modifié.                                           |

# Configuration

| Emplacement        | Attendu                                                    |
| ------------------ | ---------------------------------------------------------- |
| `config/entities/` | Un seul fichier de configuration : `entities.openapi.yml`. |
| `config/views/`    | Un fichier YAML par vue.                                   |
| `config/tasks/`    | La déclaration des tâches du projet.                       |

# Code généré

## entities/

| Fichier                             | Contenu                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `entities/entities.mjs`             | Définition de l'ensemble des entités.                                     |
| `entities/<Entity>/index.mjs`       | Fonctions de manipulation de l'entité et accesseurs de ses propriétés.    |
| `entities/<Entity>/enums/index.mjs` | Énumérations de l'entité. Ce fichier n'existe que si l'entité en utilise. |

## views/

| Emplacement                 | Contenu                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `views/_common/`            | Éléments mutualisés entre les vues : *hooks* client réutilisables, éléments GraphQL communs. |
| `views/<directory>/client/` | Composant React de la vue, *hooks*, *queries* et mutations GraphQL.                          |
| `views/<directory>/server/` | *Resolvers* et types GraphQL de la vue.                                                      |
| `views/views.mjs`           | Fichier d'exposition des vues, utilisé pour la navigation.                                   |

Le nom du répertoire d'une vue est déterminé par la propriété `directory` de son fichier de configuration.

:::BlockQuote
**\[info]** Dans le répertoire d'une vue, certains fichiers sont des squelettes à compléter : le composant React, les *resolvers* et leurs fichiers de test. Ils ne portent pas l'en-tête de code généré et ne sont pas écrasés.
:::

## migrations/

Chaque fichier porte un nom de la forme `<timestamp>_migration.js`. Le répertoire constitue l'historique du schéma du modèle de données.

:::BlockQuote
**\[warn]** Un fichier de migration déjà exécuté en base de données ne doit jamais être supprimé, renommé ni modifié. Toute correction passe par une nouvelle migration.
:::

# Fichiers à la racine

| Fichier              | Rôle                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `.env`               | Valeurs de configuration locales. Ce fichier n'est pas versionné.                                                   |
| `.env.dist`          | Modèle de configuration versionné, à partir duquel `.env` est généré.                                               |
| `env-vars.yml`       | Description des variables d'environnement attendues, validées au démarrage.                                         |
| `docker-compose.yml` | Description des services annexes utilisés en développement.                                                         |
| `index.html`         | Page hôte de l'application React.                                                                                   |
| `vite.config.js`     | Configuration du client, dont l'exposition des constantes `__CLIENT_ID__`, `__CLIENT_SECRET__` et `__SERVER_URL__`. |
| `package.json`       | Dépendances et scripts du projet.                                                                                   |

# Résumé

- L'arborescence d'un projet OAV n'est pas paramétrable : l'outillage lit et écrit à des emplacements fixes ;
- `config/` porte la description déclarative du parcours, `app/`, `server/`, `tasks/` et `transitions/` portent le code du projet ;
- `entities/`, `migrations/` et `views/` sont produits par l'outillage ;
- dans `views/`, seuls les fichiers squelettes (composants, *resolvers* et tests) sont destinés à être complétés.
