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

# Démarrage rapide

> Installez et lancez Kit'Asso en local en 10 minutes

## Prérequis

<Check>**Node.js 18+** installé ([Télécharger](https://nodejs.org))</Check>
<Check>**npm** installé</Check>
<Check>**Git** installé</Check>
<Check>**Compte Nhost** créé ([S'inscrire](https://nhost.io)) — ou utiliser les credentials dev par défaut</Check>

***

## Installation

<Steps>
  <Step title="Cloner le repository">
    ```bash theme={null}
    git clone https://github.com/Lucdidi3514/assopedia-v2.git
    cd assopedia-v2
    ```
  </Step>

  <Step title="Installer les dépendances">
    ```bash theme={null}
    npm install
    ```

    **Dépendances principales :**

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

    <Tip>L'installation prend environ 2-3 minutes</Tip>
  </Step>

  <Step title="Configurer Nhost">
    ### Créer un projet Nhost (optionnel)

    Si vous créez un nouveau projet backend :

    1. Allez sur [app.nhost.io](https://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`

    ```bash theme={null}
    # À la racine du projet
    cp .env.example .env
    ```

    Ajoutez ces variables :

    ```bash theme={null}
    VITE_NHOST_SUBDOMAIN=your_nhost_subdomain
    VITE_NHOST_REGION=eu-central-1
    ```

    <Warning>
      Ne commitez JAMAIS le fichier `.env` ! Il est déjà dans `.gitignore`
    </Warning>

    ### Où trouver ces valeurs ?

    Dans votre dashboard Nhost :

    * **Settings** → **General**
    * Copiez le **Subdomain** et la **Region**

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Lancer le serveur de développement">
    ```bash theme={null}
    npm run dev
    ```

    L'application démarre sur **[http://localhost:5173](http://localhost:5173)**

    **Vé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
  </Step>
</Steps>

***

## Premier lancement

### URLs disponibles

```bash theme={null}
npm run dev
```

**Routes disponibles :**

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

***

## 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.lu`
   * Password : `votre_mot_de_passe_securise`
4. L'utilisateur est créé et peut se connecter

### Se connecter

1. Allez sur [http://localhost:5173/admin](http://localhost:5173/admin)
2. Vous serez redirigé vers `/login`
3. Entrez vos credentials
4. Vous devriez accéder au dashboard admin

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

***

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

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

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

<Card title="Comprendre l'architecture" icon="sitemap" href="/architecture/overview">
  Documentation complète de l'organisation
</Card>

***

## Commandes disponibles

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

<CardGroup cols={2}>
  <Card title="Explorer l'architecture" icon="sitemap" href="/architecture/overview">
    Comprendre l'organisation du code
  </Card>

  <Card title="Nhost & GraphQL" icon="plug" href="/architecture/nhost-graphql">
    Backend et API Layer
  </Card>

  <Card title="API Layer" icon="code" href="/development/api-layer">
    apiCall, apiCallVoid et GraphQL
  </Card>

  <Card title="Conventions de code" icon="book" href="/development/conventions">
    Standards et bonnes pratiques
  </Card>
</CardGroup>

***

## Support

Besoin d'aide ?

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