# ThinkFlow AI

English | [中文](./README.zh-CN.md)

ThinkFlow AI is a lightweight, local-first idea-to-structure workspace. You type a core idea, and the app expands it into a navigable knowledge graph (modules/submodules). Each node supports follow-up expansion, deep-dive details, and optional image generation.

This repository currently uses the package name `housegpt` (historical) while the product name is **ThinkFlow AI**.

## Highlights

- **Idea expansion to graph**: generate a root node and expand into structured child nodes.
- **Context-aware follow-up**: expand a selected node with an additional requirement (follow-up input).
- **Deep dive**: generate detailed explanations for a node and show them inline.
- **Image generation (per node)**: generate/regenerate a visual for a node and preview it fullscreen.
- **Export to Markdown**: export the current graph as a Markdown outline (including deep-dive content).
- **Local-first settings**: API mode and endpoints are stored in `localStorage` (no backend needed).
- **Bilingual UI**: built-in English/Chinese UI with a one-click toggle.

## Tech Stack

- **Vue 3** (Composition API)
- **Vite 5**
- **TypeScript**
- **Tailwind CSS**
- **VueFlow** (`@vue-flow/core`, `background`, `controls`, `minimap`)
- **vue-i18n**
- **lucide-vue-next** (icons)

## Project Structure

Key files you will touch most often:

- `src/App.vue`: app shell, composes the layout and wires UI to business actions.
- `src/composables/useThinkFlow.ts`: core business logic (graph operations, API calls, persistence).
- `src/components/TopNav.vue`: top toolbar (layout, export, summary, settings, language toggle).
- `src/components/BottomBar.vue`: bottom input bar (core idea input + execute).
- `src/components/WindowNode.vue`: custom VueFlow node UI (expand/deep-dive/image/follow-up).
- `src/components/SettingsModal.vue`: API mode and custom endpoints configuration UI.
- `src/i18n/index.ts`: i18n bootstrap (default English; persists language in `localStorage`).

## How It Works (High-Level)

ThinkFlow AI is built around a single composable:

- `useThinkFlow` owns all reactive state for nodes/edges and UI flags.
- UI components are “thin”: they render and forward events (expand, deep-dive, image, export).
- The graph is rendered with VueFlow using a custom node type (`window`).
- Settings are stored in `localStorage`:
  - language (`language`)
  - API mode + chat/image endpoints/models/keys

## Getting Started

### Prerequisites

- Node.js **18+** (required by Vite 5)
- npm (or pnpm/yarn; examples use npm)

### Install

```bash
npm install
```

### Run Dev Server

```bash
npm run dev
```

Then open the URL printed by Vite (usually `http://localhost:5173`).

### Build

```bash
npm run build
```

### Preview Production Build

```bash
npm run preview
```

## Configuration

### Custom Mode (Bring Your Own Endpoint)

Open **Settings** in the UI:

- Switch to **Custom**
- Configure **Text Generation** (chat completion)
  - `baseUrl` (POST endpoint)
  - `model`
  - `apiKey`
- Configure **Image Generation**
  - `baseUrl` (POST endpoint)
  - `model`
  - `apiKey`

These fields are saved into `localStorage` automatically.

## Features Guide

### 1) Expand From a Core Idea

1. Type a core idea in the bottom input.
2. Press Enter or click **Execute**.
3. A root node appears and the app generates child nodes.

### 2) Expand a Specific Node (Follow-Up)

1. Click into a node’s follow-up input.
2. Type an additional requirement.
3. Press Enter to expand using the context path (root → current node).

### 3) Deep Dive a Node

Click **Deep Dive** on a node to generate a detailed explanation. The content will be stored on the node and can be reopened without re-requesting (unless you expand further).

### 4) Generate/Preview Node Image

- Click **IMG** to generate an image for a node.
- Click the image to open fullscreen preview.
- Use the regenerate action to request a new image.

### 5) Export Markdown

Use **Export** in the top toolbar:

- Root becomes the Markdown title
- Child nodes become an indented list
- Deep-dive text is exported as blockquote content under the node

## Third-Party Integrations

- **Microsoft Clarity**: included in `index.html` for analytics.
- **VueFlow plugins**:
  - Background (Dots/Lines)
  - Controls (zoom/fit)
  - MiniMap (overview)

## Internationalization (i18n)

- Default locale: **English**
- Supported: `en`, `zh`
- Language choice is stored in `localStorage` key `language`

To add a new language:

1. Add a JSON file in `src/i18n/locales/`
2. Register it in `src/i18n/index.ts`
3. Add a toggle option in the UI (currently a simple EN/ZH switch)

## Common Troubleshooting

- **CORS / Failed to fetch**: if you use a custom endpoint, ensure it allows browser requests and supports proper CORS headers.
- **401/403**: verify the API key and `Authorization: Bearer ...` format.
- **429**: rate limited by the provider; retry later.

## Scripts

- `npm run dev`: start Vite dev server
- `npm run build`: production build
- `npm run preview`: preview the build output locally