Gerege Nexus¶

Gerege Eco System · Plateforme privée

Gerege Nexus relie les organisations, services et utilisateurs de Gerege Eco System. Seuls les utilisateurs préalablement autorisés peuvent se connecter. eID vérifie l’identité ; l’administrateur de l’organisation accorde le droit d’accès.

Gerege Nexus est le socle constitué d’un backend Go, d’un web shell Next.js, d’une base de données PostgreSQL, d’un control plane pour l’opérateur et de clients natifs. Les applications métier sont ajoutées par un dépôt de distribution sous forme de modules Go compilés (compile-time). Ce dépôt de base n’est pas un paquet ERP prêt à l’emploi pour tous les secteurs.

Périmètre réel (2026-10-25) : catalog/apps.json est vide : le cœur n'embarque aucune app métier ; chaque app vient du catalogue d'une distribution. La dernière application, io.gerege.nexus.sso_clients, est partie le 2026-08-25 vers appstore-gerege-nexus, et toute distribution la récupère depuis le magasin d’applications. L’historique des migrations ou les traductions frontend d’applications telles que contacts, products, inventory, billing, documents, government workflow ou clients SSO peuvent subsister dans ce dépôt, mais leurs modules exécutables ne sont pas dans ce binaire de base. Les routes de ces applications ne s’ouvrent pas sur ce déploiement.

Монгол · العربية · 中文 · English · Français · Русский · Español

Ce que contient exactement ce dépôt¶

Partie	Implémentation actuelle
Tenant plane	Authentification, session, appartenance au locataire (tenant membership), RBAC, profil, installation/désinstallation d’applications, API IA, appareils, vérification d’e-mail, client/fournisseur SSO, moteur de rapports
Operator plane	Cycle de vie des locataires, connexion TOTP de l’opérateur, audit, support, quota/metering, feature flags, runtime settings/credentials, annonces, gestion des sauvegardes/déploiements
Application intégrée	Aucune. Chaque application arrive par le catalogue — depuis le départ de `sso_clients` le 2026-08-25, ce binaire ne contient plus aucune application métier
Web	Landing public, login/setup, profil, magasin d’applications, paramètres, control plane — le tout sur `@gerege-systems/ui` (Tailwind 4) ; les écrans d’applications (clients SSO, documents, contacts) restent dans le shell, inertes sans leur module
Natif	Shells macOS, iOS/iPadOS, Windows, Android ; PWA pour Linux
Observabilité	`/health`, `/ready`, `/metrics`, journaux structurés, OTLP/Sentry optionnels ; compose de monitoring séparé

La présence de routes, tables ou services de la plateforme de base ne signifie pas qu’une application métier visible par l’utilisateur existe. Les routes d’un module ne fonctionnent que lorsque ce module compilé implémente le contrat de pkg/nexus, est enregistré dans le binaire, figure au catalogue et est installé pour le locataire concerné.

Ce qui n’est pas dans ce binaire de base¶

Les applications métier contacts, products, inventory, billing
L’application départements/employés d’Organisation & People (le profil juridique de l’organisation sur /organisation reste toutefois une partie de la plateforme)
Le module backend Documents et l’UI de rapports. Un client frontend optionnel pour contract/inbox existe dans ce dépôt, mais l’API contract correspondante n’existe encore ni dans la base actuelle ni dans la distribution client-gerege-nexus ; tant que l’endpoint ne répond pas réellement, son lien n’apparaît pas sur le landing
L’UI/le module de workflow des services gouvernementaux
La station dans son intégralité — tableau de bord, canaux, API peer/exchange, contrat d’enveloppe. Sa dernière partie est partie vers client-gerege-nexus le 2026-08-27
Les connecteurs et webhooks vers des systèmes externes (Google Drive, Dropbox, Meet, URL du client). Partis également le 2026-08-27 ; seul le chiffrement de scellement des identifiants reste dans le cœur (nexus.SecretSealer). L’envoi automatique vers l’extérieur des documents signés a lui aussi été retiré du cœur
Un circuit breaker adaptatif générique, singleflight, un moteur de retry générique

Certains de ces éléments ont été séparés dans des dépôts de distribution produit. Voir docs/MODULES.md pour la façon dont un module est écrit et arrive par le catalogue, docs/DISTRIBUTION.md pour la façon dont une distribution récupère et met à jour le cœur, et docs/ARCHITECTURE.md pour l’architecture actuelle.

Capacités principales¶

SDK de modules compilés : contrats de route, permission, menu, dépendance, migration, rapport, outil IA et capability.
Installation d’applications et contrôle RBAC par locataire. Une route de module non installé/désactivé renvoie 403.
Catalogue local ou catalogue distant signé Ed25519 ; repli sur le cache et synchronisation manuelle/en arrière-plan.
Connexion par mot de passe, eID, DAN, Google et OIDC amont ; également fournisseur OAuth2/OIDC.
Schémas PostgreSQL workspace, registry, operator, protection RLS/rôles.
Lorsque Redis est configuré, invalidation du cache entre réplicas et rate limit partagé ; sinon, repli sur un seul processus.
Délestage (load shedding) des requêtes concurrentes. Chaque client externe a sa propre politique de timeout/retry ; un circuit breaker générique inexistant n’est pas considéré comme faisant partie de la plateforme.
Avec une clé Gemini : chat, speech-to-text, text-to-speech, traduction. Les outils IA sur les données métier sont enregistrés par le module de distribution lui-même ; le déploiement de base n’invente ni ne renvoie de chiffres d’inventory ou de billing.
Design system : le web shell et la console reposent sur @gerege-systems/ui, dont le theme.css est l’unique source des tokens. Chaque déploiement modifie son apparence sans toucher au code, via les variables d’environnement BRAND_THEME_* et le CSS « Get code » de ui.gecore.mn/#theme (DEVELOPMENT.md).
Les clients E-ID, DAN et ХУР existent dans la plateforme. En environnement production, le mock est désactivé par défaut ; utiliser les services réels exige les credentials de chacun.

Structure du dépôt¶

backend/
  cmd/                  outils api, migrate, bootstrap, catalog
  db/migrations/        migrations PostgreSQL de base
  internal/kernel/      mécanismes bas niveau communs aux trois plans
  internal/operator/    deployment/operator plane
  internal/workspace/   plan agissant au nom d'une organisation
  internal/person/      espace propre à la personne — /api/v1/me
  internal/apps/        point d'assemblage des distribution modules (vide pour l'instant)
  pkg/nexus/            SDK public des distribution modules
  pkg/host/             entry point public qui démarre un distribution binary
frontend/               Next.js web shell et UI du control plane
catalog/                catalogue de base, manifests, chronicle
native-apps/            clients macOS, iOS/iPadOS, Windows, Android
deploy/                 image, compose, nginx, monitoring
docs/                   index des documents actuels, historiques et propositions

Démarrage¶

Prérequis¶

Docker Compose, ou
Go 1.26+, Node.js 20+, PostgreSQL 16+

Docker Compose¶

docker compose up -d
docker compose ps

Compose démarre PostgreSQL, Redis, une migration à usage unique, le backend et le frontend. Les adresses suivantes sont utilisées :

Web du locataire : http://nexus.localhost:3000
Web du control plane : http://admin.localhost:3000
Santé de l’API : http://localhost:8080/health

Compte de démonstration de développement :

Champ	Valeur
E-mail	`admin@example.com`
Mot de passe	`Password123!`
Locataire	`Demo Corporation` (`demo`)

SEED_DEMO_DATA est activé par défaut dans tout environnement autre que la production. En production, le compte de démonstration n’est pas créé sans true explicite.

Manuellement¶

Démarrez d’abord PostgreSQL (et Redis si nécessaire), puis :

cd backend
go mod download
DATABASE_URL="postgres://postgres:postgrespassword@localhost:5432/platform_db?sslmode=disable" \
  go run ./cmd/migrate up

PUBLIC_ORIGIN=http://nexus.localhost:3000 \
ALLOWED_ORIGINS=http://nexus.localhost:3000,http://admin.localhost:3000 \
CONTROL_PLANE_HOST=admin.localhost \
  go run ./cmd/api

Dans un autre terminal :

cd frontend
npm ci
CONTROL_PLANE_HOST=admin.localhost \
NEXT_PUBLIC_API_URL=http://nexus.localhost:8080/api/v1 \
NEXT_PUBLIC_CONTROL_PLANE_API_URL=http://admin.localhost:8080/api/platform/v1 \
  npm run dev

Ne devinez pas la configuration de production à partir du README. Suivez .env.example pour la liste complète des variables et leurs valeurs par défaut sûres, proxmox-gerege-net (stack/nexus) pour la configuration du déploiement en service, et docs/OPERATIONS.md pour les étapes de création du premier locataire/opérateur.

Sources de vérité de l’API et du catalogue¶

La liste d’API d’un README n’est pas un contrat complet. Les sources vérifiées avec le code :

Snapshot des routes de la plateforme : backend/pkg/host/testdata/routes.txt
Snapshot de l’API publique du SDK de modules : backend/pkg/nexus/testdata/api.txt
Catalogue de base : catalog/apps.json (passerelle API seule)
Contrat SSO du SDK de modules : backend/pkg/nexus/ssoclients.go
Configuration : .env.example

Les endpoints publics de base comprennent /health, /ready, /metrics, auth, setup, OAuth2/OIDC, magasin d’applications, enrôlement d’appareils et vérification d’e-mail. Les routes exigeant une session de locataire, les routes du control plane et les routes de modules sont protégées séparément.

Tests¶

cd backend
go test ./...
go vet ./...

cd ../frontend
npm ci
npm test
npm run lint
npm run build

La CI y ajoute des tests de race adossés aux migrations, les frontières API/routes, PWA, host, le rapport des lacunes de traduction, le build Docker, govulncheck, gosec et le build des clients natifs. Voir .github/workflows/ci.yml, security.yml et native-clients.yml pour les commandes exactes exécutées.

Langues et statut de la documentation¶

Les chaînes sources de l’UI sont en mongol et en anglais ; des overlays arabe, chinois, français, russe et espagnol existent. Un overlay incomplet se replie sur l’anglais et la CI signale les lacunes — il n’est pas promis que chaque écran soit traduit à 100 %.

Le README existe en sept langues. Chaque document technique n’a pas nécessairement sept traductions ; la langue et le statut de chaque fichier sont indiqués dans docs/README.md. Les fichiers nommés PLAN, PROPOSAL, PROMPT, WORKLOG ne constituent pas le contrat runtime actuel. Ils ne doivent pas servir, à eux seuls, de source pour les instructions d’exploitation.

Sécurité et statut du projet¶

Ne publiez pas les vulnérabilités dans une issue publique ; utilisez la procédure de signalement privé de SECURITY.md.