📚 Documentation CerOps

Les capteurs declares sur un profil pilote referencent sensor_kind via sensor_kind_code. Les missions declarent leurs capteurs requis via la relation explicite mission_required_sensor.

Les contrats API peuvent exposer des champs derives comme type ou requiredSensors pour l’ergonomie des clients, mais la source de verite est la base de donnees.

La migration 20260428112000_persist_sensor_kinds cree les capteurs standards, puis 20260428114500_remove_sensor_type_enum supprime l’ancien enum et les colonnes associees. Les procedures API qui creent ou synchronisent des capteurs appellent aussi un helper d’amorcage idempotent, afin de garder les environnements de developpement initialises avec db push utilisables.

🎯 [Nom du module]

Contexte

Décrire le rôle de ce module dans CerOps.

Objectif

Quel problème ce module résout ?

Utilisateurs concernés

Agriculteur
Pilote de drone
Admin
Autre ?

Fonctionnalités (User Stories)

En tant que …, je veux …, afin de …

Données manipulées

Entités
Champs importants
Relations

API / Interfaces

Endpoints concernés
Inputs / outputs

Écrans / UX

Pages / composants liés
Comportements attendus

Cas limites

Offline ?
Erreurs ?
Données manquantes ?

Critères d’acceptation

Dépendances

Backend
Mobile
Drone
Autres modules

MVP vs Post-MVP

MVP

Post-MVP

Pricing

Contexte

Le pricing actuel des missions est calcule cote serveur dans packages/api/src/routers/missions/pricing.ts. Le calcul est volontairement simple et deterministe :

une configuration globale de mission fournit les montants communs a toutes les missions ;
chaque option d’analyse peut ajouter un forfait fixe et/ou un prix variable par hectare ;
un minimum de mission peut relever le total final si le sous-total est trop bas.

L’objectif est de conserver le serveur comme source de verite du prix et de produire un detail exploitable pour l’UI, l’audit et les tests.

Donnees d’entree

Le calcul repose sur deux objets :

1. `MissionPricingInput`

totalSurface Surface totale de la mission.
analysisOptions Liste des options d’analyse selectionnees.

Chaque option d’analyse contient :

id
code
name
basePrice
pricePerHa

2. `MissionPricingConfig`

La configuration globale de pricing contient :

id
name
missionBasePrice Forfait applique une fois par mission.
missionPricePerHa Prix de base applique par hectare.
minimumMissionPrice Montant minimum facture pour la mission.

Algorithme actuel

La fonction calculateMissionPrice(input, pricingConfig) applique les regles suivantes dans cet ordre :

Validation des donnees
Ajout du forfait mission
Ajout du prix mission par hectare
Ajout des lignes de chaque option d’analyse
Calcul du sous-total
Ajout eventuel d’un ajustement de minimum
Calcul du total final

1. Validation

Le calcul rejette :

une totalSurface negative ou non finie ;
un montant negatif ou non fini dans la configuration globale ;
un montant negatif ou non fini sur une option d’analyse.

null et undefined sont acceptes pour basePrice et pricePerHa sur les options. Ils sont traites comme 0.

2. Forfait mission

Si missionBasePrice > 0, une ligne est ajoutee :

quantity = 1
unitPrice = missionBasePrice
amount = missionBasePrice

3. Prix mission par hectare

Si missionPricePerHa > 0, une ligne est ajoutee :

quantity = totalSurface
unitPrice = missionPricePerHa
amount = missionPricePerHa * totalSurface

4. Options d’analyse

Pour chaque option :

si basePrice > 0, une ligne forfaitaire est ajoutee ;
si pricePerHa > 0, une ligne surfacique est ajoutee.

Autrement dit, la formule d’une option est :

optionTotal = (basePrice ?? 0) + (pricePerHa ?? 0) * totalSurface

5. Sous-total

Le sous-total correspond a la somme des amount de toutes les lignes generees avant application du minimum.

6. Minimum mission

Si minimumMissionPrice > subtotal, une ligne supplementaire est ajoutee pour combler l’ecart :

minimumAdjustment = minimumMissionPrice - subtotal

Cette ligne ne remplace pas les autres. Elle s’ajoute au detail pour rendre l’ajustement visible.

7. Arrondi

Chaque montant est arrondi a 2 decimales via roundMoney. Le total final est lui aussi recalcule a partir des lignes et arrondi a 2 decimales.

Structure de sortie

La fonction retourne :

totalPrice
lineItems

Chaque lineItem contient :

type
code
label
quantity
unitPrice
amount

Role de `type` et `code`

Aujourd’hui, type et code ne configurent pas le prix. Ils decrivent les lignes produites par le calcul.

`type`

type categorise la nature metier de la ligne :

mission_base forfait global de mission ;
mission_surface prix de base par hectare ;
mission_minimum_adjustment ajustement applique pour atteindre le minimum ;
analysis_option ligne issue d’une option d’analyse.

type est utile pour :

grouper ou afficher les lignes dans le front ;
reconnaitre les categories de cout dans les tests ;
garder une semantique stable cote API.

Mais type n’est pas lu comme une regle dynamique de pricing. Il est derive par le code, pas saisi en base pour piloter l’algorithme.

`code`

code identifie plus precisement la ligne.

Pour les lignes globales de mission, les codes sont statiques :

mission-base
mission-surface
mission-minimum-adjustment

Pour les options d’analyse, le code est derive du code de l’option :

${analysisOption.code}:base
${analysisOption.code}:surface

Exemples :

hydrometrie:base
hydrometrie:surface
azote:base

code sert donc a :

rattacher une ligne a une option precise ;
differencier la part forfaitaire et la part surfacique d’une meme option ;
produire un identifiant stable pour le recapitulatif ou d’eventuels traitements aval.

Comme type, code est aujourd’hui une sortie descriptive, pas un parametre de configuration du calcul.

Ce qui configure reellement le prix aujourd’hui

Les vraies entrees de configuration sont :

dans MissionPricingConfig missionBasePrice, missionPricePerHa, minimumMissionPrice ;
dans AnalysisOption basePrice, pricePerHa ;
dans l’entree de calcul totalSurface et la liste des options selectionnees.

En pratique :

changer missionBasePrice change la ligne mission_base ;
changer missionPricePerHa change la ligne mission_surface ;
changer minimumMissionPrice change l’eventuelle ligne mission_minimum_adjustment ;
changer analysisOption.basePrice ou analysisOption.pricePerHa change les lignes analysis_option correspondantes ;
changer analysisOption.code ne change pas la formule, mais change le code retourne dans les lignes ;
changer analysisOption.name ne change pas la formule, mais change le label retourne.

Exemple complet

Avec :

totalSurface = 12.5
missionBasePrice = 50
missionPricePerHa = 2
minimumMissionPrice = 0
option Hydrometrie basePrice = 120, pricePerHa = 4.5, code = hydrometrie
option Azote basePrice = 90, pricePerHa = 3.2, code = azote

Le detail produit est :

mission_base code mission-base montant 50
mission_surface code mission-surface montant 25
analysis_option code hydrometrie:base montant 120
analysis_option code hydrometrie:surface montant 56.25
analysis_option code azote:base montant 90
analysis_option code azote:surface montant 40

Total :

50 + 25 + 120 + 56.25 + 90 + 40 = 381.25

Cycle de vie de la configuration globale

L’administration du pricing global passe par packages/api/src/routers/pricing/router.ts.

Une configuration :

est creee en DRAFT ;
peut etre modifiee tant qu’elle reste en DRAFT ;
peut etre publiee ;
peut etre archivee.

Contraintes actuelles :

seule une configuration DRAFT peut etre modifiee ;
publier une configuration archive automatiquement toute configuration deja PUBLISHED ;
une configuration ARCHIVED ne peut plus etre re-archivee utilement.

Les schemas d’entree packages/api/src/schemas/pricing/schemas.ts imposent :

un name non vide, max 120 caracteres ;
des montants numeriques positifs ou nuls ;
des montants exprimes en EUR avec jusqu’a 2 decimales selon la convention documentee.

Limites du modele actuel

Le modele actuel fonctionne bien pour un pricing compose de :

forfait mission ;
prix mission par hectare ;
forfait par option ;
prix par hectare par option ;
minimum de mission.

En revanche, type et code ne permettent pas a eux seuls de rendre le pricing dynamique. Ils restent de simples marqueurs de sortie.

Si demain le projet veut rendre le modele tarifaire reellement configurable, il faudra introduire un moteur de regles versionne en base, avec des kind metier interpretes par le serveur, plutot que de transformer type ou code en champs libres pilotant le calcul.

🎯 [Nom du module]

Contexte

Décrire le rôle de ce module dans CerOps.

Objectif

Quel problème ce module résout ?

Utilisateurs concernés

Agriculteur
Pilote de drone
Admin
Autre ?

Fonctionnalités (User Stories)

En tant que …, je veux …, afin de …

Données manipulées

Entités
Champs importants
Relations

API / Interfaces

Endpoints concernés
Inputs / outputs

Écrans / UX

Pages / composants liés
Comportements attendus

Cas limites

Offline ?
Erreurs ?
Données manquantes ?

Critères d’acceptation

Dépendances

Backend
Mobile
Drone
Autres modules

MVP vs Post-MVP

MVP

Post-MVP

🎯 Stratégie Offline Mobile

Contexte

L’application mobile CerOps est utilisée en plein champ, souvent sans connexion réseau. Le mode offline permet de consulter et modifier les données sans internet, puis de synchroniser au retour de la connectivité.

Objectif

Permettre à l’utilisateur de travailler hors ligne sur ses parcelles et actions, avec synchronisation automatique à la reconnexion.

Utilisateurs concernés

Agriculteur
Pilote de drone

Fonctionnalités (User Stories)

En tant qu’agriculteur, je veux consulter mes parcelles et actions sans connexion.
En tant qu’agriculteur, je veux créer et modifier des actions hors ligne, afin qu’elles soient synchronisées à la reconnexion.
En tant qu’utilisateur, je veux télécharger une zone de carte à l’avance pour naviguer hors ligne.
En tant qu’utilisateur, je veux savoir quelles données ne sont pas encore synchronisées.

Données manipulées

Ce qui est mis en cache offline

Donnée	Faisabilité	Stratégie
Parcelles (métadonnées)	✅ Oui	Cache complet
Actions / tâches	✅ Oui	Cache complet + mise à jour optimiste
Missions de vol (métadonnées)	✅ Oui	Cache métadonnées uniquement
Tuiles de carte	✅ Oui (par zone)	Téléchargement à la demande (FMTC)
Imagerie NDVI	⚠️ Sélectif	Miniatures uniquement, à la demande
Images brutes drone	❌ Non	Serveur uniquement

Champs offline ajoutés à chaque entité

needsSync (bool) : modification locale en attente de synchronisation
lastModifiedAt (DateTime) : horodatage pour la résolution de conflits

Choix technologique

Base de données locale : Drift

Drift (SQLite ORM) est retenu pour les raisons suivantes :

Requêtes filtrées typées à la compilation (SQL)
Streaming natif compatible Riverpod (watch() → StreamProvider)
Migrations de schéma versionnées — évolutions du modèle sans perte de données
Transactions atomiques pour la cohérence lors des synchronisations
Multi-plateforme : Android, iOS, Web, Desktop

Hive (clé-valeur) a été écarté : pas de migrations natives, pas de streaming filtré, scan mémoire O(n) pour les requêtes.

Détection de connectivité : connectivity_plus

Détecte les changements Wi-Fi / données mobiles. Note : connexion détectée ≠ internet disponible — tous les appels API restent protégés par timeout.

Cartes offline : flutter_map_tile_caching (FMTC)

Téléchargement de tuiles par zone géographique délimitée. Zoom 15–17, environ 15–30 Mo par zone de 5 km². Expiration à 30 jours.

Licence GPL — à vérifier avant intégration en production.

Résolution de conflits

Stratégie : Last-Write-Wins basée sur lastModifiedAt.

Modification locale plus récente → envoyée au serveur
Version serveur plus récente → écrase la version locale
En cas d’égalité → version serveur prime

Écrans / UX

Bannière discrète quand l’application est hors ligne
Indicateur visuel sur les éléments avec needsSync: true
Notification au retour de la connectivité : « X éléments synchronisés »
Écran de téléchargement de zone carte (accessible depuis les paramètres)

Cas limites

Premier démarrage sans connexion : impossible — le cache est vide, l’utilisateur doit se connecter une première fois.
Session expirée hors ligne : l’utilisateur travaille jusqu’à expiration du token, aucune re-authentification possible sans réseau.
Stockage insuffisant : erreur explicite, téléchargement annulé.
Entité référencée absente du cache : placeholder affiché, pas d’erreur fatale.
Évolution du schéma : migration Drift, aucune perte de données.

Critères d’acceptation

L’application démarre sans connexion et affiche les données du cache.
Les parcelles et actions sont lisibles hors ligne.
Une action créée hors ligne est sauvegardée localement et synchronisée à la reconnexion.
Le statut d’une action modifié hors ligne est mis à jour immédiatement (optimiste) et synchronisé à la reconnexion.
Les éléments non synchronisés sont visuellement distingués.
Une zone de carte peut être téléchargée et consultée hors ligne.
Une mise à jour de l’application ne perd pas les données locales.

Dépendances

Packages Flutter

Package	Usage
`drift` + `drift_flutter`	Base de données locale SQLite
`drift_dev` + `build_runner`	Génération de code (dev uniquement)
`connectivity_plus`	Détection de connectivité
`flutter_map_tile_caching`	Cache de tuiles carte (GPL)

Backend

Aucun endpoint spécifique offline requis au MVP.
Chaque entité doit exposer updatedAt pour la résolution de conflits LWW.
Post-MVP : endpoint delta-sync (entités modifiées depuis un timestamp).

MVP vs Post-MVP

MVP

Cache Drift pour parcelles et actions (lecture + écriture hors ligne)
Synchronisation manuelle au retour de la connexion (pull-to-refresh / démarrage)
Mise à jour optimiste pour les actions
Indicateur visuel offline + éléments en attente de sync
Téléchargement de tuiles par zone (FMTC)
Résolution de conflits Last-Write-Wins

Post-MVP

Synchronisation automatique en arrière-plan (workmanager, toutes les 20 min)
Delta-sync depuis un timestamp
Cache miniatures NDVI à la demande
Gestion automatique de l’espace disque
Notification push pour déclencher une sync depuis le serveur

🎯 [Nom du module]

Contexte

Décrire le rôle de ce module dans CerOps.

Objectif

Quel problème ce module résout ?

Utilisateurs concernés

Agriculteur
Pilote de drone
Admin
Autre ?

Fonctionnalités (User Stories)

En tant que …, je veux …, afin de …

Données manipulées

Entités
Champs importants
Relations

API / Interfaces

Endpoints concernés
Inputs / outputs

Écrans / UX

Pages / composants liés
Comportements attendus

Cas limites

Offline ?
Erreurs ?
Données manquantes ?

Critères d’acceptation

Dépendances

Backend
Mobile
Drone
Autres modules

MVP vs Post-MVP

MVP

Post-MVP

Import RPG

Les données géométriques des parcelles de la France entière sont disponibles via le RPG, maintenu par le Ministère de l’Agriculture.

Chaque année, une nouvelle version est publiée sous forme d’archives .7z découpées en plusieurs parties (ex. RPG_2024_Ile-de-France.7z.001, RPG_2024_Ile-de-France.7z.002, etc.).

Chaque archive contient un fichier GeoPackage (.gpkg) avec les données parcellaires d’une région spécifique.

Concepts métier

Terme	Signification
Dataset	Collection annuelle (ex. “RPG 2024”). Statuts : DRAFT → COMPLETE → ACTIVE → ARCHIVED.
Job	Import d’une région dans un dataset (ex. “RPG 2024 — Ile-de-France”).
Région	Une des 13 régions administratives françaises, codées en dur dans `regions.ts`.
Activation	Passage de `isActiveRpg = true` sur les parcelles issues des jobs complétés. Un seul dataset ACTIVE à la fois.
Multipart 7z	Archives découpées en `.7z.001`, `.7z.002`, etc. Téléchargées séquentiellement, extraites comme une seule archive.

Flux

Admin UI → API (démarrer import) → file pg-boss → Worker
            events.emit(RPG_IMPORT_DISPATCH)       ├─ Téléchargement des fichiers sources
                                                   ├─ Extraction 7z → recherche rpg_parcelles.gpkg
                                                   ├─ Lecture GeoPackage (SQLite via bun:sqlite)
                                                   └─ Upsert des parcelles par lots de 500 (SQL brut)

Machine à états du workflow d’import

                          ┌─────────────────────────────────────┐
                          │                                     ▼
PENDING → DOWNLOADING → READY_TO_EXTRACT → EXTRACTING → PARSING → TRANSFORMING → IMPORTING → COMPLETED → ACTIVATED
   │           │                │               │            │           │             │          │
   │           └───────────────────────────────────────────────────────────────────────► FAILED   │
   │                            │                                                          │      │
   └────────────────────────────┴────────────────────────────────────────────────────► CANCELLED  │
                                                                                                  ▼
                                                                                               CANCELLED

FAILED est relançable quand :

Le statut est READY_TO_EXTRACT, ou
Le statut est FAILED et toutes les parties sont téléchargées (downloadedPartCount >= expectedPartCount), ou
Le statut est PENDING (job bloqué avant le démarrage du pipeline)

Mode DIRECT : saute READY_TO_EXTRACT — après le téléchargement, le pipeline continue directement vers EXTRACTING.

Mode MULTIPART_7Z : se met en pause à READY_TO_EXTRACT et attend qu’un admin déclenche manuellement l’étape d’extraction.

Il y a 2 modes d’import : DIRECT et MULTIPART_7Z. Le mode est déterminé automatiquement par le nombre de parties dans l’archive. DIRECT est utilisé pour les imports avec une seule archive .7z, tandis que MULTIPART_7Z est utilisé pour les imports avec des archives découpées en plusieurs parties.

Modules clés

`transitionRpgImportJob(jobId, to, extraFields?)`

Point d’entrée unique pour tous les changements de statut d’un job. Récupère le statut courant, valide la transition contre la machine à états, écrit de manière atomique. failRpgImportJob et completeRpgImportJob passent par cette fonction.

`JobWorkspace`

Propriétaire de tous les chemins filesystem du répertoire de travail d’un job :

workspace.dir — racine ($RPG_IMPORT_WORKDIR/<jobId>/)
workspace.downloadsDir — parties d’archive téléchargées
workspace.extractDir — GeoPackage extrait
workspace.cleanup() — supprime tout le workspace
workspace.cleanupExtracted() — supprime uniquement les artefacts extraits (conserve les téléchargements pour une nouvelle tentative)

Créé une seule fois dans pipeline.ts au démarrage du job, transmis aux fonctions d’archive.

`logImportStep(jobId, step, message, level?)`

Fonction simple. Écrit une ligne RpgImportLog. Niveau par défaut : INFO. Appelée depuis le pipeline et le geopackage-importer — pas d’instanciation de classe ni d’injection.

`flushImportChunk(rows)`

Exécute un pipeline PostgreSQL à 8 CTEs :

input — liaison des valeurs de ligne
prepared — cast des types, décodage WKB hex → géométrie PostGIS (SRID 2154)
normalized — ST_MakeValid sur les géométries invalides → ST_CollectionExtract(3) → ST_Multi
deduplicated — GROUP BY rpgSourceKey, ST_UnaryUnion pour les géométries multi-parties
annotated — marquage isEmpty, alreadyExists
upserted — INSERT … ON CONFLICT (rpgSourceKey) DO UPDATE
SELECT — retourne les compteurs : insertedRows, updatedRows, skippedRows, validRows, invalidRows

Retourne ImportChunkStats. Aucun effet de bord sur le statut du job.

Décisions d’architecture

SQL brut pour l’upsert : la normalisation géométrique PostGIS + l’upsert ON CONFLICT ne peuvent pas être exprimés via Prisma. flushImportChunk utilise prisma.$queryRawUnsafe.
Streaming via bun:sqlite : lecture SQLite directe depuis le .gpkg, découpée en lots de 500 lignes. Pendant qu’un lot est flushé en DB, le suivant est parsé (pipeline via chaîne de promesses pendingFlush).
pg-boss pour la durabilité : les jobs survivent aux redémarrages serveur. localConcurrency: 1 garantit le traitement séquentiel — pas d’imports concurrents, pas de race condition sur isActiveRpg.
Clé source déterministe : hash SHA-256 de (sourceYear, regionCode, id_parcel, code_cultu, code_group, culture_d1, culture_d2, cat_cult_p) — relancer le même import fait un upsert au lieu de dupliquer.
Limites de sécurité au téléchargement : 6 Gio par fichier, 30 Gio total, timeout de 20 minutes. Liste blanche d’hôtes via la variable d’environnement RPG_IMPORT_ALLOWED_HOSTS.
Conservation des téléchargements en cas d’échec : si l’extraction ou l’import échoue mais que les téléchargements sont complets, le workspace est conservé. La nouvelle tentative saute le téléchargement et reprend directement à l’extraction.

⚙️ DevOps & Infrastructure

Monorepo

CerOps est organisé en monorepo géré par Turborepo et Bun. Toutes les applications et packages partagés cohabitent dans un seul dépôt Git, ce qui garantit la cohérence des types TypeScript entre le backend et les frontends, et simplifie les déploiements.

Bun est utilisé à la fois comme runtime JavaScript, package manager et outil de compilation (le serveur Fastify est compilé en binaire natif via bun build --compile). Les versions des dépendances partagées sont centralisées dans le workspace catalog pour éviter toute dérive entre packages.

Application mobile Flutter

L’application mobile agriculteurs est développée en Flutter dans un dépôt séparé. Elle n’est pas intégrée au monorepo pour deux raisons principales : l’écosystème Flutter (Dart, pub.dev) est incompatible avec la chaîne d’outils Bun/Node, et les cycles de release mobiles (App Store / Play Store) suivent un rythme indépendant du déploiement web.

L’app communique avec le même backend via les mêmes endpoints ORPC.

Intégration Continue (GitHub Actions)

Quatre workflows couvrent l’ensemble du cycle de qualité :

CI (ci.yaml) : build, tests unitaires et lint (Biome, knip, sherif) — déclenché sur chaque PR et push sur main
E2E (e2e.yaml) : tests Playwright avec une base PostGIS éphémère — déclenché sur chaque PR
PR title (pr-title.yaml) : validation Conventional Commits
Docs (docs.yaml) : compilation mdBook — déclenché uniquement si docs/** est modifié

Le cache Turborepo est restauré entre les runs pour ne reconstruire que les packages affectés par la PR.

Conteneurisation (Docker)

Chaque application a son propre Dockerfile multi-stage : le pruning Turborepo extrait uniquement les fichiers nécessaires à l’app ciblée, puis le build produit une image minimale. Le serveur est distribué comme binaire compilé, les frontends Next.js en mode standalone.

Déploiement : Coolify

Coolify est le PaaS self-hosted qui orchestre tous les services. Aujourd’hui, en phase de développement, Coolify effectue lui-même les builds directement depuis le dépôt Git à chaque push sur main.

À terme, cette responsabilité sera transférée à GitHub Actions : un workflow dédié se chargera de builder et publier une image Docker taguée (ex. v1.2.0) sur le registry, et Coolify n’aura plus qu’à déployer cette image prébuilt sur l’environnement cible (production, pré-production, etc.) sans refaire de build. Cette séparation garantit que le même artefact immuable traverse tous les environnements.

Services applicatifs

Les trois applications (server, web-agri, web-pilots) sont chacune un service Coolify distinct pointant sur leur Dockerfile respectif.

Base de données

La base de données est un service PostGIS (PostgreSQL + extension géospatiale) provisionné par Coolify. L’extension PostGIS est utilisée pour les calculs géographiques liés aux zones agricoles et aux missions terrain.

Services annexes

Coolify héberge également :

OpenObserve — observabilité unifiée (logs, métriques, traces)
RustFS — stockage objet compatible S3 (uploads, livrables de missions)
pgAdmin — interface d’administration PostgreSQL
mdBook — cette documentation

Architecture de déploiement (actuelle — full dev)

GitHub (push main)
    │
    ▼ webhook + build
Coolify
    ├── server        (API Fastify)
    ├── web-agri      (frontend agriculteurs)
    ├── web-pilots     (frontend pilotes)
    ├── postgis        (base de données)
    ├── openobserve    (observabilité)
    ├── rustfs         (stockage objet)
    ├── pgadmin        (admin BDD)
    └── mdbook         (documentation)

Architecture de déploiement (cible)

GitHub (tag vX.Y.Z)
    │
    ▼ GitHub Actions (build + push image)
Container Registry
    │
    ▼ deploy image
Coolify
    ├── prod       → image :v1.2.0
    ├── preprod    → image :v1.2.0-rc1
    └── ...

Release & Déploiement

Ce chapitre détaille le processus de release et les différentes stratégies de déploiement selon l’environnement cible.

Processus de Release

Le processus de release est déclenché manuellement via GitHub Actions (workflow_dispatch) :

Déclencheur : execution manuelle du workflow avec un input de version (patch, minor, major ou 1.2.3)
Préparation : bump des versions dans les 3 package.json via bumpp
Build : création des images Docker pour les 3 applications
Publication : push des images taguées dans le registry Github en privé
Commit & Tag : commit des changements de version + création du tag Git
GitHub Release : création de la release GitHub avec le changelog généré par git-cliff

Le tag Git est créé après le build réussi, pas avant. Cela garantit que le tag pointe toujours vers du code qui a été buildé et testé.

Versionnement

Le projet suit Semantic Versioning :

MAJOR : changement breakant l’API
MINOR : nouvelle fonctionnalité backward-compatible
PATCH : correction de bug

Environnements

Développement

L’environnement de développement est déployé automatiquement via Coolify. À chaque push sur la branche main, Coolify détecte le changement et lance un build direct depuis le dépôt Git.

GitHub (push main)
    │
    ▼ webhook
Coolify dev
    ├── server    (build auto)
    ├── web-agri  (build auto)
    └── web-pilots (build auto)

Cet environnement sert aux tests d’intégration et au développement quotidien.

Production

La production n’est déployée qu’à partir de tags Git validés. L’image Docker est prébuildée par le workflow de release, puis déployée par Coolify.

Keep a Changelog

Le projet utilise git-cliff pour maintenir un historique clair des changements. Le changelog est généré automatiquement lors de la création de la release GitHub, en se basant sur les commits depuis la dernière release.

ADR-001 - Architecture monorepo avec Turborepo et Bun workspaces

Statut : Accepté
Date : 2026-04-05

Contexte

Le projet Cerops comprend plusieurs applications (web-agri, web-pilots, server) et packages partagés (api, auth, db, env, config). Ces composants sont fortement couplés : un changement de schéma de base de données impacte simultanément le backend et les deux frontends. Il est donc nécessaire de choisir une stratégie d’organisation du code source qui minimise la friction entre équipes et garantit la cohérence des types partagés.

Décision

Nous organisons le projet sous forme de monorepo géré avec Turborepo et Bun workspaces.

Alternatives considérées

Polyrepo : un dépôt Git par application/package — versioning indépendant mais synchronisation complexe entre dépôts, gestion fastidieuse des versions des packages partagés
Monorepo sans outil de build : organisation simple mais pas de cache ni de pipeline de build optimisé
Nx : alternative à Turborepo, plus complet mais plus complexe à configurer pour une petite équipe

Conséquences

Partage de code facilité entre les packages (api, auth, db) et les applications
Refactoring atomique : un seul commit peut modifier frontend, backend et packages partagés
Cache de build et exécution parallèle des tâches via Turborepo
Configuration unifiée (TypeScript, Biome, tests) à la racine du dépôt
Catalog Bun workspaces pour centraliser les versions des dépendances et éviter les dérives
Dépôt potentiellement plus lourd à cloner pour un contributeur ne travaillant que sur une partie
Nécessite une bonne discipline de gestion des dépendances (outils sherif, knip en place)
En cas de croissance de l’équipe, les conflits de merge peuvent augmenter sur les fichiers partagés

ADR-002 - Architecture monolithe modulaire

Statut : Accepté
Date : 2026-04-05

Contexte

Le projet est développé sur une durée courte avec une équipe restreinte. Le périmètre fonctionnel est bien défini (gestion de parcelles, missions de drone, marketplace) et ne nécessite pas de distribution complexe des services. Le choix architectural doit permettre un développement rapide tout en maintenant une bonne séparation des responsabilités.

Décision

Nous choisissons une architecture monolithique modulaire : un seul serveur Fastify avec une organisation interne par domaines métier via les packages oRPC (packages/api).

Alternatives considérées

Microservices : indépendance de déploiement par service, mais complexité opérationnelle (service discovery, communication inter-services, monitoring distribué) inadaptée à la taille du projet
Architecture serverless : coûts maîtrisés à faible charge, mais cold starts et difficulté de débogage local
Monolithe non structuré : développement encore plus rapide initialement, mais dette technique rapide et difficultés de maintenabilité

Conséquences

Développement et débogage plus rapides (un seul process à lancer)
Déploiement simplifié (un seul artefact serveur)
Moins de complexité opérationnelle
Bonne séparation des responsabilités via les routers oRPC par domaine
Moins scalable horizontalement qu’une architecture microservices — acceptable pour le volume actuel
Un bug critique dans un module peut affecter l’ensemble du serveur
Migration vers des microservices rendue plus difficile si le besoin émerge, bien qu’atténuée par la modularité interne

ADR-003 - Bun comme runtime JavaScript

Statut : Accepté
Date : 2026-04-05

Contexte

Le projet nécessite un runtime JavaScript pour exécuter le serveur Fastify et les scripts du monorepo. L’équipe cherche à maximiser la rapidité de démarrage, la performance des scripts de build et la simplicité de la chaîne d’outils (un seul outil pour runtime, package manager et bundler).

Décision

Nous utilisons Bun comme runtime JavaScript, package manager et bundler pour l’ensemble du monorepo.

Alternatives considérées

Node.js + npm/pnpm : écosystème mature, large communauté, tooling bien documenté
Node.js + pnpm workspaces : meilleure gestion des monorepos que npm, mais performances inférieures à Bun
Deno : sécurité by default, support natif TypeScript, mais compatibilité limitée avec l’écosystème npm

Conséquences

Démarrage du serveur et exécution des scripts significativement plus rapides qu’avec Node.js
Compatibilité native TypeScript sans étape de transpilation séparée
Package manager intégré avec support des workspaces et catalog
Compilation du serveur en binaire natif possible via bun build --compile
Runtime encore jeune : certaines APIs Node.js ne sont pas encore totalement compatibles
Communauté et documentation moins matures que Node.js
Certains packages npm peuvent présenter des comportements inattendus sous Bun
L’équipe doit rester vigilante aux breaking changes entre versions de Bun

ADR-004 - Next.js pour les applications web (architecture multi-app)

Statut : Accepté
Date : 2026-04-05

Contexte

L’application web doit servir deux audiences aux besoins très différents :

Agriculteurs (web-agri) : consultation de parcelles, suivi d’actions, accès à la marketplace
Pilotes de drone (web-pilots) : gestion de missions, suivi de vol, interface opérationnelle

Les rôles, les parcours utilisateurs et les interfaces sont suffisamment distincts pour justifier une séparation applicative. L’équipe a de l’expérience en React et cherche une solution avec SSR et bon support TypeScript.

Décision

Nous utilisons Next.js avec TypeScript pour les deux frontends web, organisés en deux applications distinctes dans le monorepo : web-agri (port 3001) et web-pilots (port 3002), partageant les packages api, auth et env.

Alternatives considérées

Une seule application Next.js avec routing par rôle : moins de duplication de configuration, mais couplage plus fort entre les deux surfaces et risque de fuite de code entre rôles
Angular : framework complet avec opinions fortes, mais courbe d’apprentissage plus raide et moins adapté à l’écosystème oRPC/TanStack
React sans framework (Vite + React Router) : plus léger, mais sans SSR natif ni App Router
Vue.js / Nuxt : écosystème plus léger, mais moins maîtrisé par l’équipe

Conséquences

SSR natif via App Router pour de meilleures performances initiales et le SEO
Architecture dual-client oRPC : appels directs en Server Components (zéro overhead réseau), hooks TanStack Query en Client Components
Séparation claire des surfaces par audience, sans risque de fuite de logique ou d’UI entre rôles
Duplication de la configuration Next.js entre les deux apps (atténuée par packages/config)
Deux processus de build distincts à maintenir
Dépendance forte à l’écosystème Next.js / Vercel pour les évolutions du framework

ADR-005 - Fastify pour le serveur backend

Statut : Accepté
Date : 2026-04-05

Contexte

Le backend doit exposer une API performante, typée, avec un bon support TypeScript et Bun. L’équipe cherche un framework léger permettant une mise en place rapide sans imposer une structure trop rigide.

Décision

Nous utilisons Fastify comme framework HTTP pour le serveur backend.

Alternatives considérées

Express.js : très répandu et bien documenté, mais moins performant, peu opiniated sur TypeScript, pas de support natif des schémas de validation
NestJS : structure imposée, DI intégrée, adapté aux grandes équipes, mais sur-ingénierie pour ce projet et compatibilité Bun non garantie
Hono : très léger, excellente compatibilité Bun, mais écosystème de plugins moins riche que Fastify
Spring Boot : inadapté à l’écosystème TypeScript du projet

Conséquences

Performances élevées (l’un des frameworks Node.js/Bun les plus rapides)
Validation intégrée via JSON Schema (complémentaire à Zod via oRPC)
Système de plugins (@fastify/cors) pour étendre les fonctionnalités
Bonne compatibilité avec Bun
Moins de structure imposée que NestJS : la discipline d’organisation repose sur l’équipe
Certains plugins Fastify peuvent ne pas être totalement compatibles avec Bun
Communauté plus petite qu’Express

ADR-006 - oRPC pour la couche de communication API

Statut : Accepté
Date : 2026-04-05

Contexte

Le projet nécessite une communication typée de bout en bout entre les frontends Next.js et le serveur Fastify. L’application est interne, sans contrainte d’exposition publique de l’API à des tiers. L’équipe veut réduire le boilerplate lié à la définition, la validation et la consommation des endpoints.

Décision

Nous utilisons oRPC pour la communication front-back, avec génération automatique d’une documentation OpenAPI via @orpc/openapi.

Alternatives considérées

API REST classique : standard universel, facilement consommable par des tiers, mais nécessite de la duplication de types et de la validation des deux côtés
GraphQL : flexibilité de requêtage, mais complexité de setup (schema, resolvers, codegen) disproportionnée pour ce projet
tRPC : concurrent direct d’oRPC, bon écosystème, mais oRPC offre une meilleure intégration OpenAPI et un support natif Zod v4

Conséquences

Type safety de bout en bout : le contrat API est défini une seule fois dans packages/api et partagé entre server et clients
Réduction du boilerplate de validation (Zod schemas réutilisés côté serveur et client)
Documentation OpenAPI auto-générée exposée sur /docs
Architecture dual-client : appels directs en Server Components (sans HTTP), hooks TanStack Query en Client Components
Couplage plus fort entre frontend et backend qu’une API REST découplée
Moins standard qu’une API REST : intégration difficile pour des clients externes ou des outils tiers
Dépendance à un écosystème plus jeune qu’Express+REST ou GraphQL

ADR-007 - PostgreSQL comme base de données relationnelle

Statut : Accepté
Date : 2026-04-05

Contexte

L’application manipule des données fortement relationnelles :

utilisateurs, rôles (agriculteurs, pilotes)
parcelles agricoles et leurs métadonnées géographiques
missions de drone et plans de vol
actions et tâches sur les parcelles
transactions de la marketplace

Elle nécessite des transactions fiables et une modélisation stricte des relations entre entités.

Décision

Nous utilisons PostgreSQL comme base de données principale.

Alternatives considérées

MongoDB : flexibilité du schéma utile pour des données non structurées, mais inadapté aux relations complexes et aux transactions multi-documents
MySQL : bonne alternative relationnelle, mais fonctionnalités avancées (types JSON, window functions, extensions géospatiales) moins riches que PostgreSQL
SQLite : parfait pour le développement local, mais inadapté à la production multi-utilisateurs et à la concurrence d’écriture
PlanetScale / Turso : bases managées intéressantes, mais complexité supplémentaire et coût

Conséquences

Forte cohérence des données et support complet des transactions ACID
Excellente modélisation des relations entre entités métier
Support des types avancés (JSONB, tableaux, UUID) utiles pour les métadonnées de parcelles
Extension PostGIS disponible si des requêtes géospatiales avancées s’avèrent nécessaires
Nécessite une modélisation stricte du schéma en amont
Requiert une instance PostgreSQL dédiée (Docker en développement, service managé en production)
Montée en charge horizontale plus complexe que des bases NoSQL distribuées

ADR-008 - Prisma comme ORM

Statut : Accepté
Date : 2026-04-05

Contexte

Le projet nécessite un accès base de données simple, typé et rapide à mettre en œuvre. Le schéma est centralisé dans packages/db et partagé entre le serveur et les packages internes. L’équipe veut éviter d’écrire du SQL brut tout en maintenant un contrôle sur les migrations.

Décision

Nous utilisons Prisma comme ORM, avec l’adaptateur @prisma/adapter-pg pour la connexion PostgreSQL et la génération de types ESM compatible Bun.

Alternatives considérées

TypeORM : mature, décorateurs TypeScript, mais configuration complexe et compatibilité Bun incertaine
Drizzle ORM : très léger, performant, SQL-like, bonne compatibilité Bun — alternative sérieuse mais adoption moins répandue dans l’équipe
Kysely : query builder typé, contrôle total sur le SQL, mais plus verbeux et sans gestion de migrations intégrée
Requêtes SQL brutes : contrôle maximal, mais perte du typage automatique et maintenance plus lourde

Conséquences

Schéma lisible et déclaratif dans les fichiers .prisma
Types TypeScript auto-générés à partir du schéma (zéro dérive entre base et code)
Migrations versionnées via prisma migrate pour la production
Prisma Studio pour explorer et modifier les données en développement
Abstraction qui peut limiter certaines optimisations SQL avancées (requêtes complexes nécessitent $queryRaw)
Génération du client requise après chaque modification de schéma (bun db:generate)
Performances légèrement inférieures à un query builder bas niveau pour des requêtes massives
Le fichier de schéma multi-fichiers (schema.prisma + auth.prisma) nécessite Prisma >= 6

ADR-009 - Flutter pour l’application mobile

Statut : Accepté
Date : 2026-04-05

Contexte

L’application mobile est utilisée par les agriculteurs et les pilotes de drone en plein champ, souvent dans des zones à faible connectivité. Les besoins incluent : consultation de parcelles, suivi de missions, affichage de cartes, mode offline, et accès caméra pour la prise de photos. Le choix mobile est un point de divergence majeur avec d’autres projets de l’équipe qui utilisent une PWA.

Décision

Nous choisissons de développer l’application mobile en Flutter (Dart), ciblant iOS et Android à partir d’une base de code unique.

Alternatives considérées

Progressive Web App (PWA) : une seule base de code web+mobile, mais accès limité aux APIs natives (GPS précis, caméra avancée, stockage local robuste), performances inférieures sur mobile, et fonctionnement offline moins fiable en conditions terrain
React Native : partage de code possible avec le frontend web (React), mais performances et accès natif inférieurs à Flutter, et gestion du mode offline plus complexe
Application native iOS/Android séparée : performances et intégration native maximales, mais double base de code, double maintenance, double coût de développement
Capacitor (Ionic) : proche du PWA avec accès natif, mais performances UI insuffisantes pour des cartes et interactions terrain

Conséquences

Performances proches du natif grâce au moteur de rendu Skia/Impeller de Flutter
Accès natif à la caméra, au GPS, au stockage sécurisé et à la connectivité réseau
Mode offline robuste via Drift (SQLite embarqué) — voir ADR-010
Un seul codebase pour iOS et Android
Langage Dart distinct du reste du stack TypeScript : la base de code mobile est totalement séparée
Les développeurs web du projet ne peuvent pas contribuer directement à la partie mobile sans apprendre Dart/Flutter
Taille de l’APK/IPA plus importante qu’une app native pure
Déploiement via les stores (App Store, Google Play) : processus de validation et de mise à jour plus lent qu’une PWA

ADR-010 - Drift pour la persistance locale sur mobile

Statut : Accepté
Date : 2026-04-05

Contexte

L’application mobile est utilisée en plein champ, dans des zones sans couverture réseau fiable. Les agriculteurs et pilotes de drone doivent pouvoir consulter leurs parcelles et créer des actions hors ligne, puis synchroniser les données à la reconnexion. Un mécanisme de persistance locale est donc indispensable sur le mobile Flutter.

Décision

Nous utilisons Drift (anciennement Moor) comme ORM SQLite pour la persistance locale sur mobile.

Alternatives considérées

Hive : base de données clé-valeur NoSQL légère pour Flutter, rapide pour de la lecture simple, mais pas adaptée aux relations et aux requêtes complexes
Isar : base orientée objet pour Flutter, très performante, mais sans support des transactions relationnelles
sqflite : accès SQLite bas niveau, contrôle total, mais verbeux et sans typage automatique
SharedPreferences : uniquement pour des données simples de type clé-valeur, inadapté à un cache structuré

Conséquences

Schéma SQLite typé et déclaratif en Dart, cohérent avec l’approche Prisma côté serveur
Support des relations entre tables, des transactions et des requêtes complexes
Génération de code via drift_dev et build_runner pour les types et les requêtes
Stratégie de synchronisation par flag needsSync : les entités modifiées hors ligne sont marquées et synchronisées à la reconnexion
La synchronisation bidirectionnelle (conflits) doit être gérée manuellement — logique non triviale
Nécessite une étape de génération de code (build_runner) après chaque modification de schéma
Deux schémas à maintenir en cohérence : Prisma (serveur) et Drift (mobile) — risque de dérive si les entités évoluent

ADR-011 - Better-Auth pour l’authentification

Statut : Accepté
Date : 2026-04-05

Contexte

L’application nécessite une gestion de l’authentification pour les utilisateurs web (agriculteurs, pilotes) et mobiles (Flutter). Le système doit gérer les sessions, les rôles, et s’intégrer avec Stripe pour les abonnements. L’équipe cherche une solution clé-en-main, typée TypeScript, sans dépendre d’un service tiers payant.

Décision

Nous utilisons Better-Auth comme bibliothèque d’authentification, avec l’adaptateur Prisma (@better-auth/prisma-adapter) et le plugin Stripe (@better-auth/stripe).

Alternatives considérées

Auth.js (NextAuth) : très répandu dans l’écosystème Next.js, mais couplé au framework Next.js et difficile à partager avec un serveur Fastify indépendant
Clerk : solution SaaS complète avec UI intégrée, mais coût mensuel récurrent et dépendance à un service tiers externe
Lucia : bibliothèque minimaliste et flexible, bonne alternative, mais nécessite plus de code custom pour les fonctionnalités avancées
Auth custom : contrôle total, mais implémentation de la sécurité (hachage, sessions, CSRF) sujette aux erreurs

Conséquences

Authentification sessions-based via cookies httpOnly — pas de gestion de JWT côté client
Schéma de base de données généré et géré automatiquement via auth.prisma
Client Flutter via better_auth_client (package communautaire) — moins mature que le SDK web
Plugin Stripe intégré pour la gestion des abonnements sans code custom
Documentation OpenAPI auto-générée sur /api/auth/reference
Dépendance à une bibliothèque relativement jeune : risque de breaking changes lors des mises à jour majeures
Le package Flutter better_auth_client est un package communautaire non officiel — sa maintenance n’est pas garantie
Moins de composants UI préconstruits que Clerk : les formulaires de connexion sont à implémenter manuellement

ADR-012 - Stripe pour la gestion des paiements

Statut : Accepté
Date : 2026-04-05

Contexte

Cerops inclut une marketplace où des services et produits agricoles peuvent être échangés. La plateforme doit gérer des abonnements et/ou des transactions entre utilisateurs. Le traitement des paiements est un domaine sensible qui nécessite conformité PCI-DSS, gestion des remboursements et des litiges.

Décision

Nous utilisons Stripe comme solution de paiement, intégré via le plugin @better-auth/stripe côté serveur.

Alternatives considérées

PayPal : notoriété internationale, mais API moins développeur-friendly et intégration plus complexe
Mollie : bonne alternative européenne, APIs modernes, mais écosystème de plugins moins riche
Paiement custom : contrôle total, mais développement long, conformité PCI-DSS à gérer manuellement — risque de sécurité majeur
LemonSqueezy : solution SaaS tout-en-un pour les abonnements, mais moins flexible pour une marketplace B2B

Conséquences

Conformité PCI-DSS déléguée à Stripe : les données de carte ne transitent jamais par nos serveurs
Gestion des abonnements, des remboursements et des webhooks via l’API Stripe
Intégration simplifiée via @better-auth/stripe qui synchronise les abonnements avec les sessions utilisateurs
Stripe Elements / Stripe.js pour les formulaires de paiement côté client
Commission Stripe sur chaque transaction (1.4% + 0.25€ pour les cartes européennes) — à intégrer dans la politique tarifaire
Dépendance forte à un service tiers : une panne Stripe impacte directement les paiements de la plateforme
Les paiements sont en euros par défaut — la gestion multi-devises nécessiterait une configuration supplémentaire
Les webhooks Stripe nécessitent un endpoint public accessible — à prévoir dans l’infrastructure de déploiement

Keyboard shortcuts

CerOps Documentation