---
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:**
```bash
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:**
```typescript
// 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 ? : }
```
**Anti-Patterns:**
```typescript
// ❌ 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:**
```bash
pnpm dlx create-t3-app@latest --CI --trpc --prisma --nextAuth --tailwind --appRouter --dbProvider postgres
```