Fruitstorm

AI-assisted brainstorming sessions

Turn a single goal into branching phases of ideas — steer with clicks, refine with focus prompts, and finish with a polished report.

Quick Start · Features · How It Works · Architecture · Full Docs

---

What is Fruitstorm?

Fruitstorm helps you brainstorm by turning a topic into iterative phases of short ideas called fruits. It ships with two board modes:

🌿 Guided phases

1. Start with a goal.
2. The LLM generates a branch of 10 fruits — concise ideas with a title + context line.
3. You mark fruits as more, exclude, or normal.
4. Each new phase uses your selections to narrow and refine the ideas.
5. When you're ready, Finalize to get a full structured report.

🧭 Open explore

• The same fruit cards and mark actions (more / normal / exclude), but marks are personal notes only — they do not steer generation.
• Ideas appear in a responsive grid.
• Generate more always requests new unique ideas (existing titles are sent as a do-not-repeat list).

Works with local LLMs (Ollama, LM Studio) and remote OpenAI-compatible providers. Boards, phases, and fruits are stored per-account in a SQLite database on the server.

---

✨ Features

Core Workflow Two board modes — Guided phases or Open explore when creating a board Multiple boards — separate sessions for different topics Zoomable canvas — pan & zoom across all phases Fruit actions — + more · ○ keep · × exclude · ↻ regenerate Next phase — branch informed by every prior selection Expand branch — add more fruits to the latest phase Finalize — Markdown report with copy, PDF export, regenerate

Power Tools Focuses — persistent extra instructions under your objective Fruit deep-dive — longer, editable write-up from a fruit (Guided phases) Drag & drop — reorder fruits within a phase Phase fork — split a phase into a new board Background jobs — generations survive tab close & refresh

Category	Highlights
LLM	Any OpenAI-compatible endpoint — Ollama, LM Studio, OpenAI, Groq, and more
Resilience	Friendly errors for connection issues, context limits, rate limits + per-phase retry
Storage	Boards, phases, fruits, focuses — in a server-side SQLite database
UI	Pure CSS + CSS variables — no heavy component libraries

---

🚀 Quick Start

Prerequisites

• Node.js 22+ (uses built-in node:sqlite)
• A running LLM server (e.g. Ollama on http://localhost:11434)

Run locally

git clone <This repo>
cd fruitstorm
npm install
npm run dev

Service	URL
Frontend (Vite)	http://localhost:5173
API + jobs (Express)	http://localhost:3456

Open http://localhost:5173. On a fresh install you’ll be asked to create the first admin (Open WebUI–style) — choose your own username and password. No default credentials are shipped.

Docker

Production image serves the built UI and the generation API on a single port.

# Build & run
docker compose up --build -d

# Or without Compose
docker build -t fruitstorm .
docker run --rm -p 3456:3456 fruitstorm

Open http://localhost:3456 and sign in.

Env	Default	Meaning
PORT	3456	Container listen port (host map with -p)
HOST	0.0.0.0	Bind address inside the container
NODE_ENV	production	Enables static file serving from dist/
DATA_DIR	/app/data	SQLite DB directory (compose mounts a volume here)
ADMIN_USERNAME	(unset)	Optional headless admin — only with ADMIN_PASSWORD
ADMIN_PASSWORD	(unset)	Optional headless admin — min 8 chars; no defaults
COOKIE_SECURE	false	Set true only behind HTTPS; leave off for http://LAN-IP

Local LLMs (Ollama / LM Studio) from Docker: generation jobs run inside the container. Prefer http://host.docker.internal:1234/v1 (compose includes host-gateway). The browser “Test connection” may still fail with that hostname — try a real phase generate, or use a LAN IP both browser and container can reach.

Remote APIs: the container needs outbound HTTPS for OpenAI-compatible providers during generation jobs.

---

🧠 How It Works

flowchart LR
    A["🎯 Set Objective"] --> B["🌿 Phase 1<br/>10 fruits"]
    B --> C{"Mark fruits<br/>+ ○ ×"}
    C --> D["➡ Next Phase"]
    D --> E["🔀 Refined branch"]
    E --> C
    E --> F["📄 Finalize Report"]
    F --> G["Copy · PDF · Regenerate"]

Loading

Step-by-step

1. Create a new board and choose a mode (Guided phases or Open explore)
2. Type your goal in the bottom bar → Start
3. Review the first branch of 10 fruits
4. Click fruits to cycle status: + (expand on this), ○ (keep), × (avoid similar)
5. Add direction in the prompt bar → Next Phase or Send (saved as a Focus)
6. Expand the current branch, regenerate individual fruits, or drag to reorder
7. Deep-dive any fruit to branch a longer, editable write-up card (Guided phases)
8. Fork a phase, move fruits to the latest phase, or delete phases (except the first)
9. Finalize Brainstorming when you're happy with the direction

Tip: Long-running generations continue on the companion server even if you close or refresh the tab. The UI resumes polling and applies results when you return.

See DOCUMENTATION.md for detailed guides on focuses, phases, LLM setup, and architecture.

---

🔐 Accounts & Storage

• Data is stored in a SQLite database on the server (DATA_DIR, default ./data/fruitstorm.db).
• Users sign in with username/password. Sessions use an HttpOnly cookie.
• Roles: admin and user. Admins can create, update, demote/promote, and delete users.
• Each account has its own boards and LLM settings.
• First-time setup (Open WebUI pattern): if the DB has no users, the UI requires creating the first admin (username + strong password + confirm). Nothing is pre-seeded with default credentials.
• Optional headless admin: set both ADMIN_USERNAME and ADMIN_PASSWORD (password ≥ 8). If either is missing, setup stays in the UI.

---

⚙️ LLM Configuration

Click the ⚙ gear icon in any board.

Setting	Example
Base URL	http://localhost:11434/v1 (Ollama) · http://localhost:1234/v1 (LM Studio)
Model	llama3.2 · qwen2.5 · gpt-4o-mini
API Key	Leave empty for local models

Presets included for Ollama, LM Studio, OpenAI, Groq, and more. A Test Connection button verifies your endpoint before you start generating.

---

🛠 Tech Stack

Layer	Tools
Frontend	Vite 8 · React 19 · TypeScript
Backend	Express 5 · tsx · node:sqlite
LLM	openai package (OpenAI-compatible)
Export	jspdf for PDF reports
Styling	Pure CSS + CSS variables

---

Storm ideas. Harvest insights.

📖 Full documentation →