Décrire son architecture en JSON

Décrivez l'infrastructure de votre wakapp dans un fichier JSON unique et importez-la en quelques clics depuis la console WakaStart. Idéal pour démarrer rapidement, cloner une app existante, ou laisser une IA générer le squelette à partir d'une simple description.

---

Pourquoi l'utiliser ?

• Démarrer vite. Plus besoin de cliquer 30 fois pour créer 5 services, 1 base et 2 URLs : un seul fichier JSON et c'est importé.
• Cloner une app. Exportez une app qui marche, importez-la sur une autre app vierge : vous repartez du même squelette.
• Authoring assisté par IA. Vous décrivez en langage naturel ce que votre wakapp doit faire, l'IA produit le JSON conforme, vous l'importez.

---

En deux mots

Le JSON décrit uniquement votre architecture : repos, services, bases, stockage, URLs, environnements. Pas vos secrets, pas vos credentials, pas vos volumes de données.

Une fois importé, votre app possède le squelette de son infrastructure. Vous pouvez ensuite instancier ce squelette dans un environnement (dev, staging, prod…) : chaque environnement créé respectera la même structure (services, bases, stockage, routing) telle que décrite dans le JSON.

---

Importer une architecture

Pré-requis

• Vous avez créé l'app cible (peu importe comment).
• L'app cible est vierge côté architecture : aucun service, aucune base, aucun bucket, aucune URL n'a encore été ajouté manuellement.

Si l'app contient déjà des ressources, le bouton Importer est désactivé (avec un tooltip explicite).

Procédure

1. Ouvrez votre app → Architecture
2. Cliquez sur Importer (en haut à droite, à côté de Exporter)
3. Étape 1 — Coller + Valider
   • Collez votre JSON dans le champ texte
   • Cliquez sur Valider : si le JSON contient une faute (champ obligatoire manquant, type invalide, référence cassée), les erreurs s'affichent avec leur chemin JSON précis pour que vous corrigiez ligne par ligne.
4. Étape 2 — Récapitulatif
   • WakaStart affiche ce qui sera créé :

     textCopier
     Ressources qui seront créées :
       • 1 Repository
       • 2 Services
       • 1 Base de données
       • 1 Bucket de stockage
       • 2 URLs publiques
       • 2 Routes HTTP
       • 3 Environnements
     
     ✅ Les 2 URLs seront attachées automatiquement au domaine
        plateforme y.wakastart.app

   • Si tout vous convient, cliquez Importer.
5. Après l'import
   • Votre app possède désormais le squelette complet de son architecture.
   • Vous pouvez ensuite créer un environnement (dev, staging, prod…) qui instanciera ce squelette : services, bases et stockage seront provisionnés à l'identique pour cet environnement.
   • Vous renseignerez vos variables et secrets par environnement, builderez votre image depuis le repo, puis déploierez.

---

Exporter une architecture

Quand ?

• Vous avez une app qui marche bien et vous voulez la cloner sur une autre app cible (autre WakaStart, autre environnement).
• Vous voulez archiver la description infra de votre app pour la versionner dans votre repo.
• Vous voulez partir d'un modèle pour qu'une IA vous aide à le modifier.

Procédure

1. Ouvrez votre app → Architecture
2. Cliquez sur Exporter → un dialog s'ouvre avec un résumé des transformations appliquées
3. Au choix :
   • Copier le JSON dans le presse-papier
   • Télécharger le fichier .json

Ce qui est exporté et ce qui ne l'est pas

Export = capture de l'existant en lecture seule. Même si votre app source possède un repo géré par WakaStart, il sera exporté comme repo référencé (isManaged: false, avec htmlUrl). L'app cible pointera par défaut vers ce même repo distant. Si vous préférez qu'un nouveau repo soit créé sur l'app cible (utile pour cloner l'architecture d'une app vers une nouvelle), éditez le JSON avant l'import et passez isManaged: true (cf. section Bloc repos).

---

Le format JSON — référence pratique

Squelette minimal

jsonCopier
{
  "version": "1.0",
  "kind": "wakastart-app-architecture",
  "app": {
    "name": "Mon Application",
    "shortname": "monapp"
  }
}

Le bloc app et l'entête version + kind sont les trois seuls champs obligatoires. Tout le reste est optionnel : vous ne décrivez que ce dont vous avez besoin.

shortname ≠ WID. Le shortname du JSON est informatif : à l'import, c'est le shortname de l'app cible qui est utilisé (déjà fixé à la création). Vous ne risquez donc jamais de collision côté import.

Sections disponibles

Bloc repos

Vos repos GitHub à brancher à votre app. Deux modes au choix selon que le repo existe déjà ou non :

Mode 1 — repo géré (isManaged: true) : WakaStart le crée pour vous

jsonCopier
"repos": [
  {
    "ref": "main",
    "name": "wk-monapp",
    "isManaged": true,
    "defaultBranch": "main",
    "visibility": "internal"
  }
]

WakaStart créera un repo GitHub vide dans l'organisation de votre instance, vous donnera son URL, et vous n'aurez plus qu'à pusher votre code dessus.

Le nom GitHub final n'est pas exactement name : WakaStart le préfixe automatiquement avec l'identifiant de votre app pour garantir l'unicité. Exemple : name: "wk-monapp" sur l'app dont l'identifiant interne est vnjdjt donnera le repo Waka-Start/vnjdjt-wk-monapp. Vous n'avez donc pas à vous soucier des collisions de noms.

Conventions :

• name : lowercase, chiffres, tirets (^[a-z0-9][a-z0-9-]*$), max 63 caractères. Convention recommandée : préfixe wk- (ex. wk-api, wk-front).
• defaultBranch défaut main.
• visibility : internal (défaut), private, public.

Mode 2 — repo existant (isManaged: false) : vous le référencez

jsonCopier
"repos": [
  {
    "ref": "main",
    "name": "monapp",
    "fullName": "moncompte/monapp",
    "htmlUrl": "https://github.com/moncompte/monapp.git",
    "isManaged": false,
    "defaultBranch": "main"
  }
]

WakaStart ne touche pas au repo : il s'en sert juste comme source pour les builds de vos services. fullName et htmlUrl sont obligatoires dans ce mode. L'URL doit pointer sur un repo accessible par votre instance WakaStart (clés de déploiement / GitHub App déjà configurées).

Quel mode choisir ?

• Vous démarrez de zéro → isManaged: true. WakaStart vous crée le repo.
• Vous avez déjà un repo Git existant → isManaged: false. WakaStart pointe dessus.

Si vous omettez isManaged, c'est true par défaut (création par WakaStart). Si vous avez exporté votre architecture depuis une autre app, le JSON contiendra toujours isManaged: false (l'export capture l'existant en lecture seule). Vous pouvez le passer à true à la main si vous voulez recréer un nouveau repo plutôt que pointer sur l'ancien.

Bloc serviceDefinitions

jsonCopier
"serviceDefinitions": [
  {
    "ref": "api",
    "name": "API Backend",
    "shortname": "api",
    "repoRef": "main-repo",
    "rootDirectory": "./backend",
    "dockerfilePath": "Dockerfile",
    "buildContext": ".",
    "imageName": "api",
    "role": "BACK",
    "technology": "nestjs",
    "defaultExposure": "PUBLIC",
    "defaultProtocol": "HTTP",
    "defaultPort": 3000,
    "defaultCpuRequest": "100m",
    "defaultCpuLimit": "500m",
    "defaultMemoryRequest": "128Mi",
    "defaultMemoryLimit": "512Mi",
    "defaultHealthCheckPath": "/health",
    "defaultHealthCheckPort": 3000,
    "varRequirements": [
      { "envVarName": "NODE_ENV", "required": true, "defaultValue": "production" },
      { "envVarName": "LOG_LEVEL", "required": false, "defaultValue": "info" }
    ]
  }
]

Champs clés :

Bloc databaseDefinitions

jsonCopier
"databaseDefinitions": [
  {
    "ref": "pg",
    "name": "PostgreSQL principale",
    "shortname": "pg",
    "engineType": "POSTGRESQL",
    "defaultMode": "IN_CLUSTER",
    "defaultPlan": "essential",
    "defaultRegion": "gra",
    "defaultVersion": "16",
    "defaultDiskSizeGb": 10,
    "defaultReplicas": 1,
    "defaultDatabaseName": "monapp"
  }
]

engineType : POSTGRESQL, MYSQL, MONGODB, VALKEY. defaultMode : IN_CLUSTER (économique) ou MANAGED (DB managée OVH).

Bloc storageBucketDefinitions

jsonCopier
"storageBucketDefinitions": [
  {
    "ref": "uploads",
    "name": "Uploads utilisateurs",
    "shortname": "uploads",
    "defaultRegion": "gra",
    "defaultStorageClass": "STANDARD",
    "defaultVersioning": false
  }
]

Blocs appUrls et appRoutes

jsonCopier
"appUrls": [
  { "ref": "api-url", "subdomain": "api", "domainRef": null },
  { "ref": "app-url", "subdomain": "app", "domainRef": null }
],
"appRoutes": [
  { "serviceRef": "api",   "urlRef": "api-url", "path": "/", "pathType": "PathPrefix" },
  { "serviceRef": "front", "urlRef": "app-url", "path": "/", "pathType": "PathPrefix" }
]

domainRef est toujours null dans le JSON. À l'import, WakaStart attache automatiquement vos URLs au domaine plateforme de votre instance (typiquement y.wakastart.app). Vous obtenez tout de suite des FQDNs prêts à l'emploi : api.dev.monapp.y.wakastart.app, app.prod.monapp.y.wakastart.app, etc.

Si vous souhaitez un domaine personnalisé (ex. app.mondomaine.com), vous le configurerez après import depuis la page Architecture → URLs → Domaines, puis vous rattacherez vos URLs au domaine custom (bouton Rattacher).

Bloc environments (optionnel)

jsonCopier
"environments": [
  { "env": "dev",     "shortname": "dev", "slug": "dev",     "urlPrefix": "dev" },
  { "env": "staging", "shortname": "stg", "slug": "staging", "urlPrefix": "staging" },
  { "env": "prod",    "shortname": "prd", "slug": "prod",    "urlPrefix": "prod" }
]

Si vous incluez ce bloc, WakaStart crée les enregistrements d'environnement. Vous devrez ensuite créer les instances (DatabaseInstance, StorageBucketInstance, ServiceInstance) par environnement depuis la console.

---

Trois exemples concrets

1. App monolithique (back + front)

jsonCopier
{
  "version": "1.0",
  "kind": "wakastart-app-architecture",
  "app": { "name": "Hello World", "shortname": "hello" },
  "repos": [
    {
      "ref": "main",
      "name": "hello-world",
      "fullName": "moncompte/hello-world",
      "htmlUrl": "https://github.com/moncompte/hello-world",
      "isManaged": false,
      "defaultBranch": "main"
    }
  ],
  "serviceDefinitions": [
    {
      "ref": "api", "name": "API", "shortname": "api",
      "repoRef": "main", "rootDirectory": "./backend",
      "dockerfilePath": "Dockerfile", "buildContext": ".",
      "imageName": "api", "role": "BACK",
      "defaultExposure": "PUBLIC", "defaultPort": 3000
    },
    {
      "ref": "web", "name": "Web", "shortname": "web",
      "repoRef": "main", "rootDirectory": "./frontend",
      "dockerfilePath": "Dockerfile", "buildContext": ".",
      "imageName": "web", "role": "FRONT",
      "defaultExposure": "PUBLIC", "defaultPort": 3000
    }
  ],
  "appUrls": [
    { "ref": "api-url", "subdomain": "api", "domainRef": null },
    { "ref": "app-url", "subdomain": "app", "domainRef": null }
  ],
  "appRoutes": [
    { "serviceRef": "api", "urlRef": "api-url", "path": "/", "pathType": "PathPrefix" },
    { "serviceRef": "web", "urlRef": "app-url", "path": "/", "pathType": "PathPrefix" }
  ]
}

2. App avec base de données et stockage

Ajoutez les blocs databaseDefinitions + storageBucketDefinitions au précédent, et déclarez les variables que votre back attend :

jsonCopier
"databaseDefinitions": [
  {
    "ref": "pg", "name": "PostgreSQL", "shortname": "pg",
    "engineType": "POSTGRESQL", "defaultMode": "IN_CLUSTER",
    "defaultVersion": "16", "defaultDiskSizeGb": 10
  }
],
"storageBucketDefinitions": [
  { "ref": "files", "name": "Uploads", "shortname": "files" }
]

Dans serviceDefinitions[].varRequirements, déclarez les noms attendus par votre code :

jsonCopier
"varRequirements": [
  { "envVarName": "DATABASE_URL", "required": true },
  { "envVarName": "S3_BUCKET",    "required": true }
]

Vous renseignerez la valeur de chaque variable depuis l'écran Environnements → Variables, par environnement. Pour les secrets, c'est depuis Environnements → Secrets.

3. App multi-services avec environnements préconfigurés

Si vous voulez créer les environnements en un seul import :

jsonCopier
"environments": [
  { "env": "dev",  "shortname": "dev", "slug": "dev",  "urlPrefix": "dev" },
  { "env": "prod", "shortname": "prd", "slug": "prod", "urlPrefix": "prod" }
]

---

Bonnes pratiques

• Un seul shortname par bloc : un service api et une DB api peuvent coexister, mais deux services avec shortname: "api" non.
• Cohérence des varRequirements : déclarez toutes les variables que votre code attend au démarrage. Vous éviterez de chercher pourquoi votre pod crash après le déploiement.
• Choisissez le bon mode de repo :
  • isManaged: true (défaut) si vous voulez que WakaStart crée le repo GitHub pour vous (idéal pour démarrer une nouvelle app).
  • isManaged: false si vous référencez un repo existant — dans ce cas n'oubliez pas fullName et htmlUrl.
• Versionnez le JSON dans votre repo : c'est la description de votre infra. La versionner avec votre code permet de la re-déployer à l'identique sur n'importe quelle instance.

---

Erreurs courantes

---

Utiliser une IA pour générer le JSON

Le format est volontairement prévisible et strict pour qu'un assistant comme Claude, ChatGPT, Cursor, etc. produise un JSON valide du premier coup.

Prompt type

Voici la description de mon projet : je veux une API Node.js qui se connecte à une PostgreSQL et écrit des fichiers dans un bucket S3, plus un frontend Next.js. Je veux que WakaStart me crée un nouveau repo (mode managé). Génère le JSON d'architecture conforme au schéma WakaStart v1.0 (kind: wakastart-app-architecture). Repos en isManaged: true (juste ref, name, isManaged), domainRef: null sur toutes les URLs, pas de wid.

Variante pour pointer un repo existant :

[...] J'ai déjà un repo https://github.com/moncompte/super-app. Génère le JSON [...] avec isManaged: false, fullName: "moncompte/super-app", htmlUrl: "https://github.com/moncompte/super-app.git".

Conseils

• Demandez à l'IA de valider le JSON avant de vous le rendre (clé d'entête "version": "1.0", "kind": "wakastart-app-architecture").
• Si l'étape Valider affiche des erreurs, renvoyez-les telles quelles à l'IA avec leur chemin JSON ; elle corrigera.
• Versionnez le prompt avec le JSON dans votre repo : votre infra devient un artefact reproductible.

---

Aller plus loin

• Repositories
• Services
• Bases, stockage, routing
• URLs et routing
• Variables et secrets
• Environnements