Skip to main content

Architecture Backend - Node.js/Express

Vue d'ensemble​

Le backend Tranoo est une API RESTful dans le monorepo tranoo-api, construite avec Node.js, Express.js et MongoDB (Atlas), avec Firebase Admin pour l'authentification et les notifications.

Stack technique​

ComposantTechnologieVersion
RuntimeNode.js-
FrameworkExpress.js^5.1.0
Base de donnéesMongoDB^6.18.0
ODMMongoose^8.16.1
AuthentificationFirebase Admin^13.4.0
NotificationsFirebase Messaging^11.9.1
WebSocketSocket.io^4.8.1
Documentation APISwagger UI^5.0.1
Upload fichiersMulter^2.0.2
Stockage cloudCloudinary^2.8.0
GéolocalisationOpenStreetMap-

Structure du projet​

tranoo-api/
├── src/
│   ├── app.js                      # Point d'entrée serveur
│   ├── config/                     # Configuration
│   │   ├── authConfig.js          # Configuration auth (OTP, MDP)
│   │   ├── agentConfig.js         # Configuration agents
│   │   ├── swagger.js             # Export spec Swagger
│   │   └── whatsappConfig.js      # Configuration WhatsApp
│   ├── controllers/                # Logique métier (43 contrôleurs)
│   │   ├── authController.js
│   │   ├── userController.js
│   │   ├── articleController.js
│   │   ├── paymentController.js
│   │   ├── deliveryController.js
│   │   └── ...
│   ├── models/                     # Schémas Mongoose (35 modèles)
│   │   ├── User.js
│   │   ├── Article.js
│   │   ├── Order.js
│   │   ├── Delivery.js
│   │   └── ...
│   ├── routes/                     # Routes Express (45 fichiers)
│   │   ├── auth.js
│   │   ├── user.js
│   │   ├── article.js
│   │   └── ...
│   ├── middlewares/                # Middlewares Express
│   │   ├── auth.js                # Vérification token Firebase
│   │   ├── role.js                # Vérification rôles
│   │   ├── verifyCaptcha.js       # Vérification CAPTCHA
│   │   ├── verifyAppCheck.js       # Vérification App Check
│   │   └── authRateLimit.js       # Rate limiting auth
│   ├── services/                   # Services métier
│   │   ├── articlePublishService.js
│   │   └── locationGeocode.js
│   ├── docs/                       # Documentation OpenAPI
│   │   └── openapi/
│   │       ├── index.js
│   │       ├── components.js
│   │       ├── tags.js
│   │       ├── helpers.js
│   │       └── paths/
│   ├── utils/                      # Utilitaires
│   └── public/                     # Fichiers statiques
├── scripts/                        # Scripts utilitaires
│   └── verify_swagger_coverage.js
├── uploads/                        # Uploads locaux
├── .env                            # Variables environnement
├── package.json
└── src/app.js                      # Point d'entrée

Points d'entrée​

app.js - Point d'entrée principal​

// Initialisation
- Configuration Express
- Connexion MongoDB
- Initialisation Firebase Admin
- Configuration Socket.io
- Montage des routes
- Exposition Swagger UI
- Gestion erreurs globales

Scripts npm​

npm run dev          # Développement avec nodemon
npm run start        # Production
npm run swagger:count    # Compter endpoints documentés
npm run swagger:verify   # Vérifier couverture API

Architecture des contrôleurs​

Contrôleurs principaux (43)​

Authentification & Users

  • authController.js - Inscription, connexion, sessions web
  • userController.js - CRUD utilisateurs, profils
  • authEventController.js - Événements auth

Commerce

  • articleController.js - Gestion articles/produits
  • achatController.js - Achats
  • orderController.js - Commandes
  • invoiceController.js - Factures

Livraison & Logistique (legacy — hors périmètre, remplacé par Livro)

  • deliveryController.js, livreurController.js, etc. — code historique, non documenté

Paiements

  • paymentController.js - Traitement paiements (Feexpay)
  • walletController.js - Gestion wallets
  • subscriptionController.js - Abonnements
  • subscriptionPricingController.js - Tarifs abonnement

Communication

  • chatController.js - Chat en temps réel
  • notificationController.js - Notifications push
  • whatsappWebhook.js - Webhooks WhatsApp

Administration

  • agentController.js - Agents commerciaux (voir Agents commerciaux)
  • statsController.js - Statistiques
  • settingsController.js - Paramètres système
  • verificationController.js - Vérifications documents

Transit

  • transitMissionController.js - Missions transit international
  • transitaireVerificationController.js - Vérification comptes transitaires
  • transitaireReviewController.js - Avis transitaires

Autres

  • tricycleController.js - Contacts tricycles
  • referralController.js - Parrainage
  • publiciteController.js - Publicités
  • uploadController.js - Upload fichiers
  • geoController.js - Géolocalisation

Architecture des modèles (35)​

Utilisateurs & Auth

  • User.js - Utilisateurs (tous rôles)
  • UserDevice.js - Appareils utilisateurs
  • AuthEvent.js - Événements authentification
  • PasswordResetRequest.js - Reset MDP

Commerce

  • Article.js - Articles/produits
  • Achat.js - Achats
  • Order.js - Commandes
  • Invoice.js - Factures
  • InvoiceSequence.js - Séquence factures

Livraison (legacy — voir Intégration Livro)

  • Delivery.js, DeliveryZone.js, DeliverySettings.js, LivreurBalance.js — modèles historiques
  • DemandeChauffeur.js - Demandes chauffeurs

Paiements

  • Payment.js - Paiements
  • Subscription.js - Abonnements
  • SubscriptionPricing.js - Tarifs abonnement
  • SellerGainPricing.js - Tarifs vendeurs

Communication

  • ChatRoom.js - Salons chat
  • Message.js - Messages
  • Notification.js - Notifications

Transit

  • TransitMission.js - Missions transit
  • TransitaireReview.js - Avis transitaires
  • TransitaireSubscriptionPricing.js - Tarifs transitaires

Autres

  • TricycleContact.js - Contacts tricycles
  • Referral.js - Parrainages
  • ReferralTariff.js - Tarifs parrainage
  • ReferralSettings.js - Configuration parrainage
  • Publicite.js - Publicités
  • PubPricing.js - Tarifs publicité
  • VerificationPricing.js - Tarifs vérification

Middlewares​

auth.js​

Vérifie le token Firebase et attache l'utilisateur à la requête.

role.js​

Vérifie les rôles utilisateur (admin, vendeur, transitaire, etc.).

verifyCaptcha.js​

Vérifie le CAPTCHA (Turnstile) pour les actions sensibles.

verifyAppCheck.js​

Vérifie Firebase App Check pour sécuriser les apps mobiles.

authRateLimit.js​

Rate limiting sur les endpoints d'authentification.

Socket.io - WebSocket​

Configuration​

  • CORS autorisé pour toutes origines
  • Stockage des connexions utilisateurs (Map)
  • Authentification via token Firebase

Events​

Client → serveur

  • authenticate — Authentification socket (token Firebase)
  • join-room / leave-room — Salons chat
  • typing-start / typing-stop — Indicateur de frappe

Serveur → client

  • authenticated — Confirmation auth socket
  • typing-indicator — État de frappe des participants

Firebase Integration​

Firebase Admin​

  • Authentification (vérification tokens)
  • Cloud Messaging (notifications push)
  • Storage (stockage fichiers)

App Check​

  • Middleware verifyAppCheck.js implémenté — non monté sur les routes actuellement

Workers au démarrage​

Lancés depuis src/app.js :

  1. Payment status worker — suivi des paiements FeexPay
  2. Cron jobs — expiration publicités, vues automatiques articles
  3. Delivery offer worker — (legacy, livraison interne)

Documentation source​

Guides dans tranoo-api/docs/ : SWAGGER.md, CAPTCHA.md, I18N.md, MIGRATION_AUTH_TELEPHONE.md

Environnement​

Variables .env requises​

MONGO_URI=                 # URI MongoDB Atlas (variable runtime)
FIREBASE_SERVICE_ACCOUNT_JSON=  # Clé service account Firebase (prod)
GOOGLE_APPLICATION_CREDENTIALS= # Alternative fichier credentials
PORT=5000                  # Port serveur (5005 en .env.prod)
NODE_ENV=development       # Environnement
WEB_SESSION_IDLE_MS=1800000  # Session web dashboard (30 min)

Sécurité​

Authentification​

  • Firebase ID tokens
  • Vérification token à chaque requête protégée
  • Sessions web avec X-Web-Session-Id

Rate Limiting​

  • Limitation sur endpoints d'authentification
  • Protection contre brute force

Validation​

  • Validation des entrées via Mongoose
  • CAPTCHA sur actions sensibles
  • App Check pour mobiles

Logs et monitoring​

  • Logs console pour développement
  • Gestion erreurs globales
  • Tracking des événements auth

Déploiement​

Développement​

npm run dev
# Serveur sur http://localhost:5000
# Swagger UI sur http://localhost:5000/api-docs

Production​

npm run start
# PM2 documenté : pm2 restart tranoo-api --update-env
# API prod : https://api.tranoo.store

Prochaines étapes​

Voir aussi :