BrickFinder Le back qui voit

Le projet : BrickFinder

Tu connais peut-être Brickit : tu photographies ton tas de briques en vrac, et l'appli te dit ce que tu peux construire. On va bâtir une version à nous, BrickFinder, de zéro, en 3 séances. Aujourd'hui, on pose les fondations : le back-end qui « voit » les pièces.

Ce qu'on construit en tout (les 3 milestones)

Ce que TON back saura faire ce soir (Milestone 1)

Tu envoies une photo de briques à ton serveur
        ↓
Il la donne à l'IA de vision (Claude)
        ↓
Il te renvoie :  [ { "type":"brique2x4", "couleur":"rouge", "quantite":5 }, ... ]
                 (du JSON propre, vérifié, prêt pour la suite)

0. C'est quoi un « back-end » ?

Une appli web, c'est deux programmes qui se parlent.

Le front demande (une requête), le back répond (une réponse). Tout le Milestone 1 consiste à construire un back qui sait répondre à une requête du type « tiens, une photo — rends-moi l'inventaire ».

1. Les outils : terminal, Node, npm

Le terminal

Le terminal (ou « console ») est une fenêtre où tu tapes des commandes au lieu de cliquer. C'est là qu'on lance les programmes de dev.

C'est quoi Node ?

JavaScript, d'habitude, tourne dans le navigateur. Node.js, c'est ce qui permet de faire tourner du JavaScript en dehors du navigateur — sur un serveur, dans ton terminal. C'est le moteur de notre back.

Installer Node

Va sur nodejs.org, télécharge la version LTS (la stable), installe-la (Suivant → Suivant). Puis ferme et rouvre ton terminal, et vérifie :

node -v

v22.9.0

Puis vérifie npm (installé en même temps) :

npm -v

10.8.3

2. Créer le projet

Le dossier du projet

On crée un dossier pour BrickFinder et on se place dedans. Dans le terminal :

mkdir brickfinder
cd brickfinder

Ouvrir le projet dans VS Code

Si tu as VS Code, tape (toujours depuis le dossier) :

code .

Initialiser le projet (package.json)

npm init -y

Activer les modules modernes

Ouvre package.json dans VS Code et ajoute une ligne "type": "module" (ça nous permet d'écrire import au lieu de l'ancien require) :

{
  "name": "brickfinder",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "test": "echo \"no test\"" }
}

Premier fichier, premier lancement

Crée un fichier index.js (dans VS Code : clic droit → Nouveau fichier) avec :

console.log("BrickFinder démarre !")

Lance-le :

node index.js

BrickFinder démarre !

3. Ton premier serveur (Express)

C'est quoi un serveur ?

Un serveur est un programme qui attend des requêtes et y répond. Il écoute sur un port (un numéro de « porte », ici 3000). Express est la librairie qui rend tout ça simple en Node.

Installer Express

npm install express

added 69 packages in 2s

Écrire le serveur

Remplace le contenu de index.js par :

import express from "express"

const app = express()

app.get("/", (req, res) => {
  res.send("BrickFinder tourne !")
})

app.listen(3000, () => {
  console.log("Serveur prêt sur http://localhost:3000")
})

Lancer et tester

node index.js

Serveur prêt sur http://localhost:3000

Le terminal ne rend pas la main : c'est normal, le serveur tourne. Ouvre ton navigateur sur http://localhost:3000 → tu dois voir « BrickFinder tourne ! ».

Arrêter / relancer sans douleur : nodemon

Pour arrêter le serveur : Ctrl + C dans le terminal. Relancer à la main à chaque modif, c'est pénible. On installe nodemon, qui redémarre tout seul à chaque sauvegarde :

npm install -D nodemon

npm run dev

4. Renvoyer du JSON (une mini-API)

Jusqu'ici on renvoie du texte (res.send). Pour une appli, on renvoie plutôt du JSON — le format que les machines s'échangent (tu l'as vu avec les 1res années : { "cle": valeur }). Un serveur qui renvoie du JSON, on appelle ça une API.

Une route qui renvoie du JSON

Ajoute dans index.js, avant le app.listen :

app.get("/api/version", (req, res) => {
  res.json({ app: "BrickFinder", version: 1 })
})

Sauvegarde (nodemon redémarre), ouvre http://localhost:3000/api/version :

{"app":"BrickFinder","version":1}

5. Recevoir une image (upload)

Notre serveur doit recevoir une photo envoyée par le client. Un fichier ne se transmet pas comme un simple texte : il voyage dans un format spécial appelé multipart/form-data. La librairie multer s'occupe de le décoder pour nous.

Installer multer

npm install multer

Configurer multer

En haut de index.js (sous les autres import) :

import multer from "multer"

const upload = multer({ storage: multer.memoryStorage() })

L'endpoint qui reçoit la photo

Ajoute (avant app.listen) :

app.post("/api/inventaire", upload.single("photo"), (req, res) => {
  console.log("Reçu :", req.file.originalname, "-", req.file.size, "octets")
  res.json({ recu: true, taille: req.file.size })
})

Tester un POST avec un fichier

Un POST avec fichier ne se teste pas dans la barre d'adresse (qui ne fait que des GET). Deux façons :

Résultat attendu (dans la réponse et dans le terminal du serveur) :

{"recu":true,"taille":84213}

(terminal) Reçu : ma-photo.jpg - 84213 octets

6. Les secrets : la clé d'API

Pour parler à l'IA de vision, il faut une clé d'API : un mot de passe secret qui identifie (et facture) les appels. Le prof te la fournit. Règle d'or : une clé ne se met jamais en dur dans le code, ne se commit jamais, et ne part jamais vers le front.

Le fichier .env

Crée un fichier nommé .env (avec le point) à la racine du projet :

ANTHROPIC_API_KEY=sk-ant-la-cle-donnee-par-le-prof

Lire le .env dans le code (dotenv)

npm install dotenv

Tout en haut de index.js (première ligne) :

import "dotenv/config"

Ne JAMAIS partager ses secrets : .gitignore

Crée un fichier .gitignore à la racine :

node_modules
.env

Vérifie vite que la clé est bien lue (ajoute temporairement) :

console.log("Clé chargée ?", process.env.ANTHROPIC_API_KEY ? "oui" : "NON")

Clé chargée ? oui

7. Appeler l'IA de vision

Le cœur du Milestone. On va envoyer l'image reçue à Claude (une IA qui sait lire des images) et lui demander l'inventaire en JSON. On construit l'appel étape par étape.

On transforme l'endpoint du chapitre 5 en async, et on le construit en 4 étapes.

Étape 1 — encoder l'image

const imageBase64 = req.file.buffer.toString("base64")
const type = req.file.mimetype   // ex. "image/jpeg"

Étape 2 — le corps de la requête

const corps = {
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      { type: "image", source: { type: "base64", media_type: type, data: imageBase64 } },
      { type: "text", text: "Identifie les pièces de construction sur la photo. Pour chaque type, donne son nom standard en anglais facon LEGO (ex. 'Brick 2 x 4', 'Plate 1 x 2', 'Tile 1 x 1'), sa couleur standard en anglais (ex. 'Red', 'Blue', 'Yellow'), et la quantite. Reponds UNIQUEMENT en JSON : un tableau d'objets {type, couleur, quantite}. Aucun texte autour." }
    ]
  }]
}

Étape 3 — envoyer à Claude

const reponse = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  },
  body: JSON.stringify(corps)
})

Étape 4 — lire la réponse

const data = await reponse.json()
const texte = data.content[0].text
res.json({ brut: texte })

N'oublie pas de marquer la fonction async :

app.post("/api/inventaire", upload.single("photo"), async (req, res) => {
  // ... les 4 étapes ci-dessus ...
})

Teste avec une vraie photo de pièces (Thunder Client / curl). Tu obtiens quelque chose comme :

{"brut":"[\n  {\"type\":\"brique2x4\",\"couleur\":\"rouge\",\"quantite\":5},\n  {\"type\":\"plaque\",\"couleur\":\"bleu\",\"quantite\":3}\n]"}

8. Fiabiliser la sortie de l'IA

Ton endpoint marche ! Mais rappelle-toi la leçon des 1res années : l'IA se trompe et peut mal formater sa réponse. Parfois elle entoure le JSON de texte (« Voici l'inventaire : … »), ou l'enveloppe dans des ```. Si on fait confiance aveuglément, le programme plante. On fiabilise.

Étape 1 — nettoyer, puis parser

const propre = texte.replace(/```json|```/g, "").trim()

let inventaire
try {
  inventaire = JSON.parse(propre)
} catch (e) {
  return res.status(422).json({ erreur: "L'IA n'a pas renvoyé un JSON lisible" })
}

Étape 2 — valider le format (Zod)

Parser ne suffit pas : il faut vérifier que chaque pièce a bien un type, une couleur (textes) et une quantite (nombre entier positif). On ne fait jamais confiance à une donnée venue de l'extérieur — règle de sécurité.

npm install zod

En haut de index.js :

import { z } from "zod"

const Piece = z.object({
  type: z.string(),
  couleur: z.string(),
  quantite: z.number().int().positive()
})
const Inventaire = z.array(Piece)

Étape 3 — appliquer le schéma

const verif = Inventaire.safeParse(inventaire)
if (!verif.success) {
  return res.status(422).json({ erreur: "Le JSON ne respecte pas le format attendu" })
}

res.json({ inventaire: verif.data })

Bravo — ton back voit !

Récapitulons ce que ton serveur sait faire, de zéro, à la fin de ce Milestone 1 :

Mini-quiz (vérifie-toi)

Tu es bloqué ? La checklist

Glossaire

Compétences mobilisées — référentiel BTS SIO SLAM