chore: initial Observable workspace with technical README

README.md

@@ -0,0 +1,137 @@
+# Observable Workspace — In-N-Out x Séismes x OVNIs (Californie)
+
+Workspace **Observable Framework** orienté data storytelling avec deux analyses géospatiales en Californie :
+
+- **In-N-Out Seismic Challenge** : classement des restaurants In‑N‑Out selon une exposition aux séismes.
+- **Paradoxe de l’Animal Style** : corrélation exploratoire entre observations OVNI et proximité d’un In‑N‑Out.
+
+## Objectifs
+
+- Démontrer une chaîne complète de visualisation interactive avec Observable Framework.
+- Croiser des données hétérogènes (OSM/Overpass, USGS, jeu OVNI) avec un traitement géospatial léger.
+- Produire des pages analytiques reproductibles, versionnables et publiables statiquement.
+
+## Stack technique
+
+- **Runtime / Build** : `@observablehq/framework` (v1.x)
+- **Langage** : JavaScript ESM (`"type": "module"`)
+- **Parsing CSV** : `d3-dsv`
+- **Visualisation** : `Plot` (via Observable), `d3`, `topojson-client`
+- **Topologie US** : `us-atlas@3` (chargement CDN)
+
+## Architecture du projet
+
+```text
+observablehq.config.js      # Configuration Observable Framework
+package.json                # Scripts npm + dépendances
+docs/
+  index.md                  # Page d'accueil
+  in-n-out-california.md    # Analyse séismes ↔ In-N-Out
+  ufo-animal-style-paradox.md # Analyse OVNI ↔ In-N-Out
+  data/
+    in-n-out-ca-overpass.json.js
+    ca-earthquakes-last365d.json.js
+    in-n-out-ca-csv.json.js
+    ufo-ca-sightings-v2.json.js
+    ...
+```
+
+## Configuration Observable
+
+Le fichier `observablehq.config.js` définit :
+
+- `root: "docs"` : toutes les pages et données vivent sous `docs/`
+- `title: "Observable Workspace"`
+- `pager: false`
+- `toc: true`
+- `theme: "dashboard"`
+
+## Pipeline de données
+
+### 1) In-N-Out (source primaire Overpass)
+
+Le module `docs/data/in-n-out-ca-overpass.json.js` :
+
+- interroge Overpass API pour les POI In‑N‑Out (`node/way/relation`),
+- normalise les attributs (`id`, `latitude`, `longitude`, `name`, `city`, `address`, `postcode`),
+- déduplique par coordonnée arrondie,
+- tente plusieurs endpoints Overpass (fallback de résilience),
+- bascule sur un fallback CSV GitHub en cas d’échec.
+
+### 2) Séismes Californie
+
+Le dataset `ca-earthquakes-last365d.json` est utilisé dans la page `in-n-out-california.md` pour :
+
+- filtrer les séismes dans une bounding box Californie,
+- calculer la distance haversine de chaque séisme à chaque magasin,
+- agréger des métriques locales (`quakeCount`, `maxMagnitude`, `avgMagnitude`, `nearestKm`),
+- produire un **Shake Index** composite.
+
+Formule utilisée :
+
+`shakeIndex = quakeCount * 1.5 + maxMagnitude * 12 + max(0, radiusKm - min(nearestKm, radiusKm)) * 0.25`
+
+### 3) OVNI Californie
+
+La page `ufo-animal-style-paradox.md` :
+
+- charge les observations OVNI et les points In‑N‑Out,
+- calcule le magasin le plus proche pour chaque observation (distance haversine),
+- marque `closeToBurger` selon un rayon interactif,
+- agrège des hotspots via regroupement par magasin le plus proche,
+- expose des KPIs interactifs (taux de proximité, volume, durée moyenne, etc.).
+
+## Visualisations
+
+- Bar charts classés (top/bottom stores)
+- Carte Californie (projection Albers)
+- Nuages de points et outils de filtrage (`Inputs.select`, `Inputs.range`)
+- Tooltips détaillés pour exploration ad hoc
+
+## Exécution locale
+
+Pré-requis :
+
+- Node.js 18+ recommandé
+- npm
+
+Installation :
+
+```bash
+npm install
+```
+
+Développement (live preview) :
+
+```bash
+npm run dev
+```
+
+Build statique :
+
+```bash
+npm run build
+```
+
+## Sorties et dossiers générés
+
+- `dist/` : artefacts de build statique (à ne pas versionner)
+- `docs/.observablehq/` : cache/framework interne (à ne pas versionner)
+
+Le `.gitignore` est configuré pour ignorer ces dossiers de cache/génération.
+
+## Qualité, limites et reproductibilité
+
+- Les données externes (Overpass, CDN, sources tierces) peuvent varier dans le temps.
+- Les métriques proposées sont exploratoires et non causales.
+- Le pipeline privilégie robustesse et disponibilité (fallback réseau) plutôt qu’une ETL lourde.
+
+## Scripts npm
+
+- `npm run dev` → `observable preview`
+- `npm run build` → `observable build`
+
+## Publication Git
+
+Ce dépôt est prévu pour être poussé sur un remote Gitea.
+Le README sert de documentation technique de référence pour maintenance, reprise et extension du projet.