# Format de l'architecture JSON

> Structure complète du document d'architecture version 1.0 — blocs, champs, références entre blocs, transformations à l'export et dérivations à l'import.

Le document d'architecture décrit les définitions d'une application, sans identifiant ni valeur propre à une application donnée. La console le produit avec **Exporter** et l'accepte avec **Importer** ; voir [Exporter et importer l'architecture](/v1.0/applications/exporter-et-importer-l-architecture).

Le format est validé par un schéma JSON (draft 2020-12). Tout champ non décrit ici est refusé.

## Racine du document

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `version` | chaîne | oui | Toujours `"1.0"` |
| `kind` | chaîne | oui | Toujours `"wakastart-app-architecture"` |
| `exportedAt` | date-heure ISO 8601 | non | Posé à l'export, ignoré à l'import |
| `app` | objet | oui | Nom et nom court de l'application d'origine, à titre indicatif |
| `repos` | tableau | non | Dépôts Git |
| `harborProject` | objet | non | Projet du registre d'images |
| `openbaoSecretEngine` | objet | non | Coffre de secrets |
| `databaseDefinitions` | tableau | non | Définitions de bases de données |
| `storageBucketDefinitions` | tableau | non | Définitions de buckets |
| `serviceDefinitions` | tableau | non | Définitions de service, avec leurs variables attendues |
| `appUrls` | tableau | non | URLs publiques, sans domaine |
| `appRoutes` | tableau | non | Routes HTTP entre une URL et un service |
| `appApexUrls` | tableau | non | Expositions sur le domaine racine d'un domaine personnalisé |
| `appUrlRedirects` | tableau | non | Redirections au niveau de l'application |
| `environments` | tableau | non | Environnements à créer, sans instance |

## Références entre blocs

Les blocs se désignent par leur clé `ref`, jamais par un identifiant de la plateforme.

| Règle | Valeur |
|---|---|
| Format d'une `ref` | `^[a-z0-9][a-z0-9-]{0,62}$` |
| Format d'un `shortname` | `^[a-z0-9][a-z0-9-]{0,11}$`, unique par application |
| Champs qui pointent vers une `ref` | `repoRef`, `serviceRef`, `urlRef`, `targetUrlRef`, `targetApexRef` |

La validation vérifie que chaque référence pointe vers un bloc existant (message `Unknown repo ref "…"`, `Unknown serviceDefinition ref "…"`, `Unknown appUrl ref "…"`, `Unknown appApexUrl ref "…"`).

## `app`

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `name` | chaîne | oui | 100 caractères au plus |
| `shortname` | chaîne | oui | voir `shortname` |

L'import cible une application existante : ces valeurs ne la renomment pas.

## `repos[]`

| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
| `ref` | ref | oui | | Clé du dépôt dans le document |
| `name` | chaîne | oui | | `^[a-z0-9][a-z0-9-]*$`, 63 caractères au plus ; sur GitHub, un dépôt géré est nommé `<wid>-<name>` |
| `isManaged` | booléen | non | `true` | `true` : Wakastart crée le dépôt ; `false` : référence à un dépôt existant |
| `fullName` | chaîne | si `isManaged: false` | | `organisation/depot` ; ignoré pour un dépôt géré |
| `htmlUrl` | URI ou `null` | si `isManaged: false` | | URL HTTPS se terminant par `.git` ; ignorée pour un dépôt géré |
| `defaultBranch` | chaîne | non | `main` | 63 caractères au plus |
| `visibility` | chaîne | non | `internal` | `public`, `private` ou `internal` |

## `harborProject` et `openbaoSecretEngine`

| Bloc | Champ | Type | Défaut |
|---|---|---|---|
| `harborProject` | `importExisting` | booléen | `false` |
| `harborProject` | `importExistingId` | chaîne | |
| `openbaoSecretEngine` | `engineType` | chaîne | `kv-v2` |
| `openbaoSecretEngine` | `description` | chaîne, 500 caractères au plus | |

Le nom du projet et le chemin du coffre sont recalculés pour l'application cible.

## `databaseDefinitions[]`

| Champ | Type | Obligatoire | Défaut | Contraintes |
|---|---|---|---|---|
| `ref` | ref | oui | | |
| `name` | chaîne | oui | | 100 caractères au plus |
| `shortname` | shortname | oui | | |
| `engineType` | chaîne | oui | | `POSTGRESQL`, `MYSQL`, `MONGODB`, `VALKEY` |
| `defaultMode` | chaîne | non | `IN_CLUSTER` | `IN_CLUSTER` ou `MANAGED` |
| `defaultPlan` | chaîne | non | | 63 caractères au plus |
| `defaultRegion` | chaîne | non | | 63 caractères au plus |
| `defaultVersion` | chaîne | non | | 20 caractères au plus |
| `defaultDiskSizeGb` | entier | non | | 1 au minimum |
| `defaultStorageSize` | chaîne | non | | par exemple `10Gi` |
| `defaultReplicas` | entier | non | `1` | 1 au minimum |
| `defaultDatabaseName` | chaîne | non | | 63 caractères au plus |

## `storageBucketDefinitions[]`

| Champ | Type | Obligatoire | Défaut |
|---|---|---|---|
| `ref` | ref | oui | |
| `name` | chaîne, 100 caractères au plus | oui | |
| `shortname` | shortname | oui | |
| `defaultRegion` | chaîne | non | `gra` |
| `defaultStorageClass` | chaîne | non | `STANDARD` |
| `defaultVersioning` | booléen | non | `false` |

## `serviceDefinitions[]`

| Champ | Type | Obligatoire | Défaut | Contraintes |
|---|---|---|---|---|
| `ref` | ref | oui | | |
| `name` | chaîne | oui | | 100 caractères au plus |
| `shortname` | shortname | oui | | |
| `slug` | chaîne | non | `shortname` | 63 caractères au plus |
| `repoRef` | ref | oui | | Dépôt du service |
| `rootDirectory` | chaîne | non | racine | Dossier du service dans le dépôt |
| `dockerfilePath` | chaîne | non | `Dockerfile` | Relatif au contexte de build |
| `buildContext` | chaîne | non | `.` | Relatif à `rootDirectory` |
| `imageRegistry` | chaîne | non | registre de la plateforme | |
| `imageProject` | chaîne | non | nom court de l'application cible | |
| `imageName` | chaîne | oui | | 63 caractères au plus |
| `role` | chaîne | oui | | `FRONT`, `BACK`, `BFF`, `WORKER` |
| `technology` | chaîne | non | | 50 caractères au plus ; `nestjs`, `nextjs` et `custom` fixent le port par défaut |
| `defaultExposure` | chaîne | oui | | `PUBLIC`, `INTERNAL`, `PRIVATE` |
| `defaultProtocol` | chaîne | non | `HTTP` | |
| `defaultPort` | entier | non | selon `technology` | 1 à 65535 |
| `defaultCpuRequest`, `defaultCpuLimit` | chaîne | non | `100m`, `500m` | millicores, par exemple `250m` |
| `defaultMemoryRequest`, `defaultMemoryLimit` | chaîne | non | `128Mi`, `512Mi` | `Mi` ou `Gi` |
| `defaultHealthCheckPath` | chaîne | non | `/health` | Chemin des sondes |
| `defaultHealthCheckInitialDelay` | entier | non | `30` | Secondes avant la première sonde de vie |
| `defaultReadinessCheckPath`, `defaultStartupCheckPath` | chaîne | non | chemin des sondes | |
| `defaultHealthCheckPort`, `defaultReadinessCheckPort`, `defaultStartupCheckPort` | entier | non | | 1 à 65535 |
| `defaultLivenessProbeEnabled` | booléen | non | `true` | |
| `defaultReadinessProbeEnabled` | booléen | non | `true` | |
| `defaultStartupProbeEnabled` | booléen | non | `false` | |
| `varRequirements` | tableau | non | | Variables attendues |

:::important
Renseignez les ressources dans le format accepté par la console : CPU en millicores (`250m`), mémoire en `Mi` ou `Gi` (`512Mi`, `1Gi`), avec au plus `2000m` de CPU et `8Gi` de mémoire. Une valeur hors de ce format empêche ensuite de modifier le service depuis la console.
:::

### `varRequirements[]`

| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
| `envVarName` | chaîne | oui | | Nom de la variable, `UPPER_SNAKE_CASE` |
| `required` | booléen | non | `true` | |
| `description` | chaîne | non | | 500 caractères au plus |
| `defaultValue` | chaîne | non | | Jamais un secret |
| `mountType` | chaîne | non | `ENV_VAR` | `ENV_VAR` ou `FILE` |
| `mountPath` | chaîne | si `FILE` | | Chemin absolu du fichier dans le conteneur |
| `mountMode` | chaîne | non | `0400` | Permissions octales |
| `mountSubPath` | chaîne | non | | |

## `appUrls[]` et `appRoutes[]`

| Bloc | Champ | Type | Obligatoire | Défaut |
|---|---|---|---|---|
| `appUrls` | `ref` | ref | oui | |
| `appUrls` | `subdomain` | chaîne, 63 caractères au plus | oui | |
| `appUrls` | `domainRef` | toujours `null` | non | |
| `appRoutes` | `serviceRef` | ref d'un service | oui | |
| `appRoutes` | `urlRef` | ref d'une URL | oui | |
| `appRoutes` | `path` | chaîne | non | `/` |
| `appRoutes` | `pathType` | `PathPrefix` ou `Exact` | non | `PathPrefix` |

À l'import, les URLs sont rattachées au domaine de la plateforme s'il existe, sinon créées détachées : rattachez-les ensuite depuis **Architecture** > **URLs**.

## `appApexUrls[]` et `appUrlRedirects[]`

| Bloc | Champ | Type | Obligatoire | Description |
|---|---|---|---|---|
| `appApexUrls` | `ref` | ref | oui | |
| `appApexUrls` | `domainName` | chaîne | oui | Nom du domaine personnalisé, par exemple `mon-app.exemple.fr` |
| `appApexUrls` | `serviceRef` | ref d'un service | oui | Service qui reçoit le trafic |
| `appApexUrls` | `path`, `pathType` | | non | `/`, `PathPrefix` |
| `appUrlRedirects` | `ref` | ref | oui | |
| `appUrlRedirects` | `domainName` | chaîne | oui | Domaine source |
| `appUrlRedirects` | `sourceSubdomain` | chaîne ou `null` | non | `null` : la source est le domaine racine |
| `appUrlRedirects` | `targetUrlRef` ou `targetApexRef` | ref | un des deux | Exactement une cible |

Ces deux blocs ne s'importent que si l'application cible possède déjà un domaine personnalisé du même nom ; sinon l'entrée est ignorée sans bloquer l'import.

## `environments[]`

| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
| `env` | chaîne | oui | | `dev`, `staging` ou `prod` |
| `shortname` | shortname | oui | | Sert aussi de nom de l'instance |
| `slug` | chaîne, 63 caractères au plus | oui | | |
| `gitRef` | chaîne | non | valeur de `env` | Branche suivie, de type branche |
| `urlPrefix` | chaîne, 20 caractères au plus | non | aucun | Préfixe d'URL |

Un environnement n'est pas créé si l'application cible possède déjà un environnement du même type. Aucune instance n'est créée.

## Transformations à l'export

| Transformation | Effet |
|---|---|
| Champs propres à l'application | Identifiant, chemins et noms qui en dérivent, champs d'état retirés |
| Dépôts gérés | Exportés avec `"isManaged": false` et leur URL `.git` ; l'export échoue si un dépôt géré n'a pas encore d'URL |
| URLs | Détachées de leur domaine (`domainRef: null`) |
| Domaines personnalisés | Non exportés ; seuls leurs noms subsistent dans `appApexUrls` et `appUrlRedirects` |
| Exigences de secrets, nombre de versions conservées du coffre | Non exportés |

## Dérivations à l'import

| Champ absent | Valeur appliquée |
|---|---|
| `serviceDefinitions[].slug` | `shortname` |
| `serviceDefinitions[].imageProject` | nom court de l'application cible |
| `serviceDefinitions[].imageRegistry` | registre par défaut de la plateforme |
| `environments[].gitRef` | valeur de `env` |

L'import est transactionnel : soit tout est créé, soit rien. Ordre de création : dépôts, projet du registre, coffre, bases, buckets, services et variables, URLs, domaines racines, routes, redirections, environnements.

## Exemple complet

```json
{
  "version": "1.0",
  "kind": "wakastart-app-architecture",
  "app": { "name": "Mon app exemple", "shortname": "monapp" },
  "repos": [
    {
      "ref": "monorepo",
      "name": "wk-monapp",
      "isManaged": false,
      "fullName": "exemple-org/wk-monapp",
      "htmlUrl": "https://github.com/exemple-org/wk-monapp.git",
      "defaultBranch": "main"
    }
  ],
  "databaseDefinitions": [
    { "ref": "main-db", "name": "Base principale", "shortname": "main", "engineType": "POSTGRESQL", "defaultMode": "MANAGED", "defaultVersion": "16" }
  ],
  "serviceDefinitions": [
    {
      "ref": "api",
      "name": "API",
      "shortname": "api",
      "repoRef": "monorepo",
      "rootDirectory": "services/api",
      "imageName": "api",
      "role": "BACK",
      "technology": "nestjs",
      "defaultExposure": "INTERNAL",
      "defaultPort": 3000,
      "defaultMemoryLimit": "1Gi",
      "varRequirements": [
        { "envVarName": "LOG_LEVEL", "defaultValue": "info", "required": false },
        { "envVarName": "DATABASE_URL" }
      ]
    },
    {
      "ref": "front",
      "name": "Front",
      "shortname": "front",
      "repoRef": "monorepo",
      "rootDirectory": "apps/front",
      "imageName": "front",
      "role": "FRONT",
      "technology": "nextjs",
      "defaultExposure": "PUBLIC"
    }
  ],
  "appUrls": [
    { "ref": "app", "subdomain": "app" },
    { "ref": "api", "subdomain": "api" }
  ],
  "appRoutes": [
    { "serviceRef": "front", "urlRef": "app", "path": "/" },
    { "serviceRef": "api", "urlRef": "api", "path": "/" }
  ]
}
```
