Skip to content

matchID-project/deces-mail-analyzer

BranchesTags

Repository files navigation

Analyseur d'Emails de Décès

Application web complète pour télécharger, analyser (via IA), stocker, indexer et rechercher des emails, avec un focus sur l'identification d'informations relatives aux décès.

Aperçu de l'Architecture

  • Frontend : Application SvelteKit construite avec Vite, utilisant TypeScript et Tailwind CSS.
  • Backend : API robuste construite avec Node.js et TypeScript (utilisant Fastify ou une structure similaire), responsable de la logique métier, de l'interaction avec les services externes et de la gestion des données.
  • Base de Données Vectorielle : LanceDB pour le stockage et la recherche sémantique des embeddings d'emails.
  • Authentification : OAuth 2.0 avec Google pour sécuriser l'accès.
  • Orchestration : Docker et Docker Compose pour la conteneurisation et la gestion des services en environnements de développement et de production.
  • Reverse Proxy : Nginx pour gérer les requêtes entrantes, le SSL (en production), et servir le frontend.
  • Cache : Redis pour la mise en cache des sessions ou d'autres données fréquemment accédées.

Structure du Projet

.
├── backend/
│   ├── src/                    # Code source du backend (TypeScript)
│   │   ├── app.ts              # Point d'entrée de l'application backend
│   │   ├── routes/             # Définitions des routes de l'API
│   │   ├── services/           # Logique métier (Gmail, Analyse IA, VectorStore)
│   │   └── types/              # Définitions des types TypeScript
│   ├── package.json
│   ├── tsconfig.json
│   ├── Dockerfile.dev          # Dockerfile pour le développement backend
│   └── Dockerfile.prod         # Dockerfile pour la production backend
├── frontend/
│   ├── src/                    # Code source du frontend (Svelte, TypeScript)
│   │   ├── app.html
│   │   ├── routes/             # Structure des pages/routes SvelteKit
│   │   ├── components/         # Composants Svelte réutilisables
│   │   └── lib/                # Utilitaires, store Svelte, client API
│   ├── static/                 # Fichiers statiques
│   ├── package.json
│   ├── svelte.config.js
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── Dockerfile.dev          # Dockerfile pour le développement frontend
│   └── Dockerfile.prod         # Dockerfile pour la production frontend
├── nginx/
│   └── nginx.conf              # Configuration Nginx (peut être adaptée pour dev/prod si besoin)
├── data/                       # Données persistantes (ex: base LanceDB)
├── scripts/                    # Scripts utilitaires (ex: initialisation)
├── .env.example                # Fichier d'exemple pour les variables d'environnement
├── docker-compose.dev.yml      # Configuration Docker Compose pour le développement
├── docker-compose.prod.yml     # Configuration Docker Compose pour la production
├── Makefile                    # Commandes Make pour simplifier les opérations courantes
└── README.md                   # Ce fichier

Prérequis

  • Docker (Installation)
  • Docker Compose (généralement inclus avec Docker Desktop, sinon Installation)
  • Make (disponible sur la plupart des systèmes Linux/macOS, peut nécessiter une installation sur Windows)
  • Git

Configuration Initiale

  1. Cloner le dépôt :

    git clone <url_du_depot>
cd deces-mail-analyzer

  2. Configurer les Variables d'Environnement : Copiez le fichier d'exemple .env.example en .env à la racine du projet :

    cp .env.example .env

    Ouvrez le fichier .env et remplissez toutes les variables requises avec vos propres clés et configurations. Consultez la section "Variables d'Environnement" ci-dessous pour plus de détails.

  3. Vérifier la configuration Docker (optionnel mais recommandé) : Cette commande vérifie que Docker et Docker Compose sont installés et fonctionnels.

    make setup

Variables d'Environnement (.env)

Le fichier .env à la racine du projet est utilisé pour configurer tous les services. Assurez-vous de remplacer les valeurs d'exemple.

# --- Google OAuth2 (Backend & Frontend) ---
GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
# Pour le backend (utilisé pour la validation du token)
GOOGLE_REDIRECT_URI=http://localhost/auth/google/callback 
# Pour le frontend (utilisé pour initier le flux OAuth) - Assurez-vous que ce port correspond à celui exposé par Nginx
VITE_GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID 
VITE_GOOGLE_REDIRECT_URI=http://localhost/auth/google/callback

# --- OpenAI API ---
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
OPENAI_MODEL=text-embedding-3-small # Ou un autre modèle d'embedding/chat
OPENAI_EMBEDDING_DIMENSION=1536 # Dimension du modèle d'embedding

# --- AWS S3 (si utilisé pour le stockage de fichiers/emails bruts) ---
AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY
AWS_REGION=your-aws-region
S3_BUCKET=your-s3-bucket-name
S3_PREFIX=emails/

# --- LanceDB ---
LANCEDB_PATH=/app/data/lancedb # Chemin à l'intérieur du conteneur backend pour la DB LanceDB
# LANCEDB_COLLECTION_NAME=emails # Nom de la collection (par défaut 'emails' dans le code)

# --- Redis Cache ---
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=votre_mot_de_passe_redis_secret
REDIS_DB=0

# --- API Backend Configuration (Node.js/Fastify) ---
API_HOST=0.0.0.0
API_PORT=8000 # Port interne au conteneur backend
API_WORKERS=1 # Nombre de workers pour l'API (ajuster pour la production)
API_LOG_LEVEL=debug # (debug, info, warn, error)

# --- Frontend Configuration (Vite) ---
# VITE_API_URL est configuré dynamiquement via Nginx (ex: /api)
NODE_ENV=development # ou production

# --- Sécurité ---
JWT_SECRET=un_secret_jwt_tres_complexe_et_long
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# --- Rate Limiting (Exemple, à implémenter si nécessaire) ---
# RATE_LIMIT_REQUESTS=100
# RATE_LIMIT_WINDOW=3600 # en secondes

# --- Email Processing (Exemple) ---
# EMAIL_BATCH_SIZE=50
# EMAIL_MAX_RETRIES=3
# EMAIL_RETRY_DELAY=60 # en secondes

Note importante pour GOOGLE_REDIRECT_URI et VITE_GOOGLE_REDIRECT_URI : Elles doivent pointer vers le callback d'authentification géré par votre backend, accessible via Nginx (par exemple, http://localhost/auth/google/callback si Nginx écoute sur le port 80). Assurez-vous que cette URI est enregistrée dans votre console Google Cloud Platform pour vos identifiants OAuth2.

Développement

  1. Initialiser l'environnement de développement (première fois ou après un make clean) : Cette commande construit les images Docker nécessaires et s'assure que le fichier .env existe (le créant à partir de .env.example si besoin).

    make init-dev

  2. Démarrer tous les services en mode développement : Utilise docker-compose.dev.yml. Les modifications du code source dans backend/ et frontend/ devraient déclencher un rechargement à chaud (hot-reloading) lorsque c'est applicable.

    make run-dev

  3. Accéder à l'application : Ouvrez votre navigateur à l'adresse :

    • Application : http://localhost (ou le port que vous avez configuré pour Nginx dans docker-compose.dev.yml, ex: http://localhost:8080)
    • L'API backend est accessible via Nginx sous le préfixe /api/ (par exemple, http://localhost/api/emails).

  4. Arrêter les services de développement : Appuyez sur Ctrl+C dans le terminal où make run-dev s'exécute.

Production

  1. Construire les images optimisées pour la production :

    make build-docker-prod

    Si vous avez besoin de construire également les artefacts applicatifs (ex: build frontend statique, compilation backend) localement avant le build Docker (moins courant si le Dockerfile de production s'en charge) :

    make build # Cible principale qui peut inclure build-backend, build-frontend-prod, build-docker-prod

  2. Démarrer tous les services en mode production : Utilise docker-compose.prod.yml. Les services démarreront en mode détaché (-d).

    make run-prod

  3. Accéder à l'application en production : Similaire au développement, généralement sur http://localhost ou le domaine configuré si déployé.

  4. Arrêter les services de production :

    # Depuis la racine du projet
docker compose -f docker-compose.prod.yml down -v

Commandes make Utiles

  • make setup: Vérifie les prérequis Docker.
  • make init-dev: Prépare l'environnement de développement (crée .env, build les images dev).
  • make run-dev: Démarre l'application en mode développement via Docker Compose.
  • make build-docker-dev: Construit les images Docker pour le développement.
  • make run-prod: Démarre l'application en mode production via Docker Compose.
  • make build-docker-prod: Construit les images Docker pour la production.
  • make build: Tâche de build complète pour la production.
  • make clean: Nettoie les artefacts de build, node_modules, et arrête/supprime les conteneurs Docker du projet.
  • make test-backend: Exécute les tests unitaires et d'intégration du backend.
  • make test-frontend: Exécute les tests du frontend.
  • make test: Exécute tous les tests.
  • make help: Affiche la liste des commandes make disponibles.

Tests

  • Backend : Les tests sont configurés avec Jest. 
    make test-backend
# ou pour des tests spécifiques dans le dossier backend:
# cd backend
# npm run test:unit
# npm run test:integration
  • Frontend : Les tests sont configurés avec Vitest (ou l'outil de test Svelte par défaut). 
    make test-frontend
# ou pour des tests spécifiques dans le dossier frontend:
# cd frontend
# npm run test # (ou la commande configurée dans package.json)

Gestion des Données LanceDB

  • Les données de la base LanceDB sont stockées dans le volume Docker mappé au dossier ./data/lancedb (ou ce qui est configuré via LANCEDB_PATH dans le conteneur).
  • Ce dossier est persisté sur votre machine hôte, donc les données survivent aux redémarrages des conteneurs.
  • Pour une réinitialisation complète de la base LanceDB, vous pouvez arrêter les conteneurs et supprimer le contenu du dossier ./data/lancedb sur votre machine hôte avant de redémarrer.

Dépannage

  • Erreurs "Cannot find module" (Linter) : Si votre éditeur de code affiche des erreurs de type "Cannot find module" pour des dépendances qui sont bien listées dans package.json (ex: @lancedb/lancedb, apache-arrow, fastify), essayez de redémarrer le serveur TypeScript de votre éditeur (souvent une commande dans la palette de l'éditeur, ex: "TypeScript: Restart TS server" pour VS Code) après un make clean et make run-dev. Ces erreurs sont parfois des faux positifs du linter de l'éditeur et n'affectent pas l'exécution si les dépendances sont correctement installées dans le conteneur Docker.
  • Problèmes de port : Si Nginx ne démarre pas ou si vous ne pouvez pas accéder à http://localhost, vérifiez qu'aucun autre service n'utilise le port 80 (ou le port que vous avez configuré pour Nginx) sur votre machine hôte.
  • Logs : Pour diagnostiquer les problèmes, consultez les logs des conteneurs : 
    # Pour le développement
docker compose -f docker-compose.dev.yml logs -f
docker compose -f docker-compose.dev.yml logs -f backend
docker compose -f docker-compose.dev.yml logs -f frontend
docker compose -f docker-compose.dev.yml logs -f nginx

# Pour la production
docker compose -f docker-compose.prod.yml logs -f

TODO / Améliorations Futures

  • Implémenter la génération réelle d'embeddings dans VectorStore (actuellement utilise des vecteurs factices).
  • Finaliser l'implémentation de la recherche par filtres, tri dans emailRoutes.
  • Ajouter des tests d'intégration plus complets.
  • Mettre en place un système de logging plus avancé pour la production.
  • Sécuriser davantage les endpoints de l'API (permissions granulaires si nécessaire).
  • Optimiser les builds Docker pour la production (multi-stage builds sont déjà en place, vérifier la taille des images).
  • Documentation API détaillée avec Swagger/OpenAPI (en partie en place avec Fastify).

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages