Concepts clés

Mockomat est construit autour d'un principe central : l'intention du domaine doit rester visible du modèle à l'exécution.

Chaque décision que tu prends — nommer une entité, définir un type de champ, établir une relation — traverse un pipeline connecté : de ton modèle de domaine, à travers la définition de l'API, jusqu'au comportement runtime live, et finalement jusqu'à un backend généré dont tu es propriétaire. Cette page explique les couches conceptuelles qui rendent cela possible.

1. Couche domaine : ce que le système signifie

La couche domaine est le fondement sémantique de ton projet. Elle définit la structure et la signification de tes données avant que tout détail d'API ou d'implémentation ne soit décidé.

Entités et tables

Une entité (ou table) représente un concept métier réel : Customer, Order, Invoice, Subscription. Chaque entité possède un nom, un ensemble d'attributs (colonnes) et éventuellement une ou plusieurs relations vers d'autres entités.

Le nommage est important. Mockomat t'encourage à utiliser le vocabulaire métier réel de ton équipe plutôt que des noms génériques. Un modèle construit avec Customer et Subscription communique l'intention bien mieux que Table1 et Table2.

Attributs

Chaque attribut possède :

• Nom — un identifiant descriptif (par ex. firstName, totalAmount, isActive)
• Type — le type de données : string, number, boolean, date, json
• Indicateur obligatoire — si le champ doit toujours avoir une valeur
• Indicateur sortable — si le champ peut être utilisé pour ordonner les résultats
• Indicateur searchable — si le champ participe aux requêtes de recherche
• Indicateur filterable — si le champ supporte les opérations de filtrage

Ces indicateurs influencent directement la manière dont la couche API expose tes données. Un champ marqué sortable: true devient disponible pour les opérations de tri dans les requêtes GraphQL. Un champ marqué filterable: true supporte les expressions de filtrage.

Relations

Les relations connectent les entités et expriment des schémas de propriété ou de référence métier :

• Un-à-un (1:1) — par ex. User → Profile
• Un-à-plusieurs (1:n) — par ex. Customer → Order[]
• Plusieurs-à-plusieurs (m:n) — par ex. Product ↔ Category

Chaque relation possède une direction et une cardinalité. La définition de la relation détermine comment le runtime résout les lookups : lorsque tu interroges un Order, les données du Customer associé sont assemblées à partir de la source de données sous-jacente en fonction de ces définitions.

Pourquoi cette couche est importante

• Réduit la dérive de nommage — tout le monde dans l'équipe utilise le même vocabulaire.
• Améliore l'alignement inter-équipes — les développeurs frontend et backend partagent un même modèle de vérité.
• Rend l'architecture révisable — l'intention du domaine est explicite, pas enfouie dans le code.
• Permet l'automatisation — la génération de code, l'exposition API et le comportement runtime dérivent tous de cette couche.

cc-01-domain-layerMissing

Modèle de couche domaine avec entités et relations.

2. Couche de définition API : comment le système est exposé

La couche API traduit l'intention du domaine en une surface de requêtes et d'opérations. Mockomat utilise une approche code-first GraphQL : tes définitions de modèle sont automatiquement traduites en un schéma GraphQL entièrement typé.

Génération dynamique du schéma

Lorsqu'un projet est activé, Mockomat génère un schéma GraphQL à la volée :

1. Charger les définitions du modèle — lire toutes les entités, attributs, relations et la configuration du projet.
2. Construire les types GraphQL — chaque entité devient un type objet GraphQL ; chaque attribut devient un champ typé.
3. Construire les points d'entrée de requête — les requêtes de liste et de détail sont générées pour chaque entité.
4. Enregistrer les resolvers — les resolvers au niveau des champs gèrent la récupération des données, le mapping et les lookups de relations.
5. Accepter les requêtes — le schéma est prêt à servir les requêtes immédiatement.

Cela signifie que tu n'écris jamais de fichiers de schéma manuellement. Le schéma est toujours synchronisé avec ton modèle.

Structure des requêtes

Chaque entité génère automatiquement deux types de requêtes :

• Requête de liste — retourne une collection paginée avec filtrage et tri optionnels.
• Requête de détail — retourne un élément unique par son identifiant.

Par exemple, si tu modélises une entité Product, les requêtes générées pourraient ressembler à :

query {
  products(offset: 0, limit: 20, filter: { ... }, sort: { ... }) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

query {
  product(id: "abc-123") {
    id
    name
    price
    description
  }
}

Filtrage

Le système de filtres supporte des expressions composables et typées :

Opérateur	Description	Types applicables
equals	Correspondance exacte	Tous les types
notEquals	Négation	Tous les types
contains	Correspondance de sous-chaîne	Chaînes de caractères
greaterThan / greaterThanOrEqual	Plage (supérieure)	Nombres, Dates
lessThan / lessThanOrEqual	Plage (inférieure)	Nombres, Dates
in	Valeur dans un ensemble	IDs, Enums
isNull / isNotNull	Vérification de null	Tous les types

Les filtres peuvent être combinés à l'aide des opérateurs logiques AND et OR, et peuvent être imbriqués pour des expressions complexes.

Tri

Les champs marqués comme sortable: true dans le modèle de domaine peuvent être utilisés dans les opérations de tri. La direction du tri est soit ascendante (ASC) soit descendante (DESC).

Pagination

Mockomat utilise la pagination basée sur l'offset :

• offset — nombre d'éléments à ignorer (par défaut : 0)
• limit — nombre d'éléments à retourner (par défaut : 20)

Ce modèle est simple et convient à la plupart des cas d'utilisation. La réponse inclut le tableau de données ainsi que les métadonnées de pagination.

cc-02-endpoint-configMissing

Vue de la définition API et de la configuration des endpoints.

3. Couche runtime : comment le comportement est validé

La couche runtime est l'endroit où tes décisions de modèle et d'API sont testées contre l'exécution réelle de requêtes. Elle répond à la question : le système se comporte-t-il comme toi l'as prévu ?

Comment fonctionne le mock runtime

Le moteur mock runtime est au cœur de la valeur de Mockomat. Il accepte les requêtes GraphQL et les traduit en opérations MongoDB à travers un pipeline en quatre étapes :

1. GraphQL Request Parser — analyse la chaîne de requête entrante en un arbre syntaxique abstrait (AST).
2. Query Planner — analyse l'AST en parallèle avec les métadonnées du modèle pour créer un plan d'exécution.
3. MongoDB Query Builder — traduit le plan d'exécution en pipeline d'agrégation MongoDB.
4. Result Assembler — restructure les résultats MongoDB pour correspondre à la structure de réponse GraphQL attendue.

Ce pipeline s'exécute à chaque requête. Comme MongoDB stocke les données dans des collections plates (dénormalisées), le runtime simule une structure relationnelle — en joignant les données liées, en résolvant les champs imbriqués et en assemblant la réponse finale comme si elle provenait d'un backend entièrement relationnel.

Prévisualisation vs consommation externe

Le même endpoint runtime sert deux audiences :

• Prévisualisation — la page Runtime intégrée à l'application où tu testes les requêtes, inspectes les formes de réponse et valides le comportement pendant la modélisation.
• Consommateurs externes — ton application frontend, ta suite de tests ou ton pipeline CI appelant le même endpoint d'API mock.

Les deux utilisent le même endpoint REST : POST /mock/{slug}/graphql. Cela signifie que ce que tu valides en prévisualisation est exactement ce que les consommateurs externes recevront.

Ce que la validation signifie en pratique

La validation runtime ne se limite pas à « la requête retourne-t-elle des données ». Elle confirme :

• Formes des champs — les types et structures retournés sont-ils ceux que tu attends ?
• Lookups de relations — les objets imbriqués se résolvent-ils correctement ?
• Comportement de pagination — offset et limit produisent-ils des tranches cohérentes ?
• Stabilité du tri — le tri sur un champ produit-il un ordre prévisible ?
• Précision des filtres — les expressions de filtrage correspondent-elles au bon sous-ensemble de données ?
• Gestion des null — les champs optionnels sont-ils correctement représentés comme null lorsqu'aucune donnée n'existe ?

cc-03-runtime-flowMissing

Flux modèle-vers-runtime avec points de contrôle de validation.

4. Sources de données et mapping de champs

Chaque attribut de ton modèle a besoin d'une source de données. Mockomat supporte plusieurs types de mapping qui déterminent d'où proviennent les valeurs des champs :

OFF_FIELD — Champs de jeux de données réels

Associe un attribut à un champ provenant d'un jeu de données réel (par ex. Open Food Facts). Cela donne à ton API mock des données réalistes et variées qui se comportent comme des données de production.

Utilise ceci lorsque tu veux :

• Des noms de produits, catégories ou mesures réalistes
• De grands volumes de données variées
• Des données qui paraissent authentiques dans les démos et les tests

FAKE — Données générées (Faker)

Associe un attribut à un générateur Faker qui produit des données synthétiques réalistes : noms, e-mails, adresses, dates, prix, et plus encore.

Utilise ceci lorsque tu veux :

• Des données personnelles (noms, e-mails, numéros de téléphone)
• Des données financières (prix, numéros de compte)
• Des données temporelles (dates, timestamps)
• Tout type de données non couvert par les jeux de données réels

CONST — Valeurs constantes

Associe un attribut à une valeur fixe identique pour chaque enregistrement.

Utilise ceci lorsque tu veux :

• Des valeurs de statut par défaut (par ex. "active")
• Des valeurs de configuration fixes
• Des données de substitution pendant la modélisation initiale

COMPUTED — Valeurs dérivées (futur)

Permettra de définir des valeurs de champs via des expressions basées sur d'autres champs. Cette fonctionnalité est prévue pour une version future.

cc-04-data-sourcesMissing

Configuration du mapping de champs avec les différents types de sources de données.

Disponibilité des sources de données

Free User

Les utilisateurs free ont accès à tous les types de mapping (OFF_FIELD, FAKE, CONST) et aux jeux de données publics. L'import de jeux de données personnalisés est disponible avec les forfaits Enterprise.

5. Isolation des projets et multi-tenancy

Chaque projet Mockomat opère dans son propre contexte isolé :

• Espace de données séparé — chaque projet possède ses propres collections MongoDB pour les données mock.
• Schéma indépendant — le schéma GraphQL est généré par projet en fonction de son modèle spécifique.
• Endpoints basés sur le slug — chaque projet obtient un chemin URL unique (/mock/{slug}/graphql).
• Scoping par tenant — tous les accès aux données sont filtrés par tenant, garantissant une isolation stricte entre les organisations.

Cela signifie que plusieurs équipes peuvent travailler sur différents projets simultanément sans aucun risque de fuite de données ou de conflit de schéma.

Isolation enterprise

Enterprise User

Les tenants enterprise bénéficient de garanties d'isolation supplémentaires : collections de données dédiées, limites de sessions configurables, rate limiting personnalisé et déploiement on-premise optionnel pour une souveraineté complète des données.

6. IA + Architecture ensemble

L'IA accélère la création. Mockomat préserve la qualité structurelle et l'explicabilité pendant que les exigences évoluent.

La plateforme est conçue pour fonctionner aux côtés des outils d'IA, pas pour les remplacer. Alors que l'IA peut générer des fragments de code rapidement, Mockomat fournit le contexte structurel que le code généré par l'IA manque souvent :

• Cohérence du schéma — ton modèle de domaine est la source unique de vérité, que tu le construises manuellement ou avec l'assistance de l'IA.
• Vérification runtime — chaque modification peut être validée à travers le pipeline de prévisualisation avant d'atteindre la production.
• Décisions traçables — les modifications du modèle sont explicites et révisables, pas enfouies dans du code généré par l'IA.

Perspective intégrateur

Developer / Integrator

Traite les artefacts générés comme des points de départ, pas comme des vérités définitives. Conserve le modèle comme source d'intention et laisse le comportement runtime confirmer la qualité. Lorsque tu intègres des workflows assistés par l'IA, utilises le modèle Mockomat comme le contrat auquel les consommateurs générés par l'IA doivent se conformer.

Perspective enterprise

Enterprise User

La valeur à long terme vient d'une architecture reproductible, pas seulement d'une sortie initiale rapide. La continuité du domaine est le point de contrôle pour l'évolution multi-équipes. Utilise les modèles Mockomat comme des artefacts de gouvernance qui survivent aux cycles de sprint individuels.