96e7902f01
Publication IA: - 4 templates (magazine, brief, essay, simple) avec CSS riche - Rewrite IA (article/exercises/tutorial/reference/mixed) - Modération avec timeout 12s + fallback safe - Quotas publish_enhance par tier (basic=2, pro=15, business=100) - Détection contenu stale (hash) - Migration DB publishedContent/publishedTemplate/publishedSourceHash Fixes: - cheerio v1.2: Element -> AnyNode (domhandler), decodeEntities cast - _isShared ajouté au type Note (champ virtuel serveur) - callout colors PDF export: extraction fonction pure testable - admin/published: guard note.userId null - Cmd+S fonctionne en mode dialog (pas seulement fullPage) i18n: - 23 clés publish* traduites dans les 15 locales - Extension Web Clipper: 13 locales mise à jour Tests: - callout-colors.test.ts (6 tests) - note-visible-in-view.test.ts (5 tests) - entitlements.test.ts + byok-entitlements.test.ts: mock usageLog + unstubAllEnvs - 199/199 tests passent Tracker: user-stories.md sync avec sprint-status.yaml
253 lines
11 KiB
Markdown
253 lines
11 KiB
Markdown
---
|
|
stepsCompleted:
|
|
- step-01-validate-prerequisites
|
|
- step-02-design-epics
|
|
- step-03-create-stories
|
|
inputDocuments:
|
|
- docs/prd.md
|
|
- memento-note/docs/brainstorm-documentation.md
|
|
- memento-note/docs/saas-deployment-prep.md
|
|
---
|
|
|
|
# Memento - Epic Breakdown
|
|
|
|
## Overview
|
|
|
|
This document provides the complete epic and story breakdown for Memento, focusing strictly on the **Commercial and AI Delta** required to launch the V3 product. Memento is a **Brownfield** project. The baseline functionality (Basic User Auth, Workspaces, CRUD Rich-Text Notes, pgvector database) already exists and is considered out-of-scope for these epics.
|
|
|
|
## Requirements Inventory
|
|
|
|
### Functional Requirements
|
|
|
|
FR4: Users can upload PDF documents and extract text for AI contextual analysis (Chat-with-PDF).
|
|
FR5: Users can invoke automated task extraction on any note to generate structured, actionable to-do lists.
|
|
FR6: Users can leverage one-shot AI to automatically generate contextual tags and titles for their notes (Auto-Tagging / Auto-Titling).
|
|
FR7: The system will proactively detect and surface semantic connections between disconnected notes in the background ("Memory Echo") to stimulate serendipitous discovery.
|
|
FR8: Hosts can initialize a real-time collaborative Brainstorm session derived from an existing note.
|
|
FR9: Guests can join a shared Brainstorm session via a frictionless sharing link without requiring an account.
|
|
FR10: Users can visually map and generate ideas on a multi-directional radial graph (Canvas).
|
|
FR11: Users can prompt AI within the shared session to generate specific ideation "Waves" (Variations, Analogies, Disruptions).
|
|
FR12: Users can export the completed Brainstorm canvas to structured formats (Markdown, Branded PPTX).
|
|
FR13: Users can monitor their remaining "AI Discovery Pack" or subscription usage limits via a real-time UI indicator.
|
|
FR14: Users can input, update, and securely store their own third-party LLM API keys (BYOK) to bypass platform limits.
|
|
FR15: Hosts can assume financial responsibility (token consumption) for all AI queries executed by guests within their active shared sessions.
|
|
FR16: Users can upgrade to paid subscription tiers (Pro, Business, Enterprise) via an integrated payment gateway.
|
|
FR17: Users can dynamically switch between supported AI providers (OpenAI, DeepSeek, Gemini, OpenRouter, etc.) for specific generation tasks.
|
|
FR18: Administrators can configure smart-routing fallback rules to default to specific models under heavy load or quota exhaustion.
|
|
FR20: Enterprise users can authenticate via Single Sign-On (SSO / SAML).
|
|
FR21: Workspace administrators can view comprehensive audit logs detailing user access events and specific AI provider utilization.
|
|
FR22: Workspace administrators can configure strict data residency requirements (e.g., EU-only storage) for their tenant.
|
|
FR23: Administrators can programmatically enforce zero-data-retention headers/flags for all outbound third-party AI API requests.
|
|
*(Note: FR1, FR2, FR3 are Baseline and excluded. FR19 is deferred to Phase 2).*
|
|
|
|
### NonFunctional Requirements
|
|
|
|
NFR-P1 (Real-Time Latency): Brainstorm Canvas WebSocket events must propagate within 150ms.
|
|
NFR-P3 (AI Routing): The internal LLM Router must dispatch the prompt within 50ms.
|
|
NFR-S1 (Encryption): BYOK API keys must be encrypted at rest using AES-256-GCM.
|
|
NFR-S2 (Data Residency): Architecture must support configurable EU-only database deployments.
|
|
NFR-S3 (Auditability): Log 100% of LLM API requests, retaining anonymized metrics for 1 year.
|
|
NFR-SC1 (Collaborative Sessions): Session gracefully supports 50 concurrent active users.
|
|
NFR-SC2 (Rate Limiting): Redis entitlement process usage checks in under 10ms.
|
|
NFR-R1 (Graceful Degradation): LLM Router falls back to secondary provider within 1.5 seconds.
|
|
NFR-GDPR1 (Cookie Consent): Granular accept/reject of analytics and tracking cookies.
|
|
NFR-GDPR2 (Right to be Forgotten): Hard deletion of all vector data, BYOK keys, and accounts.
|
|
NFR-GDPR3 (Data Portability): Secure exports of user data.
|
|
NFR-GDPR4 (Explicit Consent): Explicit user consent when processing personal data through AI APIs.
|
|
|
|
### Additional Requirements
|
|
|
|
- Next.js App Router for frontend/backend infrastructure
|
|
- D3.js required for Brainstorm radial graph
|
|
- Dedicated Socket.io server running on port 3002 for low-latency Canvas state
|
|
- PostgreSQL (managed via Prisma) for persistent data storage
|
|
- Redis for hybrid entitlement/rate-limiting system
|
|
- Custom LLM Router (`lib/ai/router.ts`) supporting 13 independent providers via OpenRouter aggregation layer for the long-tail.
|
|
- Stripe billing integration for subscription tier management
|
|
- **"Brownfield" Context**: DO NOT write development stories for basic Workspace Hierarchy, Rich-Text CRUD, or pgvector setup as they already exist. Focus 100% on the COMMERCIAL & AI DELTA.
|
|
|
|
### FR Coverage Map
|
|
|
|
FR12: Epic 4 - Data Portability / Export Brainstorm canvas
|
|
FR13: Epic 3 - Freemium "AI Discovery Pack" & Redis Quota
|
|
FR14: Epic 3 - Secure BYOK Management
|
|
FR15: Epic 3 - "Host-Pays" Session Billing Logic
|
|
FR16: Epic 3 - Stripe Subscription Tiers
|
|
FR17: Epic 3 - Custom LLM Router & OpenRouter integration
|
|
FR18: Epic 3 - Smart-routing fallback rules
|
|
FR20: Epic 4 - SSO/SAML Integration
|
|
FR21: Epic 4 - Enterprise Audit Logging
|
|
FR22: Epic 4 - EU Data Residency configuration
|
|
FR23: Epic 4 - Zero-data-retention headers
|
|
|
|
## Epic List
|
|
|
|
### Epic 3: The SaaS Commercial Engine (Monetization & API Cost Protection)
|
|
The core backend logic allowing the product to be sold without bleeding API costs (freemium limits, router fallback, host-pays).
|
|
**FRs covered:** FR13, FR14, FR15, FR16, FR17, FR18
|
|
|
|
### Epic 4: Enterprise Compliance & Privacy (B2B Requirements)
|
|
Enforcing B2B sales requirements and European legal requirements (GDPR, Cookie Consent, SSO, EU Data Residency).
|
|
**FRs covered:** FR12, FR20, FR21, FR22, FR23
|
|
|
|
---
|
|
|
|
|
|
## Epic 3: The SaaS Commercial Engine (Monetization & API Cost Protection)
|
|
|
|
Focus: The core backend logic allowing us to sell the product without bleeding API costs.
|
|
|
|
### Story 3.1: Freemium "AI Discovery Pack" Quota Tracking
|
|
|
|
As a business,
|
|
I want to track Freemium usage against a Redis quota limit,
|
|
So that I can limit my API cost exposure for free users.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a free user triggers an AI request
|
|
**When** the system intercepts the request
|
|
**Then** the quota is tracked and the UI updates
|
|
**And** (NFR-SC2) the Redis-backed check resolves in under 10ms.
|
|
|
|
### Story 3.2: Custom LLM Router & OpenRouter Integration
|
|
|
|
As a system,
|
|
I want to route AI prompts across 13 different providers via OpenRouter,
|
|
So that we have extreme flexibility in API fulfillment.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** an AI request is initiated
|
|
**When** the LLM Router intercepts it
|
|
**Then** (NFR-P3) the routing logic dispatches the prompt within 50ms to the optimal provider.
|
|
|
|
### Story 3.3: Smart-Routing Fallback
|
|
|
|
As a system,
|
|
I want to automatically fall back to a secondary provider if the primary fails,
|
|
So that users experience zero downtime during external API outages.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a primary AI provider returns a 429 or 500 error
|
|
**When** the LLM Router detects the failure
|
|
**Then** (NFR-R1) the request automatically falls back to the secondary provider within 1.5 seconds.
|
|
|
|
### Story 3.4: The "Host-Pays" Session Logic
|
|
|
|
As a host,
|
|
I want my guests' AI actions inside my Canvas session to be billed to my account,
|
|
So that my guests never hit a paywall while collaborating with me.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a guest triggers an AI Wave in a shared session
|
|
**When** the request reaches the LLM Router
|
|
**Then** the token consumption is deducted from the Host's quota, leaving the guest's quota untouched.
|
|
|
|
### Story 3.5: Secure BYOK Management
|
|
|
|
As an enterprise user,
|
|
I want to input and use my own LLM API keys (Bring Your Own Key),
|
|
So that I can bypass SaaS quotas.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I save my custom API key
|
|
**When** it is stored in the database
|
|
**Then** (NFR-S1) it is encrypted at rest using AES-256-GCM
|
|
**And** the LLM Router prioritizes this key for my requests.
|
|
|
|
### Story 3.6: Stripe Subscription Tiers
|
|
|
|
As a user,
|
|
I want to upgrade to a paid tier (Pro, Business, Enterprise) via Stripe,
|
|
So that I can unlock higher quotas and features.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I select an upgrade plan
|
|
**When** I complete checkout via the Stripe gateway
|
|
**Then** my account capabilities are instantly unlocked.
|
|
|
|
---
|
|
|
|
## Epic 4: Enterprise Compliance & Privacy (B2B Requirements)
|
|
|
|
Focus: B2B sales blockers and European legal requirements.
|
|
|
|
### Story 4.1: GDPR Cookie Consent Management
|
|
|
|
As a visitor,
|
|
I want to granularly accept or reject analytics and tracking cookies,
|
|
So that my ePrivacy rights are respected.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I visit the application
|
|
**When** the consent banner is shown
|
|
**Then** (NFR-GDPR1) I can toggle tracking cookies while strictly necessary cookies remain enforced.
|
|
|
|
### Story 4.2: GDPR Right to be Forgotten (Hard Deletion)
|
|
|
|
As a user,
|
|
I want the ability to perform a complete, hard deletion of my account,
|
|
So that I can exercise my Right to be Forgotten under GDPR.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I confirm account deletion
|
|
**When** the system processes the request
|
|
**Then** (NFR-GDPR2) the system enforces a hard deletion of all my pgvector data, BYOK keys, and user records.
|
|
|
|
### Story 4.3: Data Portability & Export
|
|
|
|
As a user,
|
|
I want to securely export my workspace data and Brainstorm canvases,
|
|
So that I have full portability of my knowledge.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I request a data export
|
|
**When** the system complies
|
|
**Then** (FR12, NFR-GDPR3) I receive a secure download (Markdown/PPTX) of my data.
|
|
|
|
### Story 4.4: Explicit AI Processing Consent
|
|
|
|
As a user,
|
|
I want to explicitly consent before any of my personal data is sent to a third-party AI,
|
|
So that I retain full control over my data privacy.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I trigger an AI feature that processes my notes or PDFs
|
|
**When** the request is initiated
|
|
**Then** (NFR-GDPR4) explicit consent is logged before the data leaves the Memento infrastructure.
|
|
|
|
### Story 4.5: EU Data Residency Configuration
|
|
|
|
As an Enterprise Administrator,
|
|
I want to configure my tenant for EU-only storage and enforce zero-data-retention on APIs,
|
|
So that our data never leaves the EU and is never trained on.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** an enterprise workspace is created
|
|
**When** EU residency is selected
|
|
**Then** (NFR-S2) the database deployment is restricted to the EU
|
|
**And** (FR23) all outbound API requests enforce zero-data-retention headers.
|
|
|
|
### Story 4.6: SSO/SAML & Audit Logging
|
|
|
|
As an Enterprise Administrator,
|
|
I want my users to authenticate via SSO and I want access to comprehensive audit logs,
|
|
So that I can secure and audit our workspace.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** I am an enterprise tenant
|
|
**When** users log in or perform actions
|
|
**Then** (FR20) authentication occurs via SSO/SAML
|
|
**And** (FR21, NFR-S3) 100% of LLM API requests and logins are logged and retained for 1 year for SOC2 compliance.
|