# Architecture et environnements

> Comment l'architecture d'une application se décline en instances dans chaque environnement, et comment les valeurs par défaut se propagent.

L'architecture décrit **ce qu'est** votre application ; un environnement décrit **où elle tourne**. Cette séparation vous permet de déclarer un service une seule fois et de le faire tourner, avec des réglages différents, en développement, en recette et en production.

## Définition

L'**architecture** regroupe tout ce qui est commun à tous les environnements de l'application. On la retrouve dans le menu **Architecture** de l'application, en quatre cartes :

| Carte | Contenu |
|---|---|
| **Repositories** | Les dépôts Git qui contiennent le code, créés par Wakastart (« Managé ») ou existants (« Importé ») |
| **Services** | Les définitions de service : quel dépôt, quel Dockerfile, quel port, quelles ressources par défaut, quelles variables attendues |
| **Dépendances** | Les définitions de bases de données et de buckets de stockage |
| **URLs** | Les sous-domaines, routes HTTP, domaines personnalisés et redirections |

Un **environnement** est un contexte de déploiement isolé. Il a un type — `dev`, `staging` ou `prod` — choisi à la création et définitif. Chaque environnement dispose de son propre espace d'exécution, de son coffre de secrets, de ses variables et de ses instances : rien n'est partagé entre deux environnements.

:::note[Une application, plusieurs environnements du même type]
Le type n'est pas un identifiant. Une application peut avoir `dev-team-a` et `dev-team-b`, tous deux de type `dev`. C'est le **nom court** qui distingue les environnements entre eux.
:::

Le type fixe aussi l'instance Keycloak qui authentifie les utilisateurs de l'environnement : Keycloak dev pour un environnement `dev`, Keycloak staging pour `staging`, Keycloak prod pour `prod`. Chaque type a son propre référentiel d'utilisateurs : une fiche utilisateur, son WID, son profil et sa matrice de droits valent pour un seul type d'environnement (voir [Comptes et environnements](/v1.0/utilisateurs/comptes-et-environnements)).

## Pourquoi ça existe

Sans cette séparation, chaque environnement serait une copie à maintenir à la main : ajouter un service obligerait à le déclarer trois fois, et les copies finiraient par diverger. Avec une architecture unique, un service ajouté est disponible pour tous les environnements ; il reste à décider, environnement par environnement, de l'y faire tourner.

## Comment ça marche

### Définitions et instances

Chaque élément de l'architecture est une définition. Dans un environnement, il devient une instance :

| Définition (architecture) | Instance (environnement) | Création de l'instance |
|---|---|---|
| Définition de service | Instance de service | Toujours explicite : **Déployer un service** dans l'environnement |
| Définition de base de données | Instance de base | Voir [Bases de données](/v1.0/bases-de-donnees) |
| Définition de bucket | Bucket | Voir [Stockage objet](/v1.0/stockage) |
| URL publique | Route provisionnée par environnement | Voir [Domaines et URLs](/v1.0/domaines-et-urls) |

### Héritage des valeurs

La définition porte des valeurs par défaut. L'instance peut surcharger chacune d'elles ; un champ laissé vide reprend la valeur de la définition.

| Champ | Définition de service | Instance en `dev` | Instance en `prod` | Valeur effective en `prod` |
|---|---|---|---|---|
| CPU Request | `100m` | vide | `500m` | `500m` |
| Memory Limit | `512Mi` | vide | vide | `512Mi` |
| Réplicas | — | `1` | `2` | `2` |

### Propagation d'un changement

Quand vous modifiez une valeur par défaut d'une définition de service, Wakastart crée un déploiement pour chaque instance concernée :

- **ressources et sondes de santé** : seules les instances qui ne surchargent pas le champ sont redéployées ;
- **port, protocole, exposition** : toutes les instances sont redéployées.

Chaque redéploiement apparaît dans l'historique des déploiements de l'environnement, avec la raison « Valeur par défaut d'architecture appliquée » ou « Configuration réseau modifiée ».

### Identité d'un environnement

| Élément | Exemple | Règle |
|---|---|---|
| Nom de l'instance | `dev-team-a` | Libre, affiché dans la console |
| Type | `dev` | `dev`, `staging` ou `prod`, définitif |
| Nom court | `teama` | 12 caractères au plus, minuscules, chiffres et tirets, unique dans l'application |
| Slug | `teama-dev` | Calculé : nom court, tiret, type |
| Espace d'exécution | `wakapp-ab12cd-teama-dev` | Calculé : `wakapp-`, identifiant de l'application, slug ; affiché « Namespace » sur la carte de l'environnement |
| Préfixe d'URL | `teama` | Inséré dans les URLs publiques : `api.teama.votre-domaine` |

## Exemples

- **Une équipe, trois environnements.** `dev` suit la branche `develop` avec build et déploiement automatiques ; `staging` suit `main` ; `prod` suit un tag de version, déployé à la main.
- **Deux équipes en parallèle.** `dev-team-a` et `dev-team-b`, de type `dev`, suivent chacun leur branche de fonctionnalité, avec les préfixes d'URL `teama` et `teamb`.
- **Une production plus robuste.** La définition de service garde `1` réplica et `512Mi` ; l'instance de production surcharge à `2` réplicas et `1Gi`.

## Pour aller plus loin

- [Cycle de vie des ressources](/v1.0/applications/cycle-de-vie)
- [Définitions et instances de service](/v1.0/services/definitions-et-instances)
- [Créer un environnement](/v1.0/applications/creer-un-environnement)
- [Format de l'architecture JSON](/v1.0/applications/format-architecture-json)
