ADR-006 - oRPC pour la couche de communication API

• Statut : Accepté
• Date : 2026-04-05

Contexte

Le projet nécessite une communication typée de bout en bout entre les frontends Next.js et le serveur Fastify. L’application est interne, sans contrainte d’exposition publique de l’API à des tiers. L’équipe veut réduire le boilerplate lié à la définition, la validation et la consommation des endpoints.

Décision

Nous utilisons oRPC pour la communication front-back, avec génération automatique d’une documentation OpenAPI via @orpc/openapi.

Alternatives considérées

• API REST classique : standard universel, facilement consommable par des tiers, mais nécessite de la duplication de types et de la validation des deux côtés
• GraphQL : flexibilité de requêtage, mais complexité de setup (schema, resolvers, codegen) disproportionnée pour ce projet
• tRPC : concurrent direct d’oRPC, bon écosystème, mais oRPC offre une meilleure intégration OpenAPI et un support natif Zod v4

Conséquences

• Type safety de bout en bout : le contrat API est défini une seule fois dans packages/api et partagé entre server et clients
• Réduction du boilerplate de validation (Zod schemas réutilisés côté serveur et client)
• Documentation OpenAPI auto-générée exposée sur /docs
• Architecture dual-client : appels directs en Server Components (sans HTTP), hooks TanStack Query en Client Components
• Couplage plus fort entre frontend et backend qu’une API REST découplée
• Moins standard qu’une API REST : intégration difficile pour des clients externes ou des outils tiers
• Dépendance à un écosystème plus jeune qu’Express+REST ou GraphQL