# Symph Agency UI

The web dashboard for managing products through the Symph Agency pipeline.

## Overview

- **Location:** `/home/aria/projects/symph-agency/`
- **Domain:** `symphony.symph.co`
- **Port:** 4000
- **Stack:** Next.js 15 + Tailwind CSS + TypeScript

## Features

- Product portfolio dashboard
- Phase-based artifact viewer
- Real-time progress tracking (SSE + file watcher)
- New product creation flows (AI Discover, Space in Mind, Client Ready)
- Discovery pipeline with orchestrated agents

## Architecture

### Real-Time Updates

Instead of polling, we use Server-Sent Events (SSE) with a file watcher:

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  AI / Users     │────▶│  YAML/MD Files   │────▶│  File Watcher   │
│  (write files)  │     │  (source of truth)│     │  (chokidar)     │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Browser        │◀────│  SSE Endpoint    │◀────│  Broadcast      │
│  (real-time UI) │     │  /api/events/*   │     │  to subscribers │
└─────────────────┘     └──────────────────┘     └─────────────────┘
```

**Key files:**
- `src/lib/file-watcher.ts` — Chokidar-based file watcher
- `src/app/api/events/[slug]/route.ts` — SSE endpoint per product
- `src/app/api/events/route.ts` — Global SSE endpoint
- `src/hooks/use-realtime.ts` — React hooks for SSE
- `src/instrumentation.ts` — Starts watcher on server boot

### File Watcher Lifecycle

The file watcher starts automatically when Next.js boots via the instrumentation hook. This ensures it's always running, even after VPS restarts.

## Deployment

### Development

```bash
cd /home/aria/projects/symph-agency
npm run dev
```

### Production (systemd)

Install the systemd service:

```bash
cd /home/aria/projects/symph-agency
chmod +x deploy/install.sh
./deploy/install.sh
```

This will:
1. Build the production app (`npm run build`)
2. Install the systemd service
3. Enable auto-start on boot
4. Start the service

### Service Management

```bash
# Check status
sudo systemctl status symph-agency

# Restart
sudo systemctl restart symph-agency

# Stop
sudo systemctl stop symph-agency

# View logs
sudo journalctl -u symph-agency -f

# App logs
tail -f /home/aria/projects/.aria-logs/symph-agency.log
```

### Caddy Configuration

The domain `symphony.symph.co` should be configured in Caddy:

```
symphony.symph.co {
    reverse_proxy localhost:4000
}
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/auth/check` | POST | Verify user email |
| `/api/products` | GET | List all products |
| `/api/products/create` | POST | Create new product |
| `/api/products/[slug]` | GET | Get product details |
| `/api/products/[slug]/[phase]` | GET | Get phase artifacts |
| `/api/products/[slug]/[phase]/progress` | GET | Get progress notes |
| `/api/products/discover/start` | POST | Start discovery scan |
| `/api/products/discover/status` | GET | Check scan status |
| `/api/discovery/active` | GET | Get active scan info |
| `/api/discovery/opportunities` | GET | Get cached opportunities |
| `/api/events` | GET | SSE: Global file changes |
| `/api/events/[slug]` | GET | SSE: Product file changes |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 4000 | Server port |
| `NODE_ENV` | development | Environment |
| `OPENCLAW_GATEWAY_URL` | http://localhost:3033 | Gateway for wake events |

## File Structure

```
symph-agency/
├── deploy/
│   ├── install.sh          # Deployment script
│   └── symph-agency.service # systemd service
├── src/
│   ├── app/
│   │   ├── (app)/          # Authenticated routes
│   │   │   ├── dashboard/
│   │   │   ├── products/
│   │   │   ├── agents/
│   │   │   └── inbox/
│   │   ├── api/            # API routes
│   │   └── login/          # Public login page
│   ├── components/         # UI components
│   ├── hooks/              # React hooks
│   └── lib/                # Utilities
└── next.config.mjs
```

## Troubleshooting

### File watcher not detecting changes

1. Check if instrumentation is enabled in `next.config.mjs`
2. Verify the watcher started: look for `[FileWatcher] Watching for changes...` in logs
3. Restart the server: `sudo systemctl restart symph-agency`

### SSE not connecting

1. Check browser console for connection errors
2. Verify the endpoint is reachable: `curl http://localhost:4000/api/events`
3. Check for proxy buffering issues (nginx/Caddy should have buffering disabled)

### Progress not updating

1. Ensure progress.md is being written correctly (format: `[timestamp] message`)
2. Check file permissions on the agency directory
3. Verify the product slug matches the SSE subscription
