# 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-`, `stop-local-services` | | **make/build.mk** | `build-*`, `build-all`, `build-all-native`, `build-service` | | **make/test.mk** | `test`, `test-`, `lint`, `lint-`, `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_` et `PORT_` 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_` 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.