
# 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

