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

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

Frontend (from `frontend/`)

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/`)

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.

3.6 KiB Raw Blame History