Démarrer en local

Prérequis

• Node ≥ 20 et pnpm 9.15.9 (figé via packageManager dans le package.json racine — corepack enable suffit).
• Docker (Postgres + Redis + MinIO + MailHog tournent en conteneurs).

Boot en trois commandes

pnpm install        # installe tous les workspaces
pnpm db:up          # docker compose : postgres (pgvector+PostGIS), redis, minio, mailhog
pnpm dev            # turbo dev : api (3001), web (3000), hermes (3002), docs (3003)

pnpm dev lance toutes les apps en parallèle via Turborepo. Les ports par défaut ne se chevauchent pas :

App	Port	Commande ciblée
apps/web	3000	pnpm --filter @pambe/web dev
apps/api	3001	pnpm --filter api dev
apps/hermes	3002	pnpm --filter @pambe/hermes dev
apps/docs	3003	pnpm --filter @pambe/docs dev

Skill « dev-pambe-local »

Le repo embarque une skill Claude Code dev-pambe-local qui vérifie Docker, les fichiers d'env, et les collisions de ports avant de booter. C'est le chemin le plus sûr pour un premier lancement.

Variables d'environnement de l'API

apps/api/src/env.ts valide l'environnement avec zod au premier appel de getEnv() — une config invalide plante au boot, pas à la première requête. Les variables sans défaut sont obligatoires :

Variable	Obligatoire	Rôle
DATABASE_URL	✅	Postgres (postgres://matching:matching@localhost:5432/matching_engine en local)
AUTH0_DOMAIN, AUTH0_AUDIENCE	✅	Vérification JWT
AUTH0_MGMT_CLIENT_ID/SECRET	✅	Management API (profils)
MISTRAL_API_KEY	✅	Embeddings + juge LLM
CLAIM_SECRET (≥ 16 car.)	✅	Signature des tokens de claim (HS256)
REDIS_URL	défaut	Cache / JWKS / cache du juge
S3_*	défauts MinIO	Stockage objet (images)
NOTIFIER_DRIVER	défaut smtp	resend (prod) · smtp (MailHog) · console
ADMIN_EMAILS	défaut ""	Liste d'emails admin séparés par des virgules — protège les routes /admin/* (voir Slice admin Hermes)
MATCH_JUDGE_TOPK, MATCH_RESULT_LIMIT_DEFAULT, MATCH_RADIUS_DEFAULT_M	défauts	Réglages du pipeline de matching

La liste complète et à jour est dans le schéma zod de apps/api/src/env.ts. Règle d'or : le code applicatif ne lit jamais process.env directement — il passe par getEnv() (voir Conventions).

Commandes utiles

pnpm build       # turbo build (toutes les apps)
pnpm lint        # turbo lint
pnpm typecheck   # turbo typecheck
pnpm format      # prettier
pnpm test        # turbo test — Vitest sur packages/lib, apps/api, apps/hermes

pnpm --filter api db:generate   # drizzle-kit generate (depuis src/db/schema.ts)
pnpm --filter api db:migrate    # applique les migrations
pnpm --filter api db:studio     # ouvre Drizzle Studio