structure-projet.md 12 KB

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 : section Infrastructure & Deployment, contraintes UE/RGPD, stack cible et patterns d’organisation du code.

Index du dossier forAI/ : 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

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