Skip to main content

​
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

1

Cloner le repository

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

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
3

Configurer Nhost

​
Créer un projet Nhost (optionnel)

Si vous créez un nouveau projet backend :
  1. Allez sur app.nhost.io
  2. Créez un nouveau projet
  3. Choisissez la région eu-central-1 (Europe)
  4. 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.
4

Lancer le serveur de développement

npm run dev
L’application démarre sur http://localhost:5173Vérifications :
  • ✅ Page d’accueil s’affiche (page unique avec quiz hero)
  • ✅ Catalogue d’outils se charge
  • ✅ Pas d’erreurs console liées à Nhost/GraphQL

​
Premier lancement

​
URLs disponibles

npm run dev
Routes disponibles :

​
Créer un compte admin

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

​
Via Dashboard Nhost

  1. Allez dans votre projet Nhost → Auth → Users
  2. Cliquez sur Add User
  3. Entrez :
    • Email : admin@lucdidion.fr
    • Password : votre_mot_de_passe_securise
  4. L’utilisateur est créé et peut se connecter

​
Se connecter

  1. Allez sur http://localhost:5173/admin
  2. Vous serez redirigé vers /login
  3. Entrez vos credentials
  4. 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 :
  1. Créer des catégories — onglet Tools du dashboard
  2. Ajouter des outils — cliquez sur + Nouvel outil, remplissez le formulaire, uploadez un logo
  3. 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)
│   │   ├── Home.tsx          # Page unique (quiz + catalogue)
│   │   ├── Admin.tsx
│   │   ├── Compare.tsx
│   │   └── Login.tsx
│   │
│   ├── types/               # 📘 Types TypeScript
│   └── utils/               # 🔧 Helpers (icons, logger, sanitize)
│
├── public/                  # 🖼️ Assets statiques
├── .env                     # 🔐 Variables d'environnement
├── 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 :
  1. Vérifiez que .env contient les bonnes valeurs (VITE_NHOST_SUBDOMAIN et VITE_NHOST_REGION)
  2. Vérifiez que votre projet Nhost est actif et accessible
  3. 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 :
  1. Vérifiez que vous êtes authentifié (JWT valide)
  2. Vérifiez les permissions Hasura pour le rôle user ou admin
  3. Accédez à la console Hasura pour inspecter les permissions

​
Page admin vide

Cause : Pas authentifié ou session expirée Solution :
  1. Reconnectez-vous via /login
  2. Nhost Auth gère le refresh automatique des tokens
  3. 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.fr