# Architecture

## Choix techniques (justifiés)

- **Framework : Laravel 11** (imposé). ORM Eloquent, validation, migrations, queue, mailer, Blade. Adapté à un hébergement avec Composer/SSH (OVH VPS ou mutualisé compatible Composer).
- **Pattern : MVC strict.** Aucune logique métier dans les vues. Toute la logique du chatbot et de l'IA est isolée dans `app/Services`. Aucune requête SQL brute dans les contrôleurs (Eloquent uniquement).
- **Frontend : Niveau 1-2** (HTML sémantique + CSS vanilla + JS vanilla, templates Blade ; Tailwind optionnel). Le back-office est un dashboard classique, aucun framework JS lourd nécessaire. Justification : interfaces CRUD + tableaux, pas de temps réel complexe.
- **Widget de chat public** : JS vanilla autonome (`public/widget/chat-widget.js`), intégrable sur le site WordPress/OVH via une simple balise `<script>`. Appelle l'API REST `/api/v1/chat`.

## Découpage

```
app/
  Models/            Entités Eloquent (User, Role, KnowledgeArticle, ...)
  Http/Controllers/
    Auth/            Authentification (login/logout, 2FA)
    Admin/           Back-office (CRUD, réglages, audit)
    Api/             API publique (chatbot) + API interne (Hub-ready)
  Http/Middleware/   Rôles, en-têtes de sécurité, audit
  Services/          ChatbotService, ClaudeClient, AiTextService, AuditLogger
  Mail/              OrgQuestionMail (email vers l'organisation)
database/
  migrations/        Schéma versionné
  seeders/           Rôles, Super Admin, réglages, base de connaissances
routes/
  web.php            Back-office + pages légales
  api.php            API publique (chat) + interne
resources/views/     Blade (layouts, admin, auth, legal)
public/widget/       Widget de chat embarquable
```

## Base de données (schéma logique)

- `users` (UUID, email, password bcrypt, role_id, 2FA, soft delete)
- `roles` (super_admin, admin, editor)
- `knowledge_categories` / `knowledge_articles` (question, réponse, mots-clés, publié)
- `chat_conversations` / `chat_messages` (historique des échanges du widget)
- `leads` (questions sans réponse + email du visiteur, envoyées à l'orga)
- `settings` (clé/valeur : IA on/off, modèle, prompt système, email orga...)
- `audit_logs` (toute action sensible)
- `ai_usage_logs` (appels IA : modèle, tokens, coût estimé)

Identifiants exposés en **UUID v4** (jamais l'auto-increment) : conforme au référentiel cross-app (règle 16.7), prêt pour le Hub.

## Points de vigilance
Voir `RGPD.md` (données perso), `DEPLOY.md` (HTTPS, secrets), `BACKUP.md` (sauvegardes), `PERMISSIONS.md` (rôles).