Minerve AI - Spatial Placement Optimizer

Minerve AI est une application web d'aide à la décision et d'optimisation spatiale. L'application résout le problème du placement optimal de personnages/tours de formes géométriques complexes (non chevauchantes) sur une grille 2D afin de maximiser les dégâts couverts par leurs portées respectives (distance de Manhattan), le tout pondéré par un chemin d'ennemis dynamique (heatmap).

---

📂 Arborescence du Projet

Minerve/
│
├── README.md                     # Documentation générale et guide de démarrage
│
├── backend/                      # Backend FastAPI (Python)
│   ├── requirements.txt          # Dépendances Python (FastAPI, OR-Tools, OpenCV, etc.)
│   ├── main.py                   # Point d'entrée de l'application FastAPI et middleware CORS
│   ├── models/
│   │   ├── __init__.py
│   │   └── placement.py          # Modèles de données Pydantic (validation stricte)
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── optimization.py       # Endpoints d'optimisation (/optimize-placement)
│   │   └── vision.py             # Endpoints d'analyse de captures d'écran (/analyze-screenshot)
│   └── services/
│       ├── __init__.py
│       ├── optimizer.py          # Algorithme d'optimisation (Google OR-Tools + Fallback Backtracking)
│       └── computer_vision/
│           ├── __init__.py
│           └── analyzer.py       # Stub pour traitement d'images OpenCV & OCR PyTesseract
│
└── frontend/                     # Frontend React + TypeScript (Vite)
    ├── package.json              # Dépendances Node.js (React 19, DnD Kit, TypeScript)
    ├── vite.config.ts            # Configuration du serveur de dev Vite
    ├── index.html                # Point d'entrée HTML
    └── src/
        ├── main.tsx              # Point d'entrée React
        ├── App.tsx               # Composant principal (gestion de l'état, logique Drag & Drop)
        ├── index.css             # Design system (Cyberpunk Dark Mode, Animations, Variables CSS)
        ├── types/
        │   └── index.ts          # Interfaces TypeScript rigoureusement typées
        ├── api/
        │   └── client.ts         # Client d'appels réseau (fetch API vers le backend)
        └── components/
            ├── InteractiveGrid.tsx    # Rendu de la grille (manual vs optimal)
            ├── GridCell.tsx           # Cellule de grille individuelle (droppable & click heatmap)
            ├── CharacterForm.tsx      # Formulaire de création de personnage + Dessinateur 3x3
            ├── CharacterList.tsx      # Liste des personnages (inventaire vs placés)
            ├── DraggableCharacter.tsx # Enveloppe DnD pour personnage déplaçable
            └── ScreenshotUploader.tsx # Composant de simulation d'analyse de screenshot via OCR

---

🏛️ Justifications Architecturales

1. Découplage Strict (Backend / Frontend) : Les couches front-end et back-end sont séparées pour permettre un développement et déploiement indépendants. La communication se fait exclusivement par appels d'API REST typées en JSON.
2. Modularité Métier dans le Backend :
   • models/ : Centralise la validation des requêtes et réponses à l'aide de Pydantic.
   • routers/ : S'occupe uniquement du protocole HTTP (FastAPI) et redirige le traitement métier vers les services associés.
   • services/ : Contient le noyau algorithmique. L'algorithme d'optimisation n'a aucune dépendance avec FastAPI et peut être réutilisé en CLI. Le sous-dossier computer_vision/ est déjà structuré pour accueillir la future logique OCR/OpenCV sans perturber le reste de l'API.
3. Double Logique Algorithmique (Hybride) :
   • Moteur Principal (OR-Tools) : Formulé en programmation linéaire/contraintes (CP-SAT) pour des résolutions d'optimisation exactes et ultra-rapides même à plus grande échelle.
   • Moteur de Fallback (Backtracking avec élagage) : Si Google OR-Tools n'est pas disponible (ex: environnement sans compilation C++), un algorithme de backtracking pur Python prend le relais. Il trie les positions candidates par pertinence et élague les branches stériles (score maximal théorique inférieur au meilleur score trouvé).
4. Typage rigoureux et Sécurité (TypeScript & DnD-Kit) :
   • Les structures de données (grilles, coordonnées, caractéristiques de personnages) partagent le même modèle de données des deux côtés de l'application.
   • La logique de drag-and-drop utilise @dnd-kit/core avec une validation géométrique immédiate côté client (évite de surcharger le réseau si l'utilisateur glisse un personnage hors-limite ou sur une case occupée).

---

🚀 Démarrage Rapide

1. Démarrer le Backend (FastAPI)

Dans le dossier backend/ :

# 1. Installer les dépendances
pip install -r requirements.txt

# 2. Lancer le serveur uvicorn
python main.py

Le serveur démarrera sur http://localhost:8000. Vous pouvez consulter la documentation interactive Swagger sur http://localhost:8000/docs.

2. Démarrer le Frontend (React/Vite)

Dans le dossier frontend/ :

# 1. Installer les dépendances
npm install

# 2. Lancer le serveur de développement Vite
npm run dev

Le site sera accessible sur http://localhost:5173.