Architecture technique de SuiteCRM expliquée avec GitHub : comment le code est structuré et versionné -

Pour un acheteur professionnel qui évalue SuiteCRM comme brique centrale de son système d’information, comprendre l’architecture technique et la façon dont le code est géré dans GitHub est un véritable atout. Cela permet d’anticiper les coûts de maintenance, la capacité à intégrer le CRM dans le SI existant, et le niveau de maîtrise que pourront atteindre vos équipes internes ou votre intégrateur.

Architecture globale de SuiteCRM : une base SugarCRM enrichie et modulaire

Origines : un fork open source de SugarCRM

SuiteCRM est historiquement un fork de SugarCRM Community Edition. Concrètement, cela signifie que la base du code reprend les grands principes de SugarCRM, avec une architecture PHP classique en mode serveur, mais que la communauté SuiteCRM a continué à faire évoluer le socle de manière indépendante.

Dans GitHub, cette filiation se traduit par une structure de répertoires assez proche de ce que connaissent déjà les développeurs passés par SugarCRM, avec :

un répertoire principal contenant les modules cœur (Accounts, Contacts, Leads, Opportunities, etc.) ;
un socle commun incluant la gestion des utilisateurs, des rôles, des droits et du framework MVC ;
des répertoires de configuration, de templates et de scripts d’upgrade.

Un framework MVC adapté au monde CRM

SuiteCRM repose sur une architecture proche du MVC (Model-View-Controller), même si elle a été adaptée à l’univers des CRM. Les concepts principaux sont :

Model : les objets métiers (beans) qui représentent les entités CRM, leurs champs et leurs relations (Compte, Contact, Affaire, Ticket, etc.) ;
View : les écrans, layouts, vues de liste, vues détaillées, formulaires de création et d’édition ;
Controller : la logique applicative, les actions appelées lors des requêtes HTTP, la validation, les workflows, la sécurité.

Pour un acheteur professionnel, ce découpage a un impact direct sur la capacité de l’intégrateur à :

séparer proprement les adaptations métiers de la logique standard ;
limiter les régressions lors des montées de version ;
contrôler plus finement les performances (en optimisant modèles ou contrôleurs ciblés).

Modules standards vs modules personnalisés

L’un des points clés de l’architecture de SuiteCRM est la distinction entre :

Modules « core » : fournis nativement dans le code source principal, versionnés directement dans le dépôt GitHub officiel ;
Modules personnalisés : créés ou étendus via le mécanisme de customisation (répertoire custom/) pour rester « upgrade-safe ».

La règle structurante est simple : tout ce qui est personnalisable devrait idéalement être placé sous custom/. Cela permet, au moment d’une mise à jour, de surcharger le comportement standard sans écraser vos personnalisations métiers. Sur GitHub, ce principe se traduit par des dossiers bien distincts, ce qui facilite :

les revues de code (pull requests focalisées sur le custom) ;
la comparaison entre votre fork et le dépôt officiel ;
la résolution des conflits lors de la fusion de nouvelles versions.

Structure détaillée du code de SuiteCRM dans GitHub

Les répertoires clés à connaître

Lorsqu’un développeur ouvre le dépôt SuiteCRM sur GitHub, il retrouve plusieurs répertoires structurants. Pour un décideur IT, les connaître permet de mieux comprendre comment seront gérées les intégrations et extensions :

/modules : cœur fonctionnel, avec un dossier par module (Accounts, Contacts, AOS_Contracts, AOW_WorkFlow, etc.). Chaque module comprend ses modèles, vues, contrôleurs spécifiques, ainsi que des métadonnées de configuration.
/custom : espace réservé aux personnalisations. C’est ici que doivent être placés les champs ajoutés, les nouvelles vues, les logiques métiers spécifiques (logic hooks) et les modules spécifiques à votre entreprise.
/include : composants transverses (framework, utilitaires, gestion des templates, librairies partagées).
/themes : gestion de l’interface graphique, des CSS, des gabarits visuels. C’est un levier important pour l’UX sans toucher au code métier.
/api ou répertoires équivalents selon la version SuiteCRM : endpoints pour l’intégration avec d’autres systèmes (ERP, e‑commerce, marketing automation, BI, etc.).
/upgrade ou répertoires d’upgrade : scripts et mécanismes de migration de données et de schéma lors des montées de version.

Pour un projet CRM d’envergure, cette organisation garantit une séparation claire entre :

le socle communautaire, mis à jour par l’éditeur et la communauté ;
vos extensions internes, gérées dans vos propres branches ou dépôts Git.

Les métadonnées : le moteur de la flexibilité

SuiteCRM fait un usage intensif des métadonnées pour définir :

les champs d’un module (type, longueur, comportements) ;
les relations entre modules (one-to-many, many-to-many) ;
les layouts, vues et sous-panneaux ;
certains éléments de logique métier configurables.

Ces métadonnées sont généralement stockées dans des tableaux PHP et sont surchargeables dans le répertoire custom/. Sur GitHub, elles apparaissent comme des fichiers de configuration par module (ex. vardefs.php, layoutdefs.php). Pour un acheteur, cet aspect est stratégique :

les évolutions métiers légères peuvent se faire par configuration (level 1) plutôt que par développement (level 2) ;
le coût de maintenance est réduit, car les mises à jour standard impactent moins ces métadonnées customisées ;
le contrôle de version est plus lisible : chaque évolution métier correspond à un diff clair dans les fichiers de métadonnées.

Logic hooks, workflows et extensions

Au-delà des modules et métadonnées, SuiteCRM met à disposition plusieurs mécanismes techniques pour intégrer votre logique métier :

Logic hooks : points d’extension où vous pouvez brancher votre code PHP (avant/après enregistrement, avant suppression, lors de l’authentification, etc.). Les fichiers de hooks résident généralement dans custom/modules/<Module>/logic_hooks.php.
Workflows (AOW) : moteur de workflow configuré depuis l’interface, mais qui repose sur une structure de code et de tables dédiée dans le dépôt GitHub.
Scheduler / Cron : tâches planifiées (envoi de rapports, synchronisation de données, processus de nettoyage), paramétrées dans l’interface mais implémentées dans le code sous forme de jobs.

Sur GitHub, ces éléments sont clairement dissociés du cœur du framework, permettant à vos équipes de :

isoler les personnalisations dans des fichiers ciblés ;
gérer les tests unitaires ou fonctionnels autour de ces hooks et workflows ;
mettre en place des revues de code spécifiques sur les processus critiques (ex. scoring de leads, contrôle de conformité, synchronisation inter‑systèmes).

Gestion du code SuiteCRM dans GitHub : branches, tags et forks

Le dépôt officiel SuiteCRM

Le projet SuiteCRM est hébergé sur GitHub dans un dépôt public maintenu par l’éditeur et la communauté. On y retrouve :

la branche principale (souvent master ou main) correspondant à la version stable la plus récente ;
des branches de développement (develop ou équivalents), où sont intégrées les nouvelles fonctionnalités avant d’être fusionnées vers la stable ;
des branches ou tags par version (ex. v7.13.x, v8.x) pour faciliter le suivi des correctifs et mises à jour.

Pour un acheteur professionnel, cette structuration donne de la visibilité sur :

le rythme de sortie des versions ;
le volume de correctifs de sécurité et de stabilité ;
la transparence du code (auditabilité, conformité, contrôle des dépendances).

Fork du dépôt et branches projet

Dans un projet réel, les intégrateurs ou vos équipes internes vont rarement travailler directement sur le dépôt officiel. Ils vont généralement :

Forker le dépôt officiel SuiteCRM vers un dépôt privé ou d’entreprise ;
créer des branches spécifiques pour chaque client ou pour chaque grand lot de fonctionnalités (ex. client‑X‑integration‑ERP, custom‑reporting‑BI) ;
mettre en place une stratégie de merge réguliers depuis le dépôt officiel pour récupérer les correctifs de sécurité ou les nouvelles fonctionnalités.

Ce modèle permet de conserver un tronc commun maîtrisé tout en isolant les développements sur‑mesure. Dans le cadre d’un appel d’offres ou d’une gouvernance IT structurée, il est recommandé de demander :

la description de la stratégie Git (branches, tags, environnements) ;
les règles de merge entre la branche client et le tronc officiel ;
la politique de revue de code et de tests avant intégration dans la branche de production.

Tags et gestion des versions projet

En plus des versions officielles SuiteCRM, un intégrateur sérieux va :

poser des tags Git à chaque livraison significative (ex. client‑X‑1.0.0, client‑X‑1.1.0) ;
documenter dans un changelog (souvent en Markdown à la racine du dépôt) les modifications incluses dans chaque tag ;
aligner ces tags avec les cycles de déploiement (recette, pré‑prod, prod).

Cette granularité de versioning est essentielle pour :

revenir rapidement à une version stable en cas de problème ;
analyser les écarts entre l’état actuel et une version antérieure ;
faciliter les audits (interne, RGPD, conformité sectorielle) en traçant les évolutions du système.

Bonnes pratiques de versionning Git pour un projet SuiteCRM

Séparation des environnements : dev, recette, production

Une architecture Git bien pensée pour SuiteCRM repose souvent sur trois branches majeures :

Branch « dev » : intégration continue des nouvelles fonctionnalités, tests de développement, POC.
Branch « recette » ou « staging » : consolidation des fonctionnalités validées par l’équipe projet, tests métier, validation des performances.
Branch « production » : version déployée en environnement de production, figée sauf pour les correctifs urgents (hotfix).

Chaque livraison vers la recette ou la production donne lieu à un merge contrôlé et, idéalement, à la création d’un tag Git. Pour un acheteur, cela permet de :

imposer un cadre méthodologique à vos prestataires ;
structurer la gestion des anomalies et des demandes d’évolution ;
limiter les risques de rupture de service lors des déploiements.

Gestion des conflits entre code custom et mises à jour SuiteCRM

Un enjeu majeur des projets SuiteCRM est la conciliation entre :

la volonté de rester proche du standard pour bénéficier des mises à jour ;
la nécessité de personnaliser profondément pour répondre à vos processus métiers.

Git et GitHub facilitent ce travail via :

la visualisation des diffs entre votre branche et la branche officielle ;
la détection des conflits sur les fichiers que vous avez modifiés dans le cœur (idéalement à limiter) ;
la possibilité de faire des merge progressifs version par version (par exemple, fusionner d’abord la 7.12.x, puis la 7.13.x, plutôt que de sauter plusieurs versions d’un coup).

Pour limiter les conflits lors des mises à jour, les bonnes pratiques de développement sur SuiteCRM recommandent :

d’utiliser autant que possible les répertoires custom/ et les mécanismes de surcharge prévus par le framework ;
d’éviter de modifier directement les fichiers du noyau, sauf cas exceptionnel dûment documenté ;
de systématiser les tests automatisés (au moins sur les processus critiques) avant et après merge.

Code review, tests et qualité

GitHub offre nativement des fonctionnalités de revue de code (pull requests, commentaires, validation) qui s’appliquent parfaitement aux projets SuiteCRM. Pour un acheteur professionnel, intégrer ces aspects au cahier des charges peut significativement réduire le risque projet :

imposer des pull requests obligatoires pour tout changement sur les modules critiques ;
demander une automatisation minimale des tests (exécution de scénarios fonctionnels de base, tests de performance ciblés) ;
exiger la tenue d’une documentation technique dans le dépôt (README, guides d’installation, architecture spécifique au client).

Ces exigences ne sont pas seulement techniques : elles structurent la gouvernance de votre CRM à moyen et long terme et permettent, le cas échéant, de changer de prestataire sans perdre le contrôle du système.

Impact pour les acheteurs B2B : intégration, gouvernance et TCO

Intégration avec le SI existant via l’API et les connecteurs

Grâce à son architecture modulaire et à la présence d’APIs, SuiteCRM s’intègre avec :

les ERP (SAP, Microsoft Dynamics 365, Sage, Cegid, etc.) ;
les outils de marketing automation (Mautic, HubSpot via connecteurs, plateformes emailing) ;
les solutions e‑commerce ou portails clients ;
les systèmes BI et data warehouses.

Dans GitHub, cette intégration se concrétise via :

des modules spécifiques ou connecteurs hébergés dans des répertoires dédiés ;
des endpoints API ajoutés dans les dossiers de services ;
des scripts de synchronisation planifiés (jobs cron) versionnés comme le reste du code.

Pour votre DSI, l’architecture technique de SuiteCRM, couplée à Git, permet donc de :

auditer facilement le comportement d’un connecteur ;
revenir à une version antérieure en cas de problème de synchronisation ;
standardiser les échanges de données (JSON, REST, parfois SOAP selon les connecteurs hérités).

Maîtrise du coût total de possession (TCO)

Le choix d’une solution CRM open source comme SuiteCRM est souvent motivé par le modèle de licence, mais le coût total de possession dépend surtout :

de la qualité de l’architecture technique ;
de la discipline de versionning dans GitHub ;
de la capacité à réaliser des montées de version régulières sans surcoût excessif.

Une architecture « propre » dans le dépôt Git (séparation core / custom, branches claires, tags réguliers) permet :

de réduire le temps passé en analyse d’impact lors des mises à jour ;
de limiter les effets de bord sur les processus métiers ;
de faciliter la collaboration entre plusieurs prestataires ou entre un intégrateur et vos équipes internes.

C’est pourquoi il est pertinent de demander, dès la phase de sélection de la solution et de l’intégrateur, une présentation détaillée de :

la structure cible du dépôt Git pour votre projet ;
les conventions de nommage des branches, tags et commits ;
la politique de tests et de revue de code associée.

Ressources pour approfondir l’architecture SuiteCRM

Pour aller plus loin dans l’analyse de la solution, évaluer les versions disponibles, comprendre les modules inclus et les capacités de personnalisation, vous pouvez consulter notre dossier complet sur SuiteCRM et ses spécificités fonctionnelles et techniques, qui met en perspective les aspects d’architecture avec les besoins typiques d’acheteurs B2B.

En croisant ces informations avec la structure détaillée du dépôt GitHub et les bonnes pratiques de versionning, vous disposez alors d’une vision claire de la manière dont SuiteCRM peut s’inscrire durablement dans votre système d’information, tout en restant maîtrisable d’un point de vue technique, financier et organisationnel.