diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..48618bb
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,200 @@
+# DynaSQY - Documentation détaillée
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Frontend (React/Vite)"
+        App[App.jsx]
+        Auth[AuthContext]
+        Components[Composants React]
+        PWA[Service Worker / PWA]
+    end
+
+    subgraph "Backend (Express)"
+        Server[server.js]
+        Routes[Routes API]
+        Controllers[Controllers]
+        Middleware[Middleware JWT]
+        Services[Services]
+    end
+
+    subgraph "Base de données"
+        MariaDB[(MariaDB 10.11<br/>dynasqy)]
+    end
+
+    subgraph "Services externes"
+        SMTP[Infomaniak SMTP<br/>mail.infomaniak.com:465]
+        VAPID[Web Push<br/>VAPID Keys]
+    end
+
+    App --> Auth
+    App --> Components
+    App --> PWA
+    Components -->|API calls| Server
+    Server --> Routes
+    Routes --> Controllers
+    Controllers --> Middleware
+    Controllers --> MariaDB
+    Controllers --> SMTP
+    Controllers --> VAPID
+```
+
+## Modèle de données
+
+```mermaid
+erDiagram
+    MEMBERS ||--o{ INVITATIONS : "reçoit"
+    MEMBERS ||--o{ ABSECTIONS : "a"
+    MEMBERS ||--o{ ACTIVITY_LOGS : "génère"
+    MEMBERS ||--o{ HONORS : "reçoit"
+    MEMBERS ||--o{ RECOMMENDATIONS : "reçoit"
+    MEMBERS ||--o{ PRESENTATION_SLIDES : "a"
+    EVENTS ||--o{ INVITATIONS : "contient"
+    EVENTS ||--o{ ACTIVITY_LOGS : "lié à"
+
+    MEMBERS {
+        int id PK
+        string name
+        string email
+        string phone
+        string company
+        string role
+        string avatar
+        boolean isActive
+        datetime created_at
+    }
+
+    EVENTS {
+        int id PK
+        string title
+        date date
+        string location
+        string description
+        string type
+        int created_by
+    }
+
+    INVITATIONS {
+        int id PK
+        int member_id FK
+        int event_id FK
+        string status
+        datetime created_at
+    }
+
+    ABSECTIONS {
+        int id PK
+        int member_id FK
+        date start_date
+        date end_date
+        string reason
+    }
+
+    HONORS {
+        int id PK
+        int member_id FK
+        string type
+        string description
+        date date
+    }
+
+    ACTIVITY_LOGS {
+        int id PK
+        int member_id FK
+        string action
+        json details
+        datetime created_at
+    }
+```
+
+## API Routes
+
+| Méthode | Route | Description | Auth |
+|---------|-------|-------------|------|
+| POST | `/api/auth/login` | Connexion | Non |
+| POST | `/api/auth/register` | Inscription | Non |
+| GET | `/api/auth/me` | Profil utilisateur | Oui |
+| GET | `/api/members` | Liste membres | Oui |
+| POST | `/api/members` | Ajouter membre | Admin |
+| PUT | `/api/members/:id` | Modifier membre | Admin |
+| DELETE | `/api/members/:id` | Supprimer membre | Admin |
+| GET | `/api/events` | Liste événements | Oui |
+| POST | `/api/events` | Créer événement | Admin |
+| GET | `/api/invitations` | Liste invitations | Oui |
+| POST | `/api/invitations` | Créer invitation | Admin |
+| GET | `/api/gallery` | Galerie photos | Oui |
+| POST | `/api/gallery` | Ajouter photo | Admin |
+| GET | `/api/honors` | Liste honneurs | Oui |
+| POST | `/api/recommendations` | Ajouter recommandation | Membre |
+| GET | `/api/stats` | Statistiques | Admin |
+| POST | `/api/push/subscribe` | Subscribe push | Oui |
+| GET | `/api/export/:format` | Export CSV/PDF | Admin |
+
+## Fonctionnalités
+
+### Membres
+- CRUD complet avec avatars
+- Rôles : admin, membre
+- Statut actif/inactif
+- Recherche et filtrage
+
+### Événements
+- Création avec date, lieu, description
+- Types : réunion, conférence, social
+- Invitations avec suivi de statut (accepté/refusé/en attente)
+- Notifications push aux membres
+
+### Absences
+- Suivi des absences par membre
+- Périodes définies (début/fin)
+- Raison optionnelle
+
+### Honneurs & Recommandations
+- Système d'honneurs (gladiateur, légende, etc.)
+- Recommandations entre membres
+- Slideshow de présentation
+
+### Galerie
+- Upload de photos
+- Organisation par événement
+- Stockage sur volume Docker bind-mount
+
+### Notifications Push
+- VAPID keys pour web push
+- Abonnement par membre
+- Envoi lors de nouveaux événements/invitations
+
+### Export
+- Export CSV des membres
+- Export PDF (via LibreOffice dans le container)
+
+## Développement
+
+```bash
+# Backend
+cd backend
+npm install
+node seed.js        # Générer les mots de passe hashés
+node server.js      # Démarre sur :3000
+
+# Frontend
+cd frontend
+npm install
+npm run dev         # Vite sur :5173
+```
+
+## Variables d'environnement
+
+Voir README.md pour la liste complète.
+
+## Déploiement Docker
+
+```yaml
+services:
+  db:        # MariaDB 10.11
+  backend:   # Node.js/Express
+  frontend:  # React/Vite + nginx
+```
+
+Le frontend sert les fichiers statiques via nginx et proxy les appels API vers le backend.