Le Code FlowZap est le moteur de vos visualisations — une interface textuelle épurée, conçue pour combler l'écart entre de simples notes et un outillage de diagrammes professionnel. Contrairement aux langages de programmation complexes, il adopte une syntaxe naturelle et intuitive qui vous permet de décrire processus, couloirs (swimlanes) et connexions aussi facilement qu'une liste de tâches. Cette source unique de vérité alimente à la fois nos vues Workflow et Séquence, ce qui vous permet de changer de perspective instantanément sans redessiner le moindre élément. Il vous suffit de définir votre logique dans l'éditeur, de cliquer sur « Mettre à jour », et FlowZap transforme votre texte brut en une architecture soignée, prête pour la présentation, en quelques millisecondes.

Que vous soyez un développeur humain ou un assistant de codage IA, ce guide vous aidera à générer du Code FlowZap valide pouvant être enregistré en fichiers `.fz` et rendu par FlowZap.xyz.

Règles de sortie principales

Toujours produire uniquement du Code FlowZap brut, sans balises Markdown, sans explications et sans texte environnant.
Ne pas ajouter de commentaires comme « Voici votre code » ou de balises ``` ; retourner le corps du code tel quel.
Utiliser uniquement du texte UTF-8 ; pas d'emojis, pas de caractères non imprimables.

Structure de haut niveau d'un diagramme FlowZap

Un diagramme FlowZap est une description en texte brut composée de rangées, nœuds, arêtes et fragments de boucle optionnels.
Chaque rangée regroupe les étapes liées à un acteur ou système (ex. User, Application, Server).
Les nœuds définissent les étapes ou décisions ; les arêtes définissent le flux directionnel entre les nœuds.
Les boucles décrivent un comportement répétitif, comme les réessais, et peuvent impliquer des nœuds de plusieurs rangées.

Contraintes globales (très important)

Les IDs de nœud doivent suivre le modèle n1, n2, n3, … et être globalement uniques dans toutes les rangées d'un même diagramme.
La numérotation des nœuds doit être séquentielle sans interruption (ex. n1, n2, n3, et non n1, n3, n5). Utilisez toujours des entiers consécutifs à partir de 1.
Seules quatre formes sont autorisées : circle, rectangle, diamond, taskbox.
Les attributs de nœud utilisent clé:"valeur" avec deux-points, tandis que les étiquettes d'arête utilisent label="valeur" avec un signe égal entre crochets.
Ne pas générer de syntaxe Mermaid, PlantUML ou autre comme graph TD, sequenceDiagram, participant ou -->.
Ne pas inventer de nouvelles clés d'attribut ; utiliser uniquement label, owner, description, system et les clés anglaises décrites ici.

Rangées (participants / couloirs)

Chaque rangée commence par un identifiant suivi d'une accolade ouvrante et d'un unique commentaire d'intitulé.

User { # User
...
}

Les IDs de rangée sont des identifiants simples comme User, Application, Server, flow, process, ops. Un seul commentaire est autorisé par rangée, immédiatement après l'accolade ouvrante, sous la forme # Intitulé. Ne placez pas de commentaires ailleurs dans le code.

Do:

User { # User
flow { # Flow

Don't:

// User ou commentaires hors de l'accolade ouvrante
Plusieurs commentaires # dans le même bloc de rangée

Nœuds (étapes, décisions, tâches)

Chaque nœud est défini sur sa propre ligne au format : nX: shape label:"Texte" plus attributs optionnels.

n1: circle label:"Début"
n2: rectangle label:"Saisir identifiant et mot de passe"
n3: diamond label:"Format valide ?"
n4: taskbox owner:"Alice" description:"Déployer" system:"CI"

Formes autorisées : circle (début/fin), rectangle (processus/action), diamond (décision), taskbox (tâche assignée avec owner/system). Utilisez deux-points (:) entre l'ID du nœud et la forme, et deux-points pour tous les attributs (ex. label:"..."). Les étiquettes de nœud doivent être entre guillemets doubles. Gardez les étiquettes concises mais descriptives, généralement moins de 50 caractères.

Do:

n1: circle label:"Début"
n3: diamond label:"Est valide ?"
n1: taskbox owner:"Alice" description:"Déployer" system:"CI"

Don't:

n1: circle label="Début" (mauvais séparateur)
n3 diamond "Est valide ?" (deux-points manquants)
Utiliser des attributs inconnus comme priority:"high"

Arêtes (connexions entre nœuds)

Les arêtes connectent toujours un .handle(direction) d'un nœud à un .handle(direction) d'un autre nœud.

n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> Application.n3.handle(top) [label="Envoyer"]

Format de base : sourceNode.handle(direction) -> targetNode.handle(direction) [label="Texte"]. Les directions doivent être : left, right, top, bottom. Pour les arêtes inter-rangées, préfixez la cible avec le nom de la rangée, ex. Application.n6.handle(top). Les étiquettes d'arête utilisent égal avec crochets, ex. [label="Oui"], jamais deux-points : [label:"Oui"]. Les étiquettes d'arête sont optionnelles.

Do:

n1.handle(right) -> n2.handle(left) [label="Aller"]
n3.handle(bottom) -> laneB.n5.handle(top)
n2.handle(bottom) -> Application.n6.handle(top) [label="Envoyer"]

Don't:

n1.handle(right) -> n2.handle(left) [label:"Aller"] (mauvais signe égal)
n3.handle(bottom) -> n5 (rangée manquante pour inter-rangées)
n2 -> n6 [label="Envoyer"] (pas de handles)

Connexions inter-rangées

Lors d'une connexion d'un nœud d'une rangée vers un nœud d'une autre, préfixez le nœud cible avec l'ID de la rangée.

n3.handle(bottom) -> Application.n6.handle(top) [label="Envoyer identifiants"]
n8.handle(top) -> User.n2.handle(bottom) [label="Non - Erreur"]

Gardez la définition de l'arête à l'intérieur des accolades de la rangée d'origine. N'omettez jamais le préfixe de rangée pour les cibles inter-rangées ; écrivez toujours RangéeId.nX.

Bonnes pratiques pour les diagrammes de séquence

Le Code FlowZap se rend à la fois en vue Workflow et en vue Séquence. La vue Séquence dessine les messages de haut en bas dans l'ordre de définition des arêtes. Suivez ces règles pour des diagrammes de séquence clairs et logiques dans du code multi-rangées.

Appariement requête-réponse — Chaque arête de requête inter-rangées doit avoir une arête de retour correspondante. Si la rangée A envoie un message à la rangée B, la rangée B doit renvoyer une réponse. Les réponses manquantes créent des diagrammes incomplets et trompeurs.
Ordre chronologique des arêtes — Définissez les arêtes dans l'ordre où elles se produisent dans le temps. Le diagramme de séquence rend les messages de haut en bas selon l'ordre de définition, pas selon les IDs de nœud. Des arêtes mal ordonnées produisent des séquences de flèches confuses.
Pas de nœuds orphelins — Chaque nœud doit participer à au moins une arête (en tant que source ou cible). Les nœuds sans arêtes apparaissent comme des étapes déconnectées et sans signification dans le diagramme de séquence.
Séparer les flux asynchrones — Si un diagramme contient des flux indépendants (ex. un chemin de requête principal et un chemin de surveillance en arrière-plan), définissez d'abord toutes les arêtes du flux principal, puis les arêtes asynchrones/arrière-plan. Ne mélangez jamais des flux non liés.

Faire : Requête avec réponse correspondante

Client { # Client
n1: rectangle label:"Envoyer requête"
n2: rectangle label:"Recevoir réponse"
n1.handle(bottom) -> Server.n3.handle(top) [label="HTTP GET"]
}
Server { # Serveur
n3: rectangle label:"Traiter requête"
n4: rectangle label:"Retourner données"
n3.handle(right) -> n4.handle(left)
n4.handle(top) -> Client.n2.handle(bottom) [label="200 OK"]
}

Ne pas faire : Réponse manquante, nœud orphelin

Client { # Client
n1: rectangle label:"Envoyer requête"
n2: rectangle label:"Recevoir réponse"
n1.handle(bottom) -> Server.n3.handle(top) [label="HTTP GET"]
}
Server { # Serveur
n3: rectangle label:"Traiter requête"
n4: rectangle label:"Retourner données"
n3.handle(right) -> n4.handle(left)
}

Problème : n2 est orphelin (aucune arête), et il n'y a pas d'arête de retour du Serveur vers le Client. Le diagramme de séquence montre une requête partant mais ne revenant jamais.

Boucles (fragments LOOP)

Utilisez le mot-clé loop pour décrire un comportement répétitif, comme les réessais.

loop [réessayer jusqu'à format valide] n2 n3 n7 n8
loop [réessayer jusqu'à 3 fois] n2 n3 n4

Format de base : loop [condition] n1 n2 n3 ... où la condition est du texte brut et les tokens suivants sont des IDs de nœud. Les conditions doivent être courtes et descriptives. Listez les nœuds impliqués dans l'ordre d'exécution ; ils peuvent être dans une ou plusieurs rangées. N'imbriquez pas les boucles ; gardez-les plates et définies après les nœuds concernés.

Modèles minimaux complets

Utilisez ces squelettes comme point de départ ; adaptez les étiquettes et arêtes au flux demandé.

Single-lane minimal flow

process { # Processus
n1: circle label:"Début"
n2: rectangle label:"Étape"
n3: circle label:"Fin"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
}

Two-lane user–app interaction

user { # Utilisateur
n1: circle label:"Début"
n2: rectangle label:"Soumettre"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> app.n3.handle(top) [label="Envoyer"]
}
app { # App
n3: rectangle label:"Traiter"
n4: circle label:"Terminé"
n3.handle(right) -> n4.handle(left)
}

Decision branch

flow { # Flux
n1: rectangle label:"Vérifier"
n2: diamond label:"OK ?"
n3: rectangle label:"Corriger"
n4: rectangle label:"Continuer"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="Non"]
n2.handle(right) -> n4.handle(left) [label="Oui"]
}

Simple loop

flow { # Flux
n1: rectangle label:"Valider"
n2: diamond label:"Valide ?"
n1.handle(right) -> n2.handle(left)
loop [réessayer jusqu'à valide] n1 n2
}

Taskbox example

ops { # Ops
n1: taskbox owner:"Alice" description:"Déployer" system:"CI"
}

Exemple complet : flux d'authentification multi-rangées

Utilisez ce modèle comme référence pour les flux typiques d'« authentification » ou de « connexion ».

User { # Utilisateur
n1: circle label:"Début"
n2: rectangle label:"Saisir identifiant et mot de passe"
n3: rectangle label:"Soumettre le formulaire"
n4: rectangle label:"Recevoir confirmation"
n5: circle label:"Accès accordé"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
n3.handle(bottom) -> Application.n6.handle(top) [label="Envoyer identifiants"]
n4.handle(right) -> n5.handle(left)
loop [réessayer jusqu'à format valide] n2 n3 n7 n8
}
Application { # Application
n6: rectangle label:"Recevoir la requête"
n7: rectangle label:"Valider le format"
n8: diamond label:"Format valide ?"
n9: rectangle label:"Transférer au serveur"
n14: rectangle label:"Transférer confirmation au client"
n6.handle(right) -> n7.handle(left)
n7.handle(right) -> n8.handle(left)
n8.handle(right) -> n9.handle(left) [label="Oui"]
n9.handle(bottom) -> Server.n10.handle(top) [label="Authentifier"]
n8.handle(top) -> User.n2.handle(bottom) [label="Non - Erreur"]
n14.handle(top) -> User.n4.handle(bottom) [label="Succès"]
}
Server { # Serveur
n10: rectangle label:"Vérifier la base de données"
n11: diamond label:"Identifiants valides ?"
n12: rectangle label:"Générer jeton de session"
n13: rectangle label:"Retourner erreur"
n10.handle(right) -> n11.handle(left)
n11.handle(right) -> n12.handle(left) [label="Oui"]
n11.handle(bottom) -> n13.handle(bottom) [label="Non"]
n12.handle(top) -> Application.n14.handle(bottom) [label="Jeton"]
n13.handle(top) -> Application.n6.handle(bottom) [label="Erreur 401"]
}

Erreurs courantes à éviter

Ne pas mettre le commentaire de rangée sur une ligne séparée. Le # Intitulé doit être sur la même ligne que l'accolade ouvrante : nomRangée { # Intitulé et non nomRangée { suivi de # Intitulé sur la ligne suivante.
Ne pas utiliser label="Texte" sur les nœuds ; les étiquettes de nœud doivent être label:"Texte".
Ne pas utiliser label:"Texte" dans les crochets d'arête ; les arêtes doivent être [label="Texte"].
Ne pas omettre les préfixes de rangée sur les arêtes inter-rangées (ex. n3 -> n5 est invalide entre rangées).
Ne pas introduire d'autres syntaxes de diagramme (Mermaid, UML, JSON, YAML, XML).
Ne pas réutiliser les IDs de nœud (n1, n2, …) dans le diagramme ; chaque ID doit être globalement unique.
Ne pas sauter de numéros de nœud. Les IDs de nœud doivent être séquentiels sans interruption (ex. n1, n2, n3, et non n1, n3, n5). Si vous avez 14 nœuds, ils doivent être numérotés de n1 à n14 consécutivement.
Ne pas ajouter de commentaires supplémentaires en dehors du # Intitulé juste après l'accolade ouvrante de chaque rangée.
Ne pas utiliser de boucles en dehors des accolades d'une rangée. Une boucle doit uniquement apparaître à l'intérieur des accolades ({...}) d'une rangée.

Conseils de prompting LLM (pour développeurs humains)

Toujours inclure une instruction comme : Référez-vous à docs/flowzap-code-guidelines.md et produisez UNIQUEMENT du Code FlowZap valide pour ce flux.
Fournir une description courte et claire du flux : acteurs, étapes clés, décisions et boucles (ex. connexion avec réessai, paiement avec passerelle).
Si la sortie du LLM contient du Markdown, des explications ou une syntaxe invalide, relancez : Supprimez tout Markdown et explications ; produisez uniquement du Code FlowZap suivant les directives.
Pour les mises à jour, collez le Code FlowZap existant et dites : Modifiez ce code sur place : ajoutez [nouvelle étape/branche/boucle] en gardant les IDs uniques et la syntaxe valide.

Rappel final pour les agents IA

Votre mission est de générer uniquement du texte Code FlowZap valide qui respecte toutes les règles de syntaxe et de structure ci-dessus afin qu'il puisse être enregistré en fichier .fz et rendu par FlowZap sans corrections manuelles.

Télécharger le guide d'intégration FlowZap Code (.md)

Plus d'exemples ici

Voir encore plus d'exemples sur Github

Comment rédiger et modifier le code FlowZap (aucune compétence technique requise !)

Règles de sortie principales

Structure de haut niveau d'un diagramme FlowZap

Contraintes globales (très important)

Rangées (participants / couloirs)

Nœuds (étapes, décisions, tâches)

Arêtes (connexions entre nœuds)

Connexions inter-rangées

Bonnes pratiques pour les diagrammes de séquence

Boucles (fragments LOOP)

Modèles minimaux complets

Single-lane minimal flow

Two-lane user–app interaction

Decision branch

Simple loop

Taskbox example

Exemple complet : flux d'authentification multi-rangées

Erreurs courantes à éviter

Conseils de prompting LLM (pour développeurs humains)

Rappel final pour les agents IA