ɳChat v0.9.1 - Complete Documentation

1. Overview
2. MeiliSearch Integration
3. Search Features
4. Analytics Dashboard
5. Usage Tracking
6. API Reference
7. Real-time Indexing
8. Export & Reporting

ɳChat provides comprehensive search and analytics capabilities powered by MeiliSearch and custom analytics aggregation.

• Full-text search across messages, files, users, and channels
• Real-time indexing via GraphQL subscriptions
• Advanced filtering with search operators
• Analytics dashboard with interactive charts
• Usage tracking with plan limit monitoring
• Export functionality (CSV, JSON)
• Performance optimized with caching and batch operations

┌─────────────────┐
│   Frontend      │
├─────────────────┤
│ Search API      │
│ /api/search     │
├─────────────────┤
│ Search Service  │
│ search.service  │
├─────────────────┤
│ Sync Service    │
│ sync.service    │
├─────────────────┤
│  MeiliSearch    │
│  Port: 7700     │
└─────────────────┘

ɳChat maintains 4 MeiliSearch indexes:

Each index is configured with:

• Filterable attributes: For precise filtering
• Sortable attributes: For ordering results
• Ranking rules: Custom relevance scoring
• Stop words: Common words to ignore
• Typo tolerance: Fuzzy matching for misspellings

// GET /api/search?q=hello
const response = await fetch('/api/search?q=hello')
const data = await response.json()

// POST /api/search
const response = await fetch('/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'project update',
    types: ['messages', 'files'],
    channelIds: ['channel-id-1'],
    dateFrom: '2024-01-01',
    dateTo: '2024-12-31',
    limit: 20,
    offset: 0,
    sortBy: 'date',
    sortOrder: 'desc',
  }),
})

ɳChat supports Slack-style search operators:

Example:

project from:alice in:engineering has:file after:2024-01-01

import { getSearchService } from '@/services/search'

const service = getSearchService()
const suggestions = await service.getSuggestions('proj', {
  limit: 10,
  types: ['messages', 'users', 'channels'],
})

Search results include highlighted matches:

{
  "id": "msg-123",
  "content": "Let's discuss the project update",
  "highlight": "Let's discuss the <mark>project</mark> update",
  "score": 0.92
}

The analytics dashboard consists of:

src/components/analytics/
├── overview/
│   ├── AnalyticsDashboard.tsx      # Main dashboard
│   ├── AnalyticsSummary.tsx        # Summary cards
│   ├── AnalyticsCards.tsx          # Quick stats
│   ├── AnalyticsHeader.tsx         # Header with filters
│   └── UsageTrackingDashboard.tsx  # Usage tracking
├── charts/
│   ├── MessageVolumeChart.tsx      # Message trends
│   ├── ActiveUsersChart.tsx        # User activity
│   ├── ChannelActivityChart.tsx    # Channel stats
│   ├── ReactionChart.tsx           # Popular reactions
│   ├── PeakHoursChart.tsx          # Activity by hour
│   ├── GrowthChart.tsx             # User growth
│   ├── FileUploadChart.tsx         # File uploads
│   ├── ResponseTimeChart.tsx       # Response times
│   └── UserEngagementChart.tsx     # Engagement metrics
├── tables/
│   ├── TopChannelsTable.tsx        # Most active channels
│   ├── TopUsersTable.tsx           # Most active users
│   ├── TopMessagesTable.tsx        # Popular messages
│   └── InactiveUsersTable.tsx      # Inactive users
├── views/
│   ├── MessageAnalytics.tsx        # Message-specific view
│   ├── UserAnalytics.tsx           # User-specific view
│   ├── ChannelAnalytics.tsx        # Channel-specific view
│   ├── FileAnalytics.tsx           # File-specific view
│   ├── SearchAnalytics.tsx         # Search-specific view
│   └── BotAnalytics.tsx            # Bot-specific view
└── export/
    └── AnalyticsExport.tsx         # Export functionality

• Total messages (24h, 7d, 30d, all-time)
• Active users (online now, today, this week)
• New channels created
• Storage usage
• Top channels by activity

• Messages over time (line chart)
• Messages by channel (bar chart)
• Messages by user (top 10)
• Message types breakdown (text, image, video, file)
• Peak hours analysis

• User growth (line chart)
• Active users trend (DAU/WAU/MAU)
• User roles breakdown (pie chart)
• Top contributors
• Inactive users (30+ days)

• Storage usage by type
• File uploads over time
• Largest files
• Files by channel
• File type distribution

• Channel activity heatmap
• Most active channels
• Channel types breakdown
• Member growth by channel

import { AnalyticsDashboard } from '@/components/analytics/overview/AnalyticsDashboard';

export default function AnalyticsPage() {
  return <AnalyticsDashboard className="container mx-auto py-6" />;
}

The dashboard supports filtering by:

• Date range: Last 7/30/90 days, custom range
• Granularity: Hour, day, week, month
• Channels: Filter by specific channels
• Users: Filter by specific users
• Include bots: Toggle bot activity

ɳChat tracks usage against plan limits:

• Safe (0-74%): Green, healthy usage
• Warning (75-99%): Amber, approaching limit
• Critical (100%+): Red, limit reached

import { UsageTrackingDashboard } from '@/components/analytics/overview/UsageTrackingDashboard';

export default function UsagePage() {
  const limits = {
    plan: 'free',
    members: { current: 45, limit: 50 },
    channels: { current: 12, limit: 15 },
    storage: { current: 8500, limit: 10240 },
    apiCalls: { current: 95000, limit: 100000 },
    videoMinutes: { current: 280, limit: 300 },
  };

  return (
    <UsageTrackingDashboard
      limits={limits}
      onUpgrade={() => router.push('/billing/upgrade')}
      onExport={(format) => console.log(`Exporting as ${format}`)}
    />
  );
}

Quick search across all types.

Query Parameters:

• q (required): Search query
• limit (optional): Results per page (default: 20, max: 100)
• offset (optional): Pagination offset (default: 0)

Response:

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Advanced search with filters.

Request Body:

{
  "query": "project update",
  "types": ["messages", "files"],
  "channelIds": ["channel-id-1"],
  "userIds": ["user-id-1"],
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "limit": 20,
  "offset": 0,
  "sortBy": "date",
  "sortOrder": "desc"
}

Response:

{
  "success": true,
  "results": [...],
  "totals": {
    "messages": 50,
    "files": 10,
    "users": 5,
    "channels": 2,
    "total": 67
  },
  "query": "project update",
  "types": ["messages", "files"],
  "pagination": {...}
}

Get index status and health.

Response:

{
  "success": true,
  "stats": {
    "messages": {
      "numberOfDocuments": 1000,
      "isIndexing": false
    },
    ...
  },
  "health": {
    "messages": {
      "healthy": true,
      "pendingTasks": 0,
      "failedTasks": 0
    },
    ...
  }
}

Trigger reindexing (admin only).

Request Body:

{
  "indexName": "messages",
  "forceRebuild": true
}

Clear all indexes (admin only).

Trigger full reindexing of all or specific indexes.

Request Body:

{
  "indexNames": ["messages", "files"],
  "forceRebuild": true,
  "batchSize": 100
}

Get reindexing progress.

Response:

{
  "success": true,
  "isReindexing": true,
  "stats": {...},
  "health": {...}
}

Get aggregated dashboard data.

Query Parameters:

• preset: Date range preset (last7days, last30days, last90days)
• start: Custom start date (ISO 8601)
• end: Custom end date (ISO 8601)
• granularity: Time granularity (hour, day, week, month)
• channels: Comma-separated channel IDs
• users: Comma-separated user IDs
• includeBots: Include bot activity (true/false)

Response:

{
  "success": true,
  "data": {
    "summary": {...},
    "messageVolume": [...],
    "activeUsers": {...},
    "channelActivity": [...],
    ...
  },
  "filters": {...},
  "meta": {
    "generatedAt": "2024-01-01T00:00:00Z",
    "cached": false
  }
}

Get message-specific analytics.

Get user-specific analytics.

Export analytics data.

Query Parameters:

• format: Export format (csv, json)
• sections: Comma-separated sections to export
• preset: Date range preset

GraphQL Subscription
        ↓
RealtimeSyncService
        ↓
    SyncService
        ↓
 MessageIndexer
        ↓
   MeiliSearch

import { getRealtimeSyncService } from '@/services/search/realtime-sync'
import { io } from 'socket.io-client'

// Initialize realtime sync
const realtimeSync = getRealtimeSyncService({
  enabled: true,
  batchInterval: 1000,
  maxBatchSize: 50,
  debug: false,
})

// Connect to Socket.io
const socket = io('http://localhost:4000')
realtimeSync.connect(socket)

// Subscribe to sync events
const unsubscribe = realtimeSync.onSync((result, event) => {
  console.log(`Indexed ${event.type}:`, result)
})

// Later: disconnect
realtimeSync.disconnect()
unsubscribe()

The sync service listens for these events:

• message:created
• message:updated
• message:deleted
• channel:created
• channel:updated
• channel:deleted
• user:created
• user:updated
• user:deleted
• file:uploaded
• file:deleted

import { getSyncService } from '@/services/search'

const syncService = getSyncService()

// Index a single message
await syncService.indexMessage(message, channel, author)

// Batch index messages
await syncService.batchIndexMessages([
  { message, channel, author },
  { message: message2, channel: channel2, author: author2 },
])

// Index other entities
await syncService.indexFile(file)
await syncService.indexUser(user)
await syncService.indexChannel(channel)

import { exportFullReport } from '@/lib/analytics/analytics-export'

exportFullReport(data, {
  format: 'csv',
  sections: ['summary', 'messages', 'users'],
  dateRange,
  includeCharts: false,
})

Generated file: analytics-report-2024-01-01.csv

exportFullReport(data, {
  format: 'json',
  sections: ['summary', 'messages', 'users'],
  dateRange,
  includeCharts: false,
})

Generated file: analytics-report-2024-01-01.json

import { useAnalyticsStore } from '@/stores/analytics-store'

const { addScheduledReport } = useAnalyticsStore()

addScheduledReport({
  id: 'weekly-report',
  name: 'Weekly Analytics Report',
  schedule: 'weekly',
  format: 'csv',
  sections: ['summary', 'messages', 'users'],
  recipients: ['[email protected]'],
  enabled: true,
})

• Analytics aggregator: 5-minute cache for dashboard data
• Search results: Client-side caching via SWR
• Index stats: 1-minute cache for index health

• Message indexing: Batched every 1 second or 50 messages
• Bulk reindexing: 100 documents per batch
• API requests: Paginated with max 100 results

Problem: Search returns no results.

Solutions:

• Check MeiliSearch is running: docker ps | grep meilisearch
• Verify indexes exist: GET /api/search/index
• Trigger reindex: POST /api/search/reindex

Problem: New messages don't appear in search.

Solutions:

• Check Socket.io connection
• Verify GraphQL subscriptions are active
• Check console for sync errors

Problem: Dashboard shows no data.

Solutions:

• Check analytics collector is running
• Verify database connection
• Clear cache: analyticsAggregator.clearCache()

Problem: Search takes too long.

Solutions:

• Reduce result limit
• Use specific types filter
• Add more MeiliSearch RAM
• Check index health

1. Use specific types when possible to narrow results
2. Implement pagination for large result sets
3. Provide suggestions for better UX
4. Show loading states during searches
5. Highlight matches in results

1. Use date range presets for common queries
2. Implement caching for expensive aggregations
3. Show comparison data for context
4. Export large datasets instead of displaying all
5. Monitor cache hit rates to optimize TTL

1. Use batch operations for bulk indexing
2. Monitor index health regularly
3. Set up alerts for indexing failures
4. Reindex periodically to maintain consistency
5. Use real-time sync for immediate updates

• MeiliSearch Documentation
• Recharts Documentation
• Analytics Implementation Plan
• API Documentation

Last Updated: 2026-02-03 Version: 0.9.1