diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..0ab35e5
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,71 @@
+# Portugais - Documentation détaillée
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Frontend (HTML/CSS/JS)"
+        Public[public/]
+        App[app.js]
+        Data[data.js]
+    end
+
+    subgraph "Backend (Express)"
+        Server[server.js]
+        Routes[Routes API]
+    end
+
+    subgraph "Base de données"
+        SQLite[(SQLite WAL<br/>better-sqlite3)]
+    end
+
+    Public --> App
+    Public --> Data
+    App -->|API calls| Server
+    Server --> Routes
+    Routes --> SQLite
+```
+
+## Fonctionnalités
+
+### Apprentissage gamifié
+- Système de points et niveaux
+- Activités d'apprentissage variées
+- Suivi de progression
+- Avatars emoji (drapeaux, etc.)
+
+### Utilisateurs
+- Inscription/connexion
+- Profil avec avatar
+- Classement des apprenants
+
+### Activités
+- Quiz de vocabulaire
+- Exercices de grammaire
+- Traductions
+- Écoute et compréhension
+
+### Administration
+- Gestion du contenu pédagogique
+- Suivi des progrès des utilisateurs
+- Ajout de nouvelles activités
+
+## Variables d'environnement
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Port du serveur (3007) |
+| `JWT_SECRET` | Secret JWT |
+| `ADMIN_PASSWORD` | Mot de passe admin |
+
+## Développement
+
+```bash
+cd server
+npm install
+node server.js         # Express sur :3007
+```
+
+## Base de données
+
+SQLite en mode WAL (Write-Ahead Logging) pour de meilleures performances en lecture simultanée.