Introduction

Documentation Persona

Persona est un assistant de newsletters personnalisées piloté par IA, orchestré avec n8n. Il gère les abonnements utilisateurs, récupère des actualités depuis une API externe, réécrit les articles via un agent IA et envoie des digests HTML par email — entièrement automatisé.

Architecture générale

Le système repose sur 10 workflows n8n organisés en couches : utilitaires bas niveau (chiffrement, CRUD), orchestrateurs (envoi, cron), et interface utilisateur (agent conversationnel, webhooks publics).

┌─────────────────────────────────────────────────────┐
│                  Interface utilisateur               │
│   persona v5 (chat IA)    Web-Action (webhooks)     │
└────────────────┬────────────────────────┬───────────┘
                 │                        │
┌────────────────▼────────────────────────▼───────────┐
│               Orchestration & Envoi                  │
│     send_article       cron_exec                    │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────┐
│               CRUD & Utilitaires                     │
│  Create  Read  Update  Delete  Cipher  Update_last  │
└─────────────────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────┐
│               Stockage                               │
│              /data/users.json                        │
└─────────────────────────────────────────────────────┘

Quick Start

Démarrer en 3 étapes

./launch.sh

Configuration

Variables d'environnement

Toutes les clés sensibles sont lues depuis un fichier .env à la racine. Ne commitez jamais de valeurs réelles dans le dépôt.

GMAIL_CLIENT_ID=your-smtp-username
GMAIL_CLIENT_SECRET=your-smtp-password
NEWSAPI_KEY=your-newsapi-key
MISTRAL_API_KEY=your-mistral-api-key
APP_BASE_URL=http://localhost:5678

Architecture

Workflows n8n

Le système est composé de 10 workflows indépendants. Les workflows CRUD et utilitaires sont appelés via executeWorkflow par les orchestrateurs.

Flux d'envoi — send_article

Ce workflow est le cœur du système. Voici le pipeline complet :

• 1 Réception de email, username et preferences[] en entrée.
• 2 Appel à NewsAPI pour chaque préférence (thème).
• 3 Fusion et déduplication des articles récupérés.
• 4 Filtrage sur le catalogue de sources vérifiées.
• 5 Réécriture des snippets par l'agent Mistral avec le ton défini par l'utilisateur.
• 6 Formatage d'un digest HTML responsive.
• 7 Envoi via credential SMTP, puis appel à Update_last_send_mail.

Déploiement

Ordre de publication des workflows

Les workflows appelés (executeWorkflow) doivent être actifs avant leurs appelants. Respectez cet ordre impérativement.

Référence API

Endpoints publics (Web-Action)

Le workflow Web-Action expose deux webhooks utilisés dans les footers des newsletters envoyées.

POST /unsubscribe-user

Désactive un compte utilisateur (active: false) sans le supprimer. L'utilisateur ne recevra plus de digest.

{
  "email": "utilisateur@example.com",
  "password": "mot-de-passe-haché"
}

POST /delete-user

Supprime définitivement le compte et toutes les données associées de users.json.

{
  "username": "nom-utilisateur",
  "password": "mot-de-passe-haché"
}

Agent IA

Persona v5 — Agent conversationnel

L'agent persona v5 est le point d'entrée conversationnel du système. Il utilise Mistral Cloud avec un tampon mémoire pour maintenir le contexte entre les tours de conversation.

Outils exposés à l'agent

• tool Create user — inscription d'un nouveau compte (demande confirmation avant d'appeler).
• tool Read user — consultation du profil par email.
• tool Update user — modification avec authentification préalable obligatoire.
• tool Delete user — suppression avec double confirmation et authentification.
• tool Cipher — hachage du mot de passe avant stockage.

Règles imposées à l'agent

Données & Conformité

RGPD & gestion des données

Les données personnelles sont stockées dans /data/users.json avec une approche de minimisation stricte.

Fichiers contenant des données personnelles

• 📄 /data/users.json — données utilisateurs (email, préférences, hash)
• 📄 /data/worflows.json — métadonnées des workflows n8n
• 📄 /n8n_data/ — données d'exécution n8n (logs d'exécution, storage interne)

Sécurité

Bonnes pratiques

Secrets et credentials

• ✓ Stockez les secrets dans .env (jamais commité) ou un store dédié (Vault, cloud secrets).
• ✓ Faites tourner régulièrement les clés API (NewsAPI, Mistral, SMTP).
• ✓ Limitez les scopes des comptes SMTP et API au minimum nécessaire.
• ✓ N'incluez jamais de vraies valeurs dans README.md ou dans le dépôt.
• ✓ En production, remplacez APP_BASE_URL=http://localhost:5678 par votre domaine réel avec HTTPS.

Endpoints publics

Les webhooks /unsubscribe-user et /delete-user sont exposés publiquement. En production, sécurisez-les avec un token signé (JWT ou HMAC) intégré dans les liens du footer email.

{{ APP_BASE_URL }}/unsubscribe-user?token={{ signed_token }}

# Le token contient email + expiration, signé avec un secret HMAC