veza/docs/MONOREPO_ORCHESTRATION.md

# Orchestration et gestion du monorepo Veza

Ce document décrit la structure du Makefile modulaire et recommande des outils open source pour orchestrer le projet pendant son développement.

---

## 1. Structure actuelle du Makefile

### Organisation

| Fichier | Rôle |
|--------|------|
| **Makefile** | Point d’entrée unique ; inclut les fragments et définit le goal par défaut (`help`) |
| **make/config.mk** | **Source de vérité** : services, ports, chemins (SERVICE_DIR_*, PORT_*, COMPOSE_*, ROOT, etc.) |
| **make/ui.mk** | Couleurs et `ECHO_CMD` |
| **make/help.mk** | Cible `help` et dashboard |
| **make/tools.mk** | `check-tools`, `install-tools`, `install-deps`, `check-ports` |
| **make/infra.mk** | `infra-up`, `infra-down`, `db-migrate`, `db-shell`, `redis-shell` |
| **make/dev.mk** | `dev`, `dev-backend`, `dev-web`, `dev-<service>`, `stop-local-services` |
| **make/build.mk** | `build-*`, `build-all`, `build-all-native`, `build-service` |
| **make/test.mk** | `test`, `test-<service>`, `lint`, `lint-<service>`, `fmt`, `status` |
| **make/services.mk** | `start-service`, `stop-service`, `restart-service`, `logs-service` (Docker) |
| **make/high.mk** | `setup`, `stop-all`, `clean`, `deploy-docker`, `deploy-incus`, `status-full`, `web-minimal` |
| **make/incus.mk** | Toutes les cibles Incus (network, deploy, start, stop, status, logs) |

### Personnalisation

- **Ajouter un service** : dans `make/config.mk`, ajouter le nom dans `SERVICES`, puis définir `SERVICE_DIR_<nom>` et `PORT_<nom>` si besoin. Adapter les règles dans les `.mk` qui font du case-by-service (ex. `dev.mk`, `build.mk`).
- **Changer un port** : dans `make/config.mk` ou via `.env` (ex. `PORT_web=3000`).
- **Changer un chemin** : modifier `SERVICE_DIR_<service>` dans `make/config.mk`.
- **Override global** : utiliser `.env` (chargé par `config.mk` avec `-include .env`).

### Cibles par service

- `make dev-web`, `make dev-backend-api`, `make dev-chat-server`, `make dev-stream-server`
- `make test-web`, `make test-backend-api`, …
- `make lint-web`, `make lint-backend-api`, …
- `make build-service SERVICE=backend-api`

---

## 2. Outils open source recommandés

En complément (ou en partie en remplacement) du Makefile, ces outils peuvent aider à orchestrer le monorepo.

### 2.1 Turborepo (JS/TS)

- **Site** : [turbo.build](https://turbo.build)
- **Rôle** : Cache des tâches et pipeline de build/test/lint pour les workspaces npm.
- **Atouts** : Cache distant optionnel, parallélisation, `turbo run build --filter=./apps/web`, intégration CI simple.
- **Limites** : Ciblé npm/pnpm workspaces (apps/web, packages/design-system). Les backends Go/Rust restent gérés par le Makefile ou des scripts.
- **Usage typique** : `turbo run build`, `turbo run test --filter=web`, `turbo run lint`.

À envisager si tu veux un cache et un graphe de tâches fiable pour la partie Node/TS, tout en gardant Make pour l’infra et les backends.

---

### 2.2 Nx

- **Site** : [nx.dev](https://nx.dev)
- **Rôle** : Monorepo “full stack” : graphe de dépendances, cache, affected (build/test uniquement sur ce qui a changé), plugins (React, Node, Go, etc.).
- **Atouts** : Très flexible, “affected” puissant, support multi-langage (y compris Go via plugins ou custom targets).
- **Limites** : Plus lourd à configurer et à maintenir que Turborepo ; courbe d’apprentissage plus forte.

Utile si le monorepo grossit encore et que tu veux “affected”, cache partagé et une seule interface pour build/test/lint (y compris backends).

---

### 2.3 Just (command runner)

- **Site** : [github.com/casey/just](https://github.com/casey/just)
- **Rôle** : Remplacer une partie des cibles Make par un fichier `justfile` (syntaxe plus lisible, arguments nommés, pas de tabs).
- **Atouts** : Scripts lisibles, facile à partager entre devs, multiplateforme (Windows possible).
- **Limites** : Pas de vrai “graphe de tâches” ni cache ; plutôt un complément ou un remplacement léger du Make pour les commandes métier.

Exemple : `just dev`, `just test web`, `just deploy docker`.

---

### 2.4 Mise (ex-asdf)

- **Site** : [mise.jdx.dev](https://mise.jdx.dev)
- **Rôle** : Gestion des versions des runtimes (Node, Go, Rust, Python) au niveau du repo ou de la machine.
- **Atouts** : Un seul outil pour `.node-version`, `.go-version`, etc. ; reproductibilité des envs entre dev et CI.
- **Limites** : Ne remplace pas le Makefile ; il assure seulement que les bonnes versions sont actives.

Recommandé pour figer Node/Go/Rust et éviter les “ça marche chez moi”.

---

### 2.5 Tâche (Task)

- **Site** : [taskfile.dev](https://taskfile.dev)
- **Rôle** : Alternative au Make en YAML, avec variables, includes, dépendances entre tâches.
- **Atouts** : Syntaxe YAML, parallélisation, bon pour des pipelines déclaratifs.
- **Limites** : Un outil de plus ; si le Make modulaire te convient, pas obligatoire.

---

## 3. Synthèse

| Besoin | Outil suggéré |
|--------|----------------|
| Un seul endroit pour config (ports, services, chemins) | **make/config.mk** (déjà en place) |
| Cache + pipeline pour JS/TS uniquement | **Turborepo** |
| Affected + cache + multi-langage (y compris Go/Rust) | **Nx** |
| Commandes lisibles, peu de dépendance à Make | **Just** |
| Versions Node/Go/Rust reproductibles | **Mise** |
| Tout garder en Make mais mieux structuré | **Makefile + make/*.mk** (actuel) |

Recommandation pragmatique : garder le **Makefile modulaire** comme entrée principale (infra, dev, deploy, Incus). Si la partie frontend/npm devient la plus coûteuse (builds, tests, lint), ajouter **Turborepo** pour les workspaces npm et appeler `turbo` depuis le Makefile si besoin (ex. `make test` → infra-up + turbo run test + tests Go/Rust). Pour les versions des runtimes, **Mise** (ou asdf) dans le repo et en CI améliore la reproductibilité sans toucher au reste.