maj

docs/06_backend_architecture.md

@@ -0,0 +1,216 @@
+
+# 06 – Architecture Backend & Déploiement (FastAPI + Uvicorn + Docker)
+
+Objectif : définir la structure technique du backend, l'organisation du code, les dépendances,
+le déploiement via Docker, et les bonnes pratiques de maintenance.
+
+---
+
+# 1. Architecture générale du backend
+
+Le backend repose sur :
+
+- Python **3.11+**
+- **FastAPI** (framework web)
+- **Uvicorn** (serveur ASGI)
+- **SQLite** (stockage local)
+- **SQLAlchemy** (ORM)
+- **Pydantic** (validation des schémas)
+- Docker (déploiement)
+- Arborescence claire modulaire
+
+---
+
+# 2. Arborescence recommandée
+
+```
+backend/
+│
+├── app/
+│   ├── api/
+│   │   ├── benchmark.py
+│   │   ├── devices.py
+│   │   ├── docs.py
+│   │   ├── links.py
+│   │   └── __init__.py
+│   │
+│   ├── core/
+│   │   ├── config.py
+│   │   ├── security.py
+│   │   └── __init__.py
+│   │
+│   ├── models/
+│   │   ├── device.py
+│   │   ├── hardware_snapshot.py
+│   │   ├── benchmark.py
+│   │   ├── manufacturer_link.py
+│   │   ├── document.py
+│   │   └── __init__.py
+│   │
+│   ├── schemas/
+│   │   ├── benchmark.py
+│   │   ├── device.py
+│   │   ├── hardware.py
+│   │   ├── document.py
+│   │   ├── link.py
+│   │   └── __init__.py
+│   │
+│   ├── db/
+│   │   ├── base.py
+│   │   ├── session.py
+│   │   ├── init_db.py
+│   │   └── __init__.py
+│   │
+│   ├── utils/
+│   │   ├── scoring.py
+│   │   └── __init__.py
+│   │
+│   ├── main.py
+│   └── __init__.py
+│
+├── Dockerfile
+├── requirements.txt
+└── README.md
+```
+
+---
+
+# 3. Dépendances backend (requirements.txt)
+
+```
+fastapi
+uvicorn
+sqlalchemy
+alembic
+pydantic
+python-multipart
+jinja2
+aiofiles
+```
+
+---
+
+# 4. Fonctionnement principal
+
+## 4.1 main.py
+
+- Initialise FastAPI
+- Charge les routes `/api/*`
+- Initialise la base SQLite
+- Expose un `GET /api/health`
+
+---
+
+# 5. Configuration (core/config.py)
+
+Variables chargées via environnement :
+
+- `API_TOKEN`
+- `DATABASE_URL` → `sqlite:///./data.db`
+- `UPLOAD_DIR` → `./uploads`
+
+---
+
+# 6. Déploiement Docker
+
+## 6.1 Dockerfile
+
+```
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+
+RUN mkdir -p /app/uploads /app/data
+
+ENV API_TOKEN=CHANGE_ME
+ENV DATABASE_URL=sqlite:////app/data/data.db
+ENV UPLOAD_DIR=/app/uploads
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8007"]
+```
+
+---
+
+## 6.2 docker-compose.yml
+
+```
+version: "3.9"
+
+services:
+  backend:
+    build: ./backend
+    container_name: linux_benchtools_backend
+    ports:
+      - "8007:8007"
+    volumes:
+      - ./backend/data:/app/data
+      - ./backend/uploads:/app/uploads
+    environment:
+      API_TOKEN: "SUPER_SECRET_TOKEN"
+      DATABASE_URL: "sqlite:////app/data/data.db"
+      UPLOAD_DIR: "/app/uploads"
+    restart: unless-stopped
+```
+
+---
+
+# 7. Gestion des documents (PDF, images)
+
+- Stockés dans `/app/uploads`
+- Nommage unique (hash)
+- Entrée correspondante dans la BDD
+- Accessibles via `/api/docs/{id}/download`
+
+---
+
+# 8. Pipeline d’un benchmark
+
+1. Le client exécute `bench.sh`
+2. Un JSON complet est envoyé vers POST `/api/benchmark`
+3. Vérification du token
+4. Recherche ou création du device
+5. Création d’un hardware snapshot
+6. Création d’un benchmark
+7. Calcul / stockage du score global
+8. Réponse `{status: "ok", ...}`
+
+---
+
+# 9. Module scoring (utils/scoring.py)
+
+Calcule :
+
+```
+global_score =
+   cpu * 0.30 +
+   mem * 0.20 +
+   disk * 0.25 +
+   net * 0.15 +
+   gpu * 0.10
+```
+
+Utilise les scores normalisés reçus depuis le client.
+
+---
+
+# 10. Sécurité
+
+- API Token unique pour tous les clients
+- Upload limité en taille
+- CORS restreint au LAN si besoin
+- Aucun endpoint destructif sans authentification
+
+---
+
+# 11. Maintenance
+
+- Backup SQLite via cron
+- Logs Docker
+- Vérification santé via `/api/health`
+- Ajout futur : export JSON/CSV global
+