# flowcraft 🔗

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![GitHub Stars](https://img.shields.io/github/stars/thehypewipe/flowcraft?style=social)](https://github.com/thehypewipe/flowcraft/stargazers)

> **Local-first visual AI workflow builder — chain LLM, API, and human steps in one SQLite file. Self-hosted Dify/n8n in one docker run, offline.**

Zapier caps at 100 steps, 10 branches, $340/mo vs $19. Make breaks on messy PDFs. Dify needs 36 containers. `flowcraft` does 5+ step stateful workflows with memory, http, llm, condition, human approval — in one `flowcraft.db`.

## Quick Start

```bash
pip install flowcraft
```

```bash
# 1. Backend (Python + SQLite, one file, no cloud)
git clone https://github.com/thehypewipe/flowcraft.git
cd flowcraft
pip install -e ".[dev]"
uvicorn flowcraft.main:app --reload  # http://127.0.0.1:8000/docs

# 2. Frontend (TypeScript + React Flow)
cd frontend
npm install
npm run dev  # http://127.0.0.1:5173

# 3. Or one docker run
# docker compose up
```

Works offline, single SQLite file `flowcraft.db`, no API keys required (LLM node is mock by default, swap to OpenAI via env).

## Why

- **One SQLite file** — no Postgres/ClickHouse/Redis like LangSmith/Dify
- **Visual builder** — React Flow canvas, save -> run -> logs, local history
- **Stateful** — handles 5+ chained steps, exceptions, human approval — where Zapier/Make choke
- **Offline & private** — all runs stay on your machine, SQLite + local Ollama optional
- **Star-proven** — n8n 203k, Dify 154k, OpenClaw 388k show huge demand for self-hosted automation, but all heavy. This is the simple one.

## API

```bash
# create workflow
curl -X POST http://127.0.0.1:8000/workflows -H "Content-Type: application/json" -d '{"name":"My flow","definition":{"nodes":[{"id":"1","type":"trigger"},{"id":"2","type":"llm","data":{"prompt":"hi"}}]}}'
# run
curl -X POST http://127.0.0.1:8000/workflows/1/run -H "Content-Type: application/json" -d '{"inputs":{"text":"hello"}}'
# list runs
curl http://127.0.0.1:8000/workflows/1/runs
```

| Method | Path | Description |
|---|---|---|
| POST | `/workflows` | create visual workflow |
| GET | `/workflows` | list |
| GET | `/workflows/{id}` | get |
| POST | `/workflows/{id}/run` | run with inputs -> logs |
| GET | `/workflows/{id}/runs` | run history |

Node types: `trigger`, `llm`, `http`, `condition`, `delay`, `human` (approval gate).

## Tech

- **Backend:** Python 3.8+, FastAPI, SQLAlchemy, SQLite, requests
- **Frontend:** TypeScript 5, React 18, React Flow 11, Vite 5

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Add node type in `backend/flowcraft/engine.py` + UI in `frontend/src/App.tsx` + test.

## License

MIT — see [LICENSE](LICENSE)

---

**If flowcraft saved you Zapier $340/mo, star it ⭐**