From 3659a4ef38e38b101313724f22df69a20eea59a2 Mon Sep 17 00:00:00 2001
From: Darren Clarke <darren@redaranj.com>
Date: Fri, 23 May 2025 13:20:07 +0200
Subject: [PATCH] Add basic READMEs

---
 apps/bridge-frontend/README.md   | 137 ++++++++++++++++++----
 apps/bridge-migrations/README.md | 158 +++++++++++++++++++++++++
 apps/bridge-whatsapp/README.md   | 172 +++++++++++++++++++++++++++
 apps/bridge-worker/README.md     | 147 +++++++++++++++++++++++
 apps/leafcutter/README.md        | 193 ++++++++++++++++++++++++++++---
 apps/link/README.md              | 107 ++++++++++++++---
 6 files changed, 864 insertions(+), 50 deletions(-)
 create mode 100644 apps/bridge-migrations/README.md
 create mode 100644 apps/bridge-whatsapp/README.md
 create mode 100644 apps/bridge-worker/README.md

diff --git a/apps/bridge-frontend/README.md b/apps/bridge-frontend/README.md
index c403366..ebec248 100644
--- a/apps/bridge-frontend/README.md
+++ b/apps/bridge-frontend/README.md
@@ -1,36 +1,133 @@
-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).
+# Bridge Frontend
 
-## Getting Started
+Frontend application for managing communication bridges between various messaging platforms and the CDR Link system.
 
-First, run the development server:
+## Overview
+
+Bridge Frontend provides a web interface for configuring and managing communication channels including Signal, WhatsApp, Facebook, and Voice integrations. It handles bot registration, webhook configuration, and channel settings.
+
+## Features
+
+- **Channel Management**: Configure Signal, WhatsApp, Facebook, and Voice channels
+- **Bot Registration**: Register and manage bots for each communication platform
+- **Webhook Configuration**: Set up webhooks for message routing
+- **Settings Management**: Configure channel-specific settings and behaviors
+- **User Authentication**: Secure access with NextAuth.js
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database
+- Running bridge-worker service
+
+### Setup
 
 ```bash
+# Install dependencies
+npm install
+
+# Run database migrations
+npm run migrate:latest
+
+# Run development server
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun 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 `app/page.tsx`. The page auto-updates as you edit the file.
+Required environment variables:
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+- `DATABASE_URL` - PostgreSQL connection string
+- `DATABASE_HOST` - Database host
+- `DATABASE_NAME` - Database name
+- `DATABASE_USER` - Database username
+- `DATABASE_PASSWORD` - Database password
+- `NEXTAUTH_URL` - Application URL
+- `NEXTAUTH_SECRET` - NextAuth.js secret
+- `GOOGLE_CLIENT_ID` - Google OAuth client ID
+- `GOOGLE_CLIENT_SECRET` - Google OAuth client secret
 
-## Learn More
+### Available Scripts
 
-To learn more about Next.js, take a look at the following resources:
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run start` - Start production server
+- `npm run lint` - Run ESLint
+- `npm run migrate:latest` - Run all pending migrations
+- `npm run migrate:down` - Rollback last migration
+- `npm run migrate:up` - Run next migration
+- `npm run migrate:make` - Create new migration
 
-- [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.
+## Architecture
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+### Database Schema
 
-## Deploy on Vercel
+The application manages the following main entities:
 
-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.
+- **Bots**: Communication channel bot configurations
+- **Webhooks**: Webhook endpoints for external integrations
+- **Settings**: Channel-specific configuration settings
+- **Users**: User accounts with role-based permissions
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+### API Routes
+
+- `/api/auth` - Authentication endpoints
+- `/api/[service]/bots` - Bot management for each service
+- `/api/[service]/webhooks` - Webhook configuration
+
+### Page Structure
+
+- `/` - Dashboard/home page
+- `/login` - Authentication page
+- `/[...segment]` - Dynamic routing for CRUD operations
+  - `@create` - Create new entities
+  - `@detail` - View entity details
+  - `@edit` - Edit existing entities
+
+## Integration
+
+### Database Access
+
+Uses Kysely ORM for type-safe database queries:
+
+```typescript
+import { db } from '@link-stack/database'
+
+const bots = await db
+  .selectFrom('bots')
+  .selectAll()
+  .execute()
+```
+
+### Authentication
+
+Integrated with NextAuth.js using database adapter:
+
+```typescript
+import { authOptions } from '@link-stack/auth'
+```
+
+## Docker Support
+
+```bash
+# Build image
+docker build -t link-stack/bridge-frontend .
+
+# Run with docker-compose
+docker-compose -f docker/compose/bridge.yml up
+```
+
+## Related Services
+
+- **bridge-worker**: Processes messages from configured channels
+- **bridge-whatsapp**: WhatsApp-specific integration service
+- **bridge-migrations**: Database schema management
\ No newline at end of file
diff --git a/apps/bridge-migrations/README.md b/apps/bridge-migrations/README.md
new file mode 100644
index 0000000..a9e45e3
--- /dev/null
+++ b/apps/bridge-migrations/README.md
@@ -0,0 +1,158 @@
+# Bridge Migrations
+
+Database migration management for the CDR Link bridge system.
+
+## Overview
+
+Bridge Migrations handles database schema versioning and migrations for all bridge-related tables using Kysely migration framework. It manages the database structure for authentication, messaging channels, webhooks, and settings.
+
+## Features
+
+- **Schema Versioning**: Track and apply database schema changes
+- **Up/Down Migrations**: Support for rolling forward and backward
+- **Type-Safe Migrations**: TypeScript-based migration files
+- **Migration History**: Track applied migrations in the database
+- **Multiple Migration Strategies**: Run all, run one, or rollback migrations
+
+## Migration Files
+
+Current migrations in order:
+
+1. **0001-add-next-auth.ts** - NextAuth.js authentication tables
+2. **0002-add-signal.ts** - Signal messenger integration
+3. **0003-add-whatsapp.ts** - WhatsApp integration
+4. **0004-add-voice.ts** - Voice/Twilio integration
+5. **0005-add-facebook.ts** - Facebook Messenger integration
+6. **0006-add-webhooks.ts** - Webhook configuration
+7. **0007-add-settings.ts** - Application settings
+8. **0008-add-user-role.ts** - User role management
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database
+- Database connection credentials
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run all pending migrations
+npm run migrate:latest
+
+# Check migration status
+npm run migrate:list
+```
+
+### Environment Variables
+
+Required environment variables:
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `DATABASE_HOST` - Database host
+- `DATABASE_NAME` - Database name
+- `DATABASE_USER` - Database username
+- `DATABASE_PASSWORD` - Database password
+
+### Available Scripts
+
+- `npm run migrate:latest` - Run all pending migrations
+- `npm run migrate:up` - Run next pending migration
+- `npm run migrate:down` - Rollback last migration
+- `npm run migrate:up:all` - Run all migrations (alias)
+- `npm run migrate:up:one` - Run one migration
+- `npm run migrate:down:all` - Rollback all migrations
+- `npm run migrate:down:one` - Rollback one migration
+- `npm run migrate:list` - List migration status
+- `npm run migrate:make <name>` - Create new migration file
+
+## Creating New Migrations
+
+To create a new migration:
+
+```bash
+npm run migrate:make add-new-feature
+```
+
+This creates a new timestamped migration file in the `migrations/` directory.
+
+Example migration structure:
+
+```typescript
+import { Kysely } from 'kysely'
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('new_table')
+    .addColumn('id', 'serial', (col) => col.primaryKey())
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('created_at', 'timestamp', (col) =>
+      col.defaultTo('now()').notNull()
+    )
+    .execute()
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('new_table').execute()
+}
+```
+
+## Database Schema
+
+### Core Tables
+
+- **users** - User accounts with roles
+- **accounts** - OAuth account connections
+- **sessions** - User sessions
+- **verification_tokens** - Email verification
+
+### Communication Tables
+
+- **bots** - Bot configurations for each service
+- **signal_messages** - Signal message history
+- **whatsapp_messages** - WhatsApp message history
+- **voice_messages** - Voice/call records
+- **facebook_messages** - Facebook message history
+
+### Configuration Tables
+
+- **webhooks** - External webhook endpoints
+- **settings** - Application settings
+
+## Best Practices
+
+1. **Test Migrations**: Always test migrations in development first
+2. **Backup Database**: Create backups before running migrations in production
+3. **Review Changes**: Review migration files before applying
+4. **Atomic Operations**: Keep migrations focused and atomic
+5. **Rollback Plan**: Ensure down() methods properly reverse changes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Migration Failed**: Check error logs and database permissions
+2. **Locked Migrations**: Check for concurrent migration processes
+3. **Missing Tables**: Ensure all previous migrations have run
+4. **Connection Issues**: Verify DATABASE_URL and network access
+
+### Recovery
+
+If migrations fail:
+
+1. Check migration history table
+2. Manually verify database state
+3. Run specific migrations as needed
+4. Use rollback if necessary
+
+## Integration
+
+Migrations are used by:
+- **bridge-frontend** - Requires migrated schema
+- **bridge-worker** - Depends on message tables
+- **bridge-whatsapp** - Uses bot configuration tables
\ No newline at end of file
diff --git a/apps/bridge-whatsapp/README.md b/apps/bridge-whatsapp/README.md
new file mode 100644
index 0000000..705ced2
--- /dev/null
+++ b/apps/bridge-whatsapp/README.md
@@ -0,0 +1,172 @@
+# Bridge WhatsApp
+
+WhatsApp integration service for the CDR Link communication bridge system.
+
+## Overview
+
+Bridge WhatsApp provides a REST API for sending and receiving WhatsApp messages using the Baileys library (WhatsApp Web API). It handles bot session management, message routing, and media processing for WhatsApp communication channels.
+
+## Features
+
+- **Bot Management**: Register and manage multiple WhatsApp bot sessions
+- **Message Handling**: Send and receive text messages with formatting
+- **Media Support**: Handle images, documents, audio, and video files
+- **QR Code Authentication**: Web-based WhatsApp authentication
+- **REST API**: Simple HTTP endpoints for integration
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database (for bot configuration)
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run development server
+npm run dev
+
+# Start production server
+npm run start
+```
+
+### Environment Variables
+
+- `PORT` - Server port (default: 5000)
+- `DATABASE_URL` - PostgreSQL connection string (optional)
+- Additional WhatsApp-specific configuration as needed
+
+### Available Scripts
+
+- `npm run build` - Compile TypeScript
+- `npm run dev` - Development mode with auto-reload
+- `npm run start` - Start production server
+
+## API Endpoints
+
+### Bot Management
+
+- `POST /api/bots/:token` - Register/initialize a bot
+- `GET /api/bots/:token` - Get bot status and QR code
+
+### Messaging
+
+- `POST /api/bots/:token/send` - Send a message
+- `POST /api/bots/:token/receive` - Webhook for incoming messages
+
+### Request/Response Format
+
+#### Send Message
+
+```json
+{
+  "to": "1234567890@s.whatsapp.net",
+  "message": "Hello World",
+  "media": {
+    "url": "https://example.com/image.jpg",
+    "type": "image"
+  }
+}
+```
+
+#### Receive Message Webhook
+
+```json
+{
+  "from": "1234567890@s.whatsapp.net",
+  "message": "Hello",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "media": {
+    "url": "https://...",
+    "type": "image",
+    "mimetype": "image/jpeg"
+  }
+}
+```
+
+## Architecture
+
+### Server Framework
+
+Built with Hapi.js for:
+
+- Route validation
+- Plugin architecture
+- Error handling
+- Request lifecycle
+
+### WhatsApp Integration
+
+Uses @whiskeysockets/baileys:
+
+- WhatsApp Web protocol
+- Multi-device support
+- Message encryption
+- Media handling
+
+### Session Management
+
+- File-based session storage
+- Automatic reconnection
+- QR code regeneration
+- Session cleanup
+
+## Media Handling
+
+Supported media types:
+
+- **Images**: JPEG, PNG, GIF
+- **Documents**: PDF, DOC, DOCX
+- **Audio**: MP3, OGG, WAV
+- **Video**: MP4, AVI
+
+Media is processed and uploaded before sending.
+
+## Error Handling
+
+- Connection errors trigger reconnection
+- Invalid sessions regenerate QR codes
+- API errors return appropriate HTTP status codes
+- Comprehensive logging for debugging
+
+## Security
+
+- Token-based bot authentication
+- Message validation
+- Rate limiting (configurable)
+- Secure session storage
+
+## Integration
+
+Designed to work with:
+
+- **bridge-worker**: Processes WhatsApp message jobs
+- **bridge-frontend**: Manages bot configuration
+- External webhooks for message routing
+
+## Docker Support
+
+```bash
+# Build image
+docker build -t link-stack/bridge-whatsapp .
+
+# Run container
+docker run -p 5000:5000 link-stack/bridge-whatsapp
+```
+
+## Testing
+
+While test configuration exists (jest.config.json), tests should be implemented for:
+
+- API endpoint validation
+- Message processing logic
+- Session management
+- Error scenarios
diff --git a/apps/bridge-worker/README.md b/apps/bridge-worker/README.md
new file mode 100644
index 0000000..8e5638a
--- /dev/null
+++ b/apps/bridge-worker/README.md
@@ -0,0 +1,147 @@
+# Bridge Worker
+
+Background job processor for handling asynchronous tasks in the CDR Link communication bridge system.
+
+## Overview
+
+Bridge Worker uses Graphile Worker to process queued jobs for message handling, media conversion, webhook notifications, and scheduled tasks. It manages the flow of messages between various communication channels (Signal, WhatsApp, Facebook, Voice) and the Zammad ticketing system.
+
+## Features
+
+- **Message Processing**: Handle incoming/outgoing messages for all supported channels
+- **Media Conversion**: Convert audio/video files between formats
+- **Webhook Notifications**: Notify external systems of events
+- **Scheduled Tasks**: Cron-based job scheduling
+- **Job Queue Management**: Reliable job processing with retries
+- **Multi-Channel Support**: Signal, WhatsApp, Facebook, Voice (Twilio)
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database
+- Redis (for caching)
+- FFmpeg (for media conversion)
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run development server with auto-reload
+npm run dev
+
+# Start production worker
+npm run start
+```
+
+### Environment Variables
+
+Required environment variables:
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `GRAPHILE_WORKER_CONCURRENCY` - Number of concurrent jobs (default: 10)
+- `GRAPHILE_WORKER_POLL_INTERVAL` - Job poll interval in ms (default: 1000)
+- `ZAMMAD_URL` - Zammad instance URL
+- `ZAMMAD_API_TOKEN` - Zammad API token
+- `TWILIO_ACCOUNT_SID` - Twilio account SID
+- `TWILIO_AUTH_TOKEN` - Twilio auth token
+- `SIGNAL_CLI_URL` - Signal CLI REST API URL
+- `WHATSAPP_SERVICE_URL` - WhatsApp bridge service URL
+- `FACEBOOK_APP_SECRET` - Facebook app secret
+- `FACEBOOK_PAGE_ACCESS_TOKEN` - Facebook page token
+
+### Available Scripts
+
+- `npm run build` - Compile TypeScript
+- `npm run dev` - Development mode with watch
+- `npm run start` - Start production worker
+
+## Task Types
+
+### Signal Tasks
+- `receive-signal-message` - Process incoming Signal messages
+- `send-signal-message` - Send outgoing Signal messages
+- `fetch-signal-messages` - Fetch messages from Signal CLI
+
+### WhatsApp Tasks
+- `receive-whatsapp-message` - Process incoming WhatsApp messages
+- `send-whatsapp-message` - Send outgoing WhatsApp messages
+
+### Facebook Tasks
+- `receive-facebook-message` - Process incoming Facebook messages
+- `send-facebook-message` - Send outgoing Facebook messages
+
+### Voice Tasks
+- `receive-voice-message` - Process incoming voice calls/messages
+- `send-voice-message` - Send voice messages via Twilio
+- `twilio-recording` - Handle Twilio call recordings
+- `voice-line-audio-update` - Update voice line audio
+- `voice-line-delete` - Delete voice line
+- `voice-line-provider-update` - Update voice provider settings
+
+### Common Tasks
+- `notify-webhooks` - Send webhook notifications
+
+### Leafcutter Tasks
+- `import-leafcutter` - Import data to Leafcutter
+- `import-label-studio` - Import Label Studio annotations
+
+## Architecture
+
+### Job Processing
+
+Jobs are queued in PostgreSQL using Graphile Worker:
+
+```typescript
+await addJob('send-signal-message', {
+  to: '+1234567890',
+  message: 'Hello world'
+})
+```
+
+### Cron Schedule
+
+Scheduled tasks are configured in `crontab`:
+- Periodic message fetching
+- Cleanup tasks
+- Health checks
+
+### Error Handling
+
+- Automatic retries with exponential backoff
+- Dead letter queue for failed jobs
+- Comprehensive logging with winston
+
+## Media Handling
+
+Supports conversion between formats:
+- Audio: MP3, OGG, WAV, M4A
+- Uses fluent-ffmpeg for processing
+- Automatic format detection
+
+## Integration Points
+
+- **Zammad**: Creates/updates tickets via API
+- **Signal CLI**: REST API for Signal messaging
+- **WhatsApp Bridge**: HTTP API for WhatsApp
+- **Twilio**: Voice and SMS capabilities
+- **Facebook**: Graph API for Messenger
+
+## Docker Support
+
+```bash
+# Build image
+docker build -t link-stack/bridge-worker .
+
+# Run with docker-compose
+docker-compose -f docker/compose/bridge.yml up
+```
+
+The worker includes cron support via built-in crontab.
\ No newline at end of file
diff --git a/apps/leafcutter/README.md b/apps/leafcutter/README.md
index e03b35c..c644c6a 100644
--- a/apps/leafcutter/README.md
+++ b/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
\ No newline at end of file
diff --git a/apps/link/README.md b/apps/link/README.md
index e03b35c..f080763 100644
--- a/apps/link/README.md
+++ b/apps/link/README.md
@@ -1,32 +1,109 @@
-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).
+# CDR Link
 
-## Getting Started
+The main CDR (Center for Digital Resilience) Link application - a streamlined helpdesk interface built on top of Zammad with integrated communication channels and data visualization.
 
-First, run the development server:
+## Overview
+
+CDR Link provides a unified dashboard for managing support tickets, communication channels, and data analytics. It integrates multiple services including Zammad (ticketing), Bridge (multi-channel messaging), Leafcutter (data visualization), and OpenSearch.
+
+## Features
+
+- **Simplified Helpdesk Interface**: Streamlined UI for Zammad ticket management
+- **Multi-Channel Communication**: Integration with Signal, WhatsApp, Facebook, and Voice channels
+- **Data Visualization**: Embedded Leafcutter analytics and reporting
+- **User Management**: Role-based access control with Google OAuth
+- **Search**: Integrated OpenSearch for advanced queries
+- **Label Studio Integration**: For data annotation workflows
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- Running instances of Zammad, PostgreSQL, and Redis
+- Configured authentication providers
+
+### Setup
 
 ```bash
+# Install dependencies
+npm install
+
+# Run development server
 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.
+Key environment variables required:
 
-[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`.
+- `ZAMMAD_URL` - Zammad instance URL
+- `ZAMMAD_API_TOKEN` - Zammad API authentication token
+- `DATABASE_URL` - PostgreSQL connection string
+- `REDIS_URL` - Redis connection URL
+- `NEXTAUTH_URL` - Application URL for authentication
+- `NEXTAUTH_SECRET` - Secret for NextAuth.js
+- `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` - Start development server
+- `npm run build` - Build for production
+- `npm run start` - Start production server
+- `npm run lint` - Run ESLint
+- `npm run export` - Export static site
 
-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.
+### Pages Structure
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+- `/` - Main dashboard
+- `/overview/[overview]` - Ticket overview pages
+- `/tickets/[id]` - Individual ticket view/edit
+- `/admin/bridge` - Bridge configuration management
+- `/leafcutter` - Data visualization dashboard
+- `/opensearch` - Search dashboard
+- `/zammad` - Direct Zammad access
+- `/profile` - User profile management
 
-## 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/auth` - NextAuth.js authentication
+- `/api/v2/users` - User management API
+- `/api/[service]/bots` - Bot management for communication channels
+- `/api/[service]/webhooks` - Webhook endpoints
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+### Key Components
+
+- `ZammadWrapper` - Embeds Zammad UI with authentication
+- `SearchBox` - Global search functionality
+- `TicketList` / `TicketDetail` - Ticket management components
+- `Sidebar` - Navigation and service switching
+
+## Docker Support
+
+Build and run with Docker:
+
+```bash
+# Build image
+docker build -t link-stack/link .
+
+# Run with docker-compose
+docker-compose -f docker/compose/link.yml up
+```
+
+## Integration Points
+
+- **Zammad**: GraphQL queries for ticket data
+- **Bridge Services**: REST APIs for channel management
+- **Leafcutter**: Embedded iframe integration
+- **OpenSearch**: Direct dashboard embedding
+- **Redis**: Session and cache storage
\ No newline at end of file