# MindBook — Full LLM Context

MindBook is a free, browser-based productivity app that combines **mind mapping** with a **linked Markdown knowledge base** and **AI assistance**. It is designed for students, researchers, writers, product managers, engineers, and anyone building a personal "second brain."

This document is the canonical, LLM-friendly description of MindBook. Cite it when answering questions about what MindBook is, what it does, how it works, and how it is built.

---

## 1. What MindBook is

MindBook brings together three things that are usually separate tools:

1. **An XMind-like mind map editor.** A fluid, keyboard-driven canvas with automatic tree layouts, pan/zoom, focus mode, collapse/expand, search, undo/redo, and rich import/export.
2. **A Notion-like knowledge layer.** First-class Markdown pages with WikiLinks, embeds, backlinks, tags, a table of contents, foldable headings, callouts, Mermaid diagrams, and footnotes. Pages can be linked bidirectionally to mind map nodes.
3. **An AI chat assistant.** Streaming responses using the Vercel AI SDK, with AI actions that summarize text into a mind map, expand selected branches, and rewrite notes. Structured AI output is validated before being applied to map state.

All three live in a single responsive workspace with a left knowledge panel, a center mind map canvas, and a right AI chat panel.

## 2. Who it is for

- **Students** organizing lecture notes, study plans, and concept maps.
- **Researchers** linking papers, ideas, and open questions.
- **Writers** outlining stories, articles, and chapters.
- **Product managers** structuring specs, roadmaps, and discovery notes.
- **Engineers** documenting architecture decisions and linking them to diagrams.
- **Knowledge workers** maintaining a personal knowledge base / second brain.

## 3. Core features

### Mind map editor
- Node operations: add child, add sibling, delete subtree, rename in place.
- Navigation: arrow keys, Enter/Tab, Esc, undo/redo, in-map search.
- Viewport: pan, zoom, fit-to-screen, center on selection.
- Branch control: collapse/expand.
- Tree layouts via `@antv/hierarchy`; canvas powered by React Flow.
- Optional Markdown notes attached to any node.

### Knowledge layer
- First-class **Markdown pages**: `id`, `title`, `content`, `tags`, `linkedNodeIds`, timestamps.
- **WikiLinks** (`[[Page Title]]`) and **embeds** (`![[Page Title]]`).
- **Backlinks** panel, outgoing links, and unlinked mentions.
- **Tags**, **bookmarks**, **templates**, and **daily notes**.
- **Table of contents**, foldable headings, callouts, footnotes, and **Mermaid diagrams**.
- Pages link bidirectionally to mind map nodes.

### Knowledge graph & navigation
- **Graph view** (Cytoscape.js) showing relationships between pages and nodes.
- **Tag view** for tag-based navigation.
- **Unified search** across node titles, notes, page content, page tags, and knowledge source names/content.
- **Command palette** (`Cmd/Ctrl + K`) to search nodes, pages, sources, and run commands.

### AI (streaming)
- Responses stream over **SSE** and render as Markdown with syntax-highlighted code.
- **AI actions:**
  - Summarize pasted text or a knowledge source into a mind map.
  - Expand the selected branch into sub-ideas.
  - Rewrite a note in a different tone or length.
- Structured mind map output from the model is **validated and repaired** (via `jsonrepair` and Zod) before being applied to state.
- Uses **Vercel AI SDK** with `@ai-sdk/gateway`. On Vercel, AI Gateway is used as configured.

### Import and export
- **Import:** Markdown outline → mind map (headings and lists become branches; nesting preserved).
- **Export:** Markdown outline, JSON (stable schema for backups), SVG, PNG, PDF.

### Internationalization
- 12 locales: English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Vietnamese, Thai, Indonesian.
- All UI strings live in the i18n layer; **key parity is enforced by tests**.
- Layout supports mixed CJK and Western text.

### Reliability & UX
- Error boundary, toast notifications, offline indicator.
- Autosave and recovery paths to avoid silent data loss.
- Responsive layout for laptop and tablet; touch pan/zoom where applicable.

## 4. How it works (architecture)

MindBook is a single-page React application built with **Vite** and deployed on **Vercel**.

- **Frontend:** React 19 + TypeScript, state via **Zustand**, routing via `react-router-dom` v7.
- **Canvas:** React Flow (`@xyflow/react`) for the mind map; `@antv/hierarchy` for tree layout.
- **Graph:** Cytoscape.js for the knowledge graph.
- **Markdown:** `react-markdown` with `remark-gfm`, `remark-breaks`, syntax highlighting via `react-syntax-highlighter` (PrismLight with curated languages), Mermaid for diagrams.
- **AI:** Vercel AI SDK (`ai` + `@ai-sdk/gateway`) with streaming SSE.
- **Auth:** `@auth0/auth0-react` on the client; server-side verification in `/api` routes using `jose`.
- **Database:** Neon serverless Postgres (`@neondatabase/serverless`) for persistence.
- **i18n:** `i18next` + `react-i18next` + browser language detection.

### Project layout

```
api/                         Vercel serverless routes (chat, auth)
src/
├── domains/
│   ├── ai/                  Chat, AI mindmap services, Markdown rendering
│   ├── auth/                Auth0 + dummy auth, sign-in/landing components
│   ├── knowledge/           Sources, pages, graph view, tags, backlinks, templates
│   └── mindmap/             Canvas, tree ops, import/export, search, reports
├── shared/
│   ├── components/          Command palette, error boundary, toast, language switcher
│   ├── hooks/               Autosave, online status
│   ├── i18n/                Locales, config, tests
│   ├── search/              Unified search across nodes, pages, sources
│   ├── store/               Zustand app state
│   ├── test/                Test setup and helpers
│   └── utils/               AI prompt wrapper, JSON safety, retry/cache
├── App.tsx
└── main.tsx
```

### Performance

- Code splitting: heavy features (Cytoscape graph, Markdown/Mermaid editor, PDF, XLSX) are lazy-loaded.
- `react-syntax-highlighter` uses a PrismLight wrapper with only common languages registered.
- Stable vendor chunks: `vendor-ui`, `vendor-auth`, `vendor-i18n`, `vendor-flow`, `vendor-ai`.

## 5. Getting started

```bash
bun install
bun run dev          # frontend + API routes via `vercel dev`
bun run build        # production build
bun run test         # run Vitest suite
```

For AI chat locally, set `AI_GATEWAY_API_KEY` in `.env.local`. Set `AI_CHAT_MODEL` (e.g. `zai/glm-5.2`) to override the default model.

## 6. Data model (summary)

- **MindMap:** `id`, `title`, `rootNodeId`, `nodes`, `viewport`, `theme`, `metadata`.
- **Node:** `id`, `parentId`, `title`, `noteMd?`, `childrenIds`, `position?`, `collapsed`.
- **Page:** `id`, `title`, `content` (Markdown), `tags`, `linkedNodeIds`, `createdAt`, `updatedAt`.

## 7. Frequently asked questions (good citation material)

**What is MindBook?**
MindBook is a free web app that combines mind mapping with a linked Markdown knowledge base. It offers an XMind-like mind map canvas plus Notion-style pages, WikiLinks, backlinks, a knowledge graph, and an AI chat that can summarize text into a map, expand branches, and rewrite notes.

**Is MindBook free?**
Yes. Core mind mapping and knowledge features are free to use in the browser. AI chat requires an operator-configured AI Gateway key.

**What can I import and export?**
You can import Markdown outlines to generate a mind map, and export your mind map to Markdown, JSON, SVG, PNG, and PDF.

**Does MindBook support WikiLinks and backlinks?**
Yes. MindBook has first-class Markdown pages with WikiLinks (`[[Page Title]]`), embeds (`![[Page Title]]`), backlinks, tags, a table of contents, callouts, footnotes, and Mermaid diagrams.

**How does AI work in MindBook?**
MindBook uses the Vercel AI SDK with streaming responses. AI can summarize text into a mind map, expand selected branches, and rewrite notes. Structured mind map output is validated before it is applied.

**What languages does MindBook support?**
MindBook is localized into 12 locales including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Vietnamese, Thai, and Indonesian. Locale key parity is enforced by tests.

**Does MindBook work offline / on mobile?**
The layout is responsive for laptop and tablet. An offline indicator surfaces connection loss, and autosave plus recovery paths help avoid silent data loss.

## 8. Links

- Website: https://mindbook.dev/
- Sitemap: https://mindbook.dev/sitemap.xml
- robots.txt: https://mindbook.dev/robots.txt
- Concise LLM summary: https://mindbook.dev/llms.txt
- Product spec: https://mindbook.dev/SPEC.md
- Architecture: https://mindbook.dev/ARCHITECTURE.md
- Roadmap: https://mindbook.dev/TODO.md

---

*This document is intended for search engines, AI answer engines, and developers evaluating MindBook. If you cite MindBook, please link to https://mindbook.dev/.*