builazoo/docs/specs/tech_architecture.md

Spécifications Techniques : Architecture et Performance

1. Stack Technologique Recommandée

Backend

• Langage : Node.js (TypeScript) ou Go (pour la performance brute des workers).
• Framework : NestJS (Node) ou Gin (Go).
• Base de Données : PostgreSQL.
  • Utilisation intensive du type JSONB pour les données flexibles (états animaux, génétique).
  • Indexation GIN sur les champs JSONB souvent requêtés.

Frontend

• Framework : React ou Vue.js.
• État : Zustand ou Pinia (léger et performant).
• Rendu Grille : Canvas API (via PixiJS ou Konva) si > 100 éléments animés, sinon DOM optimisé (CSS Grid + Transforms).

Infrastructure

• Cache : Redis (pour les sessions, les compteurs temps réel et les files d'attente de jobs).
• Message Broker : BullMQ (Redis) ou RabbitMQ pour les tâches asynchrones (morts, naissances, enchères).

---

2. Modélisation des Données (Hybride Relationnel / Document)

L'approche hybride permet de garder l'intégrité référentielle sur les entités (Zoo, User) tout en gardant la souplesse sur les attributs de gameplay.

Schéma SQL Simplifié

CREATE TABLE zoos (
  id UUID PRIMARY KEY,
  owner_id UUID NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  resources JSONB DEFAULT '{"coins": 200, "research": 0}',
  stats JSONB DEFAULT '{"reputation": 0, "survival": 100}',
  last_update TIMESTAMPTZ DEFAULT NOW() -- Clé pour le Lazy Update
);

CREATE TABLE animals (
  id UUID PRIMARY KEY,
  zoo_id UUID REFERENCES zoos(id),
  type VARCHAR(50),
  birth_date TIMESTAMPTZ,
  state JSONB, -- { health, hunger, stress, ... }
  genetics JSONB, -- { color, rarity, parents... }
  position JSONB -- { x, y }
);

---

3. Stratégie de Performance : "Lazy Updates"

Le calcul temps réel pour 1000 joueurs * 50 animaux est impossible à scaler naïvement.

Principe

Ne jamais mettre à jour la BDD à chaque seconde ("tick"). Calculer l'état d'un zoo uniquement quand c'est nécessaire (lecture par le joueur ou interaction).

Algorithme de Mise à Jour Différée (Lazy Update)

1. État Stocké : Le zoo est sauvegardé à T0 avec Faim = 10.
2. Requête : Le joueur se connecte à T1 (2 heures plus tard).
3. Calcul à la Volée :
   • Delta_Temps = T1 - T0.
   • Faim_Actuelle = Faim_Initiale + (Vitesse_Faim * Delta_Temps).
   • Appliquer les seuils (si Faim > 100, déclencher Mort).
4. Persistance : Sauvegarder le nouvel état à T1.
5. Réponse : Envoyer l'état à jour au client.

Exceptions (Workers)

Certains événements doivent arriver même si le joueur est hors ligne (ex: Enchères, Morts impactant le marché).

• Utiliser des Cron Jobs ou des Delayed Jobs (Redis) pour traiter ces événements spécifiques à leur heure d'échéance prévue.

---

4. API : Définition des Endpoints (REST)

Core Loop (Jeu)

• GET /api/zoo/me : Récupère l'état complet du zoo (déclenche le Lazy Update).
• POST /api/zoo/move : Déplace un élément (Animal/Bâtiment).
  • Body: { "entity_id": "uuid", "x": 10, "y": 5 }
• POST /api/zoo/feed : Nourrit les animaux (Global ou Ciblé).

Économie & Marché

• GET /api/market/auctions : Liste les enchères actives (Filtres: Type, Rareté).
• POST /api/market/bid : Placer une offre.
  • Body: { "auction_id": "uuid", "amount": 500 }
• POST /api/market/sell : Créer une enchère.

Système

• POST /api/auth/login : Authentification par clé.
• GET /api/config : Récupère les tables statiques (Animaux, Coûts, Saisons) pour le cache client.

Annexes UX/UI

1. Expérience Utilisateur (UX)

Chargement (Feedback)

Description UX : Le joueur attend le calcul du Lazy Update à la connexion. Description UI : Écran de chargement avec barre de progression ou animation (Animal qui marche). Emplacement : Plein écran (Démarrage). Intégration : Bloquant. Navigation : N/A Événements : APP_LOAD.

Assets

• Musiques : Thème Principal.
• Sons : N/A
• Graphiques : Logo Jeu.
• Images : N/A
• Vidéos : N/A
• Animations : Loader.
• Couleurs : Thème Jeu.
• Textes : "Calcul de la simulation...", "Rattrapage du temps...".
• Formes : N/A

Erreur Connexion (Feedback)

Description UX : Perte de connexion ou erreur API. Description UI : Toast ou Modal "Erreur Réseau". Bouton "Réessayer". Emplacement : Overlay. Intégration : Bloquant ou Non-bloquant. Navigation : Clic Réessayer. Événements : NETWORK_ERROR.

Assets

• Musiques : N/A
• Sons : error.mp3.
• Graphiques : Icône Wifi barré.
• Images : N/A
• Vidéos : N/A
• Animations : Secousse.
• Couleurs : Rouge.
• Textes : "Connexion perdue".
• Formes : N/A