# Getting Started with AITuberFlow

This guide will help you set up and run AITuberFlow.

## Easiest Way: Desktop App

Download the installer from [GitHub Releases](https://github.com/oboroge0/AITuberFlow/releases/latest) and run it.

- **macOS**: DMG file (Apple Silicon / Intel)
- **Windows**: NSIS installer (x64)

The server starts automatically and the editor opens in the app window. No setup required!

---

## Alternative: GitHub Codespaces

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/oboroge0/AITuberFlow)

GitHub Codespaces lets you set up a development environment in your browser with one click.

1. Click the badge above
2. Wait for Codespace to start (1-2 minutes)
3. Run `npm run dev` in the terminal
4. Open ports 3000 and 8001

No local setup required!

---

## Local Setup

### Prerequisites

Before you begin, make sure you have the following installed:

- **Node.js** 22 or higher
- **[Bun](https://bun.sh/)** 1.0 or higher (for TypeScript backend)
- **npm** (comes with Node.js)


## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/oboroge0/AITuberFlow.git
cd AITuberFlow
```

### 2. Set Up the Backend

```bash
# Navigate to server directory
cd apps/server-ts

# Install dependencies
bun install
```

### 3. Set Up the Frontend

```bash
# Navigate to web directory (from project root)
cd apps/web

# Install npm dependencies
npm install

# Create environment file
cp .env.example .env.local
```

### Install Everything at Once

```bash
# From project root, install all sub-project dependencies
npm run setup
```

## Running the Application

You can run AITuberFlow either using Docker (recommended for quick setup) or manually with local development tools.

### Option A: Using Docker (Recommended)

Docker provides the easiest way to get started without installing runtimes locally.

#### Prerequisites for Docker

- **Docker** 20.10 or higher
- **Docker Compose** v2.0 or higher

#### Quick Start with Docker

```bash
# From project root
docker compose up --build
```

This will:
- Build both backend and frontend images
- Start the backend at `http://localhost:8001`
- Start the frontend at `http://localhost:3000`
- Create a persistent volume for the SQLite database

#### Docker Environment Variables

Create a `.env` file in the project root to customize settings:

```bash
# Backend settings
BACKEND_PORT=8001
CORS_ORIGINS=http://localhost:3000

# Frontend settings
FRONTEND_PORT=3000
NEXT_PUBLIC_API_URL=http://localhost:8001
```

#### Production Deployment

For production environments:

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

#### Useful Docker Commands

```bash
# View logs
docker compose logs -f

# Stop services
docker compose down

# Rebuild after code changes
docker compose up --build

# Remove all data (including database)
docker compose down -v
```

### Option B: Manual Setup

If you prefer to run the application without Docker:

#### Start All Services

```bash
# From project root
npm run dev
```

This starts both the backend and frontend simultaneously.

To start services individually:

```bash
# Backend only (from apps/server-ts)
bun run dev
```

The backend starts at `http://localhost:8001`.

#### Start the Frontend Development Server

```bash
# From apps/web (in a new terminal)
npm run dev
```

The frontend will start at `http://localhost:3000`.

## Creating Your First Workflow

1. **Open the Application**
   - Navigate to `http://localhost:3000` in your browser
   - Click "New Workflow" to create a new workflow

2. **Add Nodes**
   - Drag nodes from the left sidebar onto the canvas
   - Available nodes:
     - **Manual Input**: Enter text to send downstream
     - **OpenAI LLM**: Generate AI responses
     - **Console Output**: Display text in the log panel

3. **Connect Nodes**
   - Click and drag from an output port (right side of a node)
   - Drop on an input port (left side of another node)
   - The connection will show as an animated line

4. **Configure Nodes**
   - Click on a node to select it
   - Use the Settings panel on the right to configure the node
   - For OpenAI LLM, you'll need to enter your API key

5. **Save Your Workflow**
   - Click the "Save" button in the toolbar
   - Your workflow will be persisted to the database

6. **Run the Workflow**
   - Click the "Start" button to execute the workflow
   - Watch the log panel at the bottom for execution progress
   - Click "Stop" to halt execution

## Example: Simple Chat Workflow

Create a basic workflow that takes input and generates an AI response:

1. Add a **Manual Input** node
   - Set "Input Text" to "Hello! What's 2 + 2?"

2. Add an **OpenAI LLM** node
   - Enter your OpenAI API key
   - Set System Prompt to "You are a helpful math tutor."
   - Choose a model (GPT-4o Mini is recommended for testing)

3. Add a **Console Output** node
   - Keep default settings

4. Connect the nodes:
   - Manual Input (text) → OpenAI LLM (prompt)
   - OpenAI LLM (response) → Console Output (text)

5. Save and run the workflow!

## Demo Mode

You can test workflows without external services using Demo Mode:

### LLM Nodes (Automatic)
- When no API key is configured, LLM nodes automatically return demo responses
- Useful for testing workflow logic without API costs

### TTS Nodes (Manual)
- Enable "Demo Mode" in TTS node settings
- When TTS service is unavailable, the node is skipped
- Workflow continues without errors

## Workflow Sharing (Import/Export)

Share workflows with others using the sidebar buttons:

### Export
- Click "Export" to download the workflow as JSON
- API keys are automatically excluded for security
- Safe to share publicly

### Import
- Click "Import" and select a workflow JSON file
- Creates a new workflow (doesn't overwrite existing)
- Opens the imported workflow automatically

## Troubleshooting

### Docker issues

**Container fails to start:**
- Check if ports 8001 or 3000 are already in use: `lsof -i :8001` or `lsof -i :3000`
- View container logs: `docker compose logs backend` or `docker compose logs frontend`
- Try rebuilding: `docker compose build --no-cache`

**Frontend can't connect to backend:**
- Ensure both containers are on the same network: `docker network ls`
- Check if backend is healthy: `docker compose ps`
- Verify CORS settings in `.env`

**Database persistence:**
- Data is stored in a Docker volume named `aituberflow-backend-data`
- To reset: `docker compose down -v` (this deletes all data)

### Backend won't start

- Verify Bun is installed: `bun --version` (should be 1.0+)
- Install dependencies: `cd apps/server-ts && bun install`
- Check if port 8001 is already in use: `lsof -i :8001`

### Frontend won't start

- Make sure all npm packages are installed: `npm install`
- Check Node.js version: `node --version` (should be 22+)
- Try deleting `node_modules` and reinstalling

### Can't connect to backend

- Make sure the backend is running on port 8001
- Check `apps/web/.env.local` has the correct API URL
- Look for CORS errors in the browser console

### OpenAI errors

- Verify your API key is correct
- Check that you have API credits available
- Try a different model if rate limited

## Building the Desktop App (Development)

If you want to build the desktop app from source:

### Prerequisites

- **Node.js** 22+, **Bun** 1.0+, **Rust** (stable)
- **Platform-specific**: Xcode CLI tools (macOS) or Visual Studio Build Tools (Windows)

### Build Steps

```bash
# 1. Build frontend static export
cd apps/web && npm ci && cross-env BUILD_MODE=desktop npx next build

# 2. Build server sidecar
cd apps/server-ts && bun install
bun build --compile src/index.ts --outfile=../desktop/src-tauri/binaries/server

# 3. Copy resources (plugins, templates, static frontend)
node apps/desktop/scripts/copy-resources.js

# 4. Build Tauri app
cd apps/desktop && npm install && npx tauri build
```

The resulting installer will be in `apps/desktop/src-tauri/target/release/bundle/`.

## Next Steps

- Read the [Architecture Overview](./architecture.md) to understand how AITuberFlow works
- Explore the [API Reference](./api-reference.md) for REST and WebSocket documentation
- Check out the [CLAUDE.md](../CLAUDE.md) for development guidelines
