Add basic READMEs

apps/leafcutter/README.md

@@ -1,32 +1,195 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Leafcutter
 
-## Getting Started
+Data visualization and analytics platform for the CDR Link ecosystem.
 
-First, run the development server:
+## 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
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### Environment Variables
 
-You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
+Required environment variables:
 
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`.
+- `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
 
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+### Available Scripts
 
-## Learn More
+- `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
 
-To learn more about Next.js, take a look at the following resources:
+## Architecture
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+### Page Structure
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+- `/` - 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
 
-## Deploy on Vercel
+### API Routes
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+- `/api/searches/*` - Search management
+- `/api/visualizations/*` - Visualization CRUD
+- `/api/trends/*` - Trend data
+- `/api/upload` - File upload handling
+- `/api/link/auth` - Link authentication
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+### 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