# ADR-019 : Service de Géolocalisation par IP

**Statut** : Accepté
**Date** : 2026-01-31

## Contexte

RoadWave nécessite un service de géolocalisation par IP pour le mode dégradé (utilisateurs sans GPS activé). Ce service permet de détecter la ville/région de l'utilisateur à partir de son adresse IP et d'afficher du contenu régional même sans permission GPS.

**Évolution du marché** :
- **Avant 2019** : MaxMind GeoLite2 était téléchargeable gratuitement (base de données locale)
- **Depuis 2019** : MaxMind nécessite un compte + limite 1000 requêtes/jour (gratuit), puis 0.003$/requête au-delà

**Usage RoadWave** :
- Mode dégradé : ~10% des utilisateurs (estimation)
- Volume : 1000 utilisateurs × 10% = 100 requêtes/jour (MVP)
- Critère : Aucune dépendance à un service tiers payant

## Décision

**IP2Location Lite DB** (self-hosted) pour la géolocalisation par IP.

## Alternatives considérées

| Option | Coût/mois | Précision | Hébergement | Maintenance |
|--------|-----------|-----------|-------------|-------------|
| **IP2Location Lite** | Gratuit | ±50 km | Self-hosted | Mise à jour mensuelle |
| MaxMind GeoLite2 API | ~10€ (dépassement) | ±50 km | Cloud MaxMind | Nulle |
| Self-hosted MaxMind | Gratuit | ±50 km | Self-hosted | Compte requis + MAJ |

## Justification

### IP2Location Lite (choix retenu)

**Avantages** :
- Gratuit (pas de limite de requêtes)
- Self-hosted (souveraineté des données, cohérence avec [ADR-004](004-cdn.md))
- Base de données SQLite légère (50-100 MB)
- Mise à jour mensuelle automatisable via cron
- Licence permissive (Creative Commons BY-SA 4.0)
- Pas de compte tiers requis

**Inconvénients** :
- Maintenance mensuelle (mise à jour DB)
- Précision équivalente à MaxMind (~±50 km)

### MaxMind GeoLite2 API (rejeté)

**Pourquoi rejeté** :
- Coût potentiel en cas de dépassement quota (risque faible mais existant)
- Dépendance à un service tiers (perte de souveraineté)
- Compte requis (friction opérationnelle)

### Self-hosted MaxMind (rejeté)

**Pourquoi rejeté** :
- Compte MaxMind obligatoire pour télécharger la DB (friction)
- Complexité identique à IP2Location pour résultat équivalent
- IP2Location offre même fonctionnalité sans compte tiers

## Architecture technique

### Composants

```mermaid
flowchart TD
    A[Backend Go<br/>API Handler]
    B[GeoIP Service<br/>Wrapper Go autour IP2Location]
    C[IP2Location DB<br/>SQLite ~50 MB<br/>Mise à jour mensuelle]

    A --> B
    B --> C
```

### Flux de géolocalisation

1. **Requête** : API reçoit requête utilisateur sans GPS
2. **Extraction IP** : Lecture IP depuis en-têtes HTTP (`X-Forwarded-For`, `X-Real-IP`)
3. **Lookup DB** : Query SQLite IP2Location (index sur plages IP)
4. **Réponse** : Ville + région + code pays

**Précision attendue** : ±50 km (équivalent MaxMind)

### Maintenance

**Mise à jour mensuelle** :
- Cron job télécharge nouvelle DB IP2Location (1er du mois)
- Backup DB actuelle avant remplacement
- Rechargement service GeoIP (hot reload sans downtime)

**Monitoring** :
- Alertes si DB > 60 jours (DB obsolète)
- Logs requêtes "IP non trouvée" (détection problèmes DB)

## Conséquences

### Positives
- Aucun coût récurrent (gratuit à l'infini)
- Souveraineté complète des données (cohérence ADR-004)
- Pas de dépendance externe (service tiers)
- Latence minimale (lookup local SQLite < 1ms)

### Négatives
- Maintenance mensuelle requise (automatisable)
- Précision limitée (±50 km, acceptable pour mode dégradé)
- Taille base de données (~50-100 MB sur disque)

### Risques atténués
- **DB obsolète** : Alertes automatiques si > 60 jours
- **IP non trouvée** : Fallback "France" par défaut (code pays FR)
- **Perte DB** : Backup automatique avant chaque mise à jour

## Références

- [ADR-004 : CDN (Souveraineté)](004-cdn.md)
- [ADR-015 : Hébergement](015-hebergement.md)
- [Règle 02 : RGPD (Mode Dégradé)](../regles-metier/02-conformite-rgpd.md#136-géolocalisation-optionnelle)
- IP2Location Lite : https://lite.ip2location.com/