sr2/link-stack
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
link-stack/apps/leafcutter
History
Exact
Darren Clarke 7745071e63 fix: Update Dockerfiles to copy entire app directory for package dependencies 
Changed Dockerfiles for bridge-frontend, link, and leafcutter to copy
the entire installer directory instead of selective copying. This ensures
all workspace packages (including @link-stack/logger) are available at
runtime, fixing the 'Cannot find package' error in Docker containers.
2025-08-20 12:58:03 +02:00
..
app feat: Add centralized logging system with @link-stack/logger package 2025-08-20 11:37:39 +02:00
images Add updated Leafcutter app 2023-03-31 08:34:35 +02:00
pages/api/proxy feat: Add centralized logging system with @link-stack/logger package 2025-08-20 11:37:39 +02:00
public Update deps, add robots.txt 2025-01-26 12:24:57 +01:00
.dockerignore Docker Compose refactoring 2023-06-21 12:48:07 +00:00
.gitignore Docker Compose refactoring 2023-06-21 12:48:07 +00:00
docker-entrypoint.sh Link and Leafcutter Dockerfiles 2023-05-26 15:40:34 +00:00
Dockerfile fix: Update Dockerfiles to copy entire app directory for package dependencies 2025-08-20 12:58:03 +02:00
LICENSE.md Move packages/apps back 2023-03-10 08:26:51 +00:00
middleware.ts WIP 5 2024-03-20 17:51:21 +01:00
next-env.d.ts Update deps, add robots.txt 2025-01-26 12:24:57 +01:00
next.config.js Update dependencies 2024-11-25 09:31:25 +01:00
package.json feat: Add centralized logging system with @link-stack/logger package 2025-08-20 11:37:39 +02:00
README.md Add basic READMEs 2025-05-23 13:20:07 +02:00
tsconfig.json Fix build errors 2023-08-25 09:41:41 +02:00

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

# 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