Architecture système : des décisions, une équipe et la preuve que le changement a du sens

Une définition utile en pratique

L’architecture rassemble les décisions difficiles à inverser.

On peut changer un framework, une couleur ou un endpoint. Modifier le modèle de données, les responsabilités, les paiements, les droits, le pipeline ou l’observabilité est plus difficile.

Une décision coûteuse à inverser mérite une réflexion architecturale. Une décision facilement réversible ne nécessite pas un grand comité. Cette règle protège autant du désordre sans règles que de la bureaucratie sans valeur.

Ce qu’il faut

Cinq éléments sans lesquels l’architecture reste un dessin.

Le manque concerne souvent la responsabilité, pas la technologie. On sait qu’il faut une intégration, mais personne ne précise qui gère les reprises, les doublons, les erreurs, la recette et la clôture.

L’architecture doit donc être courte, lisible et liée au flux réel. Si un client paie un audit, le système doit savoir ce que signifie ce paiement, quand lancer la mesure, comment enregistrer le rapport, notifier et afficher l’échec d’une étape.

Quand une structure légère suffit-elle et quand faut-il formaliser davantage ?

Personnes et responsabilités

Qui doit porter l’architecture et combien de personnes impliquer ?

Deux modèles fonctionnent mal : une personne impose son architecture comme une vérité, ou douze personnes donnent un avis sans assumer la décision.

La plupart des projets nécessitent un petit groupe : responsable de l’objectif métier, propriétaire technique du backend et des données, personne du frontend ou de l’UX, exploitation et sécurité, plus un spécialiste métier si nécessaire : vente, comptabilité, logistique ou assistance.

Davantage de personnes ne garantit pas une meilleure architecture. Cela peut ralentir les décisions et diluer les responsabilités. Préférez une petite équipe capable de choisir, expliquer et prouver.

Choisissez une décision et découvrez sa conséquence.

Exemple de production

Une petite fonction peut coûter cher si les frontières sont mauvaises.

Imaginons : URL, paiement, analyse, résultat enregistré, e-mail et rapport dans l’espace client. Simple sur une diapositive. En production : webhook Stripe reçu deux fois, e-mail échoué, audit lent, actualisation après paiement ou rapport créé mais non enregistré. Que fait le système ?

C’est exactement ici que commence l’architecture : dans le comportement face au monde réel, avant le choix d’une bibliothèque.

public async Task CompleteOrder(Guid orderId)
{
    var order = await db.Orders.FindAsync(orderId);
    order.Status = "Paid";

    var audit = await crawler.Run(order.TargetUrl);
    order.ReportJson = JsonSerializer.Serialize(audit);

    await email.Send(order.Email, "Raport gotowy", audit.Summary);
    await stripe.MarkProcessed(order.PaymentIntentId);
    await db.SaveChangesAsync();
}

public sealed record ConfirmAuditPayment(
    Guid OrderId,
    string PaymentIntentId,
    DateTimeOffset ConfirmedAt);

public sealed class ConfirmAuditPaymentHandler
{
    public async Task Handle(ConfirmAuditPayment command)
    {
        var order = await orders.Get(command.OrderId);

        order.MarkAsPaid(command.PaymentIntentId, command.ConfirmedAt);
        outbox.Add(new AuditRequested(order.Id, order.TargetUrl));
        outbox.Add(new CustomerNotificationRequested(order.Id));

        await unitOfWork.SaveChanges();
    }
}

SOLID sans dogme

Les principes doivent aider, pas masquer l’absence de décisions.

Single Responsibility : si changer l’e-mail casse le paiement, les responsabilités sont mêlées. Open/Closed : si chaque prestataire oblige à modifier la moitié du système, il manque un contrat. Dependency Inversion : si le domaine dépend du détail technique, ce détail gouverne le produit.

Commencez simplement par des contrats qui tiennent leurs promesses :

public interface AuditReportStore
{
    Task Save(AuditReport report, CancellationToken cancellationToken);
}

public interface AuditNotifier
{
    Task NotifyReportReady(Guid orderId, CancellationToken cancellationToken);
}

public sealed class CompleteAuditHandler
{
    public async Task Handle(AuditCompleted completed, CancellationToken ct)
    {
        await reports.Save(completed.Report, ct);
        await notifier.NotifyReportReady(completed.OrderId, ct);
    }
}

Remettez les étapes dans l’ordre. Partez de l’objectif, pas de la technologie.

Effacer les réponses

Reprendre un système existant

Avant de refactoriser, comprenez ce qui ne doit pas être cassé.

Reprendre du code n’est ni chercher un coupable ni chasser les classes laides. C’est enquêter sur les flux critiques, données sources, intégrations, décideurs et endroits où un test manquant peut coûter de l’argent au client.

Le test de caractérisation ne dit pas que l’ancien code est beau. Il dit : « Voici le comportement actuel à ne pas modifier par accident. »

[Fact]
public async Task Paid_order_requests_audit_only_once_for_duplicate_webhook()
{
    var paymentIntentId = "pi_123";

    await app.HandleStripeWebhook(paymentIntentId);
    await app.HandleStripeWebhook(paymentIntentId);

    var order = await app.FindOrderByPayment(paymentIntentId);

    Assert.Equal(OrderStatus.Paid, order.Status);
    Assert.Single(await app.Outbox.EventsOfType<AuditRequested>(order.Id));
}

Choisissez et découvrez la conséquence pour la maintenance.

ADR-004 : lancer l’audit de manière asynchrone après le paiement

Contexte :
L’audit d’un site peut durer de quelques dizaines de secondes à plusieurs minutes.
Le checkout doit se terminer rapidement.

Décision :
Après le webhook Stripe, nous enregistrons la commande comme payée
et plaçons l’événement AuditRequested dans l’outbox.

Conséquences :
Le tableau de bord affiche le statut "en attente".
Le worker peut relancer l’audit après une erreur.
Il faut surveiller la file et les tâches en échec définitif.

Preuves :
Test d’un webhook en double, test de redémarrage du worker,
log de corrélation orderId.

Questions de contrôle

Sans réponse, l’architecture n’est pas encore prête.

Conclusion

Une bonne architecture se voit surtout quand quelque chose échoue.

Si le système affiche un statut clair, répète sans danger, conserve les données, alerte, revient en arrière et laisse l’humain décider au bon endroit, l’architecture commence à rentabiliser son coût.

Elle réduit le désordre et permet de livrer sans peur ; c’est cela qui compte, pas la mode.