Retour au blog
ArchitectureMarch 28, 202612 min de lecture

Une base de code. 13 plateformes. Zéro compromis.

Comment trois fichiers deviennent un formulaire web, une commande CLI, un outil MCP, un écran natif et une tâche automatisée, en même temps.

definition.ts → web · cli · mcp · native · cron · 10 de plus

5 802 fichiers TypeScript. ~2,1 millions de lignes. Zéro `any`. Zéro erreur de type à l'exécution. Un seul pattern. Répété 374 fois.

C'est la base de code derrière unbottled.ai, et le framework qui la fait tourner, next-vibe. La même architecture fait tourner une appli web, une appli mobile, une CLI, une interface d'agent IA, un serveur MCP, un système cron, un bus d'événements websocket et un moteur de flux de données en temps réel.

Ce pattern s'appelle la Surface Unifiée. Voici ce que c'est, comment ça marche, et pourquoi, une fois que vous l'aurez vu, vous aurez du mal à revenir en arrière.

Une fonctionnalité, c'est un dossier

Dans next-vibe, chaque fonctionnalité vit dans un dossier. Trois fichiers sont obligatoires. Tout le reste est facultatif.

~/src/explain-to-my-boss/
explain-to-my-boss/
  definition.ts    ← ce qu'elle fait
  repository.ts    ← comment elle le fait
  route.ts         ← la fait exister partout
  widget.tsx       ← UI React sur mesure (facultatif)
  widget.cli.tsx   ← UI terminal sur mesure (facultatif)

C'est tout. Un dossier. Trois fichiers obligatoires. Et à partir de ces trois fichiers, la fonctionnalité existe sur jusqu'à 13 plateformes en même temps.

13 plateformes à partir de 3 fichiers

Quand vous ajoutez une fonctionnalité à next-vibe, elle ne devient pas seulement un endpoint d'API. Elle devient tout à la fois.

API web

Endpoint REST, validé automatiquement, entièrement typé

UI React

Générée automatiquement à partir de la définition, sans écrire de JSX

CLI

Chaque endpoint est une commande avec des flags générés automatiquement

Schéma d'outil IA

Schéma de function calling généré automatiquement

Serveur MCP

Se branche sur Claude Desktop, Cursor ou n'importe quel client MCP

React Native

Écrans iOS et Android à partir de la même définition

Tâche cron

Planifiez n'importe quel endpoint pour qu'il tourne à intervalles réguliers

Événements WebSocket

Envoie des mises à jour aux clients connectés une fois le travail fini

Bureau Electron

Appli de bureau native via les mêmes contrats d'endpoint

Panneau d'admin

UI d'administration générée automatiquement, sans code sur mesure

Widget VibeFrame

Widget iframe intégrable sur n'importe quel site

Skill d'agent

Appelable par des agents IA comme compétence structurée

Nœud Vibe Sense

Nœud dans un graphe de flux de données en temps réel, même endpoint

Supprimez le dossier. La fonctionnalité disparaît de partout à la fois.

L'accès aux plateformes tient dans un tableau d'enums

Vous n'écrivez pas de couche de permissions séparée pour chaque plateforme. L'accès aux plateformes est déclaré dans la définition elle-même : un seul tableau d'enums que chaque plateforme lit nativement à l'exécution.

definition.ts
// Ce seul tableau décide où la fonctionnalité apparaît
allowedRoles: [
  CLI_OFF,         // bloque la CLI
  MCP_VISIBLE,     // l'ajoute à la liste d'outils MCP
  REMOTE_SKILL,    // l'ajoute au fichier de skills de l'agent
  PRODUCTION_OFF,  // la désactive en prod
]

Même définition. Même endroit. Pas de fichiers de config à synchroniser. Pas de système de permissions séparé par plateforme.

Il n'y a pas une API pour les humains et une API pour l'IA. Il y a juste l'outil.

La démo en direct : Thea construit un endpoint

Plutôt que d'expliquer le pattern dans l'abstrait, laissez-moi vous montrer à quoi il ressemble en pratique.

Qui est Thea ?

Thea est l'IA d'administration de cette plateforme. Elle tourne en production 24 h/24, 7 j/7, et passe par exactement les mêmes contrats d'endpoint que n'importe quel utilisateur : même validation, mêmes permissions, aucune porte dérobée. Et elle peut déléguer du travail à une machine locale.

J'ai demandé à Thea de construire un nouvel endpoint, explain-to-my-boss, avec Claude Code qui tourne sur mon PC. Vous lui donnez une décision technique. Il vous rend une justification non technique que votre manager croira vraiment. Tous les développeurs en ont eu besoin un jour.

1
VousDemandez à Thea

Tapez la tâche dans le chat : deux champs de saisie, une réponse générée par l'IA, toutes les plateformes, MCP_VISIBLE, widgets React et CLI sur mesure.

2
TheaCrée une tâche

Thea raisonne à voix haute, crée une tâche avec targetInstance="hermes" (votre machine locale), puis se met en veille.

3
Hermes en localRécupère la tâche

L'instance locale se synchronise toutes les 60 secondes. Aucun port ouvert. C'est votre machine qui initie la connexion.

4
Claude CodeConstruit l'endpoint

Session interactive. Lit d'abord les patterns existants, crée cinq fichiers, lance vibe check. Zéro erreur.

5
Claude CodeSignale la fin

Appelle complete-task avec l'id de la tâche. Statut : terminé. Résumé joint.

6
TheaSe réveille

wakeUp se déclenche. Thea reprend la conversation en cours via websocket, diffuse sa réponse en streaming, la synthèse vocale parle.

7
RésultatExiste partout

Formulaire web. Commande CLI. Outil MCP. Écran React Native. Tout est en ligne. À partir de cinq fichiers.

La preuve

Dès que Claude Code a appelé complete-task, trois choses existaient qui n'existaient pas cinq minutes plus tôt :

Un widget React sur mesure : titre spectaculaire, dégradé animé sur la sortie de l'IA, un faux score d'alignement corporate.
Un widget CLI : bannière ASCII, spinner pendant que l'IA réfléchit, la justification affichée ligne par ligne en vert.
Un outil MCP, explain-to-my-boss_POST, parce que MCP_VISIBLE figurait dans la définition. Claude Desktop peut désormais expliquer vos décisions à votre patron à votre place.

Une définition. Cinq fichiers en tout. Trois UI complètement différentes. Le contrat de l'endpoint n'a pas changé. Seule la couche de présentation a changé.

Sous le capot

definition.ts : le contrat vivant

La définition n'est pas un générateur de code. C'est un contrat vivant que chaque plateforme lit nativement à l'exécution. Modifiez-la : tout se met à jour. Supprimez le dossier : rien ne casse en aval. Aucun code généré à nettoyer.

definition.ts
const { POST } = createEndpoint({
  scopedTranslation,
  aliases: [EXPLAIN_TO_MY_BOSS_ALIAS],
  method: Methods.POST,
  path: ["explain", "to-my-boss"],
  title: "post.title",
  description: "post.description",
  icon: "sparkles",
  category: "endpointCategories.ai",
  allowedRoles: [UserRole.CUSTOMER, UserRole.ADMIN] as const,
  fields: objectField(scopedTranslation, {
    type: WidgetType.CONTAINER,
    usage: { request: "data", response: true },
    children: {
      decision: requestField(scopedTranslation, {
        type: WidgetType.FORM_FIELD,
        fieldType: FieldDataType.TEXTAREA,
        label: "post.fields.decision.label",
        description: "post.fields.decision.description",
        schema: z.string().min(1).max(2000),
        columns: 12,
      }),
      justification: responseField(scopedTranslation, {
        type: WidgetType.TEXT,
        content: "post.fields.justification.content",
        schema: z.string(),
      }),
    },
  }),
  errorTypes: { /* ... all 9 required error types ... */ },
  successTypes: { title: "post.success.title", description: "post.success.description" },
  examples: { requests: { default: { decision: "Migrate to Bun" } }, responses: { default: { justification: "..." } } },
});

repository.ts : jamais de throw

Les fonctions du repository ne lèvent jamais d'exception. Les erreurs se propagent comme des données : typées, explicites, et gérables par l'appelant. L'IA peut raisonner sur les cas d'échec. Pas d'exception surprise.

repository.ts
// Renvoie ResponseType<T>, ne lève jamais d'exception
export async function explainToMyBoss(
  data: { decision: string },
  logger: Logger,
): Promise<ResponseType<{ justification: string }>> {
  const result = await ai.generateText({
    prompt: buildPrompt(data.decision),
  });
  if (!result.text) {
    return fail({ message: "AI returned empty response", errorType: EndpointErrorTypes.SERVER_ERROR });
  }
  return success({ justification: result.text });
}

route.ts : tout le pont

route.ts relie la définition au handler. endpointsHandler s'occupe de la validation, de l'authentification, des logs et de l'exposition sur les 13 plateformes. La logique métier proprement dite tient en une ligne.

route.ts
import { endpointsHandler } from "next-vibe/core/route/multi";
import { Methods } from "next-vibe/core/definition/enums";
import definitions from "./definition";
import { explainToMyBoss } from "./repository";

export const { POST, tools } = endpointsHandler({
  endpoint: definitions,
  [Methods.POST]: { handler: ({ data, logger }) => explainToMyBoss(data, logger) },
});

Les chiffres

374 endpoints

Un seul pattern, appliqué 374 fois

Zéro `any`

Imposé à la compilation, pas par convention

Trois langues

Vérifiées à la compilation : t("typo.here") est une erreur de compilation

Ce n'est pas une convention. C'est imposé à la compilation.

Un seul pattern. Répété 374 fois.

À suivre

Vibe Sense : le pipeline, c'est la plateforme

Chaque nœud d'un graphe Vibe Sense est un endpoint next-vibe ordinaire. Le même createEndpoint(). La même structure en 3 fichiers. Un indicateur EMA est un endpoint. Un évaluateur de seuil est un endpoint. Et parce que c'est un endpoint, vous pouvez l'appeler depuis la CLI, depuis l'IA, depuis n'importe où.

vibe analytics/indicators/ema --source=leads_created --period=7

Le pipeline, c'est la plateforme.

Vibe Sense, ce n'est que... davantage d'endpoints. La même chose, appliquée aux séries temporelles. Funnels de leads. Économie des crédits. Croissance des utilisateurs. Votre plateforme qui se surveille elle-même.

Définissez-le une fois. Il existe partout.

WordPress a donné à tout le monde le pouvoir de publier. next-vibe vous donne le pouvoir de construire des plateformes qui fonctionnent sur le web, le mobile, la CLI, les agents IA et l'automatisation, qui se surveillent elles-mêmes, raisonnent sur leurs propres données et agissent sur ce qu'elles trouvent.

Retour au blog