architecture.md 22 KB


stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8] inputDocuments:

  • '_bmad-output/planning-artifacts/prd.md'
  • '_bmad-output/planning-artifacts/product-brief-AImpact-Hub-2026-02-24.md'
  • '_bmad-output/planning-artifacts/ux-design-specification.md'
  • '_bmad-output/brainstorming/brainstorming-session-2026-02-24.md' workflowType: 'architecture' lastStep: 8 status: 'complete' completedAt: '2026-02-27' project_name: 'agentMarketing' user_name: 'Augustin' date: '2026-02-27' ---

Architecture Decision Document

This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together.

Project Context Analysis

Requirements Overview

Functional Requirements: 38 exigences fonctionnelles couvrant : création de workspace (1 user = 1 workspace en MVP), onboarding guidé, invitation de contributeurs, formulaire de soumission avec exemples IA contextuels (LLM), bibliothèque de cas d'usage partagée CDO–métiers, ingestion email par workspace, backlog (liste + kanban 4 colonnes), fiches enrichies par LLM (titre, domaine, type IA, explication, scores), scoring IA avec ajustement manuel, drag & drop priorisation, statuts contributeur, questions de qualification, relances (auto J+21 et manuelle), export PDF / lien partageable, conformité RGPD. Deux rôles : Transformateur (admin) et Contributeur.

Non-Functional Requirements:

  • Performance : formulaire < 2 s, confirmation < 1 s, exemples LLM < 3 s, enrichissement < 10 s, backlog (≤ 200 idées) < 3 s, ingestion email < 15 min.
  • Disponibilité : 99 % mensuel, fallback LLM sans blocage.
  • Sécurité : hébergement EU, isolation workspace, chiffrement au repos (AES-256), HTTPS/TLS 1.2+.
  • LLM : coût < 0,05 €/idée, limites tier Free (30 idées, 50 appels LLM/mois), fallback si indisponible.

Scale & Complexity:

  • Domaine principal : full-stack web (frontend, API, LLM, email).
  • Niveau de complexité : low–medium.
  • Composants architecturaux estimés : frontend SPA, API backend, service LLM, service email, stockage fichiers, base de données multi-tenant.

Technical Constraints & Dependencies

  • Hébergement : datacenters UE uniquement (AWS eu-west, OVH ou équivalent).
  • Intégrations MVP : API OpenAI (scoring LLM), ingestion email (inbox dédiée par workspace).
  • Design system : Tailwind CSS + shadcn/ui (Radix).
  • Accessibilité : WCAG 2.1 niveau AA.
  • Pas de contrainte réglementaire forte au-delà de RGPD.

Cross-Cutting Concerns Identified

  • Multi-tenancy - isolation des données et du contexte LLM par workspace.
  • Résilience LLM - fallbacks (exemples génériques, fiche sans enrichissement), délais stricts, monitoring.
  • Performance perçue - skeleton, fallback rapide, jamais de blocage.
  • RGPD - consentement, hébergement EU, droits d'accès et de suppression.
  • UX asymétrique - deux interfaces (CDO dense vs contributeur épurée).

Starter Template Evaluation

Primary Technology Domain

Full-stack web - frontend React, Next.js (App Router), API backend, base de données, intégrations LLM et email.

Starter Options Considered

  • create-t3-app - Stack aligné (Next.js, TypeScript, Tailwind, tRPC, Prisma, NextAuth), maintenu activement.
  • create-next-app - Plus minimal, nécessite ajout manuel de Prisma, Auth, tRPC.

Selected Starter: create-t3-app

Rationale for Selection: Le starter T3 fournit une base déjà configurée pour Tailwind, Prisma, NextAuth et tRPC - aligné avec la spec UX (Tailwind + shadcn/ui) et les besoins projet (multi-tenant, auth, API type-safe). Prisma facilite l'isolation par workspace et PostgreSQL pour hébergement EU.

Initialization Command:

pnpm dlx create-t3-app@latest --CI --trpc --prisma --nextAuth --tailwind --appRouter --dbProvider postgres

Architectural Decisions Provided by Starter:

Language & Runtime:

  • TypeScript strict, Node.js runtime

Styling Solution:

  • Tailwind CSS préconfiguré

Build Tooling:

  • Next.js (Turbopack)

Testing Framework:

  • À ajouter (ex. Vitest)

Code Organization:

  • App Router (src/app/), src/server/ pour tRPC, src/lib/ pour utilitaires

Development Experience:

  • Hot reload, ESLint, variables d'environnement

Note: L'initialisation du projet avec cette commande doit être la première story d'implémentation. shadcn/ui sera ajouté après le scaffold via npx shadcn@latest init.

Core Architectural Decisions

Decision Priority Analysis

Critical Decisions (Block Implementation):

  • Base de données : PostgreSQL via Neon (eu-central-1)
  • Multi-tenant : workspace_id sur toutes les tables
  • Auth : NextAuth.js (Transformateur) + accès contributeur sans compte

Important Decisions (Shape Architecture):

  • API : tRPC (interne) + Route Handlers (webhooks email, OpenAI)
  • Stockage : Vercel Blob ou S3-compatible EU pour pièces jointes
  • Hébergement : Vercel (EU region)

Deferred Decisions (Post-MVP):

  • Caching Redis (si besoin de performance)
  • Rate limiting avancé (au-delà des limites LLM)

Data Architecture

Decision Choice Version Rationale
Database PostgreSQL 15+ Multi-tenant, hébergement EU
ORM Prisma 7.x Fourni par T3, migrations, typage
Provider Neon - eu-central-1 (Frankfurt), RGPD
Multi-tenant workspace_id sur toutes les tables - Isolation stricte (NFR14)
Validation Zod - Intégré avec tRPC
Migrations Prisma Migrate - Versioning du schéma

Authentication & Security

Decision Choice Version Rationale
Auth Transformateur NextAuth.js 4.x/5.x (T3) Fourni par T3, adaptateur Prisma
Auth provider Credentials (email + password) - Simple, B2B-friendly, pas de dépendance OAuth (Google, Discord)
RBAC 2 rôles custom - Transformateur, Contributeur
Contributeur Pas de compte - FR8 : token/lien par email
Encryption at rest AES-256 - NFR15
HTTPS TLS 1.2+ - NFR16

Flux d'authentification Transformateur (décision produit 2026-02-27)

Le Transformateur s'authentifie via email + mot de passe avec confirmation par email. Pas d'OAuth (Google, Discord) en MVP.

Étape Description Implémentation
1. Inscription Formulaire email + mot de passe Page /signup, tRPC auth.register
2. Confirmation email Lien de vérification envoyé par email User.emailVerified mis à jour au clic
3. Connexion Email + mot de passe NextAuth provider Credentials
4. Création workspace Après première connexion Story 1.3 - formulaire nom entreprise + email contact

Schéma User (Prisma) : email (unique), password (hash bcrypt), emailVerified (DateTime?), name (optionnel).

Service email : Resend, SendGrid ou équivalent pour l'envoi du lien de confirmation. Le token de vérification est stocké temporairement (table VerificationToken ou champ dédié) avec expiration (ex. 24h).

API & Communication Patterns

Decision Choice Rationale
API interne tRPC Type-safety, React Query
Webhooks externes Next.js Route Handlers Email, OpenAI
Error handling tRPC error codes Standardisation
Documentation tRPC auto + OpenAPI pour routes externes Intégrations

Frontend Architecture

Decision Choice Rationale
Composants UI shadcn/ui Spec UX
Drag & drop dnd-kit Kanban
State React Query (tRPC) + état local Pas de store global
Routing App Router Fourni par T3
Design tokens Livinia Chaleureux Spec UX

Infrastructure & Deployment

Decision Choice Rationale
Hosting Vercel Next.js natif
Region EU RGPD
PostgreSQL Neon eu-central-1 Frankfurt, EU
Stockage fichiers Vercel Blob ou S3 EU Pièces jointes

Decision Impact Analysis

Implementation Sequence:

  1. Scaffold T3 App
  2. shadcn/ui init + design tokens
  3. Schéma Prisma (workspace, user, idea, etc.)
  4. NextAuth + RBAC
  5. tRPC routers (workspace, ideas, backlog)
  6. Route Handlers (email, OpenAI)
  7. Composants UI (formulaire, backlog, kanban)

Cross-Component Dependencies:

  • workspace_id → tous les routers tRPC doivent filtrer par workspace
  • NextAuth → session requise pour Transformateur
  • Contributeur → formulaire public sans auth, identification par email

Implementation Patterns & Consistency Rules

Pattern Categories Defined

Critical Conflict Points Identified: 12 zones où les agents IA pourraient diverger sans règles explicites.

Naming Patterns

Database Naming Conventions:

  • Tables : snake_case pluriel (workspaces, ideas, contributors)
  • Colonnes : snake_case (workspace_id, created_at, idea_status)
  • Clés étrangères : {table_singular}_id (workspace_id, contributor_id)
  • Index Prisma : @@index([workspace_id, created_at])
  • Règle multi-tenant : toute table liée à un workspace inclut workspace_id en premier.

API Naming Conventions:

  • Procédures tRPC : camelCase (getIdeas, updateIdeaStatus, createWorkspace)
  • Routers : nom du domaine (ideaRouter, workspaceRouter)
  • Route Handlers : app/api/... (/api/webhooks/email, /api/llm/enrich)

Code Naming Conventions:

  • Composants React : PascalCase (IdeaCard, KanbanBoard, DepartmentPicker)
  • Fichiers composants : PascalCase.tsx (IdeaCard.tsx)
  • Hooks : use + camelCase (useIdeas, useWorkspace)
  • Utilitaires : camelCase (formatIdeaStatus, getWorkspaceContext)
  • Constantes : UPPER_SNAKE_CASE (IDEA_STATUSES, MAX_ATTACHMENTS)

Structure Patterns

Project Organization:

  • src/app/ - routes App Router (pages, layouts)
  • src/components/ - composants UI (sous-dossiers par feature : backlog/, form/, shared/)
  • src/server/ - tRPC routers, context, Prisma client
  • src/lib/ - utilitaires, helpers, constantes
  • src/styles/ - tokens design, globals
  • Tests : __tests__/ à côté du fichier ou *.test.ts co-localisé

File Structure Patterns:

  • Un composant par fichier
  • Barrel exports : index.ts pour les dossiers de composants
  • Config : .env.example documenté, pas de secrets en dur

Format Patterns

API Response Formats:

  • tRPC : réponse directe, pas de wrapper { data }
  • Erreurs : TRPCError avec code (UNAUTHORIZED, NOT_FOUND, BAD_REQUEST)
  • Dates : ISO 8601 (2026-02-27T10:00:00Z)

Data Exchange Formats:

  • JSON API : camelCase (aligné TypeScript)
  • Prisma → API : mapper en camelCase si schéma DB en snake_case
  • Booléens : true/false uniquement

Communication Patterns

Event System Patterns:

  • Pas d'event bus en MVP
  • Mutations tRPC : invalidation React Query (utils.idea.invalidate())
  • Webhooks : payload JSON avec workspace_id pour routage

State Management Patterns:

  • Données serveur : React Query (hooks tRPC)
  • UI locale : useState / useReducer
  • Pas de Zustand/Redux en MVP
  • Mise à jour : immuable (spread, pas de mutation directe)

Process Patterns

Error Handling Patterns:

  • tRPC : throw new TRPCError({ code, message })
  • Route Handlers : NextResponse.json({ error: message }, { status })
  • Frontend : isError de React Query + affichage inline (pas de modale pour erreurs simples)
  • LLM : fallback silencieux, log côté serveur, jamais d'erreur brute exposée au contributeur

Loading State Patterns:

  • React Query : isLoading / isPending pour requêtes
  • Skeleton : composant Skeleton de shadcn sur la zone concernée
  • LLM : skeleton 3s max, puis fallback
  • Pas de spinner global

Enforcement Guidelines

All AI Agents MUST:

  • Filtrer toutes les requêtes par workspace_id quand applicable
  • Utiliser Zod pour la validation des inputs tRPC
  • Labelliser tout contenu LLM avec AIBadge ou équivalent
  • Respecter les conventions de nommage ci-dessus

Pattern Enforcement:

  • Vérification : ESLint + revue de code
  • Violations : documenter dans les PR
  • Mise à jour : modifier ce document et communiquer

Pattern Examples

Good Examples:

// tRPC procedure avec workspace
const getIdeas = protectedProcedure
  .input(z.object({ workspaceId: z.string() }))
  .query(async ({ ctx, input }) => {
    return ctx.db.idea.findMany({
      where: { workspaceId: input.workspaceId },
      orderBy: { createdAt: 'desc' },
    });
  });

// Composant avec fallback LLM
{isEnriching ? <Skeleton className="h-20" /> : <IdeaEnrichment data={idea} />}

Anti-Patterns:

// ❌ Pas de filtre workspace
ctx.db.idea.findMany() // fuite multi-tenant

// ❌ Erreur LLM exposée au contributeur
throw new Error(openAIError.message)

// ❌ Nommage incohérent
const UserCard = () => {} // fichier user-card.tsx

Project Structure & Boundaries

Complete Project Directory Structure

aimpact-hub/
├── README.md
├── package.json
├── pnpm-lock.yaml
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── .env.example
├── .env.local
├── .gitignore
├── .eslintrc.cjs
├── components.json
├── .github/
│   └── workflows/
│       └── ci.yml
├── docs/
│   └── architecture/
│       └── journey-to-structure.md    # Mapping parcours → dossiers
├── prisma/
│   ├── schema.prisma
│   ├── seed.ts
│   └── migrations/
├── public/
│   └── assets/
│       └── images/
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── (auth)/
│   │   │   ├── signin/
│   │   │   │   └── page.tsx
│   │   │   └── signup/
│   │   │       └── page.tsx
│   │   ├── (dashboard)/
│   │   │   ├── layout.tsx
│   │   │   ├── workspace/
│   │   │   │   ├── page.tsx
│   │   │   │   └── [workspaceId]/
│   │   │   │       ├── page.tsx
│   │   │   │       ├── backlog/
│   │   │   │       │   └── page.tsx
│   │   │   │       ├── ideas/
│   │   │   │       │   └── [ideaId]/
│   │   │   │       │       └── page.tsx
│   │   │   │       ├── contributors/
│   │   │   │       │   └── page.tsx
│   │   │   │       ├── library/
│   │   │   │       │   └── page.tsx
│   │   │   │       └── settings/
│   │   │   │           └── page.tsx
│   │   │   └── export/
│   │   │       └── page.tsx
│   │   ├── (public)/
│   │   │   └── submit/
│   │   │       └── [workspaceSlug]/
│   │   │           └── page.tsx
│   │   ├── api/
│   │   │   ├── auth/
│   │   │   │   └── [...nextauth]/
│   │   │   │       └── route.ts
│   │   │   ├── trpc/
│   │   │   │   └── [trpc]/
│   │   │   │       └── route.ts
│   │   │   ├── webhooks/
│   │   │   │   └── email/
│   │   │   │       └── route.ts
│   │   │   ├── cron/
│   │   │   │   └── relance/
│   │   │   │       └── route.ts       # Relance J+21 (Vercel Cron)
│   │   │   └── llm/
│   │   │       ├── examples/
│   │   │       │   └── route.ts
│   │   │       └── enrich/
│   │   │           └── route.ts
│   │   └── share/
│   │       └── [shareToken]/
│   │           └── page.tsx
│   ├── components/
│   │   ├── ui/
│   │   ├── shared/
│   │   ├── backlog/
│   │   ├── form/
│   │   ├── idea/
│   │   ├── workspace/
│   │   ├── library/
│   │   └── export/
│   ├── server/
│   │   ├── db.ts
│   │   ├── auth.ts
│   │   ├── api/
│   │   │   ├── root.ts
│   │   │   ├── trpc.ts
│   │   │   ├── procedures.ts
│   │   │   ├── procedures/
│   │   │   │   └── createWorkspaceProcedure.ts
│   │   │   └── routers/
│   │   │       ├── workspace.ts
│   │   │       ├── idea.ts
│   │   │       ├── contributor.ts
│   │   │       ├── library.ts
│   │   │       └── export.ts
│   │   └── services/
│   │       ├── llm.ts
│   │       ├── email.ts
│   │       ├── storage.ts             # Convention: {workspaceId}/attachments/{ideaId}/{filename}
│   │       └── export.ts
│   ├── lib/
│   │   ├── utils.ts
│   │   ├── constants.ts
│   │   ├── validators/
│   │   └── trpc.ts
│   └── styles/
│       └── tokens.css
├── __tests__/
│   ├── lib/
│   ├── components/
│   ├── server/
│   │   └── routers/
│   └── api/
│       ├── webhooks/
│       └── llm/

User Journey to Structure Mapping

Parcours Dossiers principaux Point d'entrée
Onboarding CDO (dashboard)/workspace/, components/workspace/OnboardingChecklist workspace/page.tsx
Soumission contributeur (public)/submit/, components/form/ submit/[workspaceSlug]/page.tsx
Backlog CDO (dashboard)/workspace/[id]/backlog/, components/backlog/ backlog/page.tsx
Enrichissement LLM api/llm/, services/llm.ts Appelé par webhook + tRPC
Relance J+21 api/cron/relance/ Vercel Cron

Architecture Boundaries

API Boundaries:

  • tRPC : src/server/api/routers/* - procédures protégées (Transformateur) ou publiques (formulaire)
  • Route Handlers : src/app/api/webhooks/email, src/app/api/llm/*, src/app/api/cron/relance
  • Auth : NextAuth sur (dashboard)/*, formulaire (public)/submit/* sans auth

Security Conventions (Multi-Tenant):

  • Toute procédure tRPC accédant à des données workspace DOIT utiliser createWorkspaceProcedure ou recevoir workspaceId validé
  • Route Handlers /api/llm/* : valider que l'idée appartient au workspace avant enrichissement
  • Webhook email : valider token/secret workspace avant création d'idée
  • Stockage : path = {workspaceId}/attachments/{ideaId}/{filename}

Prisma: Workspace.slug (unique) pour les URLs contributeur (/submit/[workspaceSlug]).

Requirements to Structure Mapping

Workspace & Gestion (FR1–FR5): src/app/(dashboard)/workspace/, src/server/api/routers/workspace.ts, Prisma Workspace (incl. slug)

Contributeurs (FR6–FR13): src/server/api/routers/contributor.ts, components/workspace/, services/email.ts, api/cron/relance/

Éducation IA & Bibliothèque (FR14-IA1–FR14-IA6): api/llm/examples/, components/form/ExamplesPanel.tsx, components/library/, routers/library.ts

Soumission (FR14–FR17): (public)/submit/, components/form/IdeaSubmissionForm.tsx, api/webhooks/email/

Enrichissement & Scoring (FR18–FR21): api/llm/enrich/, services/llm.ts, components/idea/ScoreSlider.tsx

Backlog (FR22–FR28): workspace/[workspaceId]/backlog/, components/backlog/*, routers/idea.ts

Qualification (FR29–FR32): components/idea/QualificationQuestion.tsx, services/email.ts

Priorisation (FR33–FR34): components/backlog/KanbanBoard.tsx, ideaRouter.updateOrder

Export (FR35–FR36): components/export/ExportPdfButton.tsx, services/export.ts, routers/export.ts

Architecture Validation Results

Coherence Validation ✅

Decision Compatibility: Stack T3 (Next.js, Prisma, tRPC, NextAuth) cohérent avec multi-tenant et LLM. Neon eu-central-1 + Vercel EU respecte RGPD. shadcn/ui + Tailwind alignés avec spec UX. Aucun conflit identifié.

Pattern Consistency: Conventions de nommage cohérentes. createWorkspaceProcedure appliqué à tous les routers. Conventions stockage et sécurité multi-tenant documentées.

Structure Alignment: Arborescence alignée avec décisions (feature-based, séparation CDO/contributeur). Route Handlers pour webhooks/LLM, tRPC pour app. Cron relance J+21, services/export.ts pour PDF.

Requirements Coverage Validation ✅

Functional Requirements: Tous les FR (FR1–FR38) couverts par la structure et les routers.

Non-Functional Requirements: Performance (fallback LLM < 3s), disponibilité, sécurité EU, chiffrement, limites LLM - tous adressés architecturalement.

Implementation Readiness Validation ✅

Decision Completeness: Versions documentées, commandes d'initialisation fournies.

Structure Completeness: Arborescence complète, mapping parcours → structure, tests définis.

Pattern Completeness: Conventions exhaustives, exemples et anti-patterns, règles sécurité multi-tenant.

Gap Analysis Results

Critical Gaps: Aucun

Important Gaps: Middleware validateWorkspaceToken pour webhook email à implémenter ; config Vercel Cron à documenter.

Nice-to-Have: Vitest, monitoring LLM (NFR8).

Architecture Completeness Checklist

✅ Requirements Analysis - Contexte, échelle, contraintes, cross-cutting concerns

✅ Architectural Decisions - Décisions critiques, stack, intégrations, performance

✅ Implementation Patterns - Nommage, structure, communication, processus

✅ Project Structure - Arborescence, frontières, intégrations, mapping requirements

Architecture Readiness Assessment

Overall Status: READY FOR IMPLEMENTATION

Confidence Level: High

Key Strengths: Multi-tenant sécurisé, fallback LLM, structure alignée parcours, enrichissements Advanced Elicitation + Party Mode.

Areas for Future Enhancement: Monitoring LLM, Vitest, DPA grands comptes.

Implementation Handoff

AI Agent Guidelines:

  • Suivre les décisions architecturales exactement
  • Appliquer les patterns de manière cohérente
  • Respecter structure et frontières
  • Consulter ce document pour toute question d'architecture

First Implementation Priority:

pnpm dlx create-t3-app@latest --CI --trpc --prisma --nextAuth --tailwind --appRouter --dbProvider postgres