link-stack/apps/leafcutter/README.md

# Leafcutter

Data visualization and analytics platform for the CDR Link ecosystem.

## Overview

Leafcutter provides powerful data visualization capabilities with multiple chart types, trend analysis, and OpenSearch integration. It enables users to create, save, and share custom visualizations of their data with support for multiple languages.

## Features

- **Multiple Visualization Types**:
  - Vertical/Horizontal Bar Charts (including stacked)
  - Line Charts (including stacked)
  - Pie/Donut Charts
  - Data Tables
  - Metrics Display
  - Tag Clouds

- **Data Management**:
  - Create and save custom searches
  - User-specific visualizations
  - Trend analysis and insights
  - OpenSearch integration for data queries

- **User Experience**:
  - Internationalization (English, French)
  - Responsive design
  - Export capabilities
  - Preview mode for sharing

## Development

### Prerequisites

- Node.js >= 20
- npm >= 10
- OpenSearch instance
- PostgreSQL database (for user data)

### Setup

```bash
# Install dependencies
npm install

# Run development server (port 3001)
npm run dev

# Build for production
npm run build

# Start production server
npm run start
```

### Environment Variables

Required environment variables:

- `OPENSEARCH_URL` - OpenSearch endpoint
- `OPENSEARCH_USERNAME` - OpenSearch username
- `OPENSEARCH_PASSWORD` - OpenSearch password
- `DATABASE_URL` - PostgreSQL connection
- `NEXTAUTH_URL` - Application URL
- `NEXTAUTH_SECRET` - NextAuth.js secret
- `GOOGLE_CLIENT_ID` - Google OAuth client ID
- `GOOGLE_CLIENT_SECRET` - Google OAuth client secret

### Available Scripts

- `npm run dev` - Development server on port 3001
- `npm run build` - Build for production
- `npm run start` - Start production server
- `npm run lint` - Run ESLint
- `npm run export` - Export static site
- `npm run aws:*` - AWS deployment utilities
- `npm run kubectl:*` - Kubernetes utilities

## Architecture

### Page Structure

- `/` - Home dashboard
- `/create` - Create new visualizations
- `/visualizations/[id]` - View/edit visualizations
- `/preview/[id]` - Public preview mode
- `/trends` - Trend analysis
- `/about` - About page
- `/faq` - Frequently asked questions
- `/setup` - Initial setup wizard

### API Routes

- `/api/searches/*` - Search management
- `/api/visualizations/*` - Visualization CRUD
- `/api/trends/*` - Trend data
- `/api/upload` - File upload handling
- `/api/link/auth` - Link authentication

### Visualization Configuration

Each visualization type has a JSON configuration in `_config/visualizations/`:
- Chart options
- Data mapping
- Styling preferences
- Aggregation settings

### Data Flow

1. User creates search query
2. Query sent to OpenSearch
3. Results processed and aggregated
4. Data rendered in chosen visualization
5. Visualization saved to PostgreSQL

## Internationalization

Supported languages:
- English (`_locales/en.json`)
- French (`_locales/fr.json`)

Language selection available in the UI with automatic persistence.

## OpenSearch Integration

### Query Structure

Leafcutter translates user inputs into OpenSearch queries:
- Full-text search
- Field filtering
- Date ranges
- Aggregations

### Index Management

Works with OpenSearch indices for:
- Document storage
- Real-time analytics
- Historical data

## Visualization Types

### Bar Charts
- Vertical and horizontal orientations
- Stacked variants for multi-series data
- Customizable colors and labels

### Line Charts
- Time series visualization
- Multiple series support
- Trend analysis

### Pie/Donut Charts
- Proportional data display
- Interactive legends
- Percentage calculations

### Data Tables
- Sortable columns
- Pagination
- Export functionality

### Metrics
- Single value display
- Comparison indicators
- Real-time updates

### Tag Clouds
- Word frequency visualization
- Interactive filtering
- Size-based importance

## Security

- Authentication via NextAuth.js
- User-scoped data access
- Secure OpenSearch queries
- Input validation

## Docker Support

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

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

## Deployment

Includes utilities for:
- AWS deployment (S3, CloudFront)
- Kubernetes deployment
- Static site export