Aller au contenu principal

ADR-0148 : Pile frontend du portail (design system, graphiques, graphes, formulaires, client API)

Contexte​

La référence d'architecture (A4.4) cite pour le portail Next.js + React + TypeScript, MUI, un client API généré depuis OpenAPI, SSE ou WebSocket, Monaco, React Hook Form + Zod, React Flow, Apache ECharts et OIDC Keycloak. Le client a décidé de ne pas utiliser MUI.

Décision​

  • Design system : Tailwind CSS + primitives radix (@radix-ui/*) + jetons webui (portal/src/app/globals.css, portal/tailwind.config.ts), composants dans portal/src/components. MUI n'est jamais ajouté (décision du client : un seul système visuel, partagé avec la console navin-manager).
  • Formulaires : React Hook Form + Zod 4 (portal/src/components/common/field-form.tsx, portal/src/lib/zod.ts) ; les formulaires de configuration sont générés depuis un JSON Schema de contracts/v1 (schemaFields, portal/src/lib/components.ts).
  • Client API : la table typée des opérations portal/src/lib/api/operations.gen.ts est générée depuis docs/api/openapi-v1.json par portal/src/lib/api/generate-operations.mjs (--check exécuté par portal/tests/openapi-client.test.ts) ; callOperation appelle une opération par son operationId. Les enveloppes de domaine de resources.ts restent des aides lisibles, vérifiées contre la spécification par portal/tests/api-conformance.test.ts.
  • Graphiques : Recharts (MIT, déjà présent et utilisé par FinOps) à la place d'Apache ECharts. Les deux sont OSI ; Recharts évite une seconde bibliothèque de graphiques et suffit aux séries temporelles et histogrammes du portail. ECharts (Apache-2.0) pourra être ajouté, épinglé, si une vue demande un type de graphique absent de Recharts.
  • Graphes : DependencyGraph dessine un graphe en couches (algorithme de Kahn, cycles listés à part) depuis GET /v1/lineage/graph, sans React Flow. React Flow (MIT) reste réservé aux vues de topologie et d'exécution s'il devient nécessaire ; le Developer Studio reste « code first » (Monaco).
  • Éditeur : Monaco (monaco-editor 0.52.2, empaqueté localement, sans CDN) pour Python, TypeScript, JSON, YAML et Rego.
  • Authentification : OIDC avec Keycloak par oidc-client-ts (portal/src/lib/auth.ts).

Conséquences​

Aucune dépendance non OSI ; aucune bibliothèque ajoutée par cette décision. Toute modification de l'OpenAPI demande de régénérer operations.gen.ts, sinon le test échoue.

Preuves​

portal/tests/openapi-client.test.ts, portal/tests/components.test.ts, portal/tests/api-conformance.test.ts, npm run typecheck, npm run lint.