📚 docs: enhance README and architecture documentation

README.md

@@ -103,7 +103,9 @@ Assurez-vous d'avoir installé les éléments suivants avant de commencer :
 
 - **Node.js** : Version 22 ou supérieure (requis pour better-auth et support ESM).
 - **pnpm** : Gestionnaire de paquets version 9.7.1+ (installer avec `npm install -g pnpm@latest`).
-- **Docker** et **Docker Compose** : Pour l'exécution des services (Redis, PostgreSQL, Typesense).
+- **Docker** et **Docker Compose** : Pour l'exécution des services (Redis, PostgreSQL, PgAdmin).
+  - **Windows/macOS** : Docker Desktop doit être installé et **lancé** avant d'exécuter les commandes Docker.
+  - **Linux** : Docker Engine et Docker Compose suffisent.
 
 ### Cloner le projet
 
@@ -143,18 +145,35 @@ cp apps/web/.env.example apps/web/.env
 
 ### Lancer le projet (développement)
 
-Démarrer les services via Docker Compose (ex: PostgreSQL, PgAdmin):
+Démarrer les services via Docker Compose (PostgreSQL, PgAdmin):
 
 ```bash
 docker-compose up -d
 ```
 
-Lancer le monorepo (backend + frontends) en mode développement:
+Vérifier que les services sont bien démarrés :
+
+```bash
+docker-compose ps
+```
+
+Attendre quelques secondes que PostgreSQL soit complètement démarré, puis lancer le monorepo (backend + frontends) en mode développement:
 
 ```bash
 pnpm dev
 ```
 
+Les services seront accessibles aux URLs suivantes :
+- **Frontend Web** : http://localhost:5173
+- **API** : http://localhost:3000
+- **Documentation API (Swagger)** : http://localhost:3000/api
+- **PgAdmin** : http://localhost:5050
+- **Application Mobile** : Un QR code s'affichera dans le terminal pour Expo Go
+
+### Migrations de base de données
+
+Les migrations sont appliquées automatiquement au démarrage de l'API. Pour plus de détails sur la gestion des migrations (création, application manuelle, etc.), consultez le [README de l'API](apps/api/README.md#database-migrations).
+
 ### Données de test (Seeds)
 
 Lors du premier lancement de l'application, des données de test sont automatiquement créées dans la base de données, incluant :
@@ -186,6 +205,26 @@ Pour vous connecter, utilisez l'un des utilisateurs générés par les seeds. Le
 
 <p align="right">(<a href="#readme-top">retour en haut</a>)</p>
 
+***
+
+<!-- DOCUMENTATION COMPLEMENTAIRE -->
+<p id="documentation-complementaire"></p>
+
+## Documentation Complémentaire
+
+Pour approfondir certains aspects techniques du projet, consultez les guides suivants :
+
+### Déploiement et Infrastructure
+- **[Guide de Déploiement](docs/deployment.md)** : Configuration complète de l'infrastructure de production (VPS, Dokploy, Traefik, Docker Swarm)
+- **[Plan de Récupération d'Urgence](docs/emergency-recovery.md)** : Procédures de restauration en cas de défaillance majeure
+
+### Gestion de Base de Données
+- **[Guide des Migrations en Production](docs/migrations-production.md)** : Stratégies et bonnes pratiques pour gérer les migrations avec de vraies données utilisateur
+
+<p align="right">(<a href="#readme-top">retour en haut</a>)</p>
+
+***
+
 <!-- LICENCE -->
 <p id="licence"></p>
 

apps/api/README.md

@@ -61,6 +61,8 @@ pnpm db:migration:create --name <MigrationName>
 pnpm db:migration:up
 ```
 
+**Note:** For production migrations with real user data, see the [Production Migrations Guide](../../docs/migrations-production.md) which details backup strategies, rollback procedures, and security best practices.
+
 ## Database Seeding
 
 The application includes seeders to populate the database with initial data:
@@ -108,3 +110,7 @@ The API documentation is automatically generated from ts-rest contracts and is a
 
 The documentation is automatically kept in sync with the API contracts defined in the shared packages, ensuring that it's always up-to-date with the latest API changes.
 
+## Architecture
+
+This API follows a hexagonal architecture (Ports & Adapters) approach to separate business logic from infrastructure concerns. For a comprehensive guide on the architecture patterns, dependency injection, and implementation details, see the [Hexagonal Architecture Guide](../../docs/architecture-hexagonale.md).
+

docs/architecture-hexagonale.md

@@ -2,14 +2,29 @@
 
 ## Vue d'ensemble
 
-DropIt utilise l'architecture hexagonale (aussi appelée "Ports & Adapters") pour isoler la **logique métier** des **frameworks et infrastructures**.
+DropIt utilise une approche inspirée de l'architecture hexagonale (aussi appelée "Ports & Adapters") pour isoler la **logique métier** des **frameworks et infrastructures**.
+
+### ⚠️ Implémentation Partielle
+
+Cette architecture est une **implémentation pragmatique** de l'hexagonale, avec un compromis assumé :
+- ✅ **Use-cases framework-agnostic** : Logique métier pure TypeScript
+- ✅ **Ports & Adapters** : Injection via interfaces
+- 🟡 **Entités avec MikroORM** : Les entités domaine utilisent les décorateurs ORM pour éviter un double mapping
+
+Ce compromis permet de bénéficier des avantages de l'architecture hexagonale (testabilité, indépendance des use-cases) sans la complexité d'un mapping complet.
 
 ### Objectifs
 - ✅ **Indépendance du framework** : La logique métier ne dépend pas de NestJS
 - ✅ **Testabilité** : Les use-cases sont testables sans mock du framework
 - ✅ **Flexibilité** : Possibilité de changer de framework (NestJS → Express, etc.) sans toucher au métier
 - ✅ **Clarté** : Séparation nette des responsabilités
 
+### Pourquoi cette architecture ?
+
+L'API a progressivement évolué d'une architecture n-tiers classique vers cette approche hexagonale partielle. Cette évolution répond à une double motivation : approfondir ma compréhension de patterns architecturaux rencontrés en contexte professionnel, et anticiper des évolutions futures nécessitant l'isolation de la logique métier (intégration matériel externe, sources de données tierces).
+
+Cette implémentation reste partielle : mes entités domaine conservent les décorateurs MikroORM plutôt que d'être des objets métier purs. Ce compromis pragmatique m'a permis de livrer un MVP fonctionnel tout en explorant concrètement les bénéfices et contraintes de l'architecture hexagonale, au-delà de la théorie.
+
 ---
 
 ## Structure des Couches