254 lines
7.1 KiB
Markdown
254 lines
7.1 KiB
Markdown
<div align="center">
|
|
|
|
<a id="readme-top"></a>
|
|
|
|
<!-- PROJECT LOGO -->
|
|
<br />
|
|
<div align="center">
|
|
<h1 align="center" style="font-size: 48px;">Multi-Agent Chat Interface</h1>
|
|
|
|
<p align="center" style="font-size: 18px; max-width: 680px;">
|
|
Beautiful, glass-morphism chat interface for interacting with multiple AI agents through n8n webhooks.<br />
|
|
<strong>Cloudflare Workers • Real-time streaming • Mobile-first design</strong>
|
|
<br />
|
|
<br />
|
|
<a href="#getting-started"><strong>Quick Start »</strong></a>
|
|
</p>
|
|
</div>
|
|
|
|
---
|
|
|
|
<!-- TABLE OF CONTENTS -->
|
|
<details open>
|
|
<summary><h2>Table of Contents</h2></summary>
|
|
<ol>
|
|
<li><a href="#about">About</a></li>
|
|
<li><a href="#tech-stack">Tech Stack</a></li>
|
|
<li><a href="#architecture">Architecture</a></li>
|
|
<li><a href="#feature-flags">Feature Flags</a></li>
|
|
<li><a href="#getting-started">Getting Started</a>
|
|
<ul>
|
|
<li><a href="#prerequisites">Prerequisites</a></li>
|
|
<li><a href="#installation">Installation</a></li>
|
|
<li><a href="#environment-variables">Environment Variables</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#development">Development</a>
|
|
<ul>
|
|
<li><a href="#common-commands">Common Commands</a></li>
|
|
<li><a href="#deployment">Deployment</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#testing">Testing</a></li>
|
|
<li><a href="#contact">Contact</a></li>
|
|
</ol>
|
|
</details>
|
|
|
|
---
|
|
|
|
</div>
|
|
|
|
## About
|
|
|
|
Multi-agent chat interface that enables users to select from configured AI agents and interact with them through n8n workflow webhooks. Built with Next.js 15 and deployed to Cloudflare Workers for global edge performance.
|
|
|
|
### Key Features
|
|
|
|
- **Multi-agent support:** Dynamically configured agents via environment variables
|
|
- **Real-time streaming:** Handles chunked responses from n8n workflows
|
|
- **Image attachments:** Base64 image upload support with feature flag control
|
|
- **Diff visualization:** Custom markdown renderer for side-by-side code diffs
|
|
- **Session persistence:** Agent-specific conversation history in localStorage
|
|
- **Mobile-optimized:** Glass-morphism design with mobile-first responsiveness
|
|
- **Feature flags:** Runtime-configurable features for controlled rollouts
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: Next.js 15.5.4 (App Router) + TypeScript
|
|
- **Runtime**: Cloudflare Workers
|
|
- **Adapter**: @opennextjs/cloudflare 1.12.0
|
|
- **Styling**: Tailwind CSS 4.1.9 with custom glass-morphism design
|
|
- **UI Components**: Radix UI primitives
|
|
- **Animations**: Framer Motion 12
|
|
- **Markdown**: react-markdown with rehype-highlight for syntax highlighting
|
|
- **Testing**: Vitest 4 + Testing Library
|
|
- **Package Manager**: pnpm
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[User Browser] -->|Chat Request| B[Next.js App Router]
|
|
B -->|API /agents| C[Environment Config]
|
|
B -->|API /chat| D[n8n Webhook]
|
|
D -->|Streaming Response| B
|
|
B -->|Rendered UI| A
|
|
C -->|Agent Config| B
|
|
B -->|Static Assets| E[Cloudflare CDN]
|
|
|
|
style B fill:#667eea
|
|
style D fill:#764ba2
|
|
style E fill:#ffd700
|
|
```
|
|
|
|
### Key Components
|
|
|
|
- **Agent Discovery**: `/api/agents` dynamically discovers agents from environment variables (`AGENT_N_URL`, `AGENT_N_NAME`, `AGENT_N_DESCRIPTION`)
|
|
- **Message Proxy**: `/api/chat` forwards user messages to the selected agent's n8n webhook with session tracking
|
|
- **Feature Flags**: Runtime-configurable flags control image uploads and diff tool rendering
|
|
- **Client State**: Agent selection and conversation history persisted in browser localStorage
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Feature Flags
|
|
|
|
The application supports runtime feature flags configured via environment variables:
|
|
|
|
| Flag | Default | Description |
|
|
| --- | --- | --- |
|
|
| `IMAGE_UPLOADS_ENABLED` | `true` | Enable/disable image attachment functionality |
|
|
| `DIFF_TOOL_ENABLED` | `true` | Enable/disable advanced diff visualization |
|
|
|
|
Configure flags in `wrangler.jsonc` for production or `.env.local` for development.
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- **Node.js** 20 or higher
|
|
- **pnpm** package manager
|
|
- **Cloudflare account** with Wrangler CLI configured
|
|
- **n8n instance** with webhook URLs for your agents
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone <your-repo-url>
|
|
cd multi-agent_chat_interface
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
3. **Configure environment variables**
|
|
|
|
Create `.env.local` for local development:
|
|
```env
|
|
AGENT_1_URL=https://n8n.example.com/webhook/your-webhook-id
|
|
AGENT_1_NAME=Your Agent Name
|
|
AGENT_1_DESCRIPTION=Description of your agent
|
|
|
|
IMAGE_UPLOADS_ENABLED=true
|
|
DIFF_TOOL_ENABLED=true
|
|
```
|
|
|
|
For production, update `wrangler.jsonc` with your agent configurations.
|
|
|
|
4. **Run the development server**
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
|
|
|
### Environment Variables
|
|
|
|
Configure agents using numbered environment variables:
|
|
|
|
- `AGENT_N_URL` - n8n webhook URL for agent N
|
|
- `AGENT_N_NAME` - Display name for agent N
|
|
- `AGENT_N_DESCRIPTION` - Optional description for agent N
|
|
|
|
Where N = 1, 2, 3, etc. The application will discover all configured agents automatically.
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Development
|
|
|
|
### Common Commands
|
|
|
|
| Command | Description |
|
|
| --- | --- |
|
|
| `pnpm dev` | Start Next.js development server at localhost:3000 |
|
|
| `pnpm build` | Build Next.js application |
|
|
| `pnpm lint` | Run ESLint checks |
|
|
| `pnpm test` | Run Vitest test suites |
|
|
| `pnpm test:ui` | Run tests with Vitest UI |
|
|
| `pnpm test:coverage` | Generate test coverage report |
|
|
|
|
### Deployment
|
|
|
|
Deploy to Cloudflare Workers:
|
|
|
|
1. **Build for Cloudflare**
|
|
```bash
|
|
npx @opennextjs/cloudflare build
|
|
```
|
|
|
|
**Important:** Always run this before deploying. Standard `next build` alone is insufficient.
|
|
|
|
2. **Deploy**
|
|
```bash
|
|
npx wrangler deploy
|
|
```
|
|
|
|
Or for specific environment:
|
|
```bash
|
|
npx wrangler deploy --env production
|
|
```
|
|
|
|
3. **View logs**
|
|
```bash
|
|
npx wrangler tail
|
|
```
|
|
|
|
See [BUILD.md](BUILD.md) for detailed deployment instructions.
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Testing
|
|
|
|
Tests are organized by domain in `__tests__/`:
|
|
|
|
- **`lib/`** - Library and utility tests (flags, types, helpers)
|
|
- **`api/`** - API route tests (agents, chat endpoints)
|
|
- **`components/`** - React component tests
|
|
- **`flags/`** - Feature flag behavior tests
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
pnpm test
|
|
|
|
# Run with UI
|
|
pnpm test:ui
|
|
|
|
# Generate coverage report
|
|
pnpm test:coverage
|
|
```
|
|
|
|
### Test Patterns
|
|
|
|
- Feature flag tests verify behavior when flags are enabled/disabled
|
|
- API tests mock external webhook calls
|
|
- Component tests use Testing Library for React rendering
|
|
- All tests clean up environment and state between runs
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|
|
|
|
## Contact
|
|
|
|
Nicholai — [@biohazardvfx](https://linkedin.com/in/biohazardvfx) — nicholai@biohazardvfx.com
|
|
|
|
<p align="right"><a href="#readme-top">back to top ↑</a></p>
|