diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..466df22
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,180 @@
+# CSV - Documentation détaillée
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Frontend (React/Vite)"
+        App[App.jsx]
+        Router[React Router]
+        Pages[Pages]
+        Auth[AuthContext]
+    end
+
+    subgraph "Backend (Express ESM)"
+        Server[index.js]
+        Routes[Routes API]
+        Multer[Multer Uploads]
+    end
+
+    subgraph "Base de données"
+        MariaDB[(MariaDB<br/>csv)]
+    end
+
+    App --> Router
+    Router --> Pages
+    Pages --> Auth
+    Pages -->|API calls| Server
+    Server --> Routes
+    Server --> Multer
+    Routes --> MariaDB
+```
+
+## Modèle de données
+
+```mermaid
+erDiagram
+    USERS ||--o{ ARTICLES : "écrit"
+    USERS ||--o{ EVENTS : "crée"
+    USERS ||--o{ LISTINGS : "publie"
+    USERS ||--o{ HELP_REQUESTS : "demande"
+    USERS ||--o{ BUSINESSES : "possède"
+    CATEGORIES ||--o{ LISTINGS : "classe"
+    CATEGORIES ||--o{ EVENTS : "classe"
+
+    USERS {
+        int id PK
+        string name
+        string email UK
+        string password
+        string phone
+        string address
+        enum role user|admin
+        string avatar
+    }
+
+    ARTICLES {
+        int id PK
+        string title
+        text content
+        string image
+        int author_id FK
+        boolean published
+    }
+
+    EVENTS {
+        int id PK
+        string title
+        text description
+        date date
+        time time
+        string location
+        string image
+        string category
+        int author_id FK
+    }
+
+    LISTINGS {
+        int id PK
+        string title
+        text description
+        float price
+        string image
+        string category
+        int author_id FK
+    }
+
+    HELP_REQUESTS {
+        int id PK
+        string title
+        text description
+        string urgency
+        int author_id FK
+    }
+
+    BUSINESSES {
+        int id PK
+        string name
+        string description
+        string address
+        string phone
+        string email
+        string website
+        string category
+        int owner_id FK
+    }
+
+    CATEGORIES {
+        int id PK
+        string name
+        enum type listing|event
+    }
+```
+
+## API Routes
+
+| Méthode | Route | Description |
+|---------|-------|-------------|
+| POST | `/api/auth/register` | Inscription |
+| POST | `/api/auth/login` | Connexion |
+| GET | `/api/auth/me` | Profil |
+| GET | `/api/articles` | Liste articles |
+| POST | `/api/articles` | Créer article |
+| GET | `/api/events` | Liste événements |
+| POST | `/api/events` | Créer événement |
+| GET | `/api/listings` | Liste annonces |
+| POST | `/api/listings` | Créer annonce |
+| GET | `/api/help-requests` | Liste demandes d'aide |
+| POST | `/api/help-requests` | Créer demande |
+| GET | `/api/businesses` | Liste entreprises |
+| POST | `/api/businesses` | Créer entreprise |
+| GET | `/api/categories` | Liste catégories |
+
+## Fonctionnalités
+
+### Articles
+- CRUD avec images (upload Multer)
+- Système de publication (brouillon/publié)
+- Auteur lié
+
+### Événements
+- Date, heure, lieu
+- Catégories (musique, sport, culture, etc.)
+- Images
+
+### Petites Annonces (Listings)
+- Prix, catégorie
+- Images uploadées
+- Recherche par catégorie
+
+### Demandes d'Aide
+- Niveau d'urgence
+- Mise en relation entre utilisateurs
+
+### Annuaire Entreprises
+- Informations contact
+- Site web, téléphone
+- Catégories métier
+
+### Administration
+- Panel admin pour gérer les contenus
+- Modération des articles/annonces
+- Gestion des utilisateurs
+
+## Développement
+
+```bash
+# Backend
+cd backend
+npm install
+node src/index.js      # Express sur :3002
+
+# Frontend
+cd frontend
+npm install
+npm run dev            # Vite sur :5173
+```
+
+## Auto-migration BDD
+
+Le backend crée automatiquement les tables au démarrage via `CREATE TABLE IF NOT EXISTS`. Pas de migration nécessaire.