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

Composant	Technologie	Version
Runtime	Node.js	-
Framework	Express.js	^5.1.0
Base de données	MongoDB	^6.18.0
ODM	Mongoose	^8.16.1
Authentification	Firebase Admin	^13.4.0
Notifications	Firebase Messaging	^11.9.1
WebSocket	Socket.io	^4.8.1
Documentation API	Swagger UI	^5.0.1
Upload fichiers	Multer	^2.0.2
Stockage cloud	Cloudinary	^2.8.0
Géolocalisation	OpenStreetMap	-

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 :

• API Swagger - Documentation API complète
• Base de données - Schémas MongoDB détaillés
• Authentification - Système d'authentification Firebase
• Transit international - Missions transitaires
• Agents commerciaux - KPIs et démos agents
• Livro - Livraison tiers