Development Guide — Backend (`app/`)

Prerequisites

Docker Engine + Docker Compose plugin
Node.js ≥ 20 (Prisma préfère ≥ 22 — warning non bloquant sinon)
Git, OpenSSL (pour génération clés/secrets)
Accès au VPS prod 51.91.57.176 via SSH si déploiement
Comptes externes : Resend, Vonage (SMS), HuggingFace, Anthropic, Sentry, PostHog, Cloudflare Stream, MinIO root creds

Installation locale

git clone git@github.com:ouattaradfabrice/superApp_V1.git
cd superApp_V1

# .env à la racine (variables compose)
# Modèle de fichier — adapter
cat > .env << 'EOF'
POSTGRES_DB=superapp
POSTGRES_USER=superapp
POSTGRES_PASSWORD=<random>
POSTGRES_PORT=5432
REDIS_PORT=6379
MINIO_ROOT_USER=<min 8 chars>
MINIO_ROOT_PASSWORD=<min 8 chars>
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
NEXTJS_PORT=3000
SENTRY_AUTH_TOKEN=<from Sentry>
TYPESENSE_API_KEY=<random base64>
EOF

# .env.vonage (séparé)
cat > .env.vonage << 'EOF'
VONAGE_API_KEY=<your-key>
VONAGE_API_SECRET=<secret>
EOF

# .env.local dans app/ (variables runtime app)
# Voir liste exhaustive dans app/.env.example si présent, sinon :
# NEXTAUTH_SECRET (JWT secret partagé cookie + Bearer)
# DATABASE_URL (override possible — sinon hérité de docker compose)
# RESEND_API_KEY
# VONAGE_API_KEY / VONAGE_API_SECRET
# HUGGINGFACE_TOKEN (CLIP embeddings)
# ANTHROPIC_API_KEY (vision search V1)
# GEMINI_API_KEY (snap-to-list OCR)
# POSTHOG_KEY + POSTHOG_HOST
# SENTRY_DSN + SENTRY_AUTH_TOKEN
# CRON_SECRET (auth endpoints /api/cron/*)
# CLOUDFLARE_STREAM_TOKEN
# MINIO_PUBLIC_URL (https://wari.pro/medias en prod, http://localhost:9000 dev)

git clone git@github.com:ouattaradfabrice/superApp_V1.git
cd superApp_V1

# .env à la racine (variables compose)
# Modèle de fichier — adapter
cat > .env << 'EOF'
POSTGRES_DB=superapp
POSTGRES_USER=superapp
POSTGRES_PASSWORD=<random>
POSTGRES_PORT=5432
REDIS_PORT=6379
MINIO_ROOT_USER=<min 8 chars>
MINIO_ROOT_PASSWORD=<min 8 chars>
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
NEXTJS_PORT=3000
SENTRY_AUTH_TOKEN=<from Sentry>
TYPESENSE_API_KEY=<random base64>
EOF

# .env.vonage (séparé)
cat > .env.vonage << 'EOF'
VONAGE_API_KEY=<your-key>
VONAGE_API_SECRET=<secret>
EOF

# .env.local dans app/ (variables runtime app)
# Voir liste exhaustive dans app/.env.example si présent, sinon :
# NEXTAUTH_SECRET (JWT secret partagé cookie + Bearer)
# DATABASE_URL (override possible — sinon hérité de docker compose)
# RESEND_API_KEY
# VONAGE_API_KEY / VONAGE_API_SECRET
# HUGGINGFACE_TOKEN (CLIP embeddings)
# ANTHROPIC_API_KEY (vision search V1)
# GEMINI_API_KEY (snap-to-list OCR)
# POSTHOG_KEY + POSTHOG_HOST
# SENTRY_DSN + SENTRY_AUTH_TOKEN
# CRON_SECRET (auth endpoints /api/cron/*)
# CLOUDFLARE_STREAM_TOKEN
# MINIO_PUBLIC_URL (https://wari.pro/medias en prod, http://localhost:9000 dev)

Lancement Docker Compose (recommandé)

# Build + up (postgres + redis + minio + typesense + nextjs)
docker compose up -d --build

# Logs
docker compose logs -f nextjs
docker compose ps

# Prisma : migrate + generate dans le conteneur
docker exec -it superapp_nextjs npx prisma generate
docker exec -it superapp_nextjs npx prisma migrate deploy

# Seed (optionnel, profile demo)
docker exec -it superapp_nextjs sh -c \
  "DATABASE_URL=\$DATABASE_URL WARI_SEED_PROFILE=demo npx prisma db seed"

# Arrêt
docker compose down
# Arrêt + suppression volumes (⚠️ détruit data postgres/minio)
docker compose down -v

# Build + up (postgres + redis + minio + typesense + nextjs)
docker compose up -d --build

# Logs
docker compose logs -f nextjs
docker compose ps

# Prisma : migrate + generate dans le conteneur
docker exec -it superapp_nextjs npx prisma generate
docker exec -it superapp_nextjs npx prisma migrate deploy

# Seed (optionnel, profile demo)
docker exec -it superapp_nextjs sh -c \
  "DATABASE_URL=\$DATABASE_URL WARI_SEED_PROFILE=demo npx prisma db seed"

# Arrêt
docker compose down
# Arrêt + suppression volumes (⚠️ détruit data postgres/minio)
docker compose down -v

Lancement local hors Docker (dev front rapide)

cd app
npm install
# Postgres + Redis + MinIO + Typesense doivent être accessibles
# (soit Docker à part, soit services tiers)
npm run dev        # Next.js dev avec Turbopack

cd app
npm install
# Postgres + Redis + MinIO + Typesense doivent être accessibles
# (soit Docker à part, soit services tiers)
npm run dev        # Next.js dev avec Turbopack

Scripts npm

{
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint",
  "test": "vitest run",
  "test:watch": "vitest",
  "test:coverage": "vitest run --coverage"
}

{
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint",
  "test": "vitest run",
  "test:watch": "vitest",
  "test:coverage": "vitest run --coverage"
}

Workflow Prisma

# Modifier app/prisma/schema.prisma
# Créer une migration (DEV only)
cd app
npx prisma migrate dev --name add_xxx
# Cela génère app/prisma/migrations/<timestamp>_add_xxx/migration.sql
# ET applique la migration localement
# ET regenere @prisma/client

# DÉPLOIEMENT PROD (ne JAMAIS migrate dev en prod)
docker exec -it superapp_nextjs npx prisma migrate deploy
docker exec -it superapp_nextjs npx prisma generate  # OBLIGATOIRE après deploy

# Studio (UI Prisma)
npx prisma studio  # http://localhost:5555

# Modifier app/prisma/schema.prisma
# Créer une migration (DEV only)
cd app
npx prisma migrate dev --name add_xxx
# Cela génère app/prisma/migrations/<timestamp>_add_xxx/migration.sql
# ET applique la migration localement
# ET regenere @prisma/client

# DÉPLOIEMENT PROD (ne JAMAIS migrate dev en prod)
docker exec -it superapp_nextjs npx prisma migrate deploy
docker exec -it superapp_nextjs npx prisma generate  # OBLIGATOIRE après deploy

# Studio (UI Prisma)
npx prisma studio  # http://localhost:5555

Règle absolue (CLAUDE.md) : après chaque migration Prisma → npx prisma generate dans le container, puis rebuild :

cd ~/superApp_V1 && docker compose build nextjs && docker compose up -d nextjs && sleep 15 && docker logs superapp_nextjs --tail 20

cd ~/superApp_V1 && docker compose build nextjs && docker compose up -d nextjs && sleep 15 && docker logs superapp_nextjs --tail 20

Turbopack ne hot-reload pas les routes API dans ce setup Docker.

Conventions code

Tirées de app/CLAUDE.md :

Toujours lire les fichiers avant de modifier — Read jamais cat, pas de réécriture aveugle
Pas de docker exec pour lire les fichiers — ils sont dans ~/superApp_V1/app/src/
JSX/TSX complexes : utiliser Python pour éviter corruption Markdown/SSH
Pas de commentaires sauf WHY non-évident (CLAUDE.md racine)
Pas de docstrings multi-lignes (CLAUDE.md racine)
Pas de feature flags ni shims rétrocompat — change le code directement
Préférer éditer existing files plutôt qu'en créer de nouveaux
Pas de gestion d'erreur pour cas impossibles — trust framework garanties
Valider aux frontières système uniquement (input user, APIs externes)
Ne pas supprimer les guards hasBuilderXXX dans vitrine-page.tsx
Ne pas installer NextAuth — auth custom avec jose

Protocole décisions techniques

Avant toute modif impliquant un choix architectural (cf. app/CLAUDE.md) :

STOPPER et présenter la décision au user au format :

🤔 DÉCISION REQUISE — [Sujet]
Contexte : ...
Options : A) ... B) ... [C) ...]
Mon avis sincère : ...
Impact si on se trompe : ...
J'attends ta validation avant de continuer.

🤔 DÉCISION REQUISE — [Sujet]
Contexte : ...
Options : A) ... B) ... [C) ...]
Mon avis sincère : ...
Impact si on se trompe : ...
J'attends ta validation avant de continuer.

Coder sans discuter uniquement pour : bugs évidents, champs optionnels sans migration, UI sans changement comportement, refactoring interne sans impact API, ajout de logs.

Tests

cd app
npm run test           # vitest run (unitaires lib/)
npm run test:watch
npm run test:coverage  # avec @vitest/coverage-v8

cd app
npm run test           # vitest run (unitaires lib/)
npm run test:watch
npm run test:coverage  # avec @vitest/coverage-v8

Cible : tests dans app/src/lib/__tests__/ (8 tests post-P0 hardening). Phase A (couverture API routes) à 0% — référencé dans audit 2026-05-20.

Validation manuelle pattern :

# Bearer test
TOKEN=$(curl -s -X POST https://wari.pro/api/mobile/auth \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"client-test@test.wari.pro","otp":"123456"}' | jq -r .bearerToken)

# Route protégée
curl -s -H "Authorization: Bearer $TOKEN" https://wari.pro/api/mobile/session | jq

# Route publique
curl -s 'https://wari.pro/api/mobile/home' | jq

# Bearer test
TOKEN=$(curl -s -X POST https://wari.pro/api/mobile/auth \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"client-test@test.wari.pro","otp":"123456"}' | jq -r .bearerToken)

# Route protégée
curl -s -H "Authorization: Bearer $TOKEN" https://wari.pro/api/mobile/session | jq

# Route publique
curl -s 'https://wari.pro/api/mobile/home' | jq

Linting

cd app
npm run lint        # eslint flat config (eslint.config.mjs)
# CI bloquant depuis P0 hardening (avant : warnings tolérés)

cd app
npm run lint        # eslint flat config (eslint.config.mjs)
# CI bloquant depuis P0 hardening (avant : warnings tolérés)

Sentry

instrumentation.ts initialise Sentry server (Next.js 16 conventions)
instrumentation-client.ts initialise Sentry client
DSN + auth token via .env.local
Replays + perf tracing activés en prod

Permissions VPS

Quand des fichiers ont été créés par root (souvent après exec conteneur) :

sudo chown -R $USER:$USER app/.next app/cache app/tsconfig.tsbuildinfo

sudo chown -R $USER:$USER app/.next app/cache app/tsconfig.tsbuildinfo

Backup VPS

# Manuel
bash app/scripts/backup-postgres.sh
bash app/scripts/backup-minio.sh

# Cron (à activer une fois par sudo)
sudo cp app/scripts/wari-backup.cron /etc/cron.d/wari-backup
sudo systemctl restart cron

# Manuel
bash app/scripts/backup-postgres.sh
bash app/scripts/backup-minio.sh

# Cron (à activer une fois par sudo)
sudo cp app/scripts/wari-backup.cron /etc/cron.d/wari-backup
sudo systemctl restart cron

Voir runbook complet : app/docs/runbook-backups.md.

Notion + IDs WP/BUG/DEC

Workflow décrit dans app/CLAUDE.md section "Workflow Notion" :

Notion (via MCP) = source de vérité du projet
CLAUDE.md = source de vérité pour les IDs
Feature livrée → entrée dans Roadmap (WP-XXX)
Bug résolu → entrée dans Bug Tracker (BUG-XXX)
Décision technique → entrée dans Décisions techniques (DEC-XXX) — si bloqué MCP, noter dans rapport de session
Fin de session : rapport au format documenté dans app/CLAUDE.md

IDs de départ session courante (Mai 2026) : WP-233, BUG-135, DEC-224.

BMAD framework

Installé 2026-05-23 dans _bmad/ + _bmad-output/ (44 skills sous .claude/skills/bmad-*).

À utiliser pour :

Cadrer epics significatifs (PRD, architecture, UX design, stories)
Pas pour bugfix routiniers — garder workflow Notion + sessions de fix dédiées

Skills clés : bmad-prd, bmad-create-architecture, bmad-create-story, bmad-dev-story, bmad-code-review.

Debug

# Tail logs container
docker compose logs -f nextjs

# Healthcheck
curl http://127.0.0.1:3000/api/mobile/health

# Postgres shell
docker exec -it superapp_postgres psql -U $POSTGRES_USER $POSTGRES_DB

# Redis shell
docker exec -it superapp_redis redis-cli

# MinIO console
# http://127.0.0.1:9001 (MINIO_ROOT_USER / MINIO_ROOT_PASSWORD)

# Typesense health
curl 'http://127.0.0.1:8108/health'

# Tail logs container
docker compose logs -f nextjs

# Healthcheck
curl http://127.0.0.1:3000/api/mobile/health

# Postgres shell
docker exec -it superapp_postgres psql -U $POSTGRES_USER $POSTGRES_DB

# Redis shell
docker exec -it superapp_redis redis-cli

# MinIO console
# http://127.0.0.1:9001 (MINIO_ROOT_USER / MINIO_ROOT_PASSWORD)

# Typesense health
curl 'http://127.0.0.1:8108/health'

Guide dev backend

Development Guide — Backend (app/)