# API Backend pour Anime-Sama - Architecture Optimisée

Je souhaite créer une API backend pour mon site https://anime-sama.fr/ qui héberge légalement des animés. L'architecture sera divisée en deux parties distinctes pour optimiser les performances : un scraper automatisé et une API REST pure.

## Architecture en deux parties

### 1. Scraper automatisé (Programme indépendant)
Programme qui s'exécute toutes les 30 minutes pour :
- Scraper intégralement anime-sama.fr
- Récupérer les métadonnées via Kitsu API
- Mettre à jour la base de données
- Fonctionnement autonome sans interaction utilisateur

### 2. API REST (Serveur web)
Serveur qui sert uniquement les données depuis la base de données :
- Aucun scraping en temps réel
- Réponses ultra-rapides (lecture seule en BDD)
- Endpoints optimisés pour l'application mobile

## Programme Scraper

### Fonctionnalités du scraper
- **Scraping complet d'anime-sama.fr** toutes les 30 minutes
- **Détection des nouveaux animés** et ajout en base
- **Détection des nouveaux épisodes** et ajout en base
- **Enrichissement via Kitsu API** : thumbnails, métadonnées
- **Mise à jour des données existantes** si modifications détectées
- **Logging complet** des opérations

### Tables de base de données existantes

#### Table `animes`
```sql
- id (PRIMARY KEY)
- titre
- titre_alternatif
- titre_anglais
- titre_japonais
- synopsis
- genres (JSON array)
- studio
- annee_sortie
- statut
- note_moyenne
- image_couverture
- poster_url
- url_anime_sama
- kitsu_id
- nombre_episodes_total
- created_at
- updated_at
```

#### Table `episodes`
```sql
- id (PRIMARY KEY)
- anime_id (FOREIGN KEY -> animes.id)
- numero_episode
- titre_episode
- description
- duree
- thumbnail_url (depuis Kitsu API)
- url_streaming (JSON array)
- qualites_disponibles (JSON array)
- date_sortie
- kitsu_episode_id
- created_at
- updated_at
```

### Processus de scraping détaillé

#### 1. Scraping d'anime-sama.fr
```
1. Parcourir la page catalogue complète
2. Pour chaque animé trouvé :
   - Extraire : titre, synopsis, genres, année, statut
   - Vérifier si existe en BDD (par titre ou URL)
   - Si nouveau : créer en BDD, sinon : vérifier les modifications
   
3. Pour chaque page d'animé :
   - Extraire la liste complète des épisodes
   - Pour chaque épisode :
     - Extraire : numéro, titre, liens streaming, qualités
     - Vérifier si existe en BDD
     - Si nouveau : créer en BDD
```

#### 2. Enrichissement via Kitsu API
```
1. Pour chaque animé sans kitsu_id :
   - Rechercher sur Kitsu API par titre
   - Récupérer : ID Kitsu, métadonnées enrichies, poster HD
   - Mettre à jour l'animé en BDD
   
2. Pour chaque épisode sans thumbnail :
   - Utiliser kitsu_id de l'animé parent
   - Récupérer les épisodes depuis Kitsu API
   - Matcher par numéro d'épisode
   - Récupérer le thumbnail et l'ID Kitsu
   - Mettre à jour l'épisode en BDD
```

### Stack technique du scraper
- **Langage** : Node.js ou Python
- **Scraping** : Puppeteer/Playwright (Node.js) ou Scrapy/BeautifulSoup (Python)
- **HTTP Client** : Axios (Node.js) ou Requests (Python)
- **Base de données** : MySQL/PostgreSQL avec ORM (Sequelize/Prisma ou SQLAlchemy)
- **Scheduling** : Cron job système ou node-cron
- **Logging** : Winston (Node.js) ou logging (Python)

### Gestion des erreurs du scraper
- **Retry automatique** : 3 tentatives pour chaque requête échouée
- **Timeout handling** : Délais d'attente configurables
- **Rate limiting Kitsu** : Respect des limites (1000 req/hour pour Kitsu)
- **Logging des échecs** : Fichiers de log détaillés avec timestamps
- **Notification d'erreurs** : Email/webhook en cas d'échec critique

## API REST (Serveur)

### Philosophie
- **Lecture seule** : Aucune modification de données
- **Performance maximale** : Cache en mémoire + Redis
- **Réponses rapides** : Toutes les données viennent de la BDD

### Endpoints optimisés

#### Animés
```
GET /api/anime/latest?limit=20 - Derniers animés (ORDER BY created_at DESC)
GET /api/anime/popular?limit=20 - Plus populaires (ORDER BY note_moyenne DESC)
GET /api/anime/search?q={query} - Recherche (FULLTEXT sur titres)
GET /api/anime/{id} - Détails animé avec épisodes
GET /api/anime/genres - Liste unique des genres
```

#### Épisodes
```
GET /api/episodes/latest?limit=50 - Derniers épisodes (ORDER BY created_at DESC)
GET /api/episode/{id} - Détails épisode avec liens streaming
GET /api/anime/{anime_id}/episodes - Tous les épisodes d'un animé
```

#### Métadonnées
```
GET /api/stats - Compteurs (SELECT COUNT(*) FROM animes/episodes)
GET /api/status - Dernière MAJ scraper + santé API
```

### Optimisations API
- **Cache Redis** : TTL 1h pour les listes, 24h pour les détails
- **Pagination** : LIMIT/OFFSET avec liens next/prev
- **Index BDD** : Sur titre, genres, created_at, anime_id
- **Compression** : Gzip automatique
- **CORS** : Configuration pour domaines autorisés

### Stack technique API
- **Framework** : Express.js (Node.js) ou FastAPI (Python)
- **Cache** : Redis avec TTL intelligent
- **Base de données** : Même que le scraper
- **Validation** : Joi (Node.js) ou Pydantic (Python)
- **Documentation** : Swagger/OpenAPI automatique

## Déploiement

### Structure des services
```
1. Service Scraper :
   - Cron job toutes les 30min
   - Logs rotatifs
   - Monitoring des performances
   
2. Service API :
   - Serveur web permanent
   - Load balancer si nécessaire
   - Cache Redis partagé
```

### Monitoring
- **Scraper** : Logs de chaque cycle, durée d'exécution, erreurs
- **API** : Temps de réponse, nombre de requêtes, erreurs HTTP
- **Base de données** : Croissance des tables, performances requêtes
- **Alertes** : Email si scraper échoue ou API down

## Configuration

### Variables d'environnement
```
# Base de données
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS

# Redis
REDIS_URL

# Kitsu API
KITSU_API_URL=https://kitsu.io/api/edge

# Scraper
SCRAPER_INTERVAL=30min
SCRAPER_TIMEOUT=60s
SCRAPER_RETRIES=3

# API
API_PORT=3000
API_CACHE_TTL=3600
```

### Exemple de cycle complet
```
1. Scraper démarre (toutes les 30min)
2. Scrape anime-sama.fr → trouve 5 nouveaux épisodes
3. Pour chaque épisode → cherche thumbnail Kitsu
4. Insert en BDD → 5 nouveaux enregistrements
5. API Redis cache invalidé automatiquement
6. Prochaine requête API → données fraîches depuis BDD
```

Cette architecture garantit des performances maximales pour l'API (aucun scraping en temps réel) tout en maintenant les données à jour automatiquement.