sepehr
3c4b9d6176
- Added multi-provider AI infrastructure (OpenAI/Ollama) - Implemented real-time tag suggestions with debounced analysis - Created AI diagnostics and database maintenance tools in Settings - Added automated garbage collection for orphan labels - Refined UX with deterministic color hashing and interactive ghost tags
13 KiB
| stepsCompleted | workflow_completed | inputDocuments | |||||||
|---|---|---|---|---|---|---|---|---|---|
|
true |
|
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
ResizeObserverpour 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
AIProviderpour 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