appflows

Génération de schémas d'architecture SVG à partir d'un simple fichier YAML ou JSON : on décrit les applications et les flux, la bibliothèque place les boîtes, trace les flèches et écrit le dessin.

apps:
  m     : "Dossier patient"
  urg   : "Urgences"
  labo  : "Laboratoire"
  ville : "Médecine de ville"
bus:
  esb : "EAI Santé"
main: m
flows_def:
  - urg -(mllp:2575)-> esb --> m [admissions]
  - labo -(sftp:22)-> esb --> m [résultats]
  - m --> esb -(mllp:2575)-> ville [comptes rendus]
  - ville --> m [identités](https://example.org/identites)

Aucun placement n'est à donner : ni coordonnées, ni tailles, ni ordre des colonnes. C'est examples/yaml/patient.yaml, rendu ici sans sa clé type — celle qui choisit le diagramme.

Deux types de diagramme

La clé type choisit ce qui est raconté, et le suffixe +tech jusqu'où on descend. La même définition sert aux deux lectures : les détails techniques s'écrivent une fois, et le type décide de les montrer ou non.

appli — le schéma de flux. Une application centrale, les autres de part et d'autre. C'est l'exemple ci-dessus.

+tech — la couche technique. Chaque protocole devient un connecteur posé sur le bord de la boîte où sa flèche arrive, le port écrit à côté. Voici la même définition, au mot près, avec type: appli+tech :

doctype — le schéma de document. Pas de centre : le schéma suit un type de document, ceux qui le produisent à gauche, ceux qui le consomment à droite. Ici en doctype+tech, depuis examples/yaml/resultats.yaml :

Un flux peut traverser un ou plusieurs bus d'intégration, porter un lien cliquable, et chaque application une étiquette. Le détail des quatre valeurs et de tout ce qui s'écrit dans une définition est dans docs/formats.md.

Installation

pip install appflows              # bibliothèque + commande
pip install appflows[png]         # + export PNG (cairosvg)
pip install appflows[ui]          # + éditeur web (FastAPI)

Trois façons de s'en servir

En ligne de commande

Un répertoire de définitions en entrée, un schéma par fichier en sortie.

appflows -i mes-schemas -o resultats -c config.yaml --overwrite

Options, codes de retour et journal : docs/cli.md.

Depuis Python

from appflows import Generator

g = Generator()
g.load_data("examples/yaml/patient.yaml")
g.load_config("examples/yaml/config.yaml")  # facultatif

svg = g.graph()

Les définitions s'écrivent aussi en objets, sans passer par un fichier. Seize exemples commentés, chacun avec son rendu, et la liste des noms exportés : docs/api.md.

Dans un éditeur web

appflows-ui          # http://localhost:8080

Deux panneaux YAML, l'aperçu à côté, l'export en SVG ou PNG. Rien n'est écrit côté serveur, et aucune ressource n'est chargée depuis Internet. Réglages, limites et API : docs/ui.md.

En conteneur

L'éditeur et le traitement par lot se construisent aussi en images OCI, vérifiées sans privilège avant d'être exportées :

scripts/build_container.sh --image all   # les deux images, exportées dans dist/
scripts/run_container.sh                 # l'éditeur, confiné, sur http://127.0.0.1:8080/

Construction, confinement et exposition derrière un mandataire : docker/README.md.

Habiller le schéma

Couleurs, dimensions, polices et marges se règlent dans un second fichier, facultatif, organisé par sujet — page, app, main, flow, tag, bus, connector :

app:
  colors: {text: '#0050ef', stroke: '#6c8ebf', fill: '#dae8fc'}
flow:
  label:
    font_size: 12

Les clés omises gardent leur valeur par défaut. examples/yaml/config.yaml les contient toutes, et docs/formats.md § 4 décrit chaque paramètre.

Documentation

• Formats d'entrée — les types de diagramme, la définition clé par clé, la disposition, la configuration, et les messages de diagnostic.
• Utiliser la bibliothèque depuis Python — seize exemples commentés, du plus court chemin au traitement par lot, chacun avec son rendu, et l'API publique.
• La commande appflows — le traitement par lot, ses options et ses codes de retour.
• L'éditeur web — la page, les variables d'environnement, les limites et l'API.
• Fonctionnement et algorithme — les cinq étapes de la génération, les formules de placement, un exemple chiffré et les limites connues.
• Développement — la barrière qualité, les suites de tests, la régénération des images.
• Analyses de qualité — une passe par fichier daté : constats retenus, faux positifs confirmés, et la méthode pour rejouer les outils.
• Publier sur PyPI — comptes, jetons, numérotation, répétition sur TestPyPI et marche à suivre.

Développement

uv sync --all-extras --group dev
uv run pytest
scripts/check.sh            # ruff, pyright, pytest — la barrière complète

Le détail est dans docs/developpement.md.

Licence

MIT — voir LICENSE.