---
stepsCompleted: [1, 2, 3, 4]
workflow_completed: true
inputDocuments:
  - _bmad-output/planning-artifacts/prd.md
  - _bmad-output/planning-artifacts/prd-web-app-requirements.md
  - _bmad-output/analysis/brainstorming-session-2026-01-06.md
---

# Keep - Epic Breakdown

## Overview

This document provides the complete epic and story breakdown for Keep, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.

## Requirements Inventory

### Functional Requirements

FR1: L'utilisateur peut créer, lire, mettre à jour et supprimer des notes (texte ou checklist).
FR2: L'utilisateur peut épingler des notes pour les maintenir en haut de la liste.
FR3: L'utilisateur peut archiver des notes pour les masquer de la vue principale.
FR4: L'utilisateur peut joindre des images aux notes.
FR5: L'utilisateur peut réorganiser l'ordre des notes manuellement (Drag-and-drop via Muuri).
FR6: Le système analyse le contenu d'une note en temps réel ou à la sauvegarde pour identifier des concepts clés.
FR7: Le système suggère des tags (labels) pertinents basés sur l'analyse du contenu.
FR8: L'utilisateur peut accepter, modifier ou rejeter les suggestions de tags de l'IA.
FR9: L'utilisateur peut créer, modifier et supprimer ses propres tags manuellement.
FR10: L'utilisateur peut filtrer et trier ses notes par tags.
FR11: L'utilisateur peut effectuer une recherche par mots-clés exacts (titre et contenu).
FR12: L'utilisateur peut effectuer une recherche sémantique en langage naturel (recherche par sens/intention).
FR13: Le système combine les résultats de recherche exacte et sémantique dans une vue unique (Recherche Hybride).
FR14: L'utilisateur peut accéder à l'application et à ses notes sans connexion internet (Mode Offline/PWA).
FR15: Le système synchronise automatiquement les modifications locales avec le serveur une fois la connexion rétablie.
FR16: L'interface utilisateur reflète instantanément les actions de l'utilisateur (Optimistic UI).
FR17: L'administrateur peut configurer le fournisseur d'IA (ex: OpenAI, Ollama) via des variables d'environnement ou une interface dédiée.
FR18: Le système supporte plusieurs adaptateurs de modèles IA interchangeables (Vercel AI SDK).
FR19: L'utilisateur peut choisir son thème (clair/sombre) et personnaliser les couleurs des notes.

### NonFunctional Requirements

NFR1: IA Responsiveness - Auto-tagging suggestions must appear within 1.5s after typing ends (debounce).
NFR2: Search Latency - Hybrid search results displayed in < 300ms for 1000 notes.
NFR3: PWA Load Time - Interactive in < 2s on average 4G network.
NFR4: API Key Isolation - AI provider keys remain server-side; never exposed to the client.
NFR5: Local-First Privacy - Full local LLM support (Ollama) ensures no note data leaves user infrastructure.
NFR6: Data at Rest - Local PWA storage secured via standard Web Storage protocols.
NFR7: Offline Resilience - 100% data integrity for offline notes during background sync.
NFR8: Vector Integrity - Automatic, background semantic index updates on every note change.
NFR9: Portability - Minimal Docker/build footprint for execution on low-resource servers.
NFR10: Compatibility - Support for current Node.js LTS versions.

### Additional Requirements

- **Stack :** Next.js 16 (App Router), TypeScript, Vercel AI SDK.
- **Layout Engine :** Muuri v0.9.5 + web-animations-js pour le Masonry robuste.
- **Synchronization :** Utilisation de `ResizeObserver` pour notifier Muuri des changements de taille des cartes sans passer par l'état React.
- **Data Persistence :** SQLite (local) / Postgres (production) avec support vectoriel.
- **AI Abstraction :** Interface `AIProvider` pour supporter plusieurs backends (OpenAI, Ollama, etc.).
- **Brownfield Context :** Extension de l'application existante avec focus sur la migration vers Muuri et l'IA.

### FR Coverage Map

FR1: Epic 1 - Gestion de base des notes (CRUD)
FR2: Epic 5 - Épinglage des notes
FR3: Epic 5 - Archivage des notes
FR4: Epic 5 - Support des images
FR5: Epic 1 - Drag-and-drop avec Muuri
FR6: Epic 2 - Analyse IA en temps réel
FR7: Epic 2 - Suggestion de tags automatique
FR8: Epic 2 - Interaction avec les suggestions (Validation)
FR9: Epic 2 - Gestion manuelle des tags
FR10: Epic 3 - Filtrage et tri par tags
FR11: Epic 3 - Recherche par mots-clés exacts
FR12: Epic 3 - Recherche sémantique par intention
FR13: Epic 3 - Moteur de recherche hybride
FR14: Epic 4 - Support Offline complet (PWA)
FR15: Epic 4 - Synchronisation automatique
FR16: Epic 1 - Optimistic UI pour le layout
FR17: Epic 5 - Configuration des providers IA
FR18: Epic 5 - Support multi-adaptateurs IA
FR19: Epic 1 - Thèmes et personnalisation visuelle

## Epic List

## Epic 1: Fondations Robustes & Nouveau Moteur de Layout (Muuri)
Remplacer le système actuel par Muuri pour garantir une base solide, un Drag-and-drop fluide et une expérience sans chevauchement.
**FRs covered:** FR1, FR5, FR16, FR19

### Story 1.1: Mise en place de l'infrastructure Muuri
As a user,
I want my notes to be displayed in a high-performance Masonry grid,
So that my dashboard is visually organized without unnecessary gaps.

**Acceptance Criteria:**
**Given** that the `muuri` and `web-animations-js` libraries are installed.
**When** I load the main page.
**Then** existing notes automatically organize themselves into a Muuri Masonry grid.
**And** the layout dynamically adapts to window resizing.

### Story 1.2: Drag-and-drop fluide et persistant
As a user,
I want to move my notes via drag-and-drop fluidly,
So that I can visually reorganize my priorities.

**Acceptance Criteria:**
**Given** an active Muuri grid.
**When** I move a note to a new position.
**Then** other notes shift with a fluid animation (web-animations-js).
**And** the new position is saved in the database via a Server Action as soon as the move is completed.

### Story 1.3: Robustesse du Layout avec ResizeObserver
As a user,
I want my grid to reorganize as soon as a note's content changes (e.g., adding text),
So that I avoid overlapping notes.

**Acceptance Criteria:**
**Given** a note with an attached `ResizeObserver`.
**When** a note's height changes (text added, image loaded).
**Then** the `ResizeObserver` notifies the Muuri instance.
**And** the grid calls `refreshItems()` and `layout()` to eliminate any overlap instantly.

## Epic 2: Assistant d'Organisation Intelligent (Auto-tagging)
Intégrer le Vercel AI SDK et mettre en place l'analyse en temps réel pour suggérer des tags automatiquement.
**FRs covered:** FR6, FR7, FR8, FR9

### Story 2.1: Infrastructure IA & Abstraction Provider
As an administrator,
I want to configure my AI provider (OpenAI or Ollama) centrally,
So that the application can use artificial intelligence securely.

**Acceptance Criteria:**
**Given** an `AIProvider` interface and the `Vercel AI SDK` installed.
**When** I provide my API key or Ollama instance URL in environment variables.
**Then** the system initializes the appropriate driver.
**And** no API keys are exposed to the client-side.

### Story 2.2: Analyse et Suggestions de Tags en temps réel
As a user,
I want to see tag suggestions appear as I write my note,
So that I can organize my thoughts without manual effort.

**Acceptance Criteria:**
**Given** an open note editor.
**When** I stop typing for more than 1.5 seconds (debounce).
**Then** the system sends the content to the AI for analysis.
**And** tag suggestions (ghost tags) are displayed discreetly under the note.

### Story 2.3: Validation des Suggestions par l'Utilisateur
As a user,
I want to be able to accept or reject a suggestion with a single click,
So that I maintain full control over my organization.

**Acceptance Criteria:**
**Given** a list of tags suggested by the AI.
**When** I click on a suggested tag.
**Then** it becomes a permanent tag for the note.
**And** if I ignore or delete it, it disappears from the current view.

## Epic 3: Moteur de Recherche Hybride & Sémantique
Déployer la recherche sémantique et hybride pour retrouver des notes par intention plutôt que par simples mots-clés.
**FRs covered:** FR10, FR11, FR12, FR13

### Story 3.1: Indexation Vectorielle Automatique
As a system,
I want to generate and store vector embeddings for every note change,
So that the notes are searchable by meaning.

**Acceptance Criteria:**
**Given** a new or updated note.
**When** the note is saved.
**Then** the system generates a vector embedding via the AI provider.
**And** the embedding is stored in the vector-enabled database (SQLite/Postgres).

### Story 3.2: Recherche Sémantique par Intention
As a user,
I want to search for notes using natural language concepts,
So that I can find information even if I don't remember the exact words.

**Acceptance Criteria:**
**Given** the search bar.
**When** I enter a conceptual query (e.g., "cooking ideas").
**Then** the system performs a cosine similarity search on the vector embeddings.
**And** relevant notes are displayed even if they don't contain the exact query words.

### Story 3.3: Vue de Recherche Hybride
As a user,
I want to see combined results from exact keyword matching and semantic search,
So that I get the most comprehensive results possible.

**Acceptance Criteria:**
**Given** a search query.
**When** the search is executed.
**Then** the system merges results from SQL `LIKE` queries and Vector similarity.
**And** results are ranked by a combination of exact match and semantic relevance.

## Epic 4: Mobilité & Résilience (PWA & Offline)
Transformer l'application en PWA complète avec support offline et synchronisation automatique.
**FRs covered:** FR14, FR15

### Story 4.1: Installation PWA et Manifeste
As a user,
I want to install Keep on my device (mobile or desktop),
So that I can access it like a native application.

**Acceptance Criteria:**
**Given** the web application.
**When** I access it via a compatible browser.
**Then** I am prompted to "Add to Home Screen".
**And** the app opens in a standalone window with its own icon.

### Story 4.2: Stockage Local et Mode Offline
As a user,
I want to view and edit my notes even without an internet connection,
So that I can remain productive in any environment.

**Acceptance Criteria:**
**Given** no active internet connection.
**When** I open the app.
**Then** the Service Worker serves the cached UI and notes from IndexedDB.
**And** I can create or edit notes which are queued for sync.

### Story 4.3: Synchronisation de Fond (Background Sync)
As a user,
I want my offline changes to be saved to the server automatically when I'm back online,
So that my data is consistent across all my devices.

**Acceptance Criteria:**
**Given** pending offline changes.
**When** an internet connection is restored.
**Then** the background sync process pushes all queued actions to the server.
**And** any conflicts are resolved (last-write-wins by default).

## Epic 5: Administration & Personnalisation (Self-Hosting Pro)
Finaliser les outils de configuration (OpenAI/Ollama) et les fonctionnalités avancées (Images, Archive).
**FRs covered:** FR2, FR3, FR4, FR17, FR18

### Story 5.1: Interface de Configuration des Modèles
As an administrator,
I want a dedicated UI to switch between AI models and providers,
So that I don't have to restart the server for configuration changes.

**Acceptance Criteria:**
**Given** the settings page.
**When** I select a new provider (e.g., switching from OpenAI to Ollama).
**Then** the application updates its internal AI driver state.
**And** the change is persisted in the database configuration table.

### Story 5.2: Gestion Avancée (Épinglage & Archivage)
As a user,
I want to pin important notes and archive old ones,
So that I can keep my main dashboard clean and focused.

**Acceptance Criteria:**
**Given** a note.
**When** I click the "Pin" icon.
**Then** the note moves to the "Pinned" section at the top.
**When** I click "Archive".
**Then** the note is moved to the Archive view and removed from the main grid.

### Story 5.3: Support Multimédia et Images
As a user,
I want to attach images to my notes,
So that I can capture visual information along with my text.

**Acceptance Criteria:**
**Given** the note editor.
**When** I upload or drag an image into the note.
**Then** the image is stored (locally or cloud) and displayed within the note card.
**And** Muuri recalculates the layout once the image is fully loaded.

### Epic 3: Moteur de Recherche Hybride & Sémantique
Déployer la recherche sémantique et hybride pour retrouver des notes par intention plutôt que par simples mots-clés.
**FRs covered:** FR10, FR11, FR12, FR13

### Epic 4: Mobilité & Résilience (PWA & Offline)
Transformer l'application en PWA complète avec support offline et synchronisation automatique.
**FRs covered:** FR14, FR15

### Epic 5: Administration & Personnalisation (Self-Hosting Pro)
Finaliser les outils de configuration (OpenAI/Ollama) et les fonctionnalités avancées (Images, Archive).
**FRs covered:** FR2, FR3, FR4, FR17, FR18