diff --git a/README.md b/README.md
index 11bfd36..d4288bd 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,48 @@
 # suivi_produit
 
+Suite self-hosted pour suivre les prix et l'état des produits Amazon.fr (et autres stores à venir).
+
+## Structure
+- `backend/` : API FastAPI + scraper Playwright + persistance SQLite
+- `frontend/` : SPA Gruvbox dark pour afficher les vignettes, graphiques et logs
+- `docker/` : fichiers nécessaires pour docker-compose + builds
+- `docs/`, `TODO.md`, `CHANGELOG.md`, `kanban.md` : documentation et suivi
+
+## Objectif MVP
+1. CRUD produits + historique des snapshots
+2. Scraper Amazon via Playwright avec logs et artifacts
+3. Interface responsive avec vignettes & graphique 30j
+4. Configuration JSON frontend/backend rangée dans le repo
+5. Docker Compose + scheduler interne pour lancer les scrapes
+
+## Environnement
+1. Copier `cp .env.example .env` avant tout lancement backend/tests.
+2. Activer le venv :
+   - `source .venv/bin/activate`
+   - ou `poetry shell`
+3. `poetry install` (backend)
+4. `npm install` (frontend, à compléter)
+
+## Tests
+- Toujours exécuter `poetry run pytest` dans l’environnement `.env` avant un `docker compose up`.
+- Test scraper en CLI (Playwright) :
+  - `SCRAPE_TEST_MAX=0 .venv/bin/poetry run python backend/app/scraper/run_scrape_tests.py`
+  - Optionnel (ouvrir le navigateur si blocage) :
+    - `SCRAPE_TEST_HEADFUL_ON_BLOCK=1 SCRAPE_TEST_MAX=0 .venv/bin/poetry run python backend/app/scraper/run_scrape_tests.py`
+
+## Audit code (imports / code mort)
+- Installer les outils (dans le venv) :
+  - `.venv/bin/pip install ruff vulture coverage pip-check-reqs pyright`
+- Lancer l’audit :
+  - `.venv/bin/ruff check backend/`
+  - `.venv/bin/vulture backend/`
+  - `.venv/bin/pip-check-reqs backend/`
+  - `.venv/bin/coverage run -m pytest`
+  - `.venv/bin/coverage report -m`
+
+## Déploiement
+1. `docker compose up --build` (à configurer)
+
+## Notes
+- Le scraping est volontairement lent (15-20 produits/jour) pour éviter le blocage.
+- Le raw JSON est conservé pendant 30 jours dans `backend/data/raw`.