​

Architecture technique

​

Vue d’ensemble

• web/ : frontend Next.js 16 / React 19.
• convex/ : backend Convex self-hosted.
• Scripts racine : build, tests Convex, stack self-hosted, backups/restores, Infisical.

​

Stack vérifiée

• Next.js 16
• React 19
• TypeScript
• TailwindCSS v4
• Shadcn UI / Radix UI
• TanStack Query / Table
• React Hook Form + Zod
• Convex React
• TipTap
• Algolia / React InstantSearch
• PostHog
• Framer Motion / Motion
• Recharts
• React Three Fiber / Drei

​

CI/CD réel et séparation des responsabilités

​

Workflows actifs

​

Règle d’architecture CI/CD

• pipeline.yml = qualité et conformité d’intégration, pas de déploiement.
• deploy.yml = exécution manuelle de production.
• Pendant le build de l’image web, l’upload des source maps PostHog est best-effort : une erreur réseau PostHog ne bloque pas le déploiement, et les .map client sont supprimées avant l’image runtime.
• release.yml = versioning uniquement, sans déclenchement du déploiement.
• docs.yml = validation documentation, sans impact applicatif.

​

Frontend web/

cd web
npm run dev
npm run build
npm run lint
npm run format
npm run format:check
npm run test -- --run
npm run test:coverage

​

Backend convex/

npm run convex:selfhosted:up
npm run convex:selfhosted:down
npm run convex:selfhosted:logs
npm run convex:selfhosted:health
npm run convex:selfhosted:admin-key
npm run convex:env:sync
npm run convex:dev
npm run convex:dev:once
npm run convex:codegen
npm run test:convex
npm run test:convex:coverage

​

Secrets et environment

npm run secrets:upload
npm run secrets:upload:dev
npm run secrets:upload:prod
npm run secrets:download
npm run secrets:download:dev
npm run secrets:download:prod

• FRONTEND_URL
• RESEND_*
• SENTRY_*
• AUTH_SECRET
• JWT_PRIVATE_KEY
• JWKS
• CONVEX_AUTH_PROVIDER_DOMAIN
• CUSTOM_AUTH_SITE_URL

​

Production : composants réels

• postgres
• pgbouncer
• postgres-backup
• convex-backend
• convex-dashboard
• web
• cloudflared
• portainer

• frontend canonique : https://cel-eleague.com
• Convex auth HTTP : https://api.cel-eleague.com/api
• déploiement sur main/master dans le workflow manuel
• runner de déploiement : self-hosted macOS dans deploy.yml

​

Crons et jobs actifs (Convex)

• match-auto-validation → 0 0 * * *
• match-ea-score-sync → */30 20-23 * * 1-5
• person-sanction-lifecycle-maintenance → */15 * * * *
• transfer-lifecycle-maintenance → */15 * * * *
• stripe-premium-entitlements-reconcile → 0 2 * * *

• user-ban-expiration-cleanup
• totw-weekly

• listCronConfigs
• listCronExecutions
• upsertCronConfig
• triggerCron

​

Backups et restauration

npm run convex:backup
npm run convex:backup:storage
npm run convex:backup:pg
npm run convex:backup:cron:install

npm run convex:restore
npm run convex:restore:latest
npm run convex:restore:append:latest

• snapshots dans backups/convex/<timestamp>/convex-export.zip
• symlink backups/convex/latest
• convex:restore = remplacement par défaut (--replace-all)
• --append à n’utiliser que si lineage/tableaux compatibles

​

Développement local

• Node.js 22+
• npm
• PostgreSQL 16 ou Docker

cp .env.convex.example .env.convex
npm install
npm run convex:selfhosted:up
npm run convex:selfhosted:admin-key
npm run convex:env:sync
npm run convex:dev:once

cd web
npm install
cp .env.example .env.local
npm run dev

​

Incohérences doc ↔ code (non résolues ici)

• .github/workflows/README.md annonce encore des déclencheurs historiques pour pipeline.yml (push + preprod) alors que le fichier réel est limité à pull_request.
• Plusieurs docs restent centrées sur des services monitorings prometheus/loki/alloy/node-exporter qui n’apparaissent plus dans docker-compose.prod.yml.
• Les docs mentionnent QUICK_START.md, fichier absent du dépôt.
• scripts/monitor-prod.sh et restore-backup.sh contiennent des cibles/path/ports qui ne correspondent pas au compose de production réel.

• Les domaines exacts exposés sur le tunnel/public (par ex. https://cel-eleague.com, https://api.cel-eleague.com) et le schéma d’alerting externe (Grafana/Telegram) ne sont pas testés dans une session d’exécution ici.