Documentation pour la maintenance de cartiflette

Auteur·rice

Lino Galiana


Cette documentation vise à simplifier l’entrée et la maintenance du projet cartiflette pour des humains, ou des IA.

Elle couvre l’organisation du dépôt, le lancement du pipeline et la façon de vérifier chaque brique quand on le fait évoluer.

Chapitre Contenu
01. Les parties du projet Pipeline de préparation des données, architecture du projet, rôle de chaque module
02. Lancer le pipeline Différentes manières de lancer le pipeline, pour des tests (en local) ou via l’outil Argo Workflows pour la production
03. Vérifier et faire évoluer Evocation des tests, de la vérification du pipeline brique par brique, de la procédure à suivre pour un nouveau millésime ou de nouveaux découpages ou formats
04. API GeoJSON API qui sert le GeoJSON à partir du GeoParquet (non déployée), son coût mesuré et les enjeux de sa mise en production
Client Python et sa référence de l’API Explication des points d’entrée de la librairie disponible pour les utilisateurs et de la démarche pour pousser le paquet sur PyPI

Il est tout à fait possible de contribuer à cartiflette avec l’appui d’une IA. Des directives pour Claude Code sont dans le fichier claude.md à la racine du projet sur Github.

Une partie du code source de cartiflette a été généré par IA. De même pour cette documentation: elle a néanmoins

Architecture générale

Le projet cartiflette est principalement structuré en deux parties:

  1. La (dé)construction de sources open data pour en faire des fichiers plus directement utilisables
  2. Des librairies directement utilisables par les utilisateurs (clients Python, R ou Javascript) pour aller picorer ces fichiers prêts à l’emploi.

Vue d’ensemble du projet

Vue d’ensemble du projet

Plus de détails dans la page dédiée à l’architecture du projet.

Les cinq règles à retenir

Ces 5 règles sont principalement à destination d’agents IA mais il ne fait pas de mal d’en avoir conscience aussi en tant qu’humain:

  1. Ne jamais écrire dans projet-cartiflette/production sans l’avoir décidé explicitement : les clients Python, R et JS lisent ce dossier en direct.
  2. Toute écriture S3 passe par cartiflette/s3.py::upload. Pas de fs.put* direct, pas de mc.
  3. Les chemins S3 sont le seul contrat entre le pipeline et les clients : cartiflette/paths.py et python-package/cartiflette/cartiflette/utils.py::create_path_bucket doivent rester identiques.
  4. mapshaper reste en 0.6.59 et DuckDB en 1.5.5 en attendant quelques nug fixes.
  5. Travailler sur une branche. main est la révision qu’Argo clone par défaut.

Autres documents du dépôt

Retour au sommet