--- 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 --- # Momento - Epic Breakdown ## Overview This document provides the complete epic and story breakdown for Momento, focusing strictly on the **Commercial and AI Delta** required to launch the V3 product. Momento 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 Momento 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.