BUSINESS ARENA — Dossier d'architecture (Mission n°37)
Simulation + Apprentissage + Aide à la décision + Compétition.
Plateforme SaaS de simulation d'entreprise dans laquelle un joueur ou une équipe dirige une
entreprise virtuelle, apprend à choisir le bon modèle de gestion, et progresse du niveau
DÉCOUVERTE au niveau EXECUTIVE.
Ce dossier est le livrable de la mission n°37 : l'architecture complète du produit,
produite avant toute ligne de code applicatif, conformément à la méthode imposée
(§35 étape 1 : analyser, identifier les ambiguïtés, proposer l'architecture, ne pas coder).
Statut du dépôt
Ayari-59/business-arena est le dépôt dédié du produit, comme l'exige le cahier des
charges. Il contient pour l'instant uniquement ce dossier d'architecture (livrable de
l'étape 1) ; le code applicatif arrivera par étapes (§35), chaque étape devant rester
conforme aux documents ci-dessous ou les amender explicitement.
Sommaire du dossier
| Fichier | Contenu (points du cahier des charges §37) |
|---|
docs/00-decisions-et-ambiguites.md | Analyse du cahier des charges, ambiguïtés identifiées, décisions d'architecture (ADR) |
docs/01-architecture-globale.md | 1. Architecture globale · 2. Architecture des dossiers · 16. Stratégie de déploiement Vercel |
docs/02-moteur-simulation.md | 3. Architecture du moteur de simulation (demande, élasticité, prix psychologique, production, coûts, finance FRNG/BFR, événements) |
docs/03-moteur-pedagogique.md | 4. Moteur pédagogique · 10. Les 20 concepts du MVP · 11. Modèles de décision · 12. Règles du système d'indices |
docs/04-moteur-competition.md | 5. Architecture du moteur de compétition (modes apprentissage / compétition / concours) |
docs/05-schema-base-de-donnees.md | 6. Schéma complet Neon PostgreSQL · 7. Relations entre tables |
docs/06-types-typescript.md | 8. Types TypeScript principaux |
docs/07-scenario-nova.md | 9. Architecture du premier scénario NOVA (6 tours) |
docs/08-scoring-et-difficulte.md | 13. Règles de scoring (Business Performance Index) · 14. Architecture des niveaux de difficulté |
docs/09-strategie-tests.md | 15. Stratégie de tests |
docs/10-strategie-evolution.md | 17. Stratégie d'évolution future (championnat, IA, internationalisation…) |
Stack (imposée, confirmée)
Next.js (App Router) · React · TypeScript strict · Vercel · Neon PostgreSQL · Drizzle ORM ·
Tailwind CSS · shadcn/ui · Git/GitHub · architecture compatible API LLM.
Note : le dépôt frère axio utilise Prisma ; BUSINESS ARENA étant un produit indépendant,
il applique la stack imposée par son propre cahier des charges, donc Drizzle.
La boucle produit
SITUATION → PROBLÈME → DIAGNOSTIC → MODÈLE D'ANALYSE → DÉCISION
↑ ↓
APPRENTISSAGE ← ANALYSE ← RÉSULTAT ← SIMULATION ←──────────┘
Chaque brique de l'architecture sert un maillon de cette boucle :
- SITUATION / PROBLÈME → moteur de scénarios + moteur d'événements (
docs/02, docs/07)
- DIAGNOSTIC / MODÈLE → moteur pédagogique, référentiels de concepts et de modèles (
docs/03)
- DÉCISION / SIMULATION / RÉSULTAT → moteur économique déterministe (
docs/02)
- ANALYSE / APPRENTISSAGE → débriefing, indices, profil de compétences, scoring (
docs/03, docs/08)
- COMPÉTITION → moteur de compétition (
docs/04)
Démarrage
npm install
npm run base:locale # une base Postgres locale, migrée et semée (voir plus bas)
# dans un autre terminal :
export DATABASE_URL=postgres://[email protected]:5434/postgres
export DIRECT_URL=$DATABASE_URL AUTH_SECRET=de-quoi-signer-les-sessions
npm run dev # http://localhost:3030
Pour travailler sur la base de production (Neon) plutôt que sur la base locale :
cp .env.example .env, y renseigner DATABASE_URL (pooler) et DIRECT_URL
(direct), puis npm run db:migrate avant npm run dev.
Vérifications : npm run typecheck · npm test · npm run build. Les trois tournent
en intégration continue (.github/workflows/ci.yml) sur chaque poussée et chaque
proposition de fusion : la suite garde désormais quelque chose.
Le parcours en navigateur
npm run test:e2e conduit un vrai navigateur sur l'application entière : un enseignant
crée son compte et une partie, un élève la rejoint par le code, joue son tour, et
l'enseignant clôture. Il existe parce que les écarts trouvés en recette manuelle vivaient
tous entre les pièces, jamais dedans, là où la suite ordinaire ne regarde pas.
Il lui faut un Postgres et l'application démarrée, contrairement aux autres tests qui ne
demandent rien. Le pilote de base suit l'URL : une adresse Neon prend le pilote HTTP de
production, toute autre adresse Postgres prend le pilote standard, avec le même schéma et
les mêmes migrations des deux côtés.
npm run base:locale & # base sur 127.0.0.1:5434, migrée et semée
export DATABASE_URL=postgres://[email protected]:5434/postgres
export DIRECT_URL=$DATABASE_URL AUTH_SECRET=de-quoi-signer-les-sessions
npm run build && npx next start -p 3040 &
E2E_BASE_URL=http://127.0.0.1:3040 npm run test:e2e
DATABASE_URL est nécessaire au processus de test lui-même, et pas seulement à
l'application : deux essais écrivent en base (une licence échue, un relevé
d'usage) pour vérifier ce que l'écran en dit.
CHROMIUM_PATH permet de désigner un binaire déjà présent ; sans elle, Playwright utilise
celui qu'il a installé (npx playwright-core install chromium).
Une base Postgres sans rien installer
npm run base:locale démarre un Postgres complet sur 127.0.0.1:5434, applique les
migrations de drizzle/ et sème le monde de démonstration, puis affiche le code de
partie à taper sur /join. Il n'y a ni paquet système à poser, ni rôle à créer, ni base
à déclarer : c'est PGlite, le Postgres compilé en WebAssembly dont les tests
d'intégration se servent déjà, que le script expose sur un port en une cinquantaine de
lignes. Aucune dépendance n'est ajoutée pour cela — le paquet qui fait ce travail épingle
ses pairs et aurait fait monter PGlite pour toute l'équipe. L'application ne fait donc
aucune différence : même schéma, mêmes migrations, même pilote que devant un Postgres
ordinaire.
| |
|---|
npm run base:locale | démarre, migre, sème, et reste ouverte |
npm run base:locale -- --neuve | repart d'une base vide |
npm run base:locale -- --sans-semis | sans le monde de démonstration |
PORT_BASE_LOCALE=5435 npm run base:locale | sur un autre port |
Les données vivent dans .pglite/, ignoré par git : la partie qu'on vient de jouer est
encore là au redémarrage. Ce n'est pas la production, qui tourne sur Neon avec son pilote
HTTP ; c'est de quoi voir l'application tourner et jouer le parcours.
Déploiement Vercel : preset Next.js, racine du dépôt. Le script vercel-build
(drizzle-kit migrate && next build) applique automatiquement les migrations au build —
définir dans le projet Vercel les variables DATABASE_URL, DIRECT_URL, AUTH_SECRET,
CRON_SECRET. (Cible long terme : migrations en CI, doc 01 §5.)
Prochaines étapes (méthode §35)
- ✅ Étape 1 — ce dossier : architecture validée avant développement.
- ✅ Étape 2 — modèle de données : schéma Drizzle (43 tables,
src/db/schema/) +
migration initiale (drizzle/), conformes à docs/05.
- ✅ Étape 3 — moteur économique déterministe + tests (
docs/02, docs/09).
- ✅ Étape 4 — scénario NOVA calibré, invariants automatisés (
docs/07).
- ✅ Étape 5 — simulation de 6 tours (périodicité mois/trimestre/année au choix).
- ✅ Étape 6 — interface joueur (arène, KPI, graphiques, décisions).
- ✅ Étape 7 — interface enseignant (parties de classe 1-8 équipes + bots,
codes d'invitation, clôture des tours, vue pédagogique).
- ✅ Étape 8 — moteur pédagogique (situations scriptées et détectées,
diagnostic, choix du modèle d'analyse, débriefing, progression).
- ✅ Étape 9 — système d'indices à 5 niveaux (séquentiels, coûtés, tracés).
- ✅ Étape 10 — scoring IPG (indice de performance globale, ex-BPI) : 6 dimensions pondérées, dont la RSE,
normalisation bornes + rang parmi les pairs, tours à poids croissants,
départage financier ; classement et décomposition affichés partout.
- ✅ Étape 11 — profil joueur
/profile : compétences par axe, maîtrise des
concepts, historique des parties avec rang et IPG.
- Étape 12 — IA coach (API LLM) : à venir (frontière réservée, doc 01 §7).
- ✅ Étape 13 — moteur de concours « Business Arena Championship » :
inscriptions par code, groupes tirés au sort (seedé, auditable), parties
en mode compétition (décisions verrouillées, indices limités — §25),
qualification à l'IPG, finale, podium.
Ce qui se vend : la licence d'établissement
Un lycée n'achète pas un abonnement par carte bancaire. Il émet un bon de commande, reçoit
une facture et paie par mandat administratif, parfois deux mois plus tard. Le produit
enregistre donc les termes convenus, il ne les encaisse pas : le montant et la
référence servent à retrouver la vente, pas à la conclure. Aucune intégration de paiement
n'est prévue tant qu'elle ne débloque aucune vente.
Une licence porte une période, un plafond d'enseignants facultatif, et de quoi la
rattacher à un devis. L'administrateur général l'enregistre depuis /admin,
établissement par établissement ; l'établissement voit son état dans /org.
Trois règles, et chacune protège quelqu'un :
- l'absence de licence vaut accès libre. Une frontière qui se refermerait d'elle-même
sur les établissements existants, sur une démonstration ou sur un essai serait une
régression déguisée en modèle économique. La limite n'existe que là où une vente l'a
définie ;
- une licence expirée n'interrompt jamais une classe en cours. Elle ferme l'ouverture
de nouvelles parties et laisse terminer celles qui tournent : clore un tour, débriefer et
exporter les notes restent possibles. Un trimestre commencé se finit, sans quoi ce
seraient les élèves qui paieraient un retard de mandatement ;
- le plafond porte sur les enseignants, l'unité que l'établissement reconnaît sur un
devis et qui ne bouge pas en cours d'année. Les élèves ne sont jamais comptés.
Les parties publiques jouées en solo ne dépendent d'aucune licence.
Comptes de démonstration
Depuis /admin (admin général), le bouton « Générer le monde démo » crée un
établissement complet : [email protected] (admin d'établissement) et
[email protected] (enseignant), avec une partie de
classe jouée sur 3 tours (le tour 4 — la crise de trésorerie — est le prochain), des vues
pédagogiques alimentées et un concours prêt à lancer. Le mot de passe est tiré au hasard
et montré une seule fois, à la création ; /admin le renouvelle ou ferme les comptes. En
production, la création est refusée sauf si AUTORISER_DEMO_EN_PRODUCTION=1. La licence de
démo couvre deux personnels. En local : npm run seed:demo. L'admin général n'a pas de
compte démo (rôle sensible : réservé aux e-mails d'ADMIN_EMAILS).
Cohortes d'épisodes manager
Une entreprise déploie les épisodes manager par cohorte. L'administrateur général la crée
depuis /admin/cohortes (ou, en local, npm run cohorte:creer -- "Nom" https://adresse-du-site), qui
affiche deux liens : l'invitation, à envoyer aux managers, et le lien de
l'animateur, qui ouvre les agrégats de la cohorte (aucun nom, rien sous cinq personnes) et se
transmet à l'animateur seul.
Aucune modification du moteur économique ne sera acceptée sans tests (§32).
