195 lines
No EOL
4.2 KiB
Markdown
195 lines
No EOL
4.2 KiB
Markdown
# 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 |