link-stack/apps/link/README.md

# CDR Link

The main CDR (Center for Digital Resilience) Link application - a streamlined helpdesk interface built on top of Zammad with integrated communication channels and data visualization.

## Overview

CDR Link provides a unified dashboard for managing support tickets, communication channels, and data analytics. It integrates multiple services including Zammad (ticketing), Bridge (multi-channel messaging), Leafcutter (data visualization), and OpenSearch.

## Features

- **Simplified Helpdesk Interface**: Streamlined UI for Zammad ticket management
- **Multi-Channel Communication**: Integration with Signal, WhatsApp, Facebook, and Voice channels
- **Data Visualization**: Embedded Leafcutter analytics and reporting
- **User Management**: Role-based access control with Google OAuth
- **Search**: Integrated OpenSearch for advanced queries
- **Label Studio Integration**: For data annotation workflows

## Development

### Prerequisites

- Node.js >= 20
- npm >= 10
- Running instances of Zammad, PostgreSQL, and Redis
- Configured authentication providers

### Setup

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm run start
```

### Environment Variables

Key environment variables required:

- `ZAMMAD_URL` - Zammad instance URL
- `ZAMMAD_API_TOKEN` - Zammad API authentication token
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis connection URL
- `NEXTAUTH_URL` - Application URL for authentication
- `NEXTAUTH_SECRET` - Secret for NextAuth.js
- `GOOGLE_CLIENT_ID` - Google OAuth client ID
- `GOOGLE_CLIENT_SECRET` - Google OAuth client secret

### Available Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run start` - Start production server
- `npm run lint` - Run ESLint
- `npm run export` - Export static site

## Architecture

### Pages Structure

- `/` - Main dashboard
- `/overview/[overview]` - Ticket overview pages
- `/tickets/[id]` - Individual ticket view/edit
- `/admin/bridge` - Bridge configuration management
- `/leafcutter` - Data visualization dashboard
- `/opensearch` - Search dashboard
- `/zammad` - Direct Zammad access
- `/profile` - User profile management

### API Routes

- `/api/auth` - NextAuth.js authentication
- `/api/v2/users` - User management API
- `/api/[service]/bots` - Bot management for communication channels
- `/api/[service]/webhooks` - Webhook endpoints

### Key Components

- `ZammadWrapper` - Embeds Zammad UI with authentication
- `SearchBox` - Global search functionality
- `TicketList` / `TicketDetail` - Ticket management components
- `Sidebar` - Navigation and service switching

## Docker Support

Build and run with Docker:

```bash
# Build image
docker build -t link-stack/link .

# Run with docker-compose
docker-compose -f docker/compose/link.yml up
```

## Integration Points

- **Zammad**: GraphQL queries for ticket data
- **Bridge Services**: REST APIs for channel management
- **Leafcutter**: Embedded iframe integration
- **OpenSearch**: Direct dashboard embedding
- **Redis**: Session and cache storage