> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cel-eleague.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

# Architecture technique

CEL est une application full-stack pour gérer des ligues d’esport autour d’EA Sports FC.

## 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

| Fichier                                   | Déclenchement réel                                                                              | Rôle réel                                                                                                          |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `.github/workflows/pipeline.yml`          | `pull_request`                                                                                  | Lint Web + tests Web + tests Convex + build Web.                                                                   |
| `.github/workflows/deploy.yml`            | `workflow_dispatch`                                                                             | Déploiement production self-hosted (build image web, `docker compose up`, Convex deploy, health checks, rollback). |
| `.github/workflows/release.yml`           | `push` sur `master`, `main`                                                                     | Versioning automatique (`semantic-release`) + tags + release GitHub.                                               |
| `.github/workflows/docs.yml`              | `pull_request` sur `docs/**`, `package.json`, `package-lock.json`, `.github/workflows/docs.yml` | Validation de la doc Mintlify (`docs:validate`, `docs:links`).                                                     |
| `.github/workflows/dependency-health.yml` | `workflow_dispatch`, `cron` hebdo `0 6 * * 1`                                                   | Audit dépendances web (`npm audit --omit=dev`).                                                                    |
| `.github/workflows/codeql.yml`            | `cron` hebdo `0 0 * * 1`                                                                        | Analyse CodeQL TS (artifact SARIF local, sans upload automatique).                                                 |

### 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/`

Scripts principaux :

```bash theme={null}
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/`

Scripts principaux :

```bash theme={null}
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

Le repo fournit aussi les scripts :

```bash theme={null}
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
```

`convex/README.md` précise que `convex:env:sync` pousse des variables runtime importantes dans Convex, dont :

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

## Production : composants réels

Le stack de production défini dans `docker-compose.prod.yml` contient :

* `postgres`
* `pgbouncer`
* `postgres-backup`
* `convex-backend`
* `convex-dashboard`
* `web`
* `cloudflared`
* `portainer`

Invariants connus :

* 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)

Enregistrement piloté par `convex/admin/crons.ts` (`initCrons`) :

* `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 * * *`

`initCrons` retire explicitement les IDs suivants :

* `user-ban-expiration-cleanup`
* `totw-weekly`

Autres points opérables via API admin Convex :

* `listCronConfigs`
* `listCronExecutions`
* `upsertCronConfig`
* `triggerCron`

## Backups et restauration

Backups Convex :

```bash theme={null}
npm run convex:backup
npm run convex:backup:storage
npm run convex:backup:pg
npm run convex:backup:cron:install
```

Restauration Convex :

```bash theme={null}
npm run convex:restore
npm run convex:restore:latest
npm run convex:restore:append:latest
```

Comportements observés :

* 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

Prérequis :

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

Commandes de montée en charge :

```bash theme={null}
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
```

Frontend local :

```bash theme={null}
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.

Ce bloc signale les écarts sans correction de code hors `docs/`.

Non vérifié :

* 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.