kado — Vue d'ensemble plateforme

01 — État

Ce qui est stabilisé

Modules en production, testés end-to-end.

Module	Description	État
Auth OTP + JWT	OTP 6 chiffres, JWT RS256, refresh tokens, blacklist Redis, garde-fous RBAC	Stable
Emission de bons	Création unitaire et CSV, HMAC QR, provision entreprise, ledger double-entrée	Stable
Validation QR (POS)	SELECT FOR UPDATE, anti double-dépense, déduit bon, crédite commerçant	Stable
Reversements commerçants	Wave Direct → Bictorys disbursement → PayDunya (cascade), cron 20h, Bull queue	Stable
Recharge provision (RH)	Bictorys Checkout + Direct (Wave/OM) + PayDunya fallback, webhook confirmation	Stable
Abonnement SaaS	Paiement en ligne par segment, activation auto via webhook, cron expiration/suspension	Stable
Espace bénéficiaire	Wallet, QR plein écran, Screen Wake Lock, PWA installable	Stable
Espace POS commerçant	Scanner QR, saisie montant, confirmation, dashboard, multi-vendeurs, pointage	Stable
Espace RH entreprise	Tableau de bord, émission, import CSV, invitations, abonnement, rapports RSE	Stable
Espace admin	Trésorerie, KYB, webhooks, contrats, équipe, diagnostics, abonnements	Stable
Signature contrat	Viewer in-page, pads de signature canvas, lien /signer?token= partageable WA/email	Stable
Notifications	SMS (Africa's Talking + Twilio fallback), WhatsApp (Baileys + Meta Cloud API), email	Stable
KYB commerçants	Upload documents, workflow PENDING→APPROVED/REJECTED, interface admin de review	Stable
Ledger comptable	Double-entrée INSERT-ONLY, invariant débit=crédit, export CSV	Stable
Webhooks paiement	Wave, Orange Money, Bictorys, PayDunya — vérification signature + idempotence	Stable

Modules en cours / à consolider

Module	Description	État
Bictorys Direct (Wave/OM)	createDirectCharge() implémenté — dépend de BICTORYS_PUBLIC_KEY non encore configuré	Config Railway
Wave Direct Payout	sendPayout() implémenté — nécessite compte Wave Business (contact merchant@wave.com)	Compte requis
PayDunya fallback	Intégré comme fallback — nécessite clés PayDunya dans Railway	Clés à ajouter
Diaspora / Transfert	Pages /diaspora/* existent — logique backend à compléter	En cours
Flash Offers géolocalisées	Modèle et endpoints créés — frontend POS partiellement connecté	En cours
Programme fidélité	LoyaltyCard en base, endpoint /loyalty/me — accumulation points à activer	En cours
Pay-requests e-commerce	API key auth, endpoints créés — intégration marchand à tester en prod	À tester
Support tickets	Backend complet — interface frontend admin à finaliser	En cours
2FA / TOTP	OTP SMS uniquement — authenticator app non prévu en V1	V2
Service Worker offline	Manifest PWA complet — cache strategies à renforcer pour 3G dégradé	À renforcer

02 — Espaces

Les 4 espaces utilisateurs

Chaque espace est une PWA installable avec sa propre URL et ses propres rôles.

Bénéficiaire

/app — kado.sn/app

Collaborateur recevant les bons cadeaux. Consulte son wallet, affiche le QR en plein écran chez le commerçant, gère son profil.

Wallet QR Historique PWA offline

RH Entreprise

/dashboard — kado.sn/dashboard

Gestionnaire RH de l'entreprise cliente. Émet des bons, importe des collaborateurs en CSV, recharge la provision, paye l'abonnement.

Émission Import CSV Provision Abonnement

POS Commerçant

/pos — kado.sn/pos

Terminal point de vente sur téléphone Android. Scanner QR instantané, encaissement, gestion des vendeurs, dashboard solde, pointage.

Scanner QR Multi-vendeur Pointage Flash offers

Admin kado

/admin — kado.sn/admin

Backoffice interne kado. Trésorerie, KYB commerçants, gestion entreprises, webhooks, contrats, abonnements, diagnostics.

Trésorerie KYB Contrats Diagnostics

03 — Fonctionnalités

Inventaire détaillé par espace

Opérationnel En cours V2

Bénéficiaire — /app

Stable

Connexion OTP (SMS + WhatsApp) + mot de passe optionnel
Wallet — liste de tous les bons avec statut (actif, utilisé, expiré)
QR code plein écran avec Screen Wake Lock (téléphone ne s'éteint pas)
Historique des transactions par bon
PWA installable sur Android (standalone, icône, raccourcis)
Gestion profil (prénom, nom, email)
Pay-request — payer avec un bon via un lien marchand
Cache offline QR codes (3G dégradé)
Manifest OK — Service Worker à renforcer
Carte fidélité — points cumulés par commerçant
Modèle en base — activation frontend V2

RH Entreprise — /dashboard

Stable

Tableau de bord — solde provision, nombre de bons, stats
Émission unitaire de bons (bénéficiaire, montant, date, message)
Import CSV collaborateurs — jusqu'à 500 lignes avec rapport d'erreurs
Gestion des invitations (envoyer, suivre, annuler)
Recharge provision — Bictorys (redirect) + Wave/OM direct + PayDunya fallback
Paiement abonnement SaaS en ligne par segment
Annulation / désactivation de bons
Rapport RSE — bilan impact social, statistiques annuelles
Historique des paiements et recharges
Bannière abonnement (TRIAL / OVERDUE / SUSPENDED)

POS Commerçant — /pos

Stable

Scanner QR — caméra active immédiatement à l'ouverture
Saisie montant + confirmation (vibration 200ms + fond vert)
Dashboard commerçant — solde à reverser, transactions récentes
Multi-vendeurs — PIN 4 chiffres, attribution transactions par vendeur
Pointage — horodatage prise/fin de service, historique shifts
Transaction-request — création de demande de paiement avec PIN
Demande de reversement à la demande
KYB — upload documents (RCCM, identité, RIB), suivi statut
Flash offers géolocalisées — création et diffusion radius 5km
Backend stable — frontend partiellement connecté

Admin kado — /admin

Stable

Trésorerie — solde, encaissements, reversements, réconciliation
KYB commerçants — review dossiers, approbation/rejet avec motif
Contrats — génération PDF, signature canvas, lien /signer partageable WA/email
Abonnements SaaS — liste, retards, confirmation paiements
Webhooks — logs, retry manuel, retry-all-failed
Reversements commerçants — déclencher, confirmer, pay-all
WhatsApp — QR pairing, statut Baileys + Meta Cloud API
Diagnostics — santé DB/Redis, réparation rôles, ledger export CSV
Gestion équipe interne (ajout, désactivation membres)
Leads & onboarding — prospects, invitations, suivi conversion

04 — Paiements

Architecture des paiements

Deux flux distincts avec des prestataires différents et des cascades de fallback.

Flux 1 — Encaissements (kado reçoit)

Entreprise paie son abonnement ou recharge sa provision

Sélection montant + méthode dans l'espace RH

Bictorys Checkout (principal)

Wave Sénégal · Orange Money · Carte bancaire — redirection

Fallback transparent → PayDunya

Si Bictorys timeout ou erreur 5xx — l'entreprise ne voit pas la différence

Webhook → provision créditée / abonnement activé

Écriture ledger automatique · SMS + email de confirmation

Flux 2 — Reversements (kado verse)

Client valide un bon chez le commerçant

Mouvement INTERNE uniquement — aucun appel Wave/Bictorys ici

Solde commerçant crédité (MerchantBalance)

Commission 5% prélevée → REVENUE_COMMISSION

20h automatique (ou à la demande)

Cron kado déclenche le reversement si solde > 0

Wave Direct → Bictorys → PayDunya

Wave 0% commission · SMS confirmation commerçant

Prestataire	Usage	Priorité	Variables Railway	État
Bictorys	Checkout encaissements · Direct Wave/OM · Disbursements OM	Principal	BICTORYS_SECRET_KEY BICTORYS_PUBLIC_KEY BICTORYS_WEBHOOK_SECRET	Clé invalide
PayDunya	Fallback encaissements · Fallback reversements Wave/OM	Fallback	PAYDUNYA_MASTER_KEY PAYDUNYA_PRIVATE_KEY PAYDUNYA_TOKEN	À configurer
Wave Direct	Reversements commerçants Wave (0% commission)	Principal Wave	WAVE_API_KEY WAVE_BASE_URL	Compte requis
Africa's Talking	SMS OTP + notifications	Principal SMS	AT_API_KEY AT_USERNAME	Actif
Twilio	Fallback SMS	Fallback SMS	TWILIO_ACCOUNT_SID TWILIO_AUTH_TOKEN	Configuré

05 — Modèle économique

Tarification par segment

2 composantes : frais d'accès annuels (fixes) + commission sur bons émis (dégressif).

TPE

Petite structure

50 000 FCFA / an

Frais d'accès plateforme

2,00 %

Commission

Actif

PME

Moyenne entreprise

150 000 FCFA / an

Frais d'accès plateforme

1,75 %

Commission

Actif

ETI

Taille intermédiaire

350 000 FCFA / an

Frais d'accès plateforme

1,50 %

Commission

Actif

Grand Compte

Grande entreprise

600 000 FCFA / an

Frais d'accès plateforme

1,00 %

Commission

Actif

Sur Mesure

Campagne ponctuelle

15 000 FCFA + 500 FCFA/bon

Par campagne (EventCampaign)

2,50 %

Commission

En cours

Commissions commerçants : 5 % retenus sur chaque transaction au moment du reversement. Ce montant est imputé sur le net reversé au commerçant, pas sur la provision de l'entreprise.

06 — Modules API

Architecture NestJS

API REST sur NestJS 10 — 13 modules, 70+ endpoints.

AuthModule

OTP SMS/WA, JWT RS256, refresh rotation, password reset, vendor PIN

VouchersModule

Cycle de vie complet, validation QR SELECT FOR UPDATE, ledger, expiration cron

MerchantsModule

KYB, flash offers, vendors, pointage, transaction-request, géolocalisation

CompaniesModule

Provision, abonnement SaaS, émission bons, import CSV, rapports RSE

PaymentsModule

Bictorys, PayDunya, Wave, OM — webhooks, settlements Bull queue, cron 20h

AdminModule

Trésorerie, KYB, abonnements, diagnostics, maintenance, contrats

NotificationsModule

SMS (Africa's Talking + Twilio), WhatsApp Baileys + Meta, email, Bull queue

LedgerModule

Double-entrée INSERT-ONLY, invariant débit=crédit, export CSV

LeadsModule

Prospects, invitations onboarding, signature contrats, tokens /signer

Jobs & Crons

Expiration bons (00h01 UTC) · Reversements (20h UTC) · Abonnements (minuit UTC)

SecurityModule

Audit log, alertes anomalies, rate limiting, HMAC webhook verification

HealthModule

Vérification PostgreSQL + Redis, endpoint /health pour uptime monitoring

07 — Stack

Technologies utilisées

Backend

NestJS 10 TypeScript strict Prisma 5 PostgreSQL 16 Redis 7 Bull (queues)

Frontend

Next.js 15 App Router React 18 PWA TypeScript

Auth & Sécurité

JWT RS256 OTP 6 chiffres HMAC SHA256 timingSafeEqual RBAC

Infra

Railway (API) Vercel (Web) Docker Compose GitHub CI

08 — Règles

Règles absolues — ne jamais violer

Ces contraintes sont non-négociables. Toute PR qui les viole est rejetée.

#	Règle	Raison
1	Montants TOUJOURS en centimes FCFA (Int)	10 000 FCFA = 1 000 000 centimes. Jamais de Float, jamais de Number JS pour les montants financiers.
2	LedgerModule : INSERT ONLY	Aucun UPDATE ni DELETE sur les entrées du ledger. Piste d'audit immuable.
3	Validation QR : SELECT FOR UPDATE dans transaction Prisma	Zéro race condition tolérée. Anti double-dépense absolu.
4	Instructions EME/paiement via queue Bull asynchrone	Jamais d'appel synchrone bloquant à une API externe sur le chemin critique.
5	Secrets 100% en variables d'environnement	Zéro hardcode dans le code source ou les commits.
6	Pour toute opération ledger : SUM(débit) = SUM(crédit)	Invariant comptable absolu. Violation = bug critique.
7	TypeScript strict — zéro any implicite	"strict": true dans tsconfig. Toutes les PR passent le typecheck.
8	Webhooks : vérification HMAC timingSafeEqual AVANT traitement	Jamais de === pour comparer les signatures. Protection contre timing attacks.
9	Affichage montants : toujours amount / 100 → FCFA	Conversion systématique centimes → FCFA dans tous les affichages.
10	Commission : Math.round(amount * rate) — jamais de float	Arrondi entier obligatoire. const commission = Math.round(amount * 0.05);