# Thé Tip Top – Plateforme du jeu-concours

## Présentation

**Thé Tip Top** est une application web complète développée dans le cadre d’un projet de certification **Expert en Stratégie et Transformation Digitale**.

Le projet simule le système d’information d’un jeu-concours organisé à l’occasion de l’ouverture de la 10ᵉ boutique Thé Tip Top à Nice.

La plateforme permet aux clients de participer avec un code unique présent sur leur ticket, de consulter leurs gains et de les récupérer en boutique. Elle fournit également des interfaces dédiées aux employés et aux administrateurs.

Au-delà de l’application, le projet met en œuvre une chaîne complète de **CI/CD**, plusieurs environnements isolés, un registre Docker privé, un reverse proxy HTTPS et une stack de supervision.

> **Projet étudiant — client fictif Thé Tip Top.**

---

## Fonctionnalités principales

### Espace client

- création de compte ;
- vérification de l’adresse email ;
- connexion email / mot de passe ;
- connexion avec Google OAuth 2.0 ;
- gestion du profil ;
- saisie d’un code ticket unique ;
- participation au jeu-concours ;
- consultation des gains.

### Espace employé

- authentification avec rôle `EMPLOYEE` ;
- recherche d’un gain ;
- contrôle des informations associées au ticket ;
- validation de la remise d’un lot.

### Espace administrateur

- authentification avec rôle `ADMIN` ;
- tableau de bord et statistiques ;
- consultation des participants ;
- gestion des données nécessaires à l’administration ;
- création de comptes employés ;
- configuration du lancement du jeu-concours ;
- tirage au sort final ;
- consultation du grand gagnant.

### Jeu-concours

Le système gère plusieurs phases :

```text
NOT_CONFIGURED
      ↓
SCHEDULED
      ↓
OPEN
      ↓
CLAIM_ONLY
      ↓
CLOSED
```

Parmi les principales règles métier :

- un ticket ne peut être utilisé qu’une seule fois ;
- les tickets du jeu sont gagnants ;
- les gains sont associés aux tickets ;
- seuls les clients participent au jeu ;
- plusieurs participations d’un même client n’augmentent pas ses chances au tirage final ;
- un seul grand gagnant peut être enregistré ;
- le tirage final respecte les contraintes temporelles définies dans l’application.

---

# Architecture générale

```text
                         UTILISATEURS
                              │
                           HTTPS
                              │
                              ▼
                         ┌─────────┐
                         │ Traefik │
                         └────┬────┘
                              │
                 ┌────────────┴────────────┐
                 │                         │
                 ▼                         ▼
          Frontend React             Backend API
          Vite + Nginx             Node.js + Express
                 │                         │
                 │                         ▼
                 │                    PostgreSQL
                 │                     + Prisma
                 │
                 └────────── API REST ─────┘
```

---

# Stack technique

## Frontend

- React
- Vite
- React Router
- Tailwind CSS
- Vitest
- Testing Library
- ESLint
- Nginx

## Backend

- Node.js 22
- Express.js
- Prisma ORM 6
- PostgreSQL 16
- JWT
- Passport.js
- Google OAuth 2.0
- Bcrypt
- Zod
- Nodemailer
- Helmet
- express-rate-limit
- Swagger / OpenAPI
- Jest
- Supertest

## DevOps

- Git
- Gitea
- Jenkins
- Docker
- Docker Compose
- Docker Registry privé
- Traefik
- HTTPS
- Let's Encrypt

## Monitoring

- Prometheus
- Grafana
- cAdvisor
- Node Exporter

---

# Structure du dépôt

```text
THE-TIP-TOP/
│
├── backend/
│   ├── prisma/
│   │   ├── migrations/
│   │   ├── schema.prisma
│   │   └── seed.js
│   ├── src/
│   ├── tests/
│   ├── Dockerfile
│   ├── package.json
│   └── README.md
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── context/
│   │   ├── pages/
│   │   ├── services/
│   │   └── test/
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   └── README.md
│
├── deploy/
│   ├── dev/
│   │   └── docker-compose.yml
│   ├── preprod/
│   │   └── docker-compose.yml
│   └── prod/
│       └── docker-compose.yml
│
├── Jenkinsfile
└── README.md
```

Pour les informations spécifiques à chaque application :

- [`backend/README.md`](backend/README.md)
- [`frontend/README.md`](frontend/README.md)

---

# Environnements

Le projet utilise trois environnements distincts.

| Environnement | Branche | Frontend | API |
|---|---|---|---|
| DEV | `develop` | `https://dev.dsp5-archi-o24a-4-5-g4.fr` | `https://api-dev.dsp5-archi-o24a-4-5-g4.fr` |
| PREPROD | `release-*` | `https://preprod.dsp5-archi-o24a-4-5-g4.fr` | `https://api-preprod.dsp5-archi-o24a-4-5-g4.fr` |
| PROD | `main` | `https://dsp5-archi-o24a-4-5-g4.fr` | `https://api.dsp5-archi-o24a-4-5-g4.fr` |

Les bases PostgreSQL et conteneurs applicatifs sont séparés entre les environnements.

---

# Stratégie Git

Le workflow de branches est organisé autour de plusieurs niveaux de validation.

```text
feature/*
    │
    │ Pull Request / Merge
    ▼
develop
    │
    │ CI + déploiement DEV
    ▼
release-*
    │
    │ CI + déploiement PREPROD
    ▼
main
    │
    │ validation manuelle Jenkins
    ▼
PRODUCTION
```

### `feature/*`

Branches utilisées pour le développement des fonctionnalités.

### `develop`

Branche d’intégration. Un changement validé sur cette branche est déployé automatiquement en DEV.

### `release-*`

Branches de préparation d’une version. Elles sont déployées en PREPROD pour validation avant production.

### `main`

Branche stable de production. Le déploiement PROD nécessite une validation manuelle dans Jenkins.

---

# Pipeline CI/CD

Le fichier `Jenkinsfile` placé à la racine du dépôt définit la chaîne d’intégration et de déploiement.

```text
Push Gitea
    │
    ▼
Jenkins
    │
    ├── Checkout
    │
    ├── Vérification workspace
    │
    ├── PostgreSQL CI temporaire
    │
    ├── Prisma migrations
    │
    ├── Prisma seed
    │
    ├── Tests backend Jest
    │
    ├── Publication JUnit
    │
    ├── Frontend ESLint
    │
    ├── Frontend Vite build
    │
    ├── Docker build
    │
    ├── Push Registry privé
    │
    └── Docker Compose deploy
    │
    ▼
DEV / PREPROD / PROD
```

## Comportement selon la branche

### Feature

```text
Push
 ↓
Tests
 ↓
Lint
 ↓
Build
```

Pas de déploiement automatique.

### Develop

```text
Push develop
 ↓
CI
 ↓
Images Docker
 ↓
Registry
 ↓
Déploiement DEV
```

### Release

```text
Push release-*
 ↓
CI
 ↓
Images Docker
 ↓
Registry
 ↓
Déploiement PREPROD
```

### Main

```text
Push main
 ↓
CI
 ↓
Images Docker
 ↓
Registry
 ↓
Validation Jenkins
 ↓
Déploiement PROD
```

Cette validation constitue une barrière supplémentaire avant la mise en production.

---

# Tests automatisés

## Backend

Les tests utilisent **Jest** et **Supertest**.

Ils couvrent notamment :

- inscription ;
- connexion ;
- parcours E2E ;
- autorisations ;
- participation ;
- phases du jeu ;
- tirage au sort ;
- notifications liées aux gains ;
- notification du grand gagnant ;
- authentification Google ;
- gestion du mot de passe ;
- comportements liés aux emails.

Commande :

```bash
cd backend
npm test
```

Dans Jenkins, PostgreSQL est lancé temporairement pour les tests. Les migrations et données initiales sont appliquées avant l’exécution des suites.

## Frontend

Les tests utilisent **Vitest** et **Testing Library**.

Ils couvrent notamment :

- connexion ;
- inscription ;
- formulaire d’inscription ;
- saisie du code unique ;
- routes protégées ;
- contexte d’authentification ;
- gestion des erreurs d’authentification ;
- services ;
- bannière de cookies.

Commandes :

```bash
cd frontend
npm run lint
npm test -- --run
npm run build
```

---

# Authentification et sécurité

Le projet met en œuvre plusieurs mécanismes de sécurité.

## Authentification

- JWT ;
- email / mot de passe ;
- Google OAuth 2.0 ;
- vérification email.

## Protection des mots de passe

Les mots de passe sont hachés avec **Bcrypt** avant stockage.

## Validation

Les données reçues par l’API sont validées avec **Zod**.

## Contrôle d’accès

Des middlewares backend contrôlent :

- l’authentification ;
- le rôle ;
- l’accès aux routes protégées.

## Sécurité HTTP

Le backend utilise notamment :

- Helmet ;
- rate limiting ;
- validation des entrées.

## HTTPS

Traefik assure le routage HTTP/HTTPS vers les différents services.

---

# Gestion des secrets

Les secrets ne doivent jamais être stockés directement dans le dépôt Git.

Sont notamment concernés :

```text
JWT_SECRET
DATABASE_URL / mots de passe PostgreSQL
MAIL_USER
MAIL_PASS
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
FACEBOOK_APP_ID
FACEBOOK_APP_SECRET
identifiants du Docker Registry
```

Les valeurs sensibles de déploiement sont externalisées sur le serveur ou injectées par Jenkins.

> Les fichiers contenant des secrets réels ne doivent jamais être ajoutés au dépôt.

---

# Docker

Le frontend et le backend disposent chacun de leur propre image Docker.

## Backend

```text
Node.js 22
   ↓
npm ci
   ↓
Prisma generate
   ↓
Application Express
```

## Frontend

Build multi-stage :

```text
Node.js 22
   ↓
npm ci
   ↓
Vite build
   ↓
Nginx
```

Les images sont versionnées et publiées dans le Registry privé par Jenkins.

---

# Docker Compose

Chaque environnement possède son propre fichier Compose :

```text
deploy/dev/docker-compose.yml
deploy/preprod/docker-compose.yml
deploy/prod/docker-compose.yml
```

Chaque stack contient notamment :

```text
Frontend
Backend
PostgreSQL
```

Les stacks sont isolées avec leurs propres conteneurs, réseaux, données et paramètres d’environnement.

---

# Reverse proxy et HTTPS

**Traefik** constitue le point d’entrée HTTP/HTTPS de l’infrastructure.

Il permet notamment :

- le routage par nom de domaine ;
- l’exposition des frontends ;
- l’exposition des APIs ;
- la terminaison TLS ;
- la gestion des certificats HTTPS.

Seuls les ports nécessaires sont exposés publiquement.

---

# Monitoring

La plateforme dispose d’une stack de supervision.

```text
Node Exporter ──┐
                │
cAdvisor ───────┼──► Prometheus ───► Grafana
                │
Services ───────┘
```

### Prometheus

Collecte les métriques.

### Grafana

Permet de construire et consulter les tableaux de bord.

### cAdvisor

Expose les métriques relatives aux conteneurs Docker.

### Node Exporter

Expose les métriques système du serveur.

---

# Documentation API

Le backend expose une documentation Swagger / OpenAPI.

En environnement local :

```text
http://localhost:5000/api-docs
```

Elle permet de :

- consulter les routes ;
- consulter les schémas ;
- examiner les paramètres ;
- tester les endpoints ;
- utiliser l’authentification prévue par l’API.

---

# Installation locale

## 1. Cloner le dépôt

```bash
git clone <URL_DU_DEPOT>
cd THE-TIP-TOP
```

## 2. Backend

```bash
cd backend
npm install
```

Configurer les variables d’environnement locales puis :

```bash
npx prisma generate
npx prisma migrate dev
npx prisma db seed
npm run dev
```

## 3. Frontend

Dans un second terminal :

```bash
cd frontend
npm install
npm run dev
```

Le frontend local est généralement accessible sur :

```text
http://localhost:5173
```

et l’API sur :

```text
http://localhost:5000
```

Consulter les README des sous-projets pour les détails de configuration.

---

# Base de données

Le projet utilise **PostgreSQL 16** avec **Prisma ORM 6**.

Commandes Prisma utiles :

```bash
npx prisma generate
npx prisma migrate dev
npx prisma migrate deploy
npx prisma db seed
npx prisma studio
```

En environnement déployé, les migrations sont appliquées avec `prisma migrate deploy`.

---

# Qualité logicielle

Le projet applique plusieurs niveaux de contrôle :

```text
Code
 ↓
ESLint
 ↓
Tests unitaires / fonctionnels
 ↓
Tests backend / E2E
 ↓
Build
 ↓
Docker Build
 ↓
Déploiement
```

Un échec dans une étape critique provoque l’échec du pipeline et empêche la promotion normale de la version.

---

# Infrastructure DevOps

Vue simplifiée :

```text
                    ┌───────────────┐
                    │     Gitea     │
                    └───────┬───────┘
                            │ Webhook
                            ▼
                    ┌───────────────┐
                    │    Jenkins    │
                    └───────┬───────┘
                            │
              Tests / Build / Docker
                            │
                            ▼
                    ┌───────────────┐
                    │Docker Registry│
                    └───────┬───────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
           DEV           PREPROD           PROD
            │               │               │
            └───────────────┼───────────────┘
                            ▼
                         Traefik
                            │
                          HTTPS
```

---

# État du projet

Le projet dispose notamment de :

- frontend React opérationnel ;
- backend Express opérationnel ;
- PostgreSQL et Prisma ;
- authentification JWT ;
- Google OAuth 2.0 ;
- vérification email ;
- gestion CLIENT / EMPLOYEE / ADMIN ;
- jeu-concours et gestion des gains ;
- tirage final ;
- tests automatisés ;
- documentation Swagger ;
- images Docker ;
- Registry privé ;
- pipeline Jenkins multibranch ;
- environnements DEV / PREPROD / PROD ;
- déploiements Docker Compose ;
- reverse proxy Traefik ;
- HTTPS ;
- monitoring Prometheus / Grafana.

---

# Documentation complémentaire

Documentation backend :

```text
backend/README.md
```

Documentation frontend :

```text
frontend/README.md
```

Ces fichiers détaillent respectivement l’API et l’application React.

---

# Projet académique

Projet réalisé dans le cadre de la certification :

**Expert en Stratégie et Transformation Digitale**

Le cas **Thé Tip Top** est utilisé comme contexte métier fictif pour la conception, le développement, les tests, la sécurisation, l’industrialisation et le déploiement de l’application.