healthai-api

REST API de la plateforme HealthAI Coach — gestion des utilisateurs, données de santé et datasets IA.

• Repo : HealthAI-Corpo/healthai-api
• Image : ghcr.io/healthai-corpo/healthai-api
• Port : 3001
• Swagger : http://localhost:3001/api (hors production uniquement)

Stack

Couche	Technologie
Framework	NestJS 11 (Express)
Langage	TypeScript 5.7
Base de données	PostgreSQL 15 via TypeORM 0.3
Authentification	Zitadel — JWT RS256 via JWKS
Messagerie	RabbitMQ via @nestjs/microservices (optionnel)
Validation	class-validator · class-transformer · Joi
Sécurité	Helmet · @nestjs/throttler
Docs	Swagger / OpenAPI à /api
Monitoring	NestJS Terminus (/health)
Tests	Jest · Supertest

Architecture

Modèle de sécurité

Chaque requête traverse dans l'ordre :

1. Rate limiter — 100 req / 60s par IP (configurable via THROTTLE_TTL / THROTTLE_LIMIT)
2. Helmet — headers CSP, HSTS, X-Frame-Options
3. CORS — whitelist d'origines via FRONTEND_ORIGIN
4. JWT Guard — valide le Bearer token RS256 contre le JWKS Zitadel, puis résout l'utilisateur local par email

Routes publiques (pas de JWT requis) : GET /health, POST /auth/login. Toutes les autres routes nécessitent un Bearer token Zitadel valide.

Clés JWKS mises en cache

Les clés publiques Zitadel sont mises en cache côté serveur. Pas d'appel réseau à chaque requête après le premier fetch.

Endpoints

Tag Swagger	Base path	Description
auth	/auth	Login, gestion de session
health	/health	Health check BDD — public
utilisateurs	/utilisateurs	CRUD utilisateurs
aliments	/aliments	Catalogue des aliments (valeurs nutritionnelles)
exercices	/exercices	Catalogue des exercices
log-aliments	/log-aliment	Journal alimentaire quotidien
log-seances	/log-seance	Journal d'entraînement
log-santes	/log-sante	Métriques de santé quotidiennes
profil-sante	/profil-sante	Profil santé — un par utilisateur
datasets-recommandations	/datasets/recommandations-regime	Dataset IA — régimes
datasets-exercices	/datasets/historique-seance-exercice	Dataset IA — séances sportives
etl-log	/etl-log	Logs du pipeline ETL

Variables d'environnement

Variable	Requis	Défaut	Description
DATABASE_URL	✅	—	PostgreSQL connection string (postgresql://...)
ZITADEL_DOMAIN	✅	—	URL de l'instance Zitadel (ex: https://auth.example.com)
JWT_ISSUER	✅	—	Doit correspondre au claim iss des tokens Zitadel
JWT_AUDIENCE	✅	—	Client ID de l'application dans Zitadel
FRONTEND_ORIGIN	✅	—	Origines CORS autorisées, séparées par virgule
PORT	❌	3001	Port d'écoute HTTP
THROTTLE_TTL	❌	60000	Fenêtre rate limit (ms)
THROTTLE_LIMIT	❌	100	Requêtes max par fenêtre par IP
RABBITMQ_ENABLED	❌	false	Active la connexion RabbitMQ
RABBITMQ_HOST	❌*	—	*Requis si RABBITMQ_ENABLED=true
RABBITMQ_USER	❌*	—	*Requis si RABBITMQ_ENABLED=true
RABBITMQ_PASS	❌*	—	*Requis si RABBITMQ_ENABLED=true
RABBITMQ_QUEUE	❌	healthai.load-balance	Nom de la queue
NODE_ENV	❌	development	development | production | test

Swagger

Le Swagger n'est disponible qu'en dehors de production. En production, la route /api renvoie 404.

RabbitMQ

Le module RabbitMQ est optionnel et désactivé par défaut. Il est activé via RABBITMQ_ENABLED=true.

Quand activé, l'API publie des événements sur la queue configurée — utilisé pour notifier l'ETL ou les services IA sans couplage direct.

Quand désactivé, tout appel à RabbitMqService.emit() ou .send() lève une ServiceUnavailableException.

Installation

npm install
cp .env.example .env  # remplir les variables requises
npm run migration:run
npm run start:dev
# → http://localhost:3001
# → http://localhost:3001/api (Swagger)

Scripts utiles

# Développement
npm run start:dev            # Mode watch

# Migrations TypeORM
npm run migration:generate   # Générer depuis les entités
npm run migration:run        # Appliquer
npm run migration:revert     # Annuler la dernière

# Seed (développement uniquement)
npm run seed:dev-account

# Tests
npm run test                 # Unitaires (Jest)
npm run test:cov             # Avec couverture
npm run test:e2e             # End-to-end

Configuration Zitadel

1. Créer une application API dans le projet Zitadel
2. JWT_ISSUER = URL de l'instance Zitadel (ex: https://auth.example.com)
3. JWT_AUDIENCE = Client ID de l'application API
4. ZITADEL_DOMAIN = même URL que JWT_ISSUER

Le JWKS est résolu automatiquement sur {ZITADEL_DOMAIN}/oauth/v2/keys.