---
stepsCompleted: [1, 2, 3, 4, 6, 7, 8, 9, 10, 11]
inputDocuments:
  - README.md
  - COMPLETED-FEATURES.md
  - _bmad-output/analysis/brainstorming-session-2026-01-06.md
workflowType: 'prd'
lastStep: 11
---

# Product Requirements Document - Keep

**Author:** Ramez
**Date:** 2026-01-07

## Executive Summary

Ce PRD décrit la transformation de **Keep** en un partenaire cognitif qui **élimine la charge mentale liée à l'organisation**, tout en préservant la simplicité et le contrôle total de l'utilisateur. S'appuyant sur l'application Next.js 16 existante, cette évolution ajoute une couche d'assistance intelligente conçue pour suggérer et faciliter, sans jamais imposer.

L'objectif est de créer un flux de travail fluide : la capture reste instantanée, mais l'organisation est accélérée par le **taggage automatique prédictif** et la **recherche sémantique intuitive**. Le système comprend l'intention, mais l'utilisateur garde la main.

### What Makes This Special : Assistance "Easy" & Zéro Friction

Le différenciateur clé est l'équilibre entre automatisation intelligente et contrôle manuel simple.

*   **Suggestion, pas Imposition :** Le système analyse le contenu et propose des tags pertinents que l'utilisateur peut valider, modifier ou ignorer d'un simple clic. L'organisation manuelle reste possible et améliorée, garantissant que l'IA reste un outil au service de l'humain.
*   **Recherche Hybride Naturelle :** Combinez la puissance de la recherche par concepts (sémantique) avec la précision des mots-clés exacts. Retrouvez "recette" en tapant "dîner", ou cherchez précisément "Error 404".
*   **Interface Familière Augmentée :** Nous conservons l'approche visuelle et intuitive "easy-to-use" du layout existant. L'intelligence est intégrée subtilement dans l'interface de gestion des tags et la barre de recherche, sans alourdir l'expérience utilisateur.

## Project Classification

**Technical Type:** web_app
**Domain:** general
**Complexity:** medium (Intégration IA/Vecteurs dans une UX simple)
**Project Context:** Brownfield - extension intelligente avec focus UX

## Success Criteria

### User Success (L'Administrateur/Utilisateur final)
*   **Zero-Config AI Setup :** L'utilisateur doit pouvoir configurer son provider IA (OpenAI, Ollama, etc.) simplement en entrant une clé API dans les paramètres ou le `.env`, sans installer de services tiers complexes.
*   **Confiance dans l'Auto-tagging :** Taux d'acceptation des tags suggérés > 85%. Si l'utilisateur passe son temps à corriger l'IA, il désactivera la fonction.
*   **Sérendipité de Recherche :** La recherche sémantique doit faire remonter des résultats pertinents qui ne contiennent *pas* les mots-clés exacts dans au moins 30% des recherches complexes.

### Business Success (Open Source & Réputation)
*   **Adoption GitHub :** Objectif de 100+ Stars dans les 3 premiers mois post-lancement de la v2.
*   **Conversion "Café" :** Avoir un lien "Sponsor/Buy me a coffee" visible et non-intrusif qui génère des dons (preuve que l'outil apporte de la valeur).
*   **Contribution Communautaire :** Avoir au moins 2 contributeurs externes qui proposent des PRs pour ajouter de nouveaux providers IA.

### Technical Success
*   **Architecture Monolithique Modulaire :** L'IA est intégrée via le **Vercel AI SDK** (ou équivalent TS) directement dans Next.js. Pas de conteneur Python supplémentaire requis.
*   **Agnosticisme du Modèle :** Le système supporte au minimum 3 providers majeurs (OpenAI, Anthropic, Local/Ollama) via une interface d'abstraction propre.
*   **Performance Hybride :** La recherche combinée (SQL/Keyword + Vecteur) s'exécute en < 300ms sur une base de 1000 notes.

### Measurable Outcomes
*   Temps de déploiement complet (de `git clone` à `ready`) < 5 minutes.
*   Latence de l'auto-tagging < 2 secondes après la fin de la frappe (ou à la sauvegarde).

## Product Scope

### MVP - Minimum Viable Product (La v2 "Smart")
*   **Core :** Toutes les fonctionnalités actuelles (CRUD, Masonry amélioré, Images).
*   **AI Backend (TS) :** Intégration Vercel AI SDK dans Next.js. Support initial pour OpenAI et Ollama (pour le gratuit/local).
*   **Auto-tagging :** Suggestion de tags à la création/édition d'une note (déclenché manuellement ou à la sauvegarde).
*   **Recherche Hybride :** Intégration d'une base vectorielle légère (ex: pgvector si passage à Postgres, ou une solution in-memory/fichier pour SQLite comme LanceDB ou simple similarité cosine en JS pour commencer simple).
*   **UX :** Interface de gestion des tags et affichage des suggestions.

### Growth Features (Post-MVP)
*   **Multi-Provider UI :** Interface graphique pour changer de modèle IA sans toucher au `.env`.
*   **Chat with Notes :** Un mode "Chat" pour poser des questions à ses notes (RAG complet).
*   **Tagging Rétroactif :** Batch job pour taguer automatiquement toutes les anciennes notes existantes.

### Vision (Future)
*   **Agents Autonomes :** Des agents qui réorganisent activement le dashboard, archivent les vieux trucs, et proposent des résumés hebdomaires.
*   **Voice-to-Note Intelligent :** Transcription vocale avec structuration automatique immédiate.

## User Journeys

### Journey 1: Alex - The "Zero-Friction" Note Taker
**Persona:** Alex, Freelance Creative & Developer. Lives in chaos, needs structure but hates maintenance.
**Goal:** Capture ideas instantly and retrieve them effortlessly later.
*   **The Chaos:** Alex saves a complex CSS Grid trick. He needs to save it *now* without spending time to tag it.
*   **The Magic:** Keep's AI analyzes the content and suggests tags like `frontend`, `css`, `snippets`. Alex approves them with one click.
*   **The Retrieval:** Weeks later, he searches "responsive layout technique" and finds the note instantly via semantic search.

### Journey 2: Sarah - The "5-Minute" Self-Hoster
**Persona:** Sarah, Home Lab Enthusiast.
**Goal:** Host her own private note-taking app with minimal fuss.
*   **The Setup:** She clones the repo, adds an API Key to her `.env`, and runs `npm run dev`. No complex infrastructure required.
*   **The Support:** Impressed by the ease of use, she donates via "Buy me a coffee".

### Journey 3: Max - The "Local-First" Contributor
**Persona:** Max, Privacy Advocate.
**Goal:** Use Keep with a completely offline LLM stack (Ollama).
*   **The Contribution:** He adds a new `OllamaProvider` using the modular `AIProvider` interface in 15 minutes and submits a PR.

## Innovation & Novel Patterns
*   **Intelligent Self-Organization:** Predictive "Human-in-the-loop" tagging reduces cognitive load.
*   **Semantic-First Retrieval:** Enterprise-grade search in a lightweight, self-hosted tool.
*   **Low-Barrier AI Distribution:** Zero-config, single-container architecture using Vercel AI SDK.

## Web App Specific Requirements

### Real-Time AI Interaction (Streaming)
*   **Behavior:** Auto-tagging suggestions appear live as the user types (debounced).
*   **UX:** Subtle UI indicators (thinking icon) show analysis progress without distraction.

### Offline Capability (PWA)
*   **Requirement:** Full PWA support; app launches and functions without internet.
*   **Strategy:** Service Workers and Local-First data storage with background sync.

### Performance & Constraints
*   **Input Limits:** Optimized for notes up to ~4000 tokens (approx. A4 size).
*   **Optimistic UI:** All actions reflect instantly in the UI before server confirmation.

## Project Scoping & Phased Development

### MVP Strategy & Philosophy
**MVP Approach:** Experience MVP - Focus on the "magic" of effortless organization to drive adoption.
**Resource Requirements:** Full-stack TypeScript/Next.js developer.

### MVP Feature Set (Phase 1)
**Core User Journeys Supported:** Alex (Zero-friction) and Sarah (Easy setup).
**Must-Have Capabilities:**
*   Streaming Auto-tagging suggestions.
*   Semantic search with local vector storage.
*   Support for OpenAI and Ollama.

### Post-MVP Features
**Phase 2 (Growth):** PWA advanced sync, multi-provider settings UI, retroactive tagging.
**Phase 3 (Expansion):** RAG Chat with notes, autonomous agents for dashboard organization.

### Risk Mitigation Strategy
**Technical Risks:** Use abstraction interfaces (`AIProvider`) to handle multiple backend types.
**Market Risks:** Focus on "Easy Hosting" to differentiate from complex AI self-hosted tools.

## Functional Requirements

### Gestion des Notes (Fondations)
- **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).

### Organisation Intelligente (IA)
- **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.

### Recherche Avancée (Découvrabilité)
- **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).

### Expérience Web & Offline (PWA)
- **FR14 :** L'utilisateur peut accéder à l'application et à ses notes sans connexion internet (Mode Offline).
- **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).

### Configuration & Administration (Self-Hosting)
- **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.
- **FR19 :** L'utilisateur peut choisir son thème (clair/sombre) et personnaliser les couleurs des notes.

## Non-Functional Requirements

### Performance
*   **IA Responsiveness:** Auto-tagging suggestions must appear within 1.5s after typing ends (debounce).
*   **Search Latency:** Hybrid search results displayed in < 300ms for 1000 notes.
*   **PWA Load Time:** Interactive in < 2s on average 4G network.

### Security & Privacy
*   **API Key Isolation:** AI provider keys remain server-side; never exposed to the client.
*   **Local-First Privacy:** Full local LLM support (Ollama) ensures no note data leaves user infrastructure.
*   **Data at Rest:** Local PWA storage secured via standard Web Storage protocols.

### Reliability & Sync
*   **Offline Resilience:** 100% data integrity for offline notes during background sync.
*   **Vector Integrity:** Automatic, background semantic index updates on every note change.

### Portability (Self-Hosting)
*   **Efficiency:** Minimal Docker/build footprint for execution on low-resource servers (e.g., Raspberry Pi).
*   **Compatibility:** Support for current Node.js LTS versions.