# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

WebCarto is a self-hosted web application for displaying and editing cartographic data (KML/GeoJSON files) with satellite/hybrid/vector map backgrounds. Deployed via Docker. UI uses "gruvbox dark vintage" theme. Specification in `consigne.md`.

## Tech Stack

- **Frontend**: Vite + React + TypeScript, MapLibre GL JS, TailwindCSS v4, Zustand, @tmcw/togeojson, DOMPurify
- **Backend**: Python FastAPI, Pydantic, SQLite via SQLModel, uvicorn
- **Deploy**: Docker Compose — 2 services: backend (FastAPI + /data volume), frontend (Vite build + Nginx)

## Architecture

```
frontend/              → React SPA (Vite)
  src/components/      → MapView, Header, LayerPanel, PropertyPanel, ImportDialog, ToastContainer, StatusBar
  src/stores/mapStore  → Zustand store (datasets, features, selection, undo, toasts)
  src/api/client       → API client (fetch wrapper)
backend/               → FastAPI REST API
  app/main.py          → FastAPI app + CORS + startup
  app/models.py        → SQLModel models: Dataset, Feature, FeatureVersion
  app/routes/datasets  → Import, list, get, export
  app/routes/features  → Update feature (with versioning)
  app/config.py        → DATA_DIR, DATABASE_URL, MAX_UPLOAD_SIZE
  app/database.py      → Engine + session dependency
  tests/test_api.py    → 9 tests (health, import, CRUD, export, 404)
samples/               → example.geojson, example.kml
```

## Development Commands

### Docker
```bash
docker-compose up --build        # Lancer le stack complet
docker-compose down              # Arrêter
```

### Frontend (from `frontend/`)
```bash
npm install                      # Installer les dépendances
npm run dev                      # Serveur dev (Vite, port 5173, proxy /api → backend:8000)
npm run build                    # Build production (tsc + vite)
npx tsc -b                      # Vérification TypeScript seule
npm run lint                     # ESLint
```

### Backend (from `backend/`)
```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest httpx  # Setup
.venv/bin/uvicorn app.main:app --reload                                          # Dev server
.venv/bin/pytest tests/ -v                                                       # Tous les tests
.venv/bin/pytest tests/test_api.py -k test_import                                # Un test spécifique
```

## Key Design Decisions

- **KML parsing côté frontend** (@tmcw/togeojson), envoyé au backend en GeoJSON normalisé
- **Fonds de carte** définis dans MapView.tsx (OSM raster, Esri satellite, Stamen labels). 3 modes: vector/satellite/hybrid
- **Versioning**: table `feature_versions` stocke before/after JSON pour chaque modification
- **Pas d'auth en v1** — accès LAN uniquement, structure prête pour OIDC/reverse proxy
- **En dev local**, le backend stocke dans `backend/data/` (en Docker: volume `/data`)
- **Tests backend** utilisent SQLite in-memory avec `StaticPool` pour l'isolation

## API Endpoints

```
GET  /api/health                              # Health check
POST /api/datasets/import                     # Import (multipart: file + geojson)
GET  /api/datasets                            # Lister les datasets
GET  /api/datasets/{id}                       # Dataset + features
PUT  /api/features/{id}                       # Update geometry/properties (avec versioning)
POST /api/datasets/{id}/export?format=geojson # Export GeoJSON
```

## Language

All user-facing text, comments in code, and commit messages should be in French. Technical identifiers (variable names, API paths) stay in English.