Architecture Repository¶

Centraliser les standards, les patterns approuves et les décisions dans un référentiel vivant — la mémoire architecturale de l'organisation.

Pourquoi un repository d'architecture¶

Sans repository centralise, la connaissance architecturale est dispersee : des ADR dans un repo, des diagrammes dans Confluence, des standards dans la tete de l'architecte senior, des patterns dans le folklore de l'équipe. Quand cette personne part, la connaissance part avec elle.

Un architecture repository est le point de référence unique pour toutes les décisions, standards et patterns architecturaux. Il répond a trois questions fondamentales :

• Qu'est-ce qu'on utilisé ? — technologies, patterns, outils approuves
• Pourquoi on l'utilisé ? — les ADR qui documentent le raisonnement
• Comment on l'utilisé ? — les guides, templates, exemples de référence

TOGAF Architecture Repository¶

TOGAF définit un modèle de repository d'architecture structure en six composants. On n'a pas besoin de tout implémenter — mais le modèle fournit une grille de lecture utile.

flowchart TD
    REPO["Architecture Repository"] --text--> META["Architecture\nMetamodel"]
    REPO --text--> LAND["Architecture\nLandscape"]
    REPO --text--> REF["Reference\nLibrary"]
    REPO --text--> STD["Standards\nInformation Base"]
    REPO --text--> GOV["Governance Log"]
    REPO --text--> CAP["Architecture\nCapability"]

    META --- M1["Definitions, taxonomies\nrelations entre concepts"]
    LAND --- L1["Etat actuel (baseline)\nEtat cible (target)\nGap analysis"]
    REF --- R1["Patterns approuves\nTemplates, guides\nExemples de reference"]
    STD --- S1["Standards techniques\nPolicies, normes\nContraintes reglementaires"]
    GOV --- G1["Decisions (ADR)\nRevues (ATAM)\nDerogations"]
    CAP --- C1["Competences, roles\nProcessus, outils\nFormation"]

Ce qu'on garde en pratique¶

Pour une organisation de taille moyenne, les composants essentiels sont :

Architecture catalog¶

L'architecture catalog inventorie les building blocks du système : les composants réutilisables, les patterns approuves, les technologies standard.

Building blocks¶

Un building block est un composant réutilisable avec une interface définie. Exemples :

• API Gateway : Kong, avec configuration standard (rate limiting, auth JWT, CORS)
• Message Broker : RabbitMQ 3.13, avec conventions de nommage des exchanges et queues
• Base de données relationnelle : PostgreSQL 16, avec conventions de schéma et migration
• Secret Store : OpenBao, avec structure de paths par environnement et équipe
• Observabilité : stack Prometheus / Grafana / Loki, avec dashboards standard

Standards par domaine¶

## Standards techniques — Catalogue

### Langages et frameworks
| Domaine       | Standard        | Version  | Statut  | ADR        |
|---------------|-----------------|----------|---------|------------|
| API Backend   | Python/FastAPI  | 3.12/0.110| Adopt  | ADR-012    |
| Frontend      | TypeScript/React| 5.4/18   | Adopt   | ADR-015    |
| Infrastructure| Ansible         | 2.16     | Adopt   | ADR-003    |
| CI/CD         | GitHub Actions  | -        | Adopt   | ADR-008    |

### Datastores
| Usage         | Standard        | Version  | Statut  | ADR        |
|---------------|-----------------|----------|---------|------------|
| OLTP          | PostgreSQL      | 16       | Adopt   | ADR-005    |
| Cache         | Redis           | 7        | Adopt   | ADR-005    |
| Search        | OpenSearch      | 2.x      | Trial   | ADR-021    |
| Object storage| MinIO / S3      | -        | Adopt   | ADR-009    |

Patterns approuves¶

Chaque pattern approuve est documente avec :

• Nom et description : ce que le pattern résout
• Contexte d'usage : quand l'utiliser (et quand ne pas l'utiliser)
• Implémentation de référence : code exemple dans le repo
• ADR associe : la décision qui a conduit à l'approbation
• Owner : l'équipe ou la personne qui maintient le pattern

Technology Radar¶

Le Technology Radar, popularise par ThoughtWorks, est un outil de visualisation des choix technologiques. Il classe les technologies en quatre anneaux selon leur niveau d'adoption recommande.

Les quatre anneaux¶

flowchart TD
    ADOPT["ADOPT\nUtiliser en production\nsans restriction"] --text--> TRIAL["TRIAL\nUtiliser sur des\nprojets pilotes"]
    TRIAL --text--> ASSESS["ASSESS\nEvaluer,\nexperimenter en sandbox"]
    ASSESS --text--> HOLD["HOLD\nNe plus adopter\npour les nouveaux projets"]

Exemple de radar¶

Processus de mise à jour¶

Le radar est mis à jour trimestriellement. Le processus :

1. Collecte : les équipes proposent des mouvements (nouvelle technologie, changement d'anneau)
2. Évaluation : le comite d'architecture évalué les propositions avec des critères objectifs
3. Publication : le radar mis à jour est publie et communique a toutes les équipes
4. Suivi : les équipes en Trial rapportent leurs retours au trimestre suivant

Documentation vivante¶

Le repository d'architecture n'est utile que s'il est à jour. La documentation vivante combine trois approches pour minimiser l'effort de maintenance.

ADR comme journal de décisions¶

Les Architecture Décision Records (presentes au chapitre 03) sont la colonne vertebrale du repository. Chaque décision est numerotee, datee, et liee aux décisions précédentes.

Diagrammes C4 comme architecture as code¶

Les diagrammes C4 (presentes au chapitre 04) sont générés à partir de code (Structurizr DSL, PlantUML). Le code source des diagrammes vit dans le même repo que le code applicatif — il est versionne, reviewe, et mis à jour avec les changements architecturaux.

Fitness functions comme tests vivants¶

Les fitness functions (section précédente de ce chapitre) sont la forme la plus fiable de documentation : elles sont exécutées en CI et échouent quand la réalité diverge de l'intention. Un test qui passe est une documentation qui est vraie.

Outils¶

Backstage (Spotify)¶

Plateforme de developer portal qui centralise le catalogue de services, la documentation, les APIs, et les outils. Chaque service a une fiche avec ses metadata (owner, lifecycle, dependencies, SLOs).

Forces : catalogue vivant, plugin ecosystem, adoption large. Limites : coût de mise en place et de maintenance, nécessité une équipe plateforme.

Structurizr¶

Outil dédié à la modélisation C4 en code (DSL). Les diagrammes sont générés à partir d'un fichier texte versionne.

Forces : architecture as code, versionning naturel, rendu cohérent. Limites : courbe d'apprentissage du DSL, pas de collaboration temps réel.

Wiki (Confluence, Notion, GitBook)¶

Pour la documentation narrative (guides, onboarding, contexte), un wiki reste pertinent à condition d'avoir un processus de revue régulier.

Forces : accessibilite, edition collaborative, faible barriere d'entree. Limites : tendance a devenir obsolète sans processus de maintenance.

ADR tools (adr-tools, Log4brains)¶

Outils CLI pour créer, lister et gérer les ADR. Log4brains généré un site statique à partir des ADR Markdown.

Forces : intégration naturelle avec git, processus léger. Limites : pas de vue d'ensemble sans outil de visualisation additionnel.

Mettre en place un repository d'architecture¶

Démarrage minimal¶

1. Semaine 1 : créer un dossier docs/architecture/ dans le repo principal avec un fichier standards.md et le premier ADR
2. Semaine 2 : ajouter les diagrammes C4 des systèmes principaux en Structurizr DSL
3. Mois 1 : publier un premier Technology Radar (même incomplet)
4. Mois 2 : ajouter les fitness functions de base et les lier aux standards

Critères de maturité¶

Drift détection — quand la réalité diverge du repository¶

Le repository documente l'intention. Le code et l'infrastructure sont la réalité. La dérivé (drift) entre les deux est inevitable — l'objectif est de la détecter et de la corriger.

Sources de dérivé¶

Automatisation du drift détection¶

# drift/test_technology_standards.py
import tomllib
from pathlib import Path

APPROVED_LANGUAGES = {"python", "typescript"}
APPROVED_FRAMEWORKS = {"fastapi", "react", "next"}

def test_no_unapproved_language():
    """Verifie que seuls les langages approuves sont utilises."""
    found_languages = set()
    if list(Path("src").rglob("*.go")):
        found_languages.add("go")
    if list(Path("src").rglob("*.java")):
        found_languages.add("java")
    if list(Path("src").rglob("*.rb")):
        found_languages.add("ruby")

    unapproved = found_languages - APPROVED_LANGUAGES
    assert not unapproved, (
        f"Langages non approuves detectes: {unapproved}. "
        f"Soumettre une demande au Technology Radar."
    )

Processus de reconciliation¶

Quand un drift est détecté, deux options :

1. Corriger le code : le code ne respecte pas le standard, on le met en conformité
2. Mettre à jour le repository : le standard est obsolète, on le fait évoluer via un ADR

Le choix dépend du contexte. L'important est de ne jamais ignorer le drift — un drift ignore devient un standard de fait.

Chapitre suivant : Gouvernance continue — le processus de gouvernance architecturale au quotidien, du comite aux guardrails automatises.