--- 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 ```