# Structure du projet AImpact Hub ## Vue d'ensemble AImpact Hub est une application SaaS de collecte et priorisation d'idées IA en entreprise. Stack : **Next.js 15** + **TypeScript** + **Prisma** + **tRPC** + **NextAuth** + **Tailwind CSS / shadcn/ui**. Hébergement : **Vercel** (app) + **Neon** (base PostgreSQL) + **Resend** (emails). **Architecture, déploiement et décisions d’infra (référence détaillée) :** [`_bmad-output/planning-artifacts/architecture.md`](../_bmad-output/planning-artifacts/architecture.md) : section *Infrastructure & Deployment*, contraintes UE/RGPD, stack cible et patterns d’organisation du code. Index du dossier `forAI/` : [README.md](./README.md). --- ## Arborescence principale ``` aimpact-hub/ ├── prisma/ ← Schéma de base de données + migrations │ ├── schema.prisma ← Définition de toutes les tables │ ├── migrations/ ← Historique des évolutions de la BDD (13 migrations) │ └── seed.ts ← Données de démarrage (25 cas d'usage IA + compte dev) │ ├── src/ │ ├── app/ ← Pages et routes (Next.js App Router) │ ├── server/ ← Logique serveur (jamais exécutée dans le navigateur) │ ├── components/ ← Blocs visuels React réutilisables │ ├── lib/ ← Utilitaires partagés │ └── env.js ← Validation des variables d'environnement au démarrage │ ├── generated/prisma/ ← Client Prisma auto-généré (ne pas modifier) ├── .env ← Variables d'environnement locales (gitignored) ├── .env.example ← Modèle des variables d'environnement ├── vercel.json ← Configuration Vercel (cron relance J+21) └── package.json ← Dépendances et scripts ``` --- ## Les pages : `src/app/` Les pages sont organisées par **groupe de routes** (les dossiers entre parenthèses sont invisibles dans l'URL) : ``` src/app/ │ ├── (auth)/ ← Pages sans menu, fond neutre │ ├── signin/page.tsx → /signin (connexion) │ └── signup/page.tsx → /signup (création de compte) │ ├── (dashboard)/ ← Pages avec sidebar, réservées aux CDO connectés │ └── workspace/ │ ├── new/page.tsx → /workspace/new (créer un workspace) │ └── [workspaceId]/ ← Routes dynamiques (l'ID du workspace est dans l'URL) │ ├── page.tsx → /workspace/xxx (tableau de bord principal) │ ├── backlog/ │ │ ├── page.tsx → /workspace/xxx/backlog (vue liste) │ │ └── kanban/page.tsx → /workspace/xxx/backlog/kanban (vue kanban) │ ├── ideas/[ideaId]/ │ │ └── page.tsx → /workspace/xxx/ideas/yyy (fiche d'une idée) │ ├── contributors/ │ │ └── page.tsx → /workspace/xxx/contributors (liste contributeurs) │ ├── library/ │ │ └── page.tsx → /workspace/xxx/library (bibliothèque IA) │ └── settings/ │ └── page.tsx → /workspace/xxx/settings (paramètres) │ ├── (public)/ ← Pages accessibles sans connexion │ ├── submit/[workspaceSlug]/ │ │ └── page.tsx → /submit/mon-workspace (formulaire contributeur) │ ├── qualify/[responseToken]/ │ │ └── page.tsx → /qualify/xxx (réponse question qualification) │ └── privacy-policy/page.tsx → /privacy-policy (mentions RGPD) │ ├── share/[shareToken]/ │ └── page.tsx → /share/xxx (pipeline lecture seule, sans connexion) │ ├── verify-email/page.tsx → /verify-email (activation du compte après inscription) │ └── api/ ← Routes API (appelées par HTTP, pas affichées) ├── trpc/[trpc]/route.ts ← Point d'entrée de toutes les requêtes tRPC ├── auth/[...nextauth]/ ← Gestion sessions NextAuth ├── cron/relance/route.ts ← Relance automatique J+21 (appelée par Vercel Cron) ├── llm/ │ ├── enrich/route.ts ← Enrichissement LLM d'une idée (titre, scores, domaine IA) │ └── examples/route.ts ← Génération d'exemples contextuels (formulaire contributeur) ├── export/pdf/route.ts ← Export PDF du pipeline ├── upload/attachments/ ← Upload de pièces jointes (Vercel Blob) └── webhooks/email/route.ts ← Réception d'idées soumises par email (Resend Inbound) ``` --- ## La logique serveur : `src/server/` ``` src/server/ │ ├── api/ │ ├── routers/ ← Fonctions appelables depuis le navigateur via tRPC │ │ ├── auth.ts ← Inscription + email de vérification │ │ ├── workspace.ts ← Créer/configurer workspace, résumé d'activité │ │ ├── contributor.ts ← Inviter, relancer, supprimer contributeurs │ │ ├── idea.ts ← Soumettre, enrichir, scorer, qualifier, supprimer idées │ │ ├── library.ts ← Bibliothèque de cas d'usage IA │ │ ├── export.ts ← Suivi quotas export PDF │ │ └── share.ts ← Créer/révoquer lien de partage lecture seule │ │ │ └── procedures/ │ └── createWorkspaceProcedure.ts ← Middleware : vérifie que l'utilisateur │ est bien propriétaire du workspace │ ├── services/ ← Services transverses (appelés par les routers) │ ├── email.ts ← Tous les envois email via Resend │ │ (invitation, confirmation, relance, notification, │ │ vérification compte, question qualification) │ ├── llm.ts ← Appels OpenAI (enrichissement + exemples contextuels) │ ├── export.tsx ← Génération PDF avec @react-pdf/renderer │ └── storage.ts ← Upload/suppression fichiers via Vercel Blob │ └── auth/ └── config.ts ← Configuration NextAuth (credentials email/password) ``` --- ## Les composants visuels : `src/components/` Organisés par domaine fonctionnel : ``` src/components/ ├── backlog/ │ ├── BacklogList.tsx ← Vue liste des idées avec filtres/recherche │ ├── KanbanBoard.tsx ← Vue kanban 4 colonnes avec drag & drop (@dnd-kit) │ ├── IdeaCard.tsx ← Carte d'une idée (version compacte pour liste/kanban) │ └── ExportPdfButton.tsx ← Bouton export PDF avec gestion quota │ ├── form/ │ ├── IdeaSubmissionForm.tsx ← Formulaire contributeur (5 champs + pièces jointes) │ ├── ExamplesPanel.tsx ← Panneau exemples IA contextuels (chargés via LLM) │ ├── FileUploadInput.tsx ← Upload de fichiers │ └── SubmissionConfirmation.tsx ← Écran de confirmation après soumission │ ├── idea/ │ ├── IdeaDetailView.tsx ← Fiche complète d'une idée (enrichissement, scores) │ ├── ScoreSlider.tsx ← Curseur ajustement manuel des scores IA │ ├── QualificationQuestionSection.tsx ← Poser une question au contributeur │ ├── QualificationResponseForm.tsx ← Formulaire réponse du contributeur │ └── IdeaAttachmentList.tsx ← Liste des pièces jointes d'une idée │ ├── library/ │ ├── LibraryBrowser.tsx ← Navigation dans la bibliothèque de cas d'usage │ ├── LibraryModal.tsx ← Modale bibliothèque (accessible depuis le formulaire) │ ├── LibraryCaseCard.tsx ← Carte d'un cas d'usage │ └── LibraryCategoryFilter.tsx ← Filtres par catégorie/secteur │ └── workspace/ ├── OnboardingChecklist.tsx ← Checklist de démarrage (configurer → inviter → attendre) ├── ContributorsList.tsx ← Liste contributeurs avec statuts ├── InviteContributorsForm.tsx ← Formulaire invitation par email ├── ManualRelanceDialog.tsx ← Dialogue relance manuelle avec message personnalisé ├── ActivitySummaryBanner.tsx ← Bandeau résumé des nouvelles activités ├── WorkspaceSettingsForm.tsx ← Formulaire paramètres workspace ├── AutoRelanceToggle.tsx ← Activer/désactiver relance automatique J+21 ├── EmailInboxSection.tsx ← Section adresse email dédiée (soumission par email) ├── SubscriptionStatus.tsx ← Affichage tier Free/Pro et quotas └── DeleteContributorButton.tsx ← Suppression RGPD d'un contributeur ``` --- ## Les utilitaires : `src/lib/` ``` src/lib/ ├── ideaStatus.ts ← Constantes et helpers pour les statuts d'idées │ (SUBMITTED, PROCESSING, ON_AGENDA, NOT_PRIORITY) ├── tier.ts ← Règles des limites Free vs Pro (quotas LLM, exports...) ├── workspace.ts ← Helpers workspace (génération slug, etc.) ├── formValidation.ts ← Schémas Zod pour la validation des formulaires ├── email-inbox.ts ← Calcul de l'adresse email dédiée par workspace │ (ideas-{slug}@{INBOUND_EMAIL_DOMAIN}) ├── fallbackExamples.ts ← Exemples génériques si OpenAI n'est pas configuré └── libraryConstants.ts ← Catégories et secteurs de la bibliothèque IA ``` --- ## La base de données : `prisma/schema.prisma` Les tables principales : | Table | Rôle | |---|---| | `User` | Compte utilisateur (CDO) avec email + mot de passe hashé | | `Workspace` | Espace de travail d'un CDO (nom, secteur, taille, tier Free/Pro) | | `Contributor` | Personne invitée à soumettre des idées (email, statut, date invitation) | | `Idea` | Idée soumise (description, département, enrichissement LLM, scores, statut) | | `QualificationQuestion` | Question posée par le CDO à un contributeur sur une idée | | `IdeaAttachment` | Pièce jointe liée à une idée (URL Vercel Blob) | | `LibraryCase` | Cas d'usage IA de la bibliothèque (seed au démarrage) | | `ShareLink` | Lien de partage lecture seule du pipeline | | `ManualRelanceLog` | Historique des relances manuelles envoyées | | `VerificationToken` | Token de vérification email (expiration 24h) | --- ## Les variables d'environnement | Variable | Rôle | |---|---| | `DATABASE_URL` | URL de connexion PostgreSQL Neon | | `AUTH_SECRET` | Clé secrète NextAuth (sessions) | | `RESEND_API_KEY` | Clé API Resend pour l'envoi d'emails | | `EMAIL_FROM` | Adresse expéditeur des emails | | `NEXT_PUBLIC_APP_URL` | URL publique de l'app (pour les liens dans les emails) | | `OPENAI_API_KEY` | Clé OpenAI (optionnel, fallback générique si absent) | | `CRON_SECRET` | Secret pour sécuriser la route cron Vercel | | `BLOB_READ_WRITE_TOKEN` | Token Vercel Blob (pièces jointes) | | `SKIP_EMAIL_VERIFY` | `1` pour bypasser la vérification email (tests uniquement) | --- ## Comment le code communique (flux de données) ``` Navigateur (React) │ │ api.router.procedure.useQuery() ou useMutation() ▼ tRPC (src/app/api/trpc/[trpc]/route.ts) │ │ Appelle la procédure correspondante ▼ Router (src/server/api/routers/*.ts) │ ├─→ Prisma (db.model.action) → Neon PostgreSQL ├─→ Services email.ts → Resend API ├─→ Services llm.ts → OpenAI API └─→ Services storage.ts → Vercel Blob ``` --- ## Scripts disponibles ```bash pnpm dev # Démarrer en local (http://localhost:3000) pnpm build # Compiler pour la production pnpm db:migrate # Appliquer les migrations Prisma sur la BDD pnpm db:seed # Insérer les données de démarrage pnpm db:studio # Ouvrir Prisma Studio (interface visuelle de la BDD) pnpm typecheck # Vérifier les types TypeScript sans compiler pnpm test # Lancer les tests Vitest ```