#Sommaire
| § | Échange modélisé | Services réels impliqués |
|---|---|---|
| 0 | Conventions de lecture et carte des participants | — |
| 1 | Connexion par code d'autorisation avec PKCE | Portail client, Keycloak, passerelle |
| 2 | Appel traversant la passerelle avec réécriture de scope | Passerelle, service scopé |
| 3 | Création d'un projet | Portail, passerelle, service de spécification |
| 4 | Génération d'une spécification par le copilote | Copilote, passerelle LLM, service de spécification |
| 5 | Pipeline de rétro-ingénierie | Service de rétro-ingénierie, dépôt distant, coffre, service de spécification |
| 6 | Exécution d'un agent en tâche Kubernetes éphémère | Service d'exécution, coffre, cluster |
| 7 | Revue et approbation avec séparation des devoirs | Portail, service de collaboration |
| 8 | Déploiement gouverné avec retour arrière | Service de déploiement, cluster, registre |
| 9 | Lecture du catalogue de plans | Portail public, passerelle, service utilisateurs |
| 10 | Vérification de la chaîne d'audit | Portail d'administration, service d'audit |
| 11 | Plafonnement d'autonomie par le plan commercial | Registre d'extensions, service utilisateurs |
| 12 | Refus par défaut du moteur de politique | Service d'exécution, moteur de politique |
| 13 | Flux d'événements serveur rejouable | Portail, service d'exécution |
| 14 | Ingestion documentaire jusqu'à l'objet de spécification | Service d'ingestion, stockage objet, service de spécification |
| 15 | Table de correspondance participant vers service réel | — |
Total : 14 diagrammes de séquence.
#0. Conventions de lecture et carte des participants
#0.1 Notation
| Élément UML de séquence | Transposition Mermaid |
|---|---|
| Ligne de vie | participant PC as Portail client |
| Message synchrone | A->>B: message |
| Message de retour | B-->>A: reponse |
| Barre d'activation | activate et deactivate |
| Fragment alternatif | alt / else / end |
| Fragment optionnel | opt / end |
| Fragment itératif | loop / end |
| Commentaire d'invariant | Note over A,B: texte |
#0.2 Les participants et leur adresse réelle
| Alias | Composant réel | Port ou domaine |
|---|---|---|
PC |
Portail client, Next.js exporté en statique | spectra.kyrieva.com |
PA |
Portail d'administration | spectra.admin.kyrieva.com |
KC |
Keycloak, realm dédié, PKCE S256 | Serveur d'identité partagé |
GW |
Passerelle API, source de vérité des routes | 4100 |
US |
Service utilisateurs, organisations, RBAC, catalogue commercial | 4101 |
SPEC |
Service de spécification, propriétaire de l'entité projet | 4107 |
COP |
Service copilote, langage naturel vers spécification | 4118 |
REV |
Service de rétro-ingénierie | 4120 |
ART |
Service d'artefacts | 4129 |
COL |
Service de collaboration et de revues | 4128 |
DEP |
Service de déploiement | 4121 |
RT |
Service d'exécution d'agents | 4119 |
EXT |
Registre d'extensions, compétences, outils, prompts | 4116 |
AUD |
Service d'audit et de conformité | 4113 |
BUS |
Service de facturation et d'usage | 4115 |
ING |
Service d'ingestion documentaire | 4125 |
CORE |
Cœur agentique et personnel virtuel | 8095 |
LLM |
Passerelle LLM | Passerelle unique du fournisseur |
PG |
PostgreSQL, une base par service | Convention ks_<service>_<env> |
VAULT |
Coffre de secrets | Accès par chemin, jamais par valeur |
K8S |
Interface Kubernetes du cluster | Depuis le cluster |
S3 |
Stockage objet | Compatible S3 |
#0.3 Deux règles de routage à connaître
| Style d'enregistrement | Comportement de la passerelle |
|---|---|
| Préfixes natifs | Le service est atteint à ses propres chemins /api/v1/<ressource> et la passerelle les proxifie verbatim. |
| Montages scopés | Le service est fronté à un préfixe unique /api/v1/<slug> et la passerelle réécrit le chemin : elle retire le scope puis préfixe la base de réécriture. |
La résolution combine des motifs d'expression régulière, la plus longue portée gagnant, puis la correspondance du plus long préfixe. C'est cette règle qui permet à /api/v1/billing/... d'aller au service utilisateurs pendant que /api/v1/billing-usage/... va au service de facturation et d'usage.
#1. Connexion par code d'autorisation avec PKCE
Aucun diagramme à afficher
Diagramme 1 — sequenceDiagram
| Point d'attention | Réalité vérifiée |
|---|---|
| Méthode de défi | S256, clients publics, aucun secret côté navigateur |
| Adresse de retour | <origine>/auth/callback |
| Stockage du jeton | Stockage de session du navigateur, pas de cookie persistant |
| Exemption de garde | Les préfixes /auth et /public sont exemptés, sinon une page anonyme boucle vers la connexion |
| Cache du jeu de clés | Rafraîchissement horaire, service de la version en cache et jusqu'à cinq tentatives |
| Écart connu | Le mode d'authentification par en-têtes auto-déclarés reste la valeur par défaut du code |
#2. Appel traversant la passerelle avec réécriture de scope
Aucun diagramme à afficher
Diagramme 2 — sequenceDiagram
| Chemin client | Chemin amont réel | Service |
|---|---|---|
/api/v1/projects/{id} |
/api/v1/projects/{id} |
Service de spécification |
/api/v1/sdlc/projects/{id}/releases |
/api/v1/projects/{id}/releases |
Service SDLC |
/api/v1/dependency-graph/projects/{id} |
/api/v1/projects/{id} |
Service de graphe de dépendances |
/api/v1/mcp/tools |
/tools |
Passerelle du protocole de contexte |
/api/v1/billing/plans |
/api/v1/billing/plans |
Service utilisateurs |
/api/v1/billing-usage/budgets |
/api/v1/budgets |
Service de facturation et d'usage |
Motif du montage scopé. Les services de deuxième vague montent tous des sous-ressources sous les espaces de noms partagés /api/v1/projects, /spec-items, /change-requests, /audit et /metrics. L'enregistrement par préfixe natif y serait impossible sans collision.
#3. Création d'un projet
Aucun diagramme à afficher
Diagramme 3 — sequenceDiagram
| Étape | Garde réelle | Code d'échec |
|---|---|---|
| Vérification du jeton | Mode strict uniquement en authentification par jeton | 401 |
| Rôle minimum | EDITOR |
403 |
| Résolution du locataire | En-tête, puis revendication, puis paramètre | 400 si absent |
| Désaccord de locataire | Masquage d'existence | 404, jamais 403 |
| Idempotence | Clé d'idempotence honorée si un cache est configuré ; sinon acceptée mais non dédupliquée | — |
#4. Génération d'une spécification par le copilote
Aucun diagramme à afficher
Diagramme 4 — sequenceDiagram
| Invariant | Formulation exacte |
|---|---|
| Aucune écriture implicite | La proposition n'est jamais persistée sans acceptation humaine explicite |
| Budget avant appel | La pré-vérification précède l'appel facturable ; un refus empêche l'émission |
| Honnêteté du compteur | Sans facturation joignable, le reçu porte metered=false |
| Contrat de sortie | Violation ⇒ erreur typée, jamais de contenu inventé |
| Limite de débit | Vingt requêtes par minute et par utilisateur sur les chemins d'intelligence artificielle |
#5. Pipeline de rétro-ingénierie
Aucun diagramme à afficher
Diagramme 5 — sequenceDiagram
| Étape | Statut du travail | Garantie |
|---|---|---|
| Création | queued |
Réponse 201 immédiate, pipeline planifié ensuite |
| Ingestion | ingesting |
Suppression du répertoire temporaire garantie même en erreur |
| Analyse | analyzing |
Chaque fait porte son emplacement fichier:ligne |
| Inférence | inferring |
Un candidat sans preuve est refusé structurellement |
| Prêt | ready |
Résumé complet écrit |
| Échec | failed |
Message assaini, écrit dans une session neuve : jamais bloqué |
Échecs typés du clone. Identifiants déclarés mais introuvables ⇒ 502 ; binaire git absent ⇒ 502 ; code de retour non nul ⇒ 502 avec sortie d'erreur caviardée et tronquée.
#6. Exécution d'un agent en tâche Kubernetes éphémère
Aucun diagramme à afficher
Diagramme 6 — sequenceDiagram
| Paramètre du runner | Valeur réelle |
|---|---|
| Espace de noms | Espace dédié au runner, jamais celui de l'application |
| Compte de service | Droits limités à créer, lire et supprimer des tâches et lire les journaux, dans ce seul espace |
| Politique de redémarrage | Never : une exécution en échec n'est jamais rejouée silencieusement en cluster |
| Durée maximale | Une heure |
| Suppression après achèvement | Dix minutes |
| Sortie réseau | Refus par défaut, une seule destination autorisée |
| Injection du secret | Par agent latéral au chemin de coffre : le secret ne touche jamais la spécification, le service, la base ni un journal |
Actions absentes de la liste d'autorisations, donc refusées : déploiement en production, suppression récursive, sortie réseau non déclarée, écriture hors de l'espace de travail, emprunt de secret non scopé.
#7. Revue et approbation avec séparation des devoirs
Aucun diagramme à afficher
Diagramme 7 — sequenceDiagram
| Transition | Autorisée depuis | Vers |
|---|---|---|
| Soumission | draft, changes_requested |
submitted |
| Approbation | submitted |
approved — terminal |
| Demande de changements | submitted |
changes_requested |
| Rejet | submitted |
rejected — terminal |
Double application volontaire. L'interface bloque le bouton avec un motif nommé avant l'appel serveur ; le serveur reste autoritatif et renvoie un code d'erreur dédié. La même règle s'applique à la gouvernance des extensions, où une contrainte de base de données constitue un filet de sécurité supplémentaire.
#8. Déploiement gouverné avec retour arrière
Aucun diagramme à afficher
Diagramme 8 — sequenceDiagram
| Garde | Code d'erreur réel |
|---|---|
| Étape hors séquence | 409 gate/out-of-order |
| Portes non franchies avant déploiement | 409 gate/not-passed |
| Avancement manuel de l'étape de déploiement | 409 deploy/via-deploy-endpoint |
| Déploiement déjà enregistré pour l'exécution | 409 deploy/already-recorded |
| Auto-approbation | 409 deploy/approval-self |
| Exécution réelle désactivée | 501 deploy/live-not-enabled |
| Outil de construction absent | 501 exec/tool-unavailable |
#9. Lecture du catalogue de plans
Aucun diagramme à afficher
Diagramme 9 — sequenceDiagram
| Plan | Code | Prix réel en base | Plafond d'autonomie |
|---|---|---|---|
| Gratuit | gratuit |
0 $ CAD | N1 |
| Équipe | team |
49,00 $ CAD par mois, 490,00 $ annuel | N2 |
| Entreprise | enterprise |
Sur devis | N3 |
⚠️ Écart connu, préalable bloquant. Trois jeux de données de démarrage incompatibles coexistent dans le dépôt, dont un sur un schéma périmé, et le catalogue gratuit affiche encore un vocabulaire hérité d'un autre domaine. Le nettoyage du catalogue est un préalable au lancement.
#10. Vérification de la chaîne d'audit
Aucun diagramme à afficher
Diagramme 10 — sequenceDiagram
| Propriété du journal | Réalité vérifiée |
|---|---|
| Structure | Chaîne de hachage : chaque événement scelle le précédent |
| Vérification | Point d'accès dédié qui recalcule et confirme l'intégrité |
| Recherche | Par acteur, action, ressource ou texte libre |
| Conformité | Rapport Loi 25 sur période, exportable localement |
| Portée | Décisions de politique, appels d'outils, approbations, exécutions |
| Alimentation | Intergiciel d'émission d'audit sur chaque mutation métier réussie des services concernés |
#11. Plafonnement d'autonomie par le plan commercial
Aucun diagramme à afficher
Diagramme 11 — sequenceDiagram
| Plan | Plafond maximal | Quota d'appels d'outils par jour |
|---|---|---|
| Gratuit | N1 | 200 |
| Équipe | N2 | 5 000 |
| Entreprise | N3 | 1 000 000 |
| Niveau | Signification opérationnelle |
|---|---|
| N0 | L'agent propose. Rien ne s'exécute sans validation humaine explicite. |
| N1 | L'agent exécute des actions en lecture et des préparations, sans effet de bord durable. |
| N2 | L'agent exécute des actions à effet de bord dans un périmètre déclaré. |
| N3 | L'agent exécute de bout en bout dans son périmètre, sous journal et budget. |
⚠️ Écart connu. Le drapeau qui active les rôles virtuels et l'application des droits vaut
falsepar défaut et n'est activé dans aucun manifeste de déploiement. Le plafonnement est écrit, testé et prouvé en développement ; son activation par environnement est une action de la phase 0.
#12. Refus par défaut du moteur de politique
Aucun diagramme à afficher
Diagramme 12 — sequenceDiagram
| Règle par défaut autorisée | Portée |
|---|---|
| Réflexion et émission de l'agent | Toujours |
| Lecture d'outil, de spécification et de mémoire | Portée large |
| Écriture de point de reprise | Toujours |
| Écriture de fichier dans l'espace de travail | Espace de travail seulement |
| Exécution d'outil dans le runner | Runner seulement |
| Commit dans l'espace de travail | Espace de travail seulement |
| Actions d'interface | Interface seulement |
| Action volontairement absente | Conséquence |
|---|---|
| Déploiement en production | Refus journalisé |
| Suppression récursive de fichiers | Refus journalisé |
| Sortie réseau non déclarée | Refus journalisé |
| Écriture hors de l'espace de travail | Refus journalisé |
| Emprunt de secret non scopé | Refus journalisé |
Extension contrôlée. Le déploiement du runner étend la liste, de façon scopée, à l'emprunt d'un chemin de secret précis et à une seule destination réseau autorisée. Aucune extension générale n'est possible.
#13. Flux d'événements serveur rejouable
Aucun diagramme à afficher
Diagramme 13 — sequenceDiagram
| Famille d'événements | Exemples réels |
|---|---|
| Cycle de vie du run | démarré, en pause, suspendu, repris, interrompu, terminé, échoué |
| Cycle de vie de l'étape | démarrée, exécutée, bloquée |
| Gouvernance | politique vérifiée, point de reprise écrit |
| Activité profonde | appel d'outil, commande, écriture de fichier, résultat, sortie, consommation, décision — secrets masqués |
| Gouverneur de session | compte sélectionné, plafond souple atteint, rotation, reprise, mise en pause |
| Cycle de la tâche | secret emprunté, tâche provisionnée, dépôt cloné, commit créé, état enregistré, tâche démontée |
⚠️ Écart connu. Le portail d'administration affiche un flux d'activité par sondage, pas par événements serveur : le jeton n'est pas transmissible sur une connexion d'événements serveur et la passerelle tamponne le flux. C'est une amélioration planifiée, annoncée telle quelle.
#14. Ingestion documentaire jusqu'à l'objet de spécification
Aucun diagramme à afficher
Diagramme 14 — sequenceDiagram
| Type de fichier | Moteur réel | Statut |
|---|---|---|
| Markdown et texte | Décodage direct | 🟢 Réel |
| Lecteur PDF | 🟢 Réel | |
| DOCX | Lecteur de document | 🟢 Réel |
| Image | Aucun | 🟡 Dégradation honnête, document stocké, zéro candidat |
| Garantie | Formulation exacte |
|---|---|
| Aucune auto-acceptation | Seul un accept explicite crée un objet dans le magasin de spécification |
| Gate Loi 25 | Un candidat marqué comme porteur de renseignements personnels exige une justification écrite |
| Identifiant canonique | Toujours celui renvoyé par le service de spécification, jamais fabriqué |
| Atomicité | Un échec aval annule l'état local : pas de demi-état |
#15. Table de correspondance participant vers service réel
| Participant des diagrammes | Nom du service dans le dépôt | Port | Base de données |
|---|---|---|---|
| Passerelle API | api-gateway |
4100 | Aucune |
| Service utilisateurs | user-service |
4101 | app_users puis ks_user_<env> |
| Service de spécification | spec-service |
4107 | Base dédiée |
| Service SDLC | sdlc-service |
4108 | ks_sdlc_<env> |
| Service de qualité | test-quality-service |
4109 | ks_testquality_<env> |
| Fabrique de données de test | test-data-factory-service |
4110 | ks_testdatafactory_<env> |
| Configuration de plateforme | platform-config-service |
4112 | ks_platformconfig_<env> |
| Service d'audit et conformité | audit-compliance-service |
4113 | ks_audit_<env> |
| Tableau d'observabilité | observability-board-service |
4114 | ks_observability_<env> |
| Facturation et usage | billing-usage-service |
4115 | ks_billing_<env> |
| Registre d'extensions | extension-registry-service |
4116 | ks_extensionregistry_<env> |
| Graphe de dépendances | dependency-graph-service |
4117 | ks_dependencygraph_<env> |
| Service copilote | copilot-service |
4118 | ks_copilot_<env> |
| Exécution d'agents | agent-runtime-service |
4119 | ks_agentruntime_<env> |
| Rétro-ingénierie | reverse-engineering-service |
4120 | ks_reverse_<env> |
| Déploiement | deploy-service |
4121 | ks_deploy_<env> |
| Orchestration de prompts | prompt-orchestration-service |
4123 | ks_promptorch_<env> |
| Ingestion documentaire | ingestion-service |
4125 | ks_ingestion_<env> |
| Service d'apprentissage | ml-service |
4126 | ks_ml_<env> |
| Collaboration et revues | collaboration-service |
4128 | ks_collaboration_<env> |
| Artefacts | artifact-service |
4129 | ks_artifact_<env> |
| Retours utilisateurs | feedback-service |
4130 | ks_feedback_<env> |
| Registre central d'agents | agent-registry-service |
4133 | ks_agentregistry_<env> |
| Cœur agentique et personnel virtuel | agentic-core-service |
8095 | Base dédiée |
Convention de nommage des bases. Une base par service, nommée ks_<slug>_<environnement> avec un environnement parmi développement, qualification et production.
KySpectra — Plateforme agentique SDD/SDLC · par Kyrieva
Documentation : kyspectradoc.kyrieva.com ·
Dossier de lancement : Strategielancement/
Document interne de pré-lancement — version 1.0 du 2026-08-17. Les données marquées
« [Gabarit : … ] » doivent être renseignées ou revalidées avant diffusion externe.