link-stack/apps/leafcutter

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

# 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

# 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