Architecture en un coup d’œil
Un schéma couvre tout le chemin d’une requête. Chaque saut ci-dessous explique une case du schéma.
Le schéma
Section intitulée « Le schéma »Les sauts
Section intitulée « Les sauts »1. Les appelants
Section intitulée « 1. Les appelants »Trois sortes d’appelants partagent la même APIà:
| Appelant | Comment il se connecte | Ce qu’il obtient |
|---|---|---|
| Le SPA du navigateur (single-page application) | Un cookie de session, après un mot de passe, une MFA ou une connexion SSO | Toute l’interface de l’espace de travail |
| Une application | OAuth 2.1 avec PKCE. L’utilisateur consent et élit un rôle | Les droits de ce rôle, réduits par l’attribution de l’application |
| Un agent | MCP (Model Context Protocol) sous un rôle épinglé | Les outils que ce rôle peut voir |
Les clés d’API statiques et les comptes de service backend entrent aussi par
ici. Une requête sans identifiant tourne sous le rôle anonymous créé par
l’initialisation — ses droits de lecture couvrent toute la surface publique de
l’API. Un identifiant présenté mais invalide répond toujours 401 ; il ne
redescend jamais vers anonymous.
2. L’entrée — HTTP et MCP
Section intitulée « 2. L’entrée — HTTP et MCP »Le backend Crystal sert les routes. Les routes de documents ressemblent à
/Api/{domain}/{doctype} ; les routes de plateforme commencent par un segment
en majuscule (/Api, /OAuth, /Ws, /Healthcheck). La chaîne
d’authentification refuse un identifiant invalide avant tout gestionnaire.
3. Le contexte d’authentification
Section intitulée « 3. Le contexte d’authentification »Facet rassemble l’appelant dans un contexte d’authentification : le principal, l’unique rôle sous lequel il agit et, pour les applications, l’attribution. Les rôles ne fusionnent jamais. Humains, applications et agents agissent tous sous ce même modèle, si bien que le contrôle se comporte pareil sur chaque canal.
4. Les contrôleurs
Section intitulée « 4. Les contrôleurs »Les contrôleurs de lecture et d’écriture traduisent les permissions du rôle en vérifications en base de donnéesà :
- Une permission nomme une action, un chemin de doctype et un périmètre de lignes facultatif.
- Les périmètres de lignes se compilent en prédicats SQL. Une liste ne renvoie que les lignes que le rôle peut voir.
- Les étiquettes de champs masquent les champs invisibles en lecture et refusent les écritures vers eux.
- Une lecture individuelle refusée répond le même
404qu’un document manquant.
5. Le journal des mutations
Section intitulée « 5. Le journal des mutations »Une écriture acceptée ajoute une ligne à la table mutations : qui a agi, par
quel canal, sur quel document, avec quel changement, et ce qui l’a causé —
une requête, une action, un hook, un retour arrière. La table n’accepte que
les ajouts. Une tâche de rétention remplace l’historique plus vieux que la
fenêtre de rétention par une seule ligne d’instantané.
6. Les projections
Section intitulée « 6. Les projections »Un déclencheur PostgreSQL applique chaque mutation à la table projections,
qui garde l’état courantà : le contenu, le nom d’affichage, le texte de
recherche et les liens entrants. Les lectures ne relisent jamais le journal.
Elles lisent les projections, avec les prédicats de périmètre du rôle
appliqués. Chaque ligne stocke l’id de sa dernière mutationà ; cette valeur
sert d’ETag (jeton de concurrence) pour les écritures optimistes.
7. Le bus d’événements
Section intitulée « 7. Le bus d’événements »Après le commit en base, le chemin d’écriture publie des événements sur Redis Streams. Les consommateurs réagissentà : les hooks de domaine exécutent du Lua, les webhooks livrent des enveloppes signées, la réplication copie des champs entre domaines, et le pont WebSocket pousse les mises à jour en direct aux navigateurs. La livraison est au plus une fois, par conception. Les données de référence restent dans PostgreSQL.
Les réactions qui écrivent des documents repassent par le saut 2, sous l’identité de la réaction, et laissent leurs propres lignes d’audit.
Vérifiez vous-même
Section intitulée « Vérifiez vous-même »Le document OpenAPI servi décrit la surface de l’API v1. Il demande un appelant connecté, comme toute lecture du plan de contrôleà :
curl -sS -H "Authorization: Bearer $FACET_TOKEN" \ https://your-facet-host/Api/openapi.jsonVoir aussi
Section intitulée « Voir aussi »- Sécurité et gouvernance — les règles de contrôle en détail.
- Qu’est-ce que Facet — l’histoire du produit derrière ce schéma.
- Glossaire — les termes employés ci-dessus.
- Internes sur GitHubà : rbac.md, mutation.md, event.md.