Brainstorm

Brainstorm is a modern, AI-powered ideation platform that gamifies the brainstorming process. By combining a "Tinder-style" card interface with advanced Large Language Model (LLM) analysis, it helps users rapidly explore, categorize, and filter creative ideas.

!NOTE This application is designed as a local-first development prototype. While it supports powerful AI integration, it currently stores sensitive data (API keys) in local storage and is intended for personal or internal use.

Installation

Brainstorm is built on the Bun runtime for high-performance development and execution.

Prerequisites

• Bun: v1.0 or higher
• Node.js: Compatible with standard Node environments (though Bun is preferred)
• Local AI (Optional): A BitNet instance running on localhost:8080 if using the default local provider.

Setup

Clone the repository and install dependencies:

# Clone the repository (if not already done)
git clone <repository-url>
cd brainstorm

# Install dependencies using Bun
bun install

Getting Started

Brainstorm operates as a Single Page Application (SPA) served via Vite.

Quick Start (Development Mode)

To start the development server with hot-module replacement (HMR):

bun run dev

The application will be accessible at http://localhost:5173.

Production Build

To build the application for production deployment:

bun run build

This generates a static output in the dist/ directory, optimized for performance.

Core Features

1. AI-Powered Analysis

Brainstorm uses a multi-stage AI pipeline to process user input:

1. Decomposition: The user's initial abstract idea is broken down into distinct semantic categories.
2. Expansion: Selected categories are sent back to the AI to generate concrete, actionable idea cards.
3. JSON Parsing: The raw LLM output is robustly parsed (extracting JSON from Markdown code blocks if necessary) to ensure valid data structures.

2. Swipe Interface

The core interaction model is a physics-based card stack:

• Swipe Right: "Keep" / "Like". The idea is saved to your session.
• Swipe Left: "Discard". The idea is removed.
• Animations: Includes velocity tracking, rotation multipliers, and smooth entrance/exit transitions configured in src/config/index.ts.

3. Session Persistence

The application maintains state locally, allowing you to close and reopen the browser without losing your conceptual progress. It tracks:

• The original input.
• Selected categories.
• The pool of generated ideas.
• Liked vs. Dismissed piles.

4. Multi-Provider Support

The system is architected to support multiple AI backends, managed via updateable configuration:

• BitNet: Local, offline LLM (default).
• OpenRouter: Gateway to commercial models (GPT-4, Claude).
• Gemini: Google's multimodal models.
• IO.net: Decentralized compute network.

Specification Reference

Data Models (Schema)

Brainstorm uses Zod for strict runtime validation. Below are the core data structures used throughout the application.

Idea Card

Represents a single generated concept.

{
  id: string;          // UUID
  title: string;       // Concise headline
  description: string; // Detailed explanation
  categories: string[]; // Association tags
  timestamp: number;   // Creation epoch
}

Session State

The specific structure persisted to storage.

{
  id: string;
  input: {
    text: string;      // > 10 chars
    timestamp: number;
  } | null;
  categories: Category[];
  ideaPool: IdeaCard[];     // Cards waiting to be swiped
  likedIdeas: IdeaCard[];   // Swiped Right
  dismissedIdeas: IdeaCard[]; // Swiped Left
  currentIndex: number;
}

AI Provider Config

Configuration object for connecting to different backends.

{
  type: 'bitnet' | 'openrouter' | 'gemini' | 'ionet';
  endpoint: string; // Must be a valid URL
  apiKey?: string;  // Optional for local models
  enabled: boolean;
}

Security & Configuration

Configuration

Global application settings are defined in src/config/index.ts. These control AI behavior, UI mechanics, and provider details.

!IMPORTANT The config object is currently hardcoded in the source. To change provider endpoints or thresholds, you must modify src/config/index.ts and rebuild the application.

Security Constraints

• API Key Storage: API keys for remote providers (OpenRouter, Gemini) are currently managed via client-side code or local storage. Do not commit API keys to version control.
• Input Validation: All User inputs are sanitized and validated against Zod schemas (UserInputSchema) before processing prevents injection vectors or malformed state.
• CORS: When connecting to local AI servers (like BitNet), ensure your server is configured to allow CORS requests from localhost:5173.

CLI Reference

While Brainstorm is primarily a web application, it provides a set of CLI commands for development lifecycle management.

bun dev

Starts the Vite development server.

Usage Output:

$ bun dev
  Vite v6.0.5  ready in 345 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

bun build

Compiles the application for production. This runs TypeScript compilation (tsc) followed by Vite's build process.

Usage Output:

$ bun build
$ tsc && vite build
vite v6.0.5 building for production...
✓ 45 modules transformed.
dist/index.html                   0.45 kB │ gzip:  0.30 kB
dist/assets/index-D5z7s1h2.css    4.12 kB │ gzip:  1.32 kB
dist/assets/index-C8w9q0p1.js    22.45 kB │ gzip:  8.12 kB
✓ built in 1.45s

bun run typecheck

Runs the TypeScript compiler in noEmit mode to verify type safety across the entire project without generating output files.

Usage Output:

$ bun run typecheck
$ tsc --noEmit
# (No output indicates success. Errors will list specific files and lines)
src/services/ai/bitnet-provider.ts:12:5 - error TS2322: Type 'string' is not assignable to type 'number'.