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

# Architecture globale

> Vue d'ensemble de l'organisation du projet Kit'Asso

## Principes de conception

Kit'Asso repose sur 3 piliers architecturaux :

### 1. Feature-Based Structure

Organisation par **domaine métier** plutôt que par type technique.

```
src/features/
├── tools/
│   └── modals/ToolModal/
│       ├── index.tsx        # Container
│       ├── ToolForm.tsx     # Formulaire
│       ├── ToolPreview.tsx  # Preview
│       ├── types.ts         # Types
│       └── useToolModal.ts  # Hook métier
├── workflows/
├── tool-packs/
└── quiz/
```

**Avantages :**

* Isolation des fonctionnalités
* Facilite le travail en équipe
* Suppression/ajout de features sans impact

<Card title="En savoir plus" icon="arrow-right" href="/architecture/feature-based">
  Guide détaillé de l'approche feature-based
</Card>

***

### 2. API Layer découplée via GraphQL

Séparation stricte entre les composants UI et l'accès aux données :

* **Composants** → utilisent des **Custom Hooks** (useAppData, useToolFilters...)
* **Hooks** → appellent l'**API Layer** (`src/api/`)
* **API Layer** → communique avec **Nhost/Hasura** via GraphQL
* **Hasura** → traduit en SQL vers PostgreSQL

```typescript theme={null}
// ✅ Pattern correct
import { useAppData } from '@/hooks/useAppData';

function HomePage() {
  const { tools, isLoading, error } = useAppData();
  // ...
}
```

<Tip>
  La logique métier est dans les hooks, pas dans les composants ni dans l'API layer.
</Tip>

***

### 3. Patterns standardisés

<CardGroup cols={3}>
  <Card title="Modals" icon="window-maximize">
    Container / Form / Preview / Hook
  </Card>

  <Card title="Forms" icon="file-lines">
    React Hook Form + Zod
  </Card>

  <Card title="Icons" icon="icons">
    getIcon() via src/utils/icons.ts
  </Card>
</CardGroup>

<Card title="Voir tous les patterns" icon="book-open" href="/architecture/patterns">
  Documentation complète des patterns
</Card>

***

## Schéma visuel

```mermaid theme={null}
graph TD
    A[React SPA - Vite] --> B[Custom Hooks]
    B --> C[API Layer]
    C --> D[Nhost Client]
    D --> E[Hasura GraphQL]
    E --> F[(PostgreSQL)]

    A --> G[UI Components]
    G --> B

    D --> H[Nhost Auth]
    D --> I[Nhost Storage]

    A --> J[Netlify Functions]
    J --> K[Resend API - Email]

    style C fill:#3B82F6
    style E fill:#22C55E
    style F fill:#6366F1
    style J fill:#00C7B7
```

***

## Structure de dossiers

```
assopedia-v2/
├── src/
│   ├── api/              # API Layer (GraphQL via Nhost)
│   │   ├── client.ts     # Client Nhost singleton
│   │   ├── base.ts       # apiCall / apiCallVoid wrappers
│   │   ├── tools.ts      # Tools CRUD
│   │   ├── workflows.ts  # Workflows CRUD
│   │   ├── packs.ts      # Packs CRUD
│   │   ├── quiz/         # Quiz operations
│   │   └── index.ts      # Barrel exports
│   │
│   ├── components/       # Composants partagés
│   │   ├── Home/         # HomeHeader, Benefits, HowItWorks
│   │   ├── sections/     # ToolPacks, Workflows, Tools, Hero
│   │   ├── App/          # AppModals, AppFooter
│   │   └── ui/           # Composants UI génériques
│   │
│   ├── features/         # Features métier
│   │   ├── tools/        # modals/ToolModal (Container/Form/Preview)
│   │   ├── workflows/
│   │   ├── tool-packs/
│   │   └── quiz/
│   │
│   ├── hooks/            # Custom hooks
│   │   ├── useAppData.ts
│   │   ├── 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/            # Routes
│   │   ├── Home.tsx      # Page unique (quiz + catalogue)
│   │   ├── Admin.tsx
│   │   ├── Compare.tsx
│   │   └── Login.tsx
│   │
│   ├── types/            # Définitions TypeScript
│   └── utils/            # Helpers (icons, logger, sanitization)
│
├── public/               # Assets statiques
├── .env                  # Variables Nhost
├── vite.config.ts
└── tailwind.config.js
```

<AccordionGroup>
  <Accordion title="src/api/ - API Layer GraphQL">
    Centralise toutes les interactions avec Nhost/Hasura :

    * `client.ts` : singleton Nhost
    * `base.ts` : wrappers apiCall/apiCallVoid + ApiError
    * Un fichier par domaine (tools, workflows, packs, quiz)
  </Accordion>

  <Accordion title="src/features/ - Domaines métier">
    Chaque feature contient ses modals avec le pattern Container/Form/Preview/Hook :

    * `index.tsx` : orchestration
    * `FeatureForm.tsx` : formulaire d'édition
    * `FeaturePreview.tsx` : aperçu détaillé
    * `useFeatureModal.ts` : logique métier
  </Accordion>

  <Accordion title="src/hooks/ - Custom Hooks">
    Logique métier réutilisable :

    * `useAppData` : charge toutes les données
    * `useToolFilters` : search + filtres + catégories
    * `useFavorites` : gestion localStorage
    * `useSmoothScroll` : navigation single-page
  </Accordion>

  <Accordion title="src/lib/ - Services">
    Configuration des services tiers :

    * Auth context (Nhost Auth)
    * Storage helpers (Nhost Storage)
    * Error tracking (Sentry)
  </Accordion>
</AccordionGroup>

***

## Navigation recommandée

<Steps>
  <Step title="Comprendre l'approche feature-based">
    [Architecture feature-based](/architecture/feature-based)
  </Step>

  <Step title="Explorer le backend Nhost">
    [Nhost & GraphQL](/architecture/nhost-graphql)
  </Step>

  <Step title="Découvrir l'API Layer">
    [API Layer](/development/api-layer)
  </Step>
</Steps>

***

## Principes directeurs

<CardGroup cols={2}>
  <Card title="Modularité" icon="puzzle-piece">
    Chaque feature peut être activée/désactivée indépendamment
  </Card>

  <Card title="Testabilité" icon="flask">
    La logique métier est découplée du framework
  </Card>

  <Card title="Type Safety" icon="shield">
    TypeScript strict + validation Zod partout
  </Card>

  <Card title="Performance" icon="rocket">
    Code splitting, lazy loading, virtualisation
  </Card>
</CardGroup>

<Warning>
  Ne contournez pas l'architecture feature-based en créant des dossiers par type technique à la racine.
  Passez toujours par l'API layer — jamais de `nhost.graphql.request()` directement dans les composants.
</Warning>