Démarrage rapide

Prérequis

Node.js 18+ installé (Télécharger)

npm installé

Git installé

Compte Nhost créé (S’inscrire) — ou utiliser les credentials dev par défaut

Installation

Cloner le repository

git clone https://github.com/Lucdidi3514/assopedia-v2.git
cd assopedia-v2

Installer les dépendances

npm install

Dépendances principales :

react 18
vite 6
@nhost/nhost-js (client GraphQL + Auth + Storage)
react-router-dom 6.x
tailwindcss 3.x

L’installation prend environ 2-3 minutes

Configurer Nhost

Créer un projet Nhost (optionnel)

Si vous créez un nouveau projet backend :

Allez sur app.nhost.io
Créez un nouveau projet
Choisissez la région eu-central-1 (Europe)
Notez le subdomain et la region

Créer le fichier `.env`

# À la racine du projet
cp .env.example .env

Ajoutez ces variables :

VITE_NHOST_SUBDOMAIN=your_nhost_subdomain
VITE_NHOST_REGION=eu-central-1

Ne commitez JAMAIS le fichier .env ! Il est déjà dans .gitignore

Où trouver ces valeurs ?

Dans votre dashboard Nhost :

Settings → General
Copiez le Subdomain et la Region

Des valeurs par défaut sont intégrées dans le code (client.ts) pour l’environnement de développement partagé. Vous pouvez démarrer sans .env si vous utilisez le backend commun.

Lancer le serveur de développement

npm run dev

L’application démarre sur http://localhost:5173Vérifications :

✅ Page d’accueil (landing) s’affiche avec CTA quiz
✅ Catalogue d’outils se charge sur /catalogue
✅ Quiz accessible sur /quiz/diagnostic-digital
✅ Pas d’erreurs console liées à Nhost/GraphQL

Premier lancement

URLs disponibles

npm run dev

Routes disponibles :

🏠 Landing : http://localhost:5173 (page d’accueil avec CTA quiz)
📋 Catalogue : http://localhost:5173/catalogue (outils + kits + guides)
🔐 Admin : http://localhost:5173/admin
📊 Quiz : http://localhost:5173/quiz/diagnostic-digital
🔍 Compare : http://localhost:5173/compare
🔑 Login : http://localhost:5173/login
📜 Mentions légales : http://localhost:5173/mentions-legales
🔒 Confidentialité : http://localhost:5173/politique-confidentialite

Créer un compte admin

L’authentification est gérée par Nhost Auth (email/password).

Via Dashboard Nhost

Allez dans votre projet Nhost → Auth → Users
Cliquez sur Add User
Entrez :
- Email : admin@lucdidion.lu
- Password : votre_mot_de_passe_securise
L’utilisateur est créé et peut se connecter

Se connecter

Allez sur http://localhost:5173/admin
Vous serez redirigé vers /login
Entrez vos credentials
Vous devriez accéder au dashboard admin

Une fois connecté, Nhost gère automatiquement le refresh des tokens JWT. Pas besoin de se reconnecter à chaque refresh.

Ajouter des données de test

Option 1 : Manuellement via Admin Dashboard

Une fois connecté en admin :

Créer des catégories — onglet Tools du dashboard
Ajouter des outils — cliquez sur + Nouvel outil, remplissez le formulaire, uploadez un logo
Créer un workflow — onglet Workflows, définissez les étapes, publiez (status = active)

Option 2 : Via Hasura Console

Accédez à la console Hasura de votre projet Nhost pour insérer des données directement :

mutation {
  insert_categories(objects: [
    { name: "Communication" },
    { name: "Gestion de projet" },
    { name: "Site Web" }
  ]) {
    returning { id name }
  }
}

mutation {
  insert_tools(objects: {
    name: "Notion",
    description: "Outil tout-en-un pour la gestion de projets",
    pricing_tier: "Freemium",
    category_id: "uuid-de-la-categorie",
    website_url: "https://notion.so"
  }) {
    returning { id name }
  }
}

Structure du projet

assopedia-v2/
├── src/
│   ├── api/                 # 🔌 API Layer (GraphQL via Nhost)
│   │   ├── client.ts        # Client Nhost singleton
│   │   ├── base.ts          # apiCall / apiCallVoid wrappers
│   │   ├── tools.ts         # Tools CRUD (GraphQL)
│   │   ├── workflows.ts     # Workflows CRUD
│   │   ├── packs.ts         # Packs CRUD
│   │   ├── quiz/            # Quiz operations
│   │   └── index.ts         # Barrel exports
│   │
│   ├── components/          # 🎨 Composants partagés
│   │   ├── Home/            # Header, Benefits, HowItWorks
│   │   ├── sections/        # ToolPacks, Workflows, Tools, Hero
│   │   ├── App/             # Modals, Footer
│   │   └── ui/              # Composants UI génériques
│   │
│   ├── features/            # 📦 Features métier
│   │   ├── tools/           # Modals outil (Container/Form/Preview)
│   │   ├── workflows/       # Modals workflow
│   │   ├── tool-packs/      # Modals packs
│   │   └── quiz/            # Quiz engine + admin
│   │
│   ├── hooks/               # 🪝 Custom hooks
│   │   ├── useAppData.ts    # Données centralisées
│   │   ├── useToolFilters.ts
│   │   ├── useFavorites.ts
│   │   ├── useToolComparison.ts
│   │   ├── useAppModals.ts
│   │   └── useSmoothScroll.ts
│   │
│   ├── lib/                 # 🛠️ Services
│   │   ├── auth.tsx         # Auth context (Nhost)
│   │   ├── storage.ts       # Nhost Storage helpers
│   │   └── sentry.ts        # Error tracking
│   │
│   ├── pages/               # 📄 Pages (routes)
│   │   ├── Landing.tsx       # Page d'accueil (CTA quiz)
│   │   ├── Home.tsx          # Catalogue (outils + kits + guides)
│   │   ├── Admin.tsx
│   │   ├── Compare.tsx
│   │   └── Login.tsx
│   │
│   ├── types/               # 📘 Types TypeScript
│   └── utils/               # 🔧 Helpers (icons, logger, sanitize)
│
├── netlify/
│   └── functions/           # ⚡ Netlify Serverless Functions
│       └── send-report.ts   # Envoi de rapport par email (Resend)
├── public/                  # 🖼️ Assets statiques
├── .env                     # 🔐 Variables d'environnement
├── netlify.toml             # 🔧 Config Netlify (build + redirects)
├── vite.config.ts           # ⚡ Config Vite
├── tailwind.config.js       # 🎨 Config Tailwind
└── package.json

Comprendre l'architecture

Documentation complète de l’organisation

Commandes disponibles

# Développement
npm run dev              # Lancer le serveur de dev (port 5173)

# Build
npm run build            # Build de production
npm run preview          # Preview du build local

# Quality
npm run lint             # Linter ESLint
npm run typecheck        # Vérification TypeScript

# Tests
npm test                 # Lancer les tests (Vitest)
npm run test:watch       # Tests en mode watch
npm run test:coverage    # Coverage report

Troubleshooting

Erreur : “Failed to fetch” ou “Network error”

Cause : Connexion Nhost/GraphQL échoue Solutions :

Vérifiez que .env contient les bonnes valeurs (VITE_NHOST_SUBDOMAIN et VITE_NHOST_REGION)
Vérifiez que votre projet Nhost est actif et accessible
Ouvrez les DevTools → Network → filtrez par graphql pour voir les requêtes

Erreur : “Permission denied” sur une mutation

Cause : Permissions Hasura bloquent l’opération Solution :

Vérifiez que vous êtes authentifié (JWT valide)
Vérifiez les permissions Hasura pour le rôle user ou admin
Accédez à la console Hasura pour inspecter les permissions

Page admin vide

Cause : Pas authentifié ou session expirée Solution :

Reconnectez-vous via /login
Nhost Auth gère le refresh automatique des tokens
Si persistant, videz le localStorage et reconnectez-vous

Prochaines étapes

Explorer l'architecture

Comprendre l’organisation du code

Nhost & GraphQL

Backend et API Layer

API Layer

apiCall, apiCallVoid et GraphQL

Conventions de code

Standards et bonnes pratiques

Support

Besoin d’aide ?

📖 Documentation : Parcourez les sections ci-dessous
💬 GitHub Discussions : Posez vos questions
🐛 Issues : Signalez un bug
📧 Email : contact@lucdidion.lu

Introduction

Architecture

Déploiement

Prérequis

Installation

Créer un projet Nhost (optionnel)

Créer le fichier `.env`

Où trouver ces valeurs ?

Premier lancement

URLs disponibles

Créer un compte admin

Via Dashboard Nhost

Se connecter

Ajouter des données de test

Option 1 : Manuellement via Admin Dashboard

Option 2 : Via Hasura Console

Structure du projet

Comprendre l'architecture

Commandes disponibles

Troubleshooting

Erreur : “Failed to fetch” ou “Network error”

Erreur : “Permission denied” sur une mutation

Page admin vide

Prochaines étapes

Explorer l'architecture

Nhost & GraphQL

API Layer

Conventions de code

Support

​Prérequis

​Installation

​Créer un projet Nhost (optionnel)

​Créer le fichier .env

​Où trouver ces valeurs ?

​Premier lancement

​URLs disponibles

​Créer un compte admin

​Via Dashboard Nhost

​Se connecter

​Ajouter des données de test

​Option 1 : Manuellement via Admin Dashboard

​Option 2 : Via Hasura Console

​Structure du projet

Comprendre l'architecture

​Commandes disponibles

​Troubleshooting

​Erreur : “Failed to fetch” ou “Network error”

​Erreur : “Permission denied” sur une mutation

​Page admin vide

​Prochaines étapes

Explorer l'architecture

Nhost & GraphQL

API Layer

Conventions de code

​Support

Prérequis

Installation

Créer un projet Nhost (optionnel)

Créer le fichier `.env`

Où trouver ces valeurs ?

Premier lancement

URLs disponibles

Créer un compte admin

Via Dashboard Nhost

Se connecter

Ajouter des données de test

Option 1 : Manuellement via Admin Dashboard

Option 2 : Via Hasura Console

Structure du projet

Commandes disponibles

Troubleshooting

Erreur : “Failed to fetch” ou “Network error”

Erreur : “Permission denied” sur une mutation

Page admin vide

Prochaines étapes

Support