Les Architecture Decision Records (ADR), introduits par Michael Nygard en 2011, servent à capturer les décisions architecturales importantes d’un projet logiciel. Souvent sous-estimés, ces documents sont pourtant cruciaux pour consigner ces choix stratégiques. Mais l’architecture logicielle n’est pas que du ressort des architectes et les ADR s’avèrent d’une grande utilité pour les développeurs. Ils ne se limitent pas à un simple outil documentaire, mais représentent un complément essentiel aux pratiques du Clean Code, du Domain-Driven Design (DDD) et de la Living Documentation. Dans cette présentation, nous présenterons le format d’ADR et, à travers des exemples concrets, nous montreront comment les ADR peuvent quotidiennement assister les développeurs.

1. Thématique
DEVELOPpeMENT
& LANGAGES
DEVOXX FRANCE 2024

2. ADR
/ Le chainon manquant
DEVOXX FRANCE 2024

3. Ça dépend !
« Quelle est la meilleure solution pour … ? »
DEVOXX FRANCE 2024

4. DEVOXX FRANCE 2024
ARCHITECTURE
DECISION
RECORD

5. SYLVAIN AURAT
REEFACT
ADR
/ Le chainon manquant
DEVOXX FRANCE 2024

6. ADR
ARCHITECTURE
DECISION
RECORD
DEVOXX FRANCE 2024

7. ADR
ARCHITECTURE
DECISION
RECORD
DEVOXX FRANCE 2024

8. ADR
IMPORTANT
ARCHITECTURE
DECISION
RECORD
DEVOXX FRANCE 2024

9. Michael Nygard
DOCUMENTING ARCHITECTURE DECISIONS
(2011)
DEVOXX FRANCE 2024

10. DEVOXX FRANCE 2024

11. DEVOXX FRANCE 2024
DEFENSIF

12. OFFENSIF
DEVOXX FRANCE 2024

13. OFFENSIF
DEVOXX FRANCE 2024
DEFENSIF

14. DEVOXX FRANCE 2024

15. DEVOXX FRANCE 2024

16. Cahier des charges fonctionnel
Spécifications techniques détaillées
Guidelines de développement
Manuel d'installation
Documentation d'API
Guide de contribution
Changelog
Diagrammes d'architecture
Documentation des dépendances
Plan de Test
Rapports de Bugs / Incidents
Release note
Documentation du Code (Javadoc, ...)
Rapport de Sécurité
Plan de gestion de configuration
Guide de déploiement
Manuel utilisateur
Product backlog
User stories
Definition of done
Burndown charts
Retrospective outcomes
Roadmap produit
Diagramme de séquence
Architecture decision record
Rosetta Stone
…

17. ADR
/ Le chainon manquant
DEVOXX FRANCE 2024

18. DEVOXX FRANCE 2024

19. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

20. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

21. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

22. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

23. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

24. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
• Proposé
• Accepté
• Remplacé
DEVOXX FRANCE 2024

25. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
• Proposé
• Accepté
• Remplacé
DEVOXX FRANCE 2024

26. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
• Proposé
• Accepté
• Remplacé
DEVOXX FRANCE 2024

27. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

28. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

29. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

30. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• JUSTIFICATION
• AL
TERNATIVES
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

31. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• JUSTIFICATION
• AL
TERNATIVES
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

32. • ID
• DATE
• TITRE
• STATUT
• CONTEXTE
• DECISION
• JUSTIFICATION
• AL
TERNATIVES
• CONSEQUENCES
ADR
FORMAT
DEVOXX FRANCE 2024

33. DEVOXX FRANCE 2024
…

34. ADR
CAS CONCRET
Client
e-Mail
S2
Con.
e-Mail S3 Sn
µBot
1
…
/ CONTEXTE
Con.
mobile
Mobile
Client
Chat
Con.
chat
µBot
2
…
DEVOXX FRANCE 2024
Plateforme

35. ADR
CAS CONCRET
Client
e-Mail
S2
Con.
e-Mail S3 Sn
µBot
1
…
/ CONTEXTE
Con.
mobile
Mobile
Client
Chat
Con.
chat
µBot
2
…
DEVOXX FRANCE 2024
Plateforme

36. ADR
TITRE
Délestage des services conversationnels par stockage temporaire des pièces
jointes.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

37. ADR
ST
A
TUT
#proposed
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

38. ADR
ID
42
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

39. ADR
DA
TE
N/A
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

40. ADR
CONTEXTE
Notre système de chatbot, dont le traitement des messages s’effectue à
travers une chaîne de services, nécessite une solution efficace pour le transit
des pièces jointes.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

41. ADR
CONTEXTE
Ces pièces jointes transitent actuellement depuis le service en entrée
jusqu’au service de sortie et surchargent l’ensemble des services de la
plateforme dans lesquels elles ne sont d’aucune utilité.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

42. ADR
CONTEXTE
Les services sont déployés dans un environnement Kubernetes pour lequel
nous ne disposons pas de solution de stockage disque pour l’instant. Obtenir
un stockage disque nous coûterait de l’argent et nous ferait attendre
plusieurs semaines.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

43. ADR
CONTEXTE
Nous n’avons pour l’instant que quelques utilisateurs actifs (250 environ) avec
peu de requêtes (3000 / mois) et les pièces jointes sont assez petites
(quelques ko) lorsqu’il y en a.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

44. ADR
CONTEXTE
Nous avons besoin d’une solution rapide et facile à mettre en place et
facilement évolutive car (…).
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

45. ADR
CONTEXTE
…
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

46. ADR
DECISION
Nous avons décidé de développer un service gRPC de délestage des pièces
jointes avec un stockage in-memory.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

47. ADR
CAS CONCRET
Client
e-Mail
S2
Con.
e-Mail S3 Sn
µBot
1
…
Spj
SET GET
/ CONTEXTE
Plateforme

48. ADR
JUSTIFICA
TIONS
Perte potentielle des pièces jointes : Les pièces jointes sont stockées in-
memory pendant moins d’une seconde. L’arrêt d’un service durant cette
seconde est peu probable. Il sera possible d’ajouter des services en
redondances si nécessaire. Dans le mode conversationnel, la perte éventuelle
des pièces jointes n’est pas problématique, l’utilisateur peut – au pire -
constater l’erreur et renvoyer les pièces jointes.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

49. ADR
JUSTIFICA
TIONS
Taille mémoire : Le nombre d’utilisateurs, de requêtes, la faible taille des
pièces jointes ainsi que le délai de stockage limité à quelques secondes nous
permet pour l’instant d’envisager un stockage in-memory.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

50. ADR
JUSTIFICA
TIONS
Budget / délais : Un service gRPC avec stockage in-memory est rapide et facile
à mettre en place dans notre environnement Kubernetes ; il ne nécessite
aucune demande infra supplémentaire qui nécessiterait des justifications
budgétaires et des délais de mise en œuvre prolongés.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

51. ADR
JUSTIFICA
TIONS
Performance : L'utilisation de gRPC au lieu de REST nous permet de bénéficier
de communications inter-services performantes pour les données binaires.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

52. ADR
JUSTIFICA
TIONS
…
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

53. ADR
AL
TERNA
TIVES
Conserver le transfert inter-services : Écarté en raison du nombre de
sérialisation/désérialisation et du risque de surcharge des services (en
particulier les agents conversationnels « vendors »).
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

54. ADR
AL
TERNA
TIVES
Utilisation de solutions de stockage disque / nouvelle base de données
persistante : Non retenue pour l’instant à cause des délais de mise en œuvre
/ coûts liés aux équipes infra.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

55. ADR
AL
TERNA
TIVES
Utilisation de notre base de données PostgreSQL existante : Non retenue afin
de ne pas surcharger celle-ci.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

56. ADR
AL
TERNA
TIVES
Utilisation de REST : Non retenue pour des raisons de performances.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

57. ADR
AL
TERNA
TIVES
…
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

58. ADR
CONSEQUENCES
Nous allons pouvoir commencer immédiatement le développement du
service et l’intégrer au sein de plateforme en re-routant les pièces-jointes.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

59. ADR
CONSEQUENCES
Adaptation de l'équipe: l'équipe, plus habituée au développement d’API REST
devra se former sur gRPC.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

60. ADR
CONSEQUENCES
Envisager la perte potentielle des pièces jointes.
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

61. ADR
CONSEQUENCES
…
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD

62. ADR
# ADR 0042
**Délestage des services conversationnels par stockage temporaire des pièces jointes.**
#proposé
## CONTEXTE
- Notre système de chatbot, dont le traitement des messages s’effectue à travers une chaîne de services, nécessite une solution efficace pour le transit des pièces jointes.
- Ces pièces jointes transitent actuellement depuis le service en entrée jusqu’au service de sortie et surchargent l’ensemble des services de la plateforme dans lesquels elles ne sont d’aucune utilité.
- Les services sont déployés dans un environnement Kubernetes pour lequel nous ne disposons pas de solution de stockage disque pour l’instant. Obtenir un stockage disque nous coûterait de l’argent et nous ferait attendre plusieurs
semaines.
- Nous n’avons pour l’instant que quelques utilisateurs actifs (250 environ) avec peu de requêtes (3000 / mois) et les pièces jointes sont assez petites (quelques ko) lorsqu’il y en a.
- Nous avons besoin d’une solution rapide et facile à mettre en place et facilement évolutive car (…).
## DECISION
Nous avons décidé de développer un service gRPC de délestage des pièces jointes avec un stockage in-memory.
## JUSTIFICATIONS
- **Perte potentielle des pièces jointes :** Les pièces jointes sont stockées in-memory pendant moins d’une seconde. L’arrêt d’un service durant cette seconde est peu probable. Il sera possible d’ajouter des services en redondances si
nécessaire. Dans le mode conversationnel, la perte éventuelle des pièces jointes n’est pas problématique, l’utilisateur peut – au pire - constater l’erreur et renvoyer les pièces jointes.
- **Taille mémoire :** Le nombre d’utilisateurs, de requêtes, la faible taille des pièces jointes ainsi que le délai de stockage limité à quelques secondes nous permet pour l’instant d’envisager
un stockage in-memory.
- **Budget / délais :** Un service gRPC avec stockage in-memory est rapide et facile à mettre en place dans notre environnement Kubernetes ; il ne nécessite aucune demande infra supplémentaire qui nécessiterait des justifications
budgétaires et des délais de mise en œuvre prolongés.
- **Performance :** L'utilisation de gRPC au lieu de REST nous permet de bénéficier de communications inter-services performantes pour les données binaires.
## ALTERNATIVES
- **Conserver le transfert inter-services :** Écarté en raison du nombre de sérialisation/désérialisation et du risque de surcharge des services (en particulier les agents conversationnels « vendors »).
- **Utilisation de REST :** Non retenue pour des raisons de performances.
- **Utilisation de solutions de stockage disque / nouvelle base de données persistante :** Non retenue pour l’instant à cause des délais de mise en œuvre / coûts liés aux équipes infra.
- **Utilisation de notre base de données PostgreSQL existante :** Non retenue afin de ne pas surcharger celle-ci.
## CONSEQUENCES
- **Développement du service :** Nous allons pouvoir commencer immédiatement le développement du service et l’intégrer au sein de plateforme en re-routant les pièces-jointes
- **Adaptation de l'équipe :** L'équipe, plus habituée au développement d’API REST devra se former sur gRPC.
- **Risque de perte des pièces jointes.**
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD
ADR0042.md

63. - Notre système de chatbot, dont le traitement des messages s’effectue à travers une chaîne de services, nécessite une solution efficace pour le transit des pièces jointes.
- Ces pièces jointes transitent actuellement depuis le service en entrée jusqu’au service de sortie et surchargent l’ensemble des services de la plateforme dans lesquels elles ne sont d’aucune utilité.
- Les services sont déployés dans un environnement Kubernetes pour lequel nous ne disposons pas de solution de stockage disque pour l’instant. Obtenir un stockage disque nous coûterait de l’argent et nous ferait attendre plusieurs
semaines.
- Nous n’avons pour l’instant que quelques utilisateurs actifs (250 environ) avec peu de requêtes (3000 / mois) et les pièces jointes sont assez petites (quelques ko) lorsqu’il y en a.
- Nous avons besoin d’une solution rapide et facile à mettre en place et facilement évolutive car (…).
## DECISION
Nous avons décidé de développer un service gRPC de délestage des pièces jointes avec un stockage in-memory.
## JUSTIFICATIONS
- **Perte potentielle des pièces jointes :** Les pièces jointes sont stockées in-memory pendant moins d’une seconde. L’arrêt d’un service durant cette seconde est peu probable. Il sera possible d’ajouter des services en redondances si
nécessaire. Dans le mode conversationnel, la perte éventuelle des pièces jointes n’est pas problématique, l’utilisateur peut – au pire - constater l’erreur et renvoyer les pièces jointes.
- **Taille mémoire :** Le nombre d’utilisateurs, de requêtes, la faible taille des pièces jointes ainsi que le délai de stockage limité à quelques secondes nous permet pour l’instant d’envisager
un stockage in-memory.
- **Budget / délais :** Un service gRPC avec stockage in-memory est rapide et facile à mettre en place dans notre environnement Kubernetes ; il ne nécessite aucune demande infra supplémentaire qui nécessiterait des justifications
budgétaires et des délais de mise en œuvre prolongés.
- **Performance :** L'utilisation de gRPC au lieu de REST nous permet de bénéficier de communications inter-services performantes pour les données binaires.
## ALTERNATIVES
- **Conserver le transfert inter-services :** Écarté en raison du nombre de sérialisation/désérialisation et du risque de surcharge des services (en particulier les agents conversationnels « vendors »).
- **Utilisation de REST :** Non retenue pour des raisons de performances.
- **Utilisation de solutions de stockage disque / nouvelle base de données persistante :** Non retenue pour l’instant à cause des délais de mise en œuvre / coûts liés aux équipes infra.
- **Utilisation de notre base de données PostgreSQL existante :** Non retenue afin de ne pas surcharger celle-ci.
## CONSEQUENCES
- **Développement du service :** Nous allons pouvoir commencer immédiatement le développement du service et l’intégrer au sein de plateforme en re-routant les pièces-jointes
- **Adaptation de l'équipe :** L'équipe, plus habituée au développement d’API REST devra se former sur gRPC.
- **Risque de perte des pièces jointes.**
ADR
DEVOXX FRANCE 2024
CAS CONCRET
/ ARCHITECTURE DECISION RECORD
ADR0042.md
# ADR 0042
**Délestage des services conversationnels par stockage temporaire des pièces jointes.**
#accepté le vendredi 19 avril 2024
## CONTEXTE

64. ADR
/ Le chainon manquant
DEVOXX FRANCE 2024

65. DEVOXX FRANCE 2024
THANKS
FOR WATCHING

66. DEVOXX FRANCE 2024
ADR
REFERENCES
& SLIDES
/
Le
chainon
manquant