Momento/memento-note/BRAINSTORM-CANVAS-SPEC.md

Brainstorm Canvas — Feature Spec for OpenCode

PROJECT CONTEXT

• Stack: Next.js 15 + Prisma + PostgreSQL (pgvector)
• Location: ~/dev/Momento/memento-note/
• Existing models: User, Note, Notebook, Canvas (Excalidraw), Agent, Conversation, Workflow, etc.
• Existing API routes: /app/api/notes, /notebooks, /ai, /canvas, /chat, /agents, etc.
• UI lib: Radix UI + Tailwind CSS + shadcn components
• State: @tanstack/react-query
• Auth: NextAuth (auth.ts, auth.config.ts)

⚠️ CRITICAL RULES

1. DO NOT modify existing models or API routes — only ADD new ones
2. DO NOT touch prisma/schema.prisma without creating a migration — use npx prisma migrate dev --name add_brainstorm
3. Study the existing code patterns before writing new code — match the project conventions
4. Look at how existing API routes are structured (e.g., /app/api/notes/route.ts) and follow the same pattern
5. Look at how existing components use React Query and follow the same pattern
6. Use existing UI components from /components/ui/ (shadcn) — don't install new UI libs
7. The project uses TypeScript — maintain strict typing
8. Do NOT run npm build — only dev server if needed for testing

FEATURE: Brainstorm Canvas (Wave Brainstorming)

Concept

A temporary workspace for brainstorming ideas using AI-generated "waves" of ideas, displayed as a radial graph. The output feeds back into the notes system.

Data Model — ADD these 2 models to prisma/schema.prisma:

model BrainstormSession {
  id               String    @id @default(cuid())
  seedIdea         String
  sourceNoteId     String?
  contextNoteIds   String?   // JSON array of note IDs
  exportedNoteId   String?
  userId           String
  createdAt        DateTime  @default(now())
  updatedAt        DateTime  @updatedAt
  ideas            BrainstormIdea[]
  sourceNote       Note?     @relation(fields: [sourceNoteId], references: [id])
  exportedNote     Note?     @relation(fields: [exportedNoteId], references: [id])
  user             User      @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@index([userId])
  @@index([userId, createdAt])
}

model BrainstormIdea {
  id                  String    @id @default(cuid())
  sessionId           String
  waveNumber          Int       // 1, 2, or 3
  title               String
  description         String
  connectionToSeed    String?
  noveltyScore        Int?
  parentIdeaId        String?   // for "dig deeper" sub-brainstorms
  convertedToNoteId   String?
  relatedNoteIds      String?   // JSON array
  status              String    @default("active") // active, dismissed, converted
  positionX           Float?
  positionY           Float?
  createdAt           DateTime  @default(now())
  session             BrainstormSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
  parentIdea          BrainstormIdea?   @relation("IdeaTree", fields: [parentIdeaId], references: [id])
  children            BrainstormIdea[]  @relation("IdeaTree")
  convertedNote       Note?             @relation(fields: [convertedToNoteId], references: [id])

  @@index([sessionId])
  @@index([waveNumber])
  @@index([status])
  @@index([parentIdeaId])
}

Also add relations to User model:

brainstormSessions BrainstormSession[]

And to Note model — add these two relations:

sourceBrainstormSessions  BrainstormSession[]  @relation via sourceNoteId
exportedBrainstormSessions BrainstormSession[] @relation via exportedNoteId  
convertedBrainstormIdeas  BrainstormIdea[]     @relation via convertedToNoteId

API Routes — Create /app/api/brainstorm/

1. POST /api/brainstorm/wave — Create new brainstorm session

   • Input: { seedIdea, sourceNoteId?, contextNoteIds? }
   • Uses existing AI setup (check how /api/ai/ routes call LLM)
   • Generates 3 waves of ~3 ideas each (9 total)
   • For each idea, does an embedding search to find related notes (check how semantic search works in existing code)
   • Saves session + ideas to DB
   • Returns: { sessionId, ideas: [...] }

2. POST /api/brainstorm/[sessionId]/expand — Dig deeper on an idea

   • Input: { ideaId }
   • Uses the clicked idea as new seed
   • Generates 3 more waves, linked as children
   • Returns new ideas with parentIdeaId set

3. POST /api/brainstorm/[sessionId]/dismiss — Mark idea as not relevant

   • Input: { ideaId }
   • Sets status = "dismissed"

4. POST /api/brainstorm/[sessionId]/convert — Convert idea to a real Note

   • Input: { ideaId }
   • Creates a Note with pre-filled content
   • Auto-tags: "brainstorm", "idée"
   • Links to source note if exists
   • Sets idea.status = "converted", idea.convertedToNoteId = newNote.id
   • Returns the created note

5. POST /api/brainstorm/[sessionId]/export — Export session as summary note

   • Generates a Markdown summary note
   • Groups by waves, shows which ideas were converted
   • Links to all converted notes
   • Returns the created note

6. GET /api/brainstorm — List user's brainstorm sessions

   • Returns sessions ordered by date, with idea counts

7. GET /api/brainstorm/[sessionId] — Get full session with ideas

   • Returns session + all ideas + their status

Frontend — Canvas Component

Use react-force-graph-2d (install it: npm install react-force-graph-2d). It's a React wrapper around d3-force — declarative API, same physics engine.

Layout:

• Center node = seed idea (large, white)
• Ring 1 (radius ~150px) = Wave 1 ideas (orange)
• Ring 2 (radius ~300px) = Wave 2 ideas (blue)
• Ring 3 (radius ~450px) = Wave 3 ideas (purple)
• Use d3.forceRadial for ring constraint
• Dismissed nodes = opacity 0.3, smaller
• Converted nodes = green border + icon
• Click node = side panel with details + 3 action buttons

Side Panel (when clicking a node):

• Show: title, description, connection to seed, related notes
• 3 buttons: Dig Deeper, Create Note, Dismiss
• Uses existing shadcn Sheet or Dialog component

Sidebar Integration:

• Add "Brainstorms" section in the existing sidebar
• List sessions with preview (seed idea + count)
• Click to reopen saved canvas state

Entry Points:

1. From a note: Brainstorm button in note toolbar/editor
2. From sidebar: "+ New Brainstorm" button

AI Prompt for Wave Generation

The LLM prompt should generate 3 waves:

• Wave 1 — Variations: Direct variations/expansions of the seed (sous-aspects, reformulations, variations)
• Wave 2 — Analogies: Cross-domain analogies (autres domaines, biologie, technologie, etc.)
• Wave 3 — Disruptions: Inversions, provocations, ideas that challenge assumptions

Each idea should have:

• title (short)
• description (1-2 sentences)
• connectionToSeed (how it relates to the seed)
• noveltyScore (1-10)

Implementation Order

1. Prisma schema + migration
2. API routes (start with /wave and /convert)
3. Brainstorm canvas component (react-force-graph-2d)
4. Sidebar integration
5. Note toolbar button
6. Export functionality