Serveurs et API

Documentation des serveurs, API, authentification, accès aux données, configuration des environnements et services backend.

Serveur principal NestJS

Rôle

Le backend Web principal est une application NestJS située dans uniksim-back-end/. Elle centralise les API utilisateur, jeu, administration, support, notifications, push, mail et IA.

Démarrage

Le point d’entrée est src/main.ts.

Assemblage du backend

src/app.module.ts branche les principaux sous-systèmes :

Contrôleurs importants

Administration : API NestJS et Admin Server Express

Vue d’ensemble

L’administration backend d’Uniksim repose sur deux couches distinctes qu’il ne faut pas confondre :

  1. les routes d’administration de l’API NestJS principale, protégées par des guards et reliées aux services backend;
  2. un serveur Express d’administration séparé dans uniksim-back-end/src/node.js/server/admin_server.js, qui écoute localement sur le port 8105 et gère surtout des opérations historiques/BrainCloud et certains flux SSE.

Architecture backend d’administration

flowchart LR
    CLIENT[Clients Web / outils internes] --> NEST[NestJS principal]
    CLIENT --> EXPRESS[Admin Server Express :8105]

    NEST --> AC[AdminController]
    NEST --> AUC[AdminUserController]
    NEST --> APC[AdminPresenceController]
    NEST --> SAC[SupportAdminController]

    AC --> AS[AdminService]
    AUC --> AUS[AdminUserService]
    APC --> PS[PresenceService]

    AS --> DB[(MySQL / TypeORM)]
    AUS --> DB
    PS --> REDIS[(Redis)]

    EXPRESS --> BC[BrainCloud]
    EXPRESS --> REDIS
    EXPRESS --> SSE[SSE / copie de simulations]

1. Administration dans l’API NestJS

Les contrôleurs d’administration sont regroupés dans uniksim-back-end/src/app.controller.ts et enregistrés dans AppModule.

La logique métier correspondante se trouve notamment dans src/service/admin.service.ts, src/service/adminUser.service.ts et src/service/presence.service.ts.

2. Admin Server Express séparé

Le fichier src/node.js/server/admin_server.js démarre un serveur Express distinct sur ConstantsInUse.ADMIN_SERVER_PORT, actuellement 8105. Son URL locale de référence est définie par ADMIN_SERVER_URL dans constantsVariable.js.

Ce serveur est utilisé notamment pour :

Flux d’une commande Admin Server

sequenceDiagram
    participant C as Client / outil admin
    participant E as Admin Server Express
    participant B as BrainCloud
    participant R as Redis
    participant S as Flux SSE

    C->>E: Requête admin
    alt Commande BrainCloud
        E->>B: Exécute la commande
        B-->>E: Résultat
    else Commande Redis
        E->>R: redisBulkCommands(...)
        R-->>E: Résultat
    else Copie de simulation
        E->>B: Copie données / simulation
        E-->>S: Progression
        S-->>C: Événements SSE
    end
    E-->>C: Réponse

Sécurité backend

Les routes NestJS utilisent notamment AuthGuardAdmin et AuthGuardAdminUser. Toute modification d’une route d’administration doit vérifier le guard attendu et le rôle autorisé.

Fichiers principaux

Authentification et guards

Vue d’ensemble

L’authentification combine JWT côté backend et des guards côté backend et frontend.

Backend

Frontend

Les guards Angular sont dans uniksimFrontEnd/src/app/service/auth/. Les routes sont protégées directement dans app.module.ts.

AuthInterceptorService est enregistré comme HTTP_INTERCEPTORS afin d’appliquer la logique d’authentification aux appels HTTP.

Connexion

LoginController expose notamment signIn, signUp et le login spécial Chenelière. La logique métier correspondante se trouve dans src/service/login.service.ts.

Socket.IO et notifications du jeu

socketAuthMiddleware est installé sur /account et /support. Il vérifie le JWT avant tout handler puis stocke le payload dans client.data.user. Le token peut venir de handshake.auth.token, de la query ou de Authorization. Angular envoie auth: { token } via le transport commun RealtimeSocket.

Les rooms support sont soumises à l’appartenance à la conversation; typing exige d’avoir rejoint la room et checkOnline limite les non-admins à leurs admins assignés. Les sockets de présence appartiennent au namespace compte.

POST /saveNotification utilise AuthGuardUser. GameNotificationService vérifie le profil actif destinataire et les membres de la simulation BrainCloud; les types réservés au serveur sont refusés. Les routes d’inbox et d’installations FCM dérivent le compte de request.user.sub.

Configuration, environnements et constantes

Vue d’ensemble

La configuration backend est principalement répartie entre les fichiers d’environnement et uniksim-back-end/src/node.js/server/constantsVariable.js. Ce fichier centralise de nombreuses valeurs utilisées par les serveurs, les intégrations et les règles métier.

Ne jamais recopier de secrets dans le wiki. Le fichier contient des clés, mots de passe et credentials qui doivent rester dans le code ou une configuration sécurisée et ne doivent pas être documentés en clair.

Fichiers d’environnement

Les scripts de démarrage du backend sélectionnent explicitement l’un de ces fichiers via node --env-file ... dist/main.

constantsVariable.js

Le fichier src/node.js/server/constantsVariable.js sert de registre central pour plusieurs familles de constantes.

ConstantsInUse

ConstantsInUse agit comme configuration runtime commune. Elle contient notamment la base ciblée, le host SQL, le port SQL, le serveur courant, l’URL du site, la version WebGL locale et les ports des serveurs auxiliaires.

Lorsqu’un bug apparaît uniquement en dev/demo/live, ce bloc est un des premiers endroits à vérifier avec le fichier .env correspondant.

Frontend

Côté Angular, uniksimFrontEnd/src/environments/environment.ts définit notamment les URLs de serveur utilisables et le backend attendu.

Points d’attention

Configuration IA et temps réel actuelle

Au 30 septembre 2026 : GOOGLE_CLOUD_PROJECT est requis pour Vertex AI; GOOGLE_CLOUD_LOCATION vaut global par défaut et cette location est imposée par la politique tarifaire actuelle. L’authentification utilise les credentials Google par défaut de l’environnement. Chroma Cloud utilise les variables CHROMA_API_KEY, CHROMA_TENANT et CHROMA_DATABASE; la collection est game. Ne pas recopier leurs valeurs ici.

AI_MODELS configure gemini-3.5-flash-lite et gemini-embedding-001. AI_PRICE_VERSIONS référence vertex-global-standard-2026-09-29; THINKING_LEVEL vaut LOW. Le provider de génération et celui d’embedding restent indépendants. Le serveur IA écoute sur loopback; son token interne protège les opérations query/summary.

NOTIFICATION_CONFIG fixe le suffixe _notifications, la taille maximale de l’inbox (100), sa rétention (10 519 200 secondes), les types serveur réservés et la taille du payload client (2 048 caractères). Les constantes Angular sont séparées dans realtime.constants.ts (transport), account.constants.ts (activité du compte) et support.constants.ts (support).

Base de données et persistance

Vue d’ensemble

Le backend utilise principalement MySQL via TypeORM pour les données relationnelles, et Redis pour plusieurs données temporaires ou temps réel.

Architecture de persistance

flowchart TD
    API[NestJS Controllers] --> SERVICES[Services métier]
    SERVICES --> ORM[TypeORM]
    ORM --> MYSQL[(MySQL)]

    SERVICES --> REDIS[RedisService]
    REDIS --> CACHE[(Redis)]

    SERVICES --> BC[BrainCloud]

    MYSQL --> E1[Users / rôles]
    MYSQL --> E2[Produits / codes]
    MYSQL --> E3[Support]
    MYSQL --> E4[FCM installations]

    CACHE --> R1[Présence]
    CACHE --> R2[Sessions]
    CACHE --> R3[Notifications]
    CACHE --> R4[Rankings / données temps réel]

Configuration TypeORM

Le point central est uniksim-back-end/src/database.providers.ts.

La connexion est créée avec TypeOrmModule.forRoot(...) et utilise :

Le backend est configuré avec synchronize: false. Les changements de schéma ne doivent donc pas être supposés automatiques.

Entités principales

Les entités TypeORM sont dans uniksim-back-end/src/entities/. Parmi les principales :

Redis

Redis n’est pas seulement un cache. Il est utilisé pour plusieurs fonctions runtime importantes, notamment :

Choisir le bon stockage

flowchart LR
    CHANGE[Besoin métier] --> ENTITY{Donnée relationnelle ?}
    ENTITY -- Oui --> MODEL[Entity TypeORM]
    MODEL --> ORM[Repository / Service]
    ORM --> SCHEMA[Vérifier schéma SQL / migration]

    ENTITY -- Non --> RUNTIME{Temporaire ou temps réel ?}
    RUNTIME -- Oui --> REDIS[RedisService]
    RUNTIME -- Non --> OTHER[Vérifier BrainCloud / stockage existant]

Points d’attention

Évolution de la persistance des notifications

Au 30 septembre 2026, les entités enregistrées dans database.providers.ts comprennent UserFcmToken, sans modèle de subscription par produit. Une installation appartient au compte; les push ciblent toutes ses installations. L’inbox Redis user_<id>_notifications est bornée à 100 entrées; son TTL de 10 519 200 secondes est renouvelé à chaque insertion. NotificationService possède maintenant la logique d’inbox; les anciennes fonctions de notification dans server.js ont été retirées. Voir Notifications et Push.

Build et déploiement Web

Vue d’ensemble

Le frontend Angular et le backend NestJS sont déployés ensemble. Le build Angular de production écrit directement dans le backend, puis le backend est compilé et démarré avec l’environnement voulu.

Pipeline de build

flowchart TD
    A[uniksimFrontEnd] -->|npm run build| B[uniksim-back-end/src/front]
    B -->|npm run build dans le backend| C[uniksim-back-end/dist]
    C -->|npm run start:demo| D[Node + demo.env]
    D --> E[sim.dev.uniksim.com]

Pourquoi le frontend apparaît dans le backend

Dans uniksimFrontEnd/angular.json, la configuration de production utilise :

outputPath: ../uniksim-back-end/src/front

Le dossier src/front contient donc le résultat compilé d’Angular. Ce n’est pas un dossier frontend à modifier manuellement.

Lors du build NestJS, ces fichiers sont ensuite disponibles dans le build backend, et ServeStaticModule les sert au navigateur.

Serveur de développement hébergé

L’instance de développement est accessible via sim.dev.uniksim.com sur l’infrastructure DigitalOcean.

Le workflow serveur utilisé actuellement est :

  1. Se connecter au serveur DigitalOcean.
  2. Passer sur l’utilisateur forge avec sudo -u forge ou la commande équivalente utilisée sur le serveur.
  3. Aller dans le dossier du site avec cd sim.dev.uniksim.com.
  4. Mettre le code à jour.
  5. Builder le frontend Angular avec npm run build dans uniksimFrontEnd.
  6. Builder le backend NestJS avec npm run build dans uniksim-back-end.
  7. Démarrer le backend avec npm run start:demo.

Ordre de build

sequenceDiagram
    participant D as Développeur
    participant F as Angular
    participant B as Backend NestJS
    participant N as Node demo
    participant W as sim.dev.uniksim.com

    D->>F: npm run build
    F-->>B: Génère src/front
    D->>B: npm run build
    B-->>N: Génère dist
    D->>N: npm run start:demo
    N->>N: Charge demo.env
    N-->>W: Sert API + frontend compilé

Scripts backend disponibles

Points d’attention

Conventions de sécurité Web

But

Cette page résume les mécanismes de sécurité réellement présents dans le projet. Elle ne remplace pas un audit de sécurité; elle sert de guide pour éviter de contourner les protections existantes lorsqu’on ajoute une feature.

Authentification et autorisation

Le backend utilise des JWT et plusieurs guards spécialisés :

Les tokens peuvent être lus depuis l’en-tête Authorization: Bearer ... ou, selon le flux, depuis le cookie token. Les guards backend restent la source d’autorité; les guards Angular servent surtout à contrôler la navigation.

Flux d’autorisation

sequenceDiagram
    participant C as Client
    participant G as Guard NestJS
    participant J as JwtService
    participant E as Endpoint

    C->>G: Requête + token
    G->>J: Vérifie signature / expiration
    J-->>G: Payload
    G->>G: Vérifie rôle si nécessaire
    alt Autorisé
        G->>E: Continue
        E-->>C: Réponse
    else Refusé
        G-->>C: 401 Unauthorized
    end

Configuration HTTP

Dans src/main.ts :

Uploads du support

SupportAttachmentService applique plusieurs contrôles avant de stocker ou servir une image :

Sécurité des fichiers

flowchart TD
    U[Upload] --> BIN[Valider signature binaire]
    BIN --> SIZE[Vérifier dimensions / taille]
    SIZE --> NORMAL[Normaliser en WebP]
    NORMAL --> NAME[Générer nom aléatoire]
    NAME --> QUOTA[Vérifier quotas]
    QUOTA --> SAVE[Écrire avec création exclusive]

    READ[Lecture] --> PATH[Vérifier nom / chemin]
    PATH --> OWNER[Vérifier conversation + utilisateur]
    OWNER --> FILE[Servir le fichier]

Secrets et configuration

Le projet contient encore des secrets historiques dans la configuration. Ils ne doivent jamais être copiés dans le wiki, le frontend ou les logs. Toute nouvelle intégration devrait préférer les fichiers d’environnement ou une gestion de secrets dédiée plutôt qu’ajouter une nouvelle clé en clair dans le code.

IA et contrôle d’usage

Le système IA possède des limites de requêtes, budgets, timeouts et plafonds de tokens configurés dans AI_CONFIG. Le dossier src/node.js/server/ai/guard/ contient également la logique de garde liée aux coûts.

Checklist pour une nouvelle route