Gerege Nexus

Production · Couche 3 — Socle applicatif · Dépôt : open-gerege-nexus · nexus.gerege.mn

Une plateforme unifiée pour les services, les opérations et les systèmes. Une plateforme modulaire qui réunit sur un même socle les services, les opérations, les systèmes et les données des organismes publics et privés. Open source, licence Apache 2.0.

Nexus désigne le point de connexion — là où se rencontrent organisations, services, processus, systèmes, utilisateurs et données. La plateforme elle-même ne vise aucun secteur en particulier : ce sont les modules qui tournent au-dessus d'elle qui définissent les besoins d'une organisation donnée.

Le modèle de l'écosystème change

Gerege Nexus est le socle successeur de la Template Platform. L'ancien modèle était « un modèle → un fork par produit » ; le nouveau est « un upstream (Nexus) → un fork par marque, rafraîchi par fusion depuis l'upstream ». La transition est en cours — les plateformes existantes restent en production. Voir Architecture en couches.

La différence essentielle : une application est un module

Dans l'ancien modèle, un nouveau produit signifiait un nouveau dépôt, un nouveau déploiement et une nouvelle base de données. Sur Nexus, un nouveau produit est généralement un nouveau module — une application compilée dans le même binaire, que chaque locataire peut activer ou désactiver.

	Modèle Template (ancien)	Modèle Nexus (nouveau)
Nouveau produit	Forker le modèle	Écrire un module et l'ajouter au catalogue
Distribution	Un déploiement par dépôt	Par locataire, via l'app store
Partage de code	Paquets open-gerege-core + @gerege/ui-core	Un seul upstream ; les forks aval fusionnent depuis lui
Appels entre modules	HTTP (quand les dépôts sont séparés)	Appels Go en processus
Activation / désactivation	Nécessite un déploiement	Un administrateur décide dans app_installations

Monolithe modulaire

Les modules métier implémentent le contrat Go Module et se compilent dans un seul binaire. Les applications actives pour un locataire donné sont déterminées dynamiquement par la table app_installations dans PostgreSQL.

• Aucun saut réseau supplémentaire — les modules s'appellent en processus : ni latence de microservices, ni complexité d'orchestration.
• Résolution de dépendances par DAG — les dépendances sont résolues récursivement sur un graphe orienté acyclique, avec détection de cycles et validation semver.
• Synchronisation du catalogue — catalog/apps.json est l'unique source de vérité ; la table apps en est rafraîchie à chaque démarrage. Ajouter une application ne demande aucun SQL écrit à la main.
• Contrôle d'accès applicatif — une route appartenant à une application non installée répond 403 Forbidden.

Pourquoi pas des microservices ?

Les frontières entre modules sont garanties par des interfaces Go, pas par le réseau. La garantie de frontière est conservée, tandis que la latence réseau, les transactions distribuées et le coût d'exploitation de multiples déploiements sont tous évités.

Les modules livrés avec la plateforme

Module	ID	Chemin	Objet
Contacts	io.example.contacts	/contacts	Répertoire de contacts, auto-remplissage XYP
Products	io.example.products	/products	Produits, tarifs, SKU par locataire
Inventory	io.example.inventory	/inventory	Entrepôts, niveaux de stock, journal de mouvements en ajout seul
Billing & e-Barimt	io.example.billing	/billing	Factures, TVA à 10 %, reçus e-Barimt
Digital Documents	io.example.documents	/documents	Documents électroniques et circuits de validation
Developer Portal	io.example.developer_portal	/developer/apps	Enregistrement des applications clientes OAuth2
Signature électronique PDF	io.example.esign	/esign	Signature juridiquement valable via eID Mongolia (PIN2)
Services publics	io.example.gov_services	/gov	Processus de service configurable, hiérarchie, SLA

Processus de service public configurable

Le module gov_services transforme une seule base de code en une capacité de délivrance de service que chaque locataire — et chaque service au sein d'un locataire — configure pour lui-même. Choisir entre trois modes n'implique aucune modification de code :

Mode	Signification
LOCAL	L'unité réceptrice traite la demande elle-même
DELEGATE	Transmise à une unité inférieure, l'unité supérieure suit et vérifie
HYBRID	Une règle de routage décide au cas par cas

Le principe directeur — le code décide de ce qui est possible, la configuration décide de ce qui est proposé. La table canonique des transitions vit dans le code ; une version publiée peut la restreindre, jamais l'élargir. Un locataire mal configuré ne peut donc pas atteindre un état impossible.

Autres garanties :

• Le statut est calculé côté serveur — un client envoie une action, jamais un statut.
• Le travail achevé par une unité inférieure ne clôt jamais la demande — lorsqu'une étape exige une vérification, l'achèvement aboutit à AWAITING_VERIFICATION.
• Le retard est dérivé (due_at < now()), jamais écrit par-dessus le statut métier.
• L'isolation par locataire et par unité vit dans le schéma — chaque clé étrangère est composite et inclut tenant_id, de sorte qu'une ligne ne peut pointer vers un autre locataire même en cas de bogue applicatif.
• Ingestion idempotente — une demande entrante est identifiée par (tenant_id, source_system, external_request_id) ; un renvoi identique retourne "created": false, et un rejeu au contenu substantiellement différent est refusé par un 409.
• La notification sortante passe par un outbox — un endpoint distant ne peut jamais annuler ni bloquer une transition.

Signature électronique — eID Mongolia (PIN2)

Le module esign se raccorde à la signature qualifiée à distance d'eID Mongolia en tant que partie utilisatrice :

1. le PDF est haché → eID pousse ce condensé sur le téléphone du citoyen,
2. le citoyen approuve avec le PIN2,
3. le doc-signer d'eID intègre le PKCS#7 avec les données OCSP et CRL et assemble un PDF signé en PAdES.

La clé privée de signature n'atteint jamais la plateforme. Le niveau de certificat vaut QUALIFIED par défaut — accepter ADVANCED déclasserait silencieusement chaque document produit par la plateforme.

Signer au nom d'une organisation

Les droits de représentation sont lus en direct dans le registre national, et non dans un certificat — car un dirigeant démissionnaire d'hier détient toujours le certificat d'hier.

Sont également inclus : un journal des signatures (filtres, pagination, export CSV), la signature par lot, le placement du cachet avec aperçu A4, la connexion HSM et la politique de signature. Un locataire peut exiger des signatures eID qualifiées et désactiver entièrement la voie HSM — y compris pour les appelants qui s'adressent directement à l'API.

Authentification et intégration avec l'État

• Son propre fournisseur OAuth2 / OIDC — /.well-known/openid-configuration, /oauth2/token, /oauth2/introspect, /oauth2/revoke, avec authorization_code, client_credentials et refresh_token.
• eID et DAN — les quatre canaux officiels : signature numérique PKI, Mobile OTP, SSO bancaire et vérification faciale biométrique.
• XYP — état civil (WS100101) et vérification des personnes morales (WS100201).
• Jetons de session opaques, 256 bits, stockés uniquement sous forme de condensé SHA-256. La déconnexion les révoque réellement.

Le mode mock ne tourne pas en production

Les modes mock E-ID / DAN / XYP n'existent que pour le développement. Sous ENVIRONMENT=production, ils se désactivent automatiquement : impossible de se connecter avec des données citoyennes fabriquées.

IA et résilience

IA — un assistant Gemini ancré dans l'état réel de la base du locataire (/api/v1/ai/chat, /stt, /tts, /translate), des prompts et une base de connaissances gérés par l'administrateur, ainsi qu'un prévisionnel de demande en stock.

Résilience cloud-native (inspirée de go-zero) :

Composant	Rôle
Adaptive circuit breaker	Taux d'échec sur fenêtre glissante, à la manière du SRE Google
Adaptive load shedding	503 + Retry-After lorsque la concurrence est dépassée
Singleflight coalescing	Fusionne les requêtes dupliquées et évite l'effondrement du cache
Exponential backoff retry	Réessaie les défaillances transitoires avec temporisation

Politique linguistique

Le mongol plus les six langues officielles de l'ONU = sept au total. Le mongol est la source. La documentation existe dans les sept, mais le logiciel est livré en mongol et en anglais, les cinq autres s'activant dans Paramètres → Apparence. C'est le même principe que la politique i18n de ce site.

Marques dérivées

Nexus est l'upstream ; chaque marque en dérive et se rafraîchit par fusion.

Marque	Dépôt	Domaine	Ce qui diffère
Gerege Nexus	open-gerege-nexus	nexus.gerege.mn	Upstream, déploiement de référence
Gerege SSO	sso-gerege-nexus	—	Fork centré sur la couche connexion, droits et accès
Eduge.mn	eduge-mn-nexus	eduge.mn	Marque du secteur éducatif ; embarque un overlay de construction sur l'hôte quand GHCR est inaccessible

Deux choses appelées Gerege SSO

sso-gerege-nexus est le nouveau fork bâti sur Nexus ; sso.gerege.mn en production tourne toujours sur l'ancien code sso-gerege-mn. Ne les confondez pas : jusqu'à la fin de la transition, c'est le comportement décrit sur la page Gerege SSO qui fait foi.

Déploiement

Un push sur main déclenche GitHub Actions : construction et envoi des images backend et frontend vers GHCR → copie de docker-compose.prod.yml sur le serveur → récupération des images → bascule de l'API et du frontend une fois les migrations terminées → vérification de /health et /ready. Le déploiement ne démarre qu'après que la CI est réellement passée.

Le serveur n'a besoin que de Docker — ni source, ni Go, ni Node.

PUBLIC_ORIGIN définit trois choses à la fois

CORS, l'issuer OIDC et le callback eID dérivent d'une seule variable. La modifier déplace ensemble le DNS, le certificat TLS et chaque client dépendant de l'issuer. Lors d'un changement de domaine, utilisez la liste de contrôle de la page Authentification et autorisations.

Stack

Couche	Choix
Backend	Go 1.25 · routeur chi · pgx (sans ORM, SQL écrit à la main)
Frontend	Next.js 15 App Router
Base de données	PostgreSQL 16 — schéma partagé, isolation par tenant_id
Migrations	goose (backend/db/migrations/) ; DDL interdit à l'exécution
Observabilité	Prometheus (/metrics) · OpenTelemetry
Conteneurs	Docker Compose · GHCR

Pour la vue d'ensemble de l'écosystème, voir Stack technique.

Documentation détaillée

La documentation de niveau implémentation vit dans le dépôt, en sept langues :

Document	Contenu
README.md	Vue d'ensemble de la plateforme (7 langues)
docs/ARCHITECTURE_SPECIFICATION.md	Couches et décisions d'architecture (MN/EN)
docs/MODULE_AUTHORING_GUIDE.md	Comment écrire un nouveau module applicatif
docs/GOV_SERVICES_WORKFLOW.md	Le modèle complet du processus de service public
docs/DOCUMENTS_SIGNING.md	La cérémonie de signature et son contrat
docs/TRANSLATION_GUIDE.md	Le guide de traduction en sept langues
CHANGELOG.md	Les changements par version