🏗️ Architecture de MyClub - Guide pour les développeurs

Créé par Jean-Emmanuel Bissey le 10/02/2026 Publié

Bienvenue dans le projet MyClub ! Ce document présente l'architecture globale de l'application pour faciliter votre prise en main et vos contributions au projet.

Vue d'ensemble

MyClub est une application web modulaire construite avec une architecture MVC (Modèle-Vue-Contrôleur) moderne. Le projet adopte une organisation claire qui sépare les responsabilités et facilite la maintenance et l'évolution du code.

Stack technique

  • Backend : PHP avec le micro-framework Flight
  • Base de données : SQLite avec système de migrations
  • Templates : Latte (moteur de templates moderne et sécurisé)
  • Frontend : Bootstrap + JavaScript vanilla (pas de framework lourd)
  • Architecture : Modulaire avec séparation stricte des préoccupations

Architecture des données

Stockage et accès aux données

Toutes les données de l'application sont stockées dans une base de données SQLite située dans WebSite/data/MyClub.sqlite. L'accès aux données se fait exclusivement via des helpers (classes d'aide) qui encapsulent la logique d'accès à la base.

Emplacement : WebSite/app/models/

Vous y trouverez notamment :

  • Database.php : Gestion de la connexion à la base de données
  • DataHelper.php : Classe de base pour tous les helpers
  • *DataHelper.php : Helpers spécialisés (PersonDataHelper, EventDataHelper, ArticleDataHelper, etc.)

Exemple de helper

// Utilisation d'un helper pour récupérer des données
$personHelper = new PersonDataHelper();
$person = $personHelper->getById($personId);

Migrations de base de données

Principe fondamental : Chaque évolution du modèle de données nécessite la création d'un nouveau migrateur.

Emplacement : WebSite/app/models/database/migrators/

Les migrateurs suivent une nomenclature stricte :

  • V1ToV2Migrator.php : Migration de la version 1 vers la version 2
  • V2ToV3Migrator.php : Migration de la version 2 vers la version 3
  • etc.

Cette approche garantit que :

  • Les bases de données existantes peuvent être mises à jour automatiquement
  • L'historique des changements est traçable
  • Les migrations peuvent être testées et validées

Architecture des vues

Organisation modulaire

Les vues utilisent le moteur de templates Latte combiné avec Bootstrap pour le design et JavaScript vanilla pour l'interactivité. Chaque module de l'application possède son propre dossier de vues.

Emplacement : WebSite/app/modules/[NomDuModule]/views/

Exemples de modules et leurs vues

WebSite/app/modules/
├── Article/
│   └── views/
│       ├── article_edit.latte
│       ├── article_show.latte
│       └── articles_index.latte
├── Event/
│   └── views/
│       ├── event_detail.latte
│       ├── guest.latte
│       └── weekEvents.latte
├── User/
│   └── views/
│       ├── user_account.latte
│       ├── user_preferences.latte
│       └── users_directory.latte
└── Kanban/
    └── views/
        └── kanban.latte

Structure d'un module

Chaque module est autonome et contient :

  • Controllers : Logique métier et orchestration
  • Views : Templates Latte pour le rendu HTML
  • JS : Scripts JavaScript spécifiques au module
  • Services : Logique métier complexe (optionnel)

Routage avec Flight

Configuration centralisée

Toutes les routes de l'application (HTTP et API) sont définies de manière centralisée dans le répertoire de configuration.

Emplacement : WebSite/app/config/

Organisation des routes

WebSite/app/config/
├── Routes.php          # Point d'entrée principal du routage
└── routes/
    ├── Article.php     # Routes du module Article
    ├── Event.php       # Routes du module Event
    ├── User.php        # Routes du module User
    ├── ArticleApi.php  # API du module Article
    ├── EventApi.php    # API du module Event
    └── ...

Exemple de définition de routes

// Fichier routes/Article.php
Flight::route('GET /articles', [ArticleController::class, 'index']);
Flight::route('GET /article/@id', [ArticleController::class, 'show']);
Flight::route('POST /article/create', [ArticleController::class, 'create']);

// Fichier routes/ArticleApi.php (API REST)
Flight::route('GET /api/articles', [ArticleApi::class, 'getAll']);
Flight::route('POST /api/article', [ArticleApi::class, 'create']);
Flight::route('PUT /api/article/@id', [ArticleApi::class, 'update']);

Séparation Routes HTTP / API

  • Routes HTTP : Renvoient des vues HTML (templates Latte)
  • Routes API : Renvoient du JSON pour les interactions AJAX et l'interopérabilité

Structure des modules principaux

Module Article

Gestion des articles, médias, sondages et commandes :

  • Publication et édition d'articles
  • Upload et gestion de médias
  • Création de sondages et commandes

Module Event

Gestion complète des événements :

  • Création et planification d'événements
  • Gestion des participants et invités
  • Système de besoins et fournitures
  • Intégration calendrier (iCal, Google Calendar, Outlook)

Module User

Gestion des utilisateurs :

  • Authentification et comptes
  • Profils et préférences
  • Dashboard personnel
  • Annuaire et connexions

Module Games

Mini-jeux intégrés :

  • Karaoke : Karaoké avec synchronisation paroles
  • Leapfrog : Jeu de saute-mouton
  • Solfège : Apprentissage du solfège

Module Kanban

Gestion de projets avec tableau Kanban :

  • Projets et colonnes personnalisables
  • Cartes et types de cartes
  • Drag & drop

Architecture API

Les APIs suivent une architecture REST et héritent de AbstractApi.php. Elles retournent systématiquement des objets ApiResponse pour une cohérence des réponses.

Emplacement : WebSite/app/apis/

Principales APIs disponibles

  • ArticleApi : Gestion des articles
  • EventApi : Gestion des événements
  • GroupApi : Gestion des groupes
  • MediaApi : Gestion des médias
  • MessageApi : Messagerie
  • NotificationApi : Notifications

Services et logique métier

Les services encapsulent la logique métier complexe et peuvent être partagés entre contrôleurs.

Emplacement : WebSite/app/services/

Exemples :

  • AuthenticationService : Gestion de l'authentification
  • AuthorizationService : Gestion des autorisations
  • EmailService : Envoi d'emails
  • EventService : Logique métier des événements

Helpers et utilitaires

Des classes utilitaires facilitent les tâches courantes.

Emplacement : WebSite/app/helpers/

Exemples :

  • Application.php : Informations sur l'application
  • ConnectedUser.php : Utilisateur connecté
  • File.php : Manipulation de fichiers
  • MyClubDateTime.php : Gestion des dates
  • NotificationSender.php : Envoi de notifications

Gestion des erreurs et exceptions

Des exceptions personnalisées permettent une gestion fine des erreurs.

Emplacement : WebSite/app/exceptions/

  • AuthenticationException
  • DatabaseException
  • UnauthorizedAccessException
  • etc.

Tests

Le projet dispose d'une infrastructure de tests complète.

Emplacement : test/

  • Tests unitaires et d'intégration
  • Tests automatisés des routes
  • Base de données de test dédiée (test/Database/tests.sqlite)

Pour démarrer

1. Comprendre la structure

Explorez les modules existants pour comprendre les conventions :

WebSite/app/modules/[Module]/
├── [Module]Controller.php
├── views/
│   └── *.latte
└── js/
    └── *.js

2. Suivre les conventions

  • Un contrôleur par responsabilité
  • Un helper par table/entité
  • Un fichier de routes par module
  • Migrations pour tout changement de schéma

3. Contribuer

  1. Identifiez le module concerné par votre contribution
  2. Créez ou modifiez les helpers si nécessaire
  3. Créez un migrateur si vous modifiez le schéma de base de données
  4. Implémentez le contrôleur et les vues
  5. Ajoutez les routes dans config/routes/
  6. Testez votre code

Ressources

  • Documentation Flight : https://flightphp.com/
  • Documentation Latte : https://latte.nette.org/
  • Bootstrap : https://getbootstrap.com/

Conclusion

L'architecture de MyClub privilégie la clarté, la modularité et la maintenabilité. Chaque composant a une responsabilité bien définie, ce qui facilite les contributions et l'évolution du projet.

N'hésitez pas à explorer le code, poser des questions et proposer vos améliorations !

Bon développement ! 🚀