About WAFlow

WAFlow is a minimal local sandbox designed for building and testing webhook-based chatbots. It allows developers to set up a complete local environment with a single command, enabling them to chat in a browser UI, see webhooks hit instantly, and utilize conversation replay for rapid regression testing. This tool is ideal for testing chatbots locally without the need for external services or internet connectivity.

• Instant Setup: Launch a running sandbox with a single 'docker compose up' command.

• Conversation Replay: Export and import conversations as JSON files for efficient regression testing.

• Local & Offline Development: Test your bot entirely on your machine, ensuring privacy and reliability.

• Simple & Focused Interface: A clean UI, a simulator API, and your webhook are all you need.

Architecture Overview

The WAFlow architecture includes:

• WAFlow.Simulator: A minimal API (.NET) for injecting user messages, dispatching webhooks, and storing conversation feeds.

• WAFlow.Chat: A Blazor UI for chatting, exporting/importing conversations, resetting the state, and displaying an online status banner.

• LlmBot.Example: An example bot that uses the Gemini API to respond to webhooks.

• docker-compose.yml: Orchestrates the services for easy deployment.

The system utilizes specific ports for local development: UI on 5056, Simulator on 5080, and LlmBot on 5199. Within Docker, services communicate via service DNS on port 8080 (e.g., http://sim:8080).

Requirements

To run WAFlow, you will need:

• Docker Desktop.

• Optionally, the .NET 8 SDK if you prefer to run without Docker.

• Optionally, a Gemini API key if you intend to use the example LlmBot.

Quickstart Guide

Follow these steps to get started:

1. Clone the repository: git clone <your-repo>.git waflow

2. Navigate to the directory: cd waflow

3. Create a .env file with your Gemini API key: echo "GOOGLE_API_KEY=your_gemini_key" > .env

4. Build and run the Docker containers: docker compose up -d --build

Access the UI at http://localhost:5056/. You can monitor service logs using docker compose logs -f sim and docker compose logs -f llmbot.

Webhook Integration

WAFlow supports two methods for webhook integration:

1. Auto-register (Docker): The llmbot automatically registers its webhook upon startup by configuring environment variables in docker-compose.yml.

2. Manual register: Use a cURL command to manually register your webhook URL with the simulator.

You can check the stored webhooks by sending a GET request to http://localhost:5080/webhook or delete them with a DELETE request.

Limitations (MVP)

• The UI currently supports a single user.

• Only text messages are processed; support for images, buttons, and lists is planned.

• A single global webhook is available without authentication.

Roadmap

Future enhancements include:

1. User selector with per-user feeds.

2. Support for richer message types and basic UI rendering.

3. A CLI runner for transcript execution and comparison.

4. Per-user webhooks with HMAC signing and retry mechanisms.

5. An integrated logs panel in the UI.

6. Addition of integration tests and data fixtures.