⚡ Sienna Builder

Visual platform to build and deploy AI-powered chatbots that connect to your APIs — no custom backend required.

---

Configure chatbot projects from a web UI, connect any OpenAI-compatible model (GPT-4, Claude, Mistral, Ollama…), and define how your chatbot interacts with external REST APIs — all without writing a single line of backend code.

Two operational modes adapt to your use case:

• Flows — define structured intents, collect parameters, call an API, render a templated response
• Agent — expose your endpoints as tools and let the AI reason, chain actions, and respond autonomously

---

✨ Features

• 🤖 Dual AI modes — predictable Flows or autonomous Agent with native tool calling
• 🔌 Any OpenAI-compatible provider — GPT-4, Claude, Mistral, Llama via Ollama, and more
• 📋 Visual Flow Builder — step-by-step wizard: intent → parameters → API call → Mustache template
• 🔧 Endpoint Manager — define external REST APIs with typed, labeled parameters
• 💬 Built-in Chat Simulator — real-time chat UI with a debug panel (matched flow, extracted params, raw API response)
• 🎨 Mustache templating — build dynamic responses from API result data
• 📊 Analytics & Logs — track conversations, sessions, and error rates per project
• 🔑 Per-project AI config — isolated API keys, models, and temperature per chatbot
• 🛡️ Production-ready backend — Helmet, rate limiting, CORS, Zod validation, structured Pino logging

---

🛠️ Tech Stack

Layer	Technology
Backend	Express 4 · TypeScript 5.7 · Node.js 18+
Database	MongoDB 8 · Mongoose 8
Frontend	React 19 · Vite 6 · Tailwind CSS 3.4
State	Zustand 5 · TanStack Query 5
Forms	React Hook Form 7 · Zod 3
AI	OpenAI SDK 4 (any compatible provider)
Templating	Mustache 4
Logging	Pino 9

---

📋 Requirements

Requirement	Version
Node.js	18 or higher
pnpm	8 or higher
MongoDB	6+ locally or a MongoDB Atlas URI
AI Provider	API key for any OpenAI-compatible service

Install pnpm if you don't have it:

npm install -g pnpm

---

🚀 Installation

1. Clone the repository

git clone https://github.com/Jsequeirag/sienna-builder.git
cd sienna-builder

2. Set up the backend

cd be
pnpm install
cp .env.example .env

Edit be/.env:

PORT=3001
MONGODB_URI=mongodb://localhost:27017/sienna-builder
LOG_LEVEL=info
CORS_ORIGIN=http://localhost:5173
NODE_ENV=development

Your AI provider API key is configured per-project from the UI — not in .env.

3. Set up the frontend

cd ../fe
pnpm install

---

▶️ Running the App

Open two terminals from the project root:

# Terminal 1 — Backend
cd be && pnpm dev      # → http://localhost:3001

# Terminal 2 — Frontend
cd fe && pnpm dev      # → http://localhost:5173

Then open http://localhost:5173.

---

💡 Basic Usage

1 — Create a project

In the UI, create a project and enter your AI provider credentials (API key + model name + temperature).

2 — Add an endpoint

POST /api/projects/:id/endpoints
{
  "name": "search product",
  "url": "https://api.example.com/products",
  "method": "GET",
  "fields": [
    { "name": "query", "label": "Product name", "type": "string", "required": true },
    { "name": "size",  "label": "Size",         "type": "number", "required": false }
  ]
}

3 — Send a message

POST /api/chat/:projectId/message
{
  "session_id": "user-001",
  "message": "Find Nike sneakers size 42"
}

The AI detects the intent, calls the configured endpoint, and returns a natural language response.

---

⚔️ Flows vs Agent — When to Use Each

	Flows	Agent
Setup required	Flows + parameter mapping	Endpoints only
Response style	Templated, predictable	Natural language
Multi-step actions	One flow per message	Multiple tools per message
Control level	Full — you define the path	Delegated to the AI
Best for	Simple, guided conversations	Complex, open-ended queries

---

📂 Project Structure

sienna-builder/
├── be/                        # Express + TypeScript backend
│   └── src/
│       ├── models/            # Mongoose schemas (Project, Flow, Conversation, Message)
│       ├── modules/           # Routes → Controllers → Services per feature
│       │   ├── chat/          # Main chat endpoint
│       │   ├── projects/      # Project CRUD
│       │   └── flows/         # Flow CRUD + test
│       └── services/
│           └── aiService.ts   # Core AI logic: flows + tool calling
└── fe/                        # React 19 + Vite frontend
    └── src/
        ├── pages/             # Dashboard · Flows · Simulator · Logs · ConfigAI
        ├── store/             # Zustand stores (project, simulator, toast)
        └── api/               # Axios config + React Query custom hooks

---

🤝 Contributing

Contributions are welcome. To keep the commit history clean and the activity graph consistent, follow these guidelines:

• Commit format: Conventional Commits (feat:, fix:, chore:, docs:, refactor:)
• Language: English only, imperative mood (add, fix, update — not added, fixed)
• Frequency: at least one meaningful commit per feature or bug fix — avoid squashing all work into a single commit at the end of a session
• Scope: keep commits atomic — one logical change per commit

feat(flows): add priority reordering via drag and drop
fix(chat): handle empty session_id in agent mode
docs: update installation steps for Windows

---

📄 License

MIT © 2026 José Luis Sequeira G

MIT was chosen because it maximizes adoption: it is the most permissive widely-recognized license, allows unrestricted commercial use and self-hosting, and imposes no obligations beyond attribution. For a developer tool intended to be forked and extended, MIT lowers the barrier to entry more than any alternative (Apache 2.0 adds patent clauses; GPL forces derivative works to remain open source).