Guide utilisateur

Atlas est un éditeur de diagrammes d'architecture. L'écran se compose de trois zones : le header en haut (projet, recherche, YAML), le panneau à gauche (niveaux, palette, flows, vues) et le canvas central où vous dessinez.

1. 1Au premier lancement, un projet de démonstration est chargé pour explorer librement.
2. 2Le panneau gauche se réduit en barre d’icônes : cliquez sur « ‹ » pour le rétracter, sur une icône pour ouvrir une section.
3. 3Tout est sauvegardé automatiquement dans votre navigateur : vous retrouvez votre travail en revenant.

Astuce Appuyez sur Échap pour fermer un panneau ou un menu ouvert.

Le menu projet (le nom du projet en haut à gauche, avec le chevron) regroupe toutes les actions de gestion.

1. 1Cliquez sur le nom du projet en haut à gauche pour ouvrir le menu.
2. 2« Nouveau projet » crée un projet vierge ; « Ouvrir… » liste vos projets existants.
3. 3« Renommer » change le nom du projet courant ; « Supprimer le projet » le retire et ouvre un projet vierge.
4. 4Chaque modification est enregistrée automatiquement, sans bouton « Sauvegarder ».

Le diagramme est organisé en niveaux d’abstraction (du contexte général jusqu’aux composants et au déploiement). Vous descendez dans le détail puis remontez.

1. 1Ouvrez la section « Niveaux » dans le panneau gauche pour voir l’arbre des éléments.
2. 2Sélectionnez un nœud puis cliquez sur l’icône « Détailler » (flèche d’angle) de sa barre d’action pour entrer dans son détail.
3. 3Utilisez la flèche « Retour » du header (à côté du badge de niveau) pour remonter au niveau parent.
4. 4Le header affiche en permanence le niveau courant (C1, C2…), le scope et le nombre d’éléments.

La palette (panneau gauche) liste les types disponibles pour le niveau courant, groupés par catégorie (acteurs, systèmes, conteneurs, composants, infrastructure…).

1. 1Ouvrez la section « Palette » ; utilisez le champ de recherche pour filtrer le catalogue.
2. 2Cliquez sur un type pour ajouter un nœud au centre, ou glissez-le directement sur le canvas à l’endroit voulu.
3. 3Faites glisser un nœud pour le déplacer ; cliquez dessus pour le sélectionner.
4. 4Sur un nœud sélectionné, la barre d’action en haut à droite donne accès à Propriétés, Détailler et Supprimer.

Un type du catalogue (base de données, cache, file de messages…) est un archétype générique : il prend un comportement précis (latence, capacité) quand vous lui associez une technologie via un preset. Exemple : un nœud database devient une base vectorielle en choisissant le preset vector-db. Sans preset, l’archétype reste neutre avec des valeurs par défaut.

1. 1Ajoutez un nœud d’archétype (database, cache, message-queue…) depuis la palette, comme tout autre type.
2. 2Ouvrez ses Propriétés et renseignez la « Technologie » : le preset correspondant cale automatiquement la latence et la capacité simulées.
3. 3Changez de preset à tout moment pour comparer deux technologies sur le même archétype, sans redessiner le diagramme.
4. 4Les nœuds d’hébergement on-prem (datacenter, bare-metal) accueillent vos instances comme des hôtes physiques, en plus des hôtes cloud.

Astuce Approximations signalées (mandat de réalisme) : la latence est modélisée ~constante pour le stockage, le filtrage et les appels externes ; le cache utilise un taux de hit générique par défaut ; la capacité d’une base vaut 100 connexions par défaut en déploiement ; le garde-fou mémoire est comparé à la capacité CPU brute. Coût on-prem : les nœuds datacenter/bare-metal portent un mode de coût (CAPEX amorti + OPEX) purement déclaratif — le calcul du €/mois et le point d’équilibre cloud / on-prem arriveront en B.2.

Les relations relient deux nœuds via leurs ports (les points sur les bords gauche, droit, haut et bas).

1. 1Approchez le curseur d’un bord de nœud pour faire apparaître son port.
2. 2Tirez depuis ce port jusqu’à un port d’un autre nœud pour tracer la relation.
3. 3Au relâchement, choisissez le type de relation proposé dans la fenêtre contextuelle.
4. 4Une relation invalide est signalée pendant le tracé : relâchez sur une cible compatible.

Le panneau de droite « Propriétés » permet d’ajuster le détail d’un élément ou d’une relation sélectionné.

1. 1Sélectionnez un nœud puis cliquez sur l’icône Propriétés (engrenage) de sa barre d’action.
2. 2Modifiez le nom, le type, la technologie et la description dans les champs.
3. 3Ajoutez des tags pour catégoriser l’élément.
4. 4Les overrides permettent d’ajuster une valeur spécifique à une vue sans changer le modèle global.
5. 5La section « Profil de simulation » ajuste les paramètres numériques propres à ce composant (latence de base, capacité…) : l’archétype reste verrouillé (on règle uniquement les paramètres de l’archétype résolu), et le bouton ↺ d’un champ rétablit sa valeur héritée.

Astuce Profils coût et panne pas encore éditables (moteurs B.2 / B.7 à venir). Mandat de réalisme : en mode logique, une surcharge du profil de simulation ne prend effet que si le composant porte un preset ou un override (sinon il reste neutre/passthrough) ; en mode déploiement, elle s’applique toujours.

Un flow décrit, dans l’ordre, comment les éléments du diagramme s’enchaînent pour réaliser un scénario (passer une commande, s’authentifier…). Chaque étape (« step ») pointe vers un objet déjà présent : une relation tracée devient un message (↔), un nœud devient un traitement (◉). On ne saisit donc pas les étapes au clavier — on les capture en cliquant le canvas, puis on peut les enrichir en détail.

1. 1Ouvrez la section « Flows » du panneau gauche. Saisissez un nom dans « Nouveau flow… », cliquez « + » pour le créer, puis cliquez un flow de la liste pour le sélectionner.
2. 2Dans le panneau de droite, onglet « Flow », renommez-le si besoin via le champ « Nom du flow actif ».
3. 3Sous « Déclencheur », choisissez ce qui démarre le flow : entry (acteur externe), onMessage (consommation d’un événement — sélectionnez la relation écoutée), schedule (planifié — saisissez une expression cron, validée à la frappe) ou called (appelé uniquement via un sous-flow).
4. 4Cliquez « Capturer des steps » (il passe en « Capturer… (cliquez le canvas) »), puis cliquez sur le canvas, dans l’ordre du scénario, les relations (↔) et les nœuds (◉) concernés : chaque clic ajoute une étape.
5. 5Dans la liste « Steps », réordonnez une étape avec ↑ / ↓ et retirez-la avec ×.
6. 6Enrichissement (C1 → C2) : cliquez « C2+ » sur une étape pour détailler son sous-enchaînement, capturez les relations fines, puis « repasser en C1 » pour revenir. Une bannière signale les détails C2 incohérents (relation parente manquante).
7. 7Structurez l’enchaînement sans quitter le panneau : « ⏲+ » enveloppe une étape en différé (délai en ms éditable), « Insérer un appel » ajoute un sous-flow, et « + branche » ajoute une branche à une étape parallèle.
8. 8Créer une étape parallèle de zéro se fait encore via le YAML (voir l’exemple) ; une fois la structure posée, ses branches et son contenu s’éditent dans le panneau.

1flows:2  - id: commande3    name: Passer commande4    trigger:5      kind: entry          # démarré par un acteur externe6    steps:7      - type: message      # ↔ une relation tracée8        label: Client → API9        relationId: r-client-api10      - type: parallel     # branches concurrentes (join-all)11        label: Validation12        branches:13          - - type: message14              label: API → Paiement15              relationId: r-api-pay16          - - type: message17              label: API → Stock18              relationId: r-api-stock19      - type: deferred     # découplé : n’attend pas la suite20        label: Notifier21        afterMs: 500022        steps:23          - type: process  # ◉ un nœud qui travaille24            label: Envoi e-mail25            elementId: e-mailer

Astuce Tracez d’abord vos relations : une étape référence toujours une relation ou un nœud existant, jamais du texte libre.

La vue déploiement décrit le runtime : elle place vos conteneurs (logiques) sur des hôtes physiques (nœuds de déploiement) sous forme d’instances imbriquées — quel conteneur tourne où, et en combien d’exemplaires.

1. 1Ouvrez la section « Vues » du panneau gauche, puis cliquez « + Vue de déploiement » (actif dès qu’au moins un conteneur existe).
2. 2Choisissez le mode de départ : « Démarrage rapide » crée une instance par conteneur existant ; « Modèle vide » vous laisse tout placer à la main.
3. 3La vue apparaît dans la liste « Vues » : cliquez-la pour y revenir, ou créez-en plusieurs (par environnement, par exemple).
4. 4En vue déploiement, la section « Conteneurs à déployer » liste les conteneurs (étiquette « déployer ») et les acteurs (« acteur »).
5. 5Glissez un conteneur sur le canvas pour créer une instance (« Conteneur #n ») ; déposez-le directement sur un hôte pour l’y imbriquer. Sur un hôte incompatible, l’instance reste libre.
6. 6Glissez un acteur de la même façon : il est placé tel quel, sans être instancié.
7. 7Placez un répartiteur (load-balancer) reliant un conteneur à ses instances : sa « Stratégie » choisit la répartition — round-robin (tour de rôle), weighted (proportionnel au « Poids (LB) » de chaque instance) ou least-connections (vers l’instance la moins chargée).

Astuce least-connections est ici approximé par la charge du tick courant (pas de connexions persistantes en vol) : fidèle pour comparer des répartitions, à affiner quand le vrai « in-flight » arrivera. round-robin et weighted sont exacts.

Quand une panne est injectée (un nœud « tué » ou une zone tombée), le routage devient conscient de l’état : le répartiteur n’envoie plus qu’aux backends survivants et tente de récupérer un appel raté. Ces garde-fous sont une politique côté appelant, résolue depuis le `faultProfile` de chaque composant.

1. 1Le routeur évite automatiquement les nœuds morts ; avec `retries`, un appel échoué (surcharge, nœud tombé, timeout) est rejoué sur un autre survivant (événement RequestRetried). S’il reste des backends mais aucun éligible, l’appel est abandonné (drop « no-healthy-backend »).
2. 2Avec `timeoutMs`, un appel plus lent que ce délai est abandonné : drop « timeout », son coût de latence étant plafonné à `timeoutMs`.
3. 3Avec `circuitBreaker` (+ `cbThreshold` / `cbOpenTicks`), après `cbThreshold` échecs consécutifs vers une cible, le circuit s’ouvre pour `cbOpenTicks` ticks : un appel direct échoue immédiatement (« circuit-open ») et le répartiteur exclut ce backend du pool. Un succès remet le compteur à zéro.
4. 4Politique côté appelant : ces garde-fous s’appliquent aussi bien à un LB / une passerelle en frontal qu’à un service qui en appelle directement un autre — aucun répartiteur n’est requis.
5. 5Le bouton « Calculer la résilience » du panneau Diagnostic note chaque flow de 0 à 100 sous les pannes injectées. Le calcul est fait à la demande (coûteux : il rejoue des runs de simulation sous panne) et n’est pas rafraîchi automatiquement quand le modèle change — recliquez pour recalculer après une modification.

Astuce Mandat de réalisme : le half-open du circuit-breaker est simplifié — à l’expiration des `cbOpenTicks` le circuit se referme et les appels reprennent, sans restriction à une seule sonde concurrente. Et `retries` n’a d’effet que s’il existe des alternatives (plusieurs backends) : sans backend de secours, le rejeu ne change rien. Le score de résilience pondère taux de drop, dégradation p99 et temps de récupération : la saturation p99 après récupération du nœud (`postRecoveryP99`) est mesurée mais pas encore pondérée dans le score (laissée informative en attendant une recalibration).

En mode chaos (lecture de simulation), chaque requête génère une particule animée qui traverse le chemin du flow en temps réel. Le trafic est simulé par un processus de Poisson seedé, ce qui rend les arrivées reproductibles mais décorrélées entre flows.

1. 1Chaque requête produit une particule (1 par requête) colorée par issue : bleu = en transit, vert = succès, rouge = erreur/drop.
2. 2Le trafic entrant suit un processus de Poisson seedé (graine fixée par scénario) : les inter-arrivées sont aléatoires mais reproductibles — relancer la même session produit exactement les mêmes particules.
3. 3Quand un nœud est tué, une onde de choc se propage depuis ce nœud (anneau rouge expansif) pour signaler visuellement la panne.
4. 4En vue déploiement, les particules circulent sur les instances et le répartiteur (load-balancer) selon la stratégie active.
5. 5Au-delà du seuil de trafic, un échantillonnage par route est appliqué : seule une fraction des particules est dessinée, avec un badge ×N indiquant le facteur — le moteur et toutes les métriques restent exacts, seul l’affichage est allégé.
6. 6En mode réduit (prefers-reduced-motion), l’onde de choc n’est pas affichée.
7. 7En l’absence de trafic simulé, aucune particule n’est dessinée (non-régression canvas vide).

Astuce Approximations signalées (mandat de réalisme) : (1) un hop sans relation dessinée est rendu par un segment droit centre-à-centre (pas de courbe le long de la relation) ; (2) le scrub (déplacement dans le temps) n’anime pas les particules d’un tick passé — seul le tick courant est rendu en live ; (3) au-delà du seuil, l’échantillonnage est par route (toutes les routes restent représentées, badge ×N) mais n’est pas proportionnel à la charge instantanée de chaque route ; (4) le modèle de Poisson n’est pas un modèle de session utilisateur (pas de think-time, pas de sessions persistantes).

Pendant une simulation, le tiroir « Chemin critique » (bouton en bas à gauche du canvas) décompose la latence p99 d’un flow en cascade (waterfall) : une ligne par nœud traversé, chaque barre positionnée sur l’axe temps selon son décalage de départ et sa durée. On voit ainsi d’un coup d’œil où part le temps.

1. 1Lancez une simulation : le bouton « Chemin critique » apparaît en bas à gauche du canvas (il reste masqué tant qu’aucun run n’est en cours).
2. 2Mettez la simulation en pause pour figer la mesure, puis ouvrez le tiroir : la cascade du p99 du flow se calcule à ce moment-là.
3. 3Choisissez le flow à analyser dans le sélecteur en haut du tiroir ; le p99 du flow est rappelé à droite.
4. 4Lisez la cascade : chaque barre montre le décalage de départ et la durée du nœud (info-bulle au survol). L’étape la plus lente — la « coupable » — est tracée en rouge.
5. 5Basculez le tri : « Chronologique » positionne les barres dans le temps et affiche la durée en ms ; « Coupables » trie par durée décroissante et affiche la part de chaque étape en % du p99.
6. 6Une pastille rouge sur le bouton signale qu’une étape coupable domine le p99 (elle pèse à elle seule une large part du total).
7. 7Un badge ambre « N+1 ×N » marque un nœud visité plusieurs fois en moyenne par requête (motif N+1 probable). Cliquez une ligne pour sélectionner le nœud sur le canvas et ouvrir ses Propriétés.

Astuce Approximations signalées (mandat de réalisme) : la cascade est figée sur le tick courant (mise en pause), elle n’est pas rafraîchie en continu. Le repère « N+1 » est une heuristique fondée sur le nombre moyen (fractionnaire) de visites par requête — il n’y a pas de traçage SQL réel : ×4,7 reste affiché tel quel et n’est pas arrondi à 5.

Atlas vérifie en continu la cohérence du modèle et signale les problèmes détectés.

1. 1Surveillez la bannière de diagnostics qui apparaît quand des problèmes sont détectés.
2. 2Ouvrez l’onglet « Diagnostic » du panneau de droite pour la liste détaillée.
3. 3Les liens incompatibles sont mis en évidence directement sur le canvas.
4. 4Corrigez les éléments concernés : les diagnostics se mettent à jour automatiquement.

Le modèle peut être lu et écrit en YAML, pratique pour le versionnage, le partage ou l’édition externe.

1. 1Cliquez sur l’icône YAML (accolades) du header pour ouvrir le panneau YAML de la vue courante.
2. 2Pour importer, ouvrez le menu projet puis « Importer » et choisissez un fichier .yaml.
3. 3Pour exporter, utilisez « Exporter » dans le menu projet ou copiez le contenu du panneau YAML.
4. 4Un YAML invalide est rejeté avec un message d’erreur : corrigez puis réimportez.

1nodes:2  - id: web3    type: container4    name: Application web5    tech: Next.js6  - id: api7    type: container8    name: API9relations:10  - from: web11    to: api12    type: uses