Correspondents/README.md

<div align="center">

<a id="readme-top"></a>

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <img src="public/logos/Logo-Transparent.png" alt="Multi-Agent Chat Interface Logo" width="400">

  <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.

### Screenshots

<div align="center">
  <img src="public/ui/desktop.png" alt="Desktop Interface" width="800">
  <p><em>Desktop interface with glass-morphism design</em></p>

  <img src="public/ui/mobile.png" alt="Mobile Interface" width="400">
  <p><em>Mobile-optimized responsive layout</em></p>

  <img src="public/ui/chat.png" alt="Chat View" width="800">
  <p><em>Chat interface with markdown rendering and syntax highlighting</em></p>
</div>

### 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
- **Polished UI:** Message formatting with proper wrapping, smooth animations, and refined scrollbars
- **Custom agents:** Create and pin custom agents via Morgan (Agent Architect)

<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. **Run the standard Next.js build**
   ```bash
   pnpm build
   ```
   This catches type errors before packaging for Workers.

2. **Fix lint errors**
   ```bash
   pnpm lint
   ```
   Resolve every reported error (warnings are OK) so the Cloudflare build doesn't fail mid-deploy.

3. **Build for Cloudflare**
   ```bash
   npx @opennextjs/cloudflare build
   ```

   **Important:** Always run this before deploying. Standard `next build` alone is insufficient.

4. **Deploy**
   ```bash
   npx wrangler deploy
   ```

   **Note:** The deployment uses the default configuration from `wrangler.jsonc` with route `agents.nicholai.work`. Do not use `--env` flags.

5. **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>