radiantone/eoc-customer-support-assistant repository overview

⁠EOC Customer Support Assistant

EOC Customer Support Assistant is an AI-powered NestJS service for automating and orchestrating customer support workflows. It integrates with Chatwoot and GitHub, leverages AWS Bedrock AI models for intelligent conversation routing and knowledge management, and uses Redis and Qdrant for operational context storage and vector search capabilities.

⁠Table of Contents

• Features⁠
• Architecture Overview⁠
• API Base Path and Versioning⁠
• Health Endpoints⁠
• Prerequisites⁠
• Setup⁠
• Usage⁠
• Build and Test⁠
• Docker⁠
• Deployment⁠
• Environment Variables⁠
• Production Notes⁠
• Contributing⁠
• License⁠

⁠Features

• Webhook Processing: Ingests and processes Chatwoot and GitHub webhooks with signature validation
• AI-Driven Workflows: Conversation routing, intent classification, and label assignment using AWS Bedrock
• Knowledge Management: Vector-based knowledge storage and retrieval using Qdrant
• Memory System: Episodic and permanent memory for conversation context using Redis
• Operational Context: Stores and retrieves conversation state using Redis and Qdrant
• Job Processing: Asynchronous task processing with BullMQ for data synchronization
• Health Monitoring: Liveness and readiness probes for Kubernetes deployments
• Security: Rate limiting, CORS controls, Helmet headers, request validation, and webhook signature verification
• Modular Integrations: Redis, AWS Bedrock, Qdrant, BullMQ, Chatwoot API, GitHub API

⁠Architecture Overview

The application follows a modular NestJS architecture:

src/
├── modules/
│   ├── chatwoot/           # Chatwoot webhook ingestion and conversation orchestration
│   ├── github-webhook/     # GitHub webhook processing and KB embedding sync
│   ├── health/             # Liveness/readiness probes
│   ├── ai/                 # AI service for Bedrock integration
│   ├── memory/             # Episodic and permanent memory management
│   └── app/                # Core application module
├── integrations/
│   ├── redis/              # Redis client and caching
│   ├── bedrock/            # AWS Bedrock AI integration
│   ├── qdrant/             # Qdrant vector database client
│   ├── bullmq/             # Job queue processing
│   └── chatwoot/           # Chatwoot API client
├── core/
│   ├── config/             # Typed configuration and environment validation
│   ├── guards/             # Authentication and authorization guards
│   ├── http/               # HTTP filters and interceptors
│   └── logger/             # Application logging

⁠API Base Path

• Global prefix: /api (configurable via APP_BASE_PATH environment variable)

⁠Health Endpoints

• Liveness: GET /api/health/live
• Readiness: GET /api/health/ready

⁠Prerequisites

• Node.js 20+
• npm 10+
• Redis 7+
• (Optional) Qdrant for vector search
• (Optional) AWS credentials for Bedrock AI models
• (Optional) Chatwoot instance for customer support integration
• (Optional) GitHub repository access for knowledge base sync

⁠Setup

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Configure environment variables
# Edit .env with your credentials and deployment-specific values

⁠Usage

⁠Run Locally

# Development mode with hot reload
npm run start:dev

# Production build
npm run build

# Production mode
npm run start:prod

⁠Process a Chatwoot Webhook

Send a POST request to /api/chatwoot/webhook with a valid Chatwoot payload. The service will:

1. Validate the webhook signature
2. Classify the conversation intent using AI
3. Route to appropriate workflow
4. Update conversation state and labels
5. Generate responses using AI models

⁠Health Check

curl http://localhost:3000/api/health/live

⁠Build and Test

# Lint code
npm run lint

# Build application
npm run build

# Run unit tests
npm run test

# Run end-to-end tests
npm run test:e2e

# Check code formatting
npm run format:check

• Unit tests: src/**/*.spec.ts
• E2E tests: test/app.e2e-spec.ts

⁠Docker

⁠Build Image

docker build -t eoc-customer-support-assistant .

⁠Run with Docker Compose (API + Redis)

docker compose up --build

⁠Run Standalone Container

docker run -p 3000:3000 --env-file .env eoc-customer-support-assistant

⁠Deployment

⁠Docker Compose

Use docker-compose.yml for local development or simple deployments.

⁠Kubernetes with Helm

Use the Helm chart in charts/eoc-customer-support-assistant/ for Kubernetes deployments:

helm install eoc-customer-support-assistant ./charts/eoc-customer-support-assistant

⁠Cloud Providers

Adapt environment variables and secrets for your cloud provider (AWS, GCP, Azure). Use secret management services for sensitive credentials.

⁠Environment Variables

See .env.example for the complete variable matrix. Core configuration categories:

⁠Runtime Configuration

• NODE_ENV: Application environment (development, production, test)
• PORT: Server port (default: 3000)
• APP_BASE_PATH: API base path (default: /api)
• LOG_LEVEL: Logging level (debug, info, warn, error)
• CORS_ORIGINS: Allowed CORS origins (comma-separated)
• BODY_LIMIT: Maximum request body size
• REQUEST_TIMEOUT_MS: Request timeout in milliseconds
• TRUST_PROXY: Enable when behind a reverse proxy

⁠Rate Limiting

• RATE_LIMIT_TTL_MS: Rate limit time window
• RATE_LIMIT_LIMIT: Maximum requests per window

⁠Redis

• REDIS_HOST: Redis server hostname
• REDIS_PORT: Redis server port
• REDIS_PASSWORD: Redis authentication password
• REDIS_DB: Redis database number

⁠AWS Bedrock

• BEDROCK_AWS_REGION: AWS region for Bedrock
• BEDROCK_AWS_ACCESS_KEY_ID: AWS access key
• BEDROCK_AWS_SECRET_ACCESS_KEY: AWS secret key

⁠Qdrant Vector Database

• QDRANT_URL: Qdrant server URL (e.g. https://xyz-example.qdrant.io)
• QDRANT_API_KEY: Qdrant API key (if authentication enabled)
• QDRANT_PORT: Qdrant port (default: 443)
• QDRANT_USE_HTTPS: Use HTTPS for Qdrant connection (default: true)
• QDRANT_COLLECTION_NAME: Qdrant collection used for RAG semantic search (required, e.g. product_knowledge - same box that doc-sync writes to)

⁠Documentation Sync REST Endpoints (Primary / Active Workflow)

Powers Swagger UI (/swagger) and the REST API (POST /api/documentation/seed, remove, seed-all) to sync markdown documentation files into Qdrant vectors.

• DOCUMENTATION_SYNC_ENABLED: Master toggle for documentation synchronization and queue processing
• DOCUMENTATION_SYNC_API_KEY: Secure admin API key for Swagger UI authorization and REST endpoint authentication
• DOCUMENTATION_SYNC_GITHUB_TOKEN: GitHub Personal Access Token to fetch repository trees/blobs (increases rate limits)
• DOCUMENTATION_SYNC_ALLOWED_ORGS: Comma-separated allowlist of approved GitHub organizations (default: radiantlogic-v8)
• DOCUMENTATION_SYNC_COLLECTION_NAME: Target Qdrant collection (defaults to QDRANT_COLLECTION_NAME if omitted)
• DOCUMENTATION_SYNC_CLIENTS: Optional JSON map of service client IDs to HMAC secrets for machine-to-machine requests
• DOCUMENTATION_SYNC_SIGNATURE_TOLERANCE_SECONDS: Window for HMAC timestamp tolerance (default: 300)
• DOCUMENTATION_SYNC_NONCE_TTL_SECONDS: Anti-replay nonce TTL in Redis (default: 300)
• DOCUMENTATION_SYNC_JOB_RETENTION_SECONDS: Job history and event retention TTL in Redis (default: 2592000 = 30 days)
• DOCUMENTATION_SYNC_LOCK_TTL_SECONDS: Distributed concurrency lock TTL in Redis (default: 21600 = 6 hours)

⁠Chatwoot Integration

• CHATWOOT_BASE_URL: Chatwoot instance URL
• CHATWOOT_AGENT_BOT_ACCESS_TOKEN: Bot access token
• CHATWOOT_USER_ACCESS_TOKEN: User access token
• CHATWOOT_WEBHOOK_SECRET: Webhook signature secret
• CHATWOOT_ACCOUNT_ID: Chatwoot account ID

⁠GitHub Webhook Integration (Passive / Optional Alternative)

Listens for incoming GitHub repository push events at POST /api/webhooks/github. Note: Not needed if you are using the Swagger REST endpoints to seed and sync documentation.

• GITHUB_WEBHOOK_ENABLED: Master toggle for the GitHub webhook endpoint (default: false)
• GITHUB_WEBHOOK_SECRET: Secret configured in GitHub Repo Settings -> Webhooks

⁠Production Notes

⁠Security

• Webhook signature validation is enabled by default
• Global request validation using class-validator
• Rate limiting is enabled to prevent abuse
• Helmet provides security headers
• CORS is configured for allowed origins only
• Raw body parsing is enabled for signature verification

⁠Reliability

• Request timeout handling
• Graceful shutdown on SIGTERM/SIGINT
• Health checks for Kubernetes probes
• Error handling and logging throughout

⁠Secrets Management

• Never commit secrets to the repository
• Use runtime secret managers (Kubernetes Secrets, AWS Secrets Manager, HashiCorp Vault)
• Rotate secrets regularly
• Restrict access to sensitive credentials

⁠Monitoring

• Structured logging for observability
• Health endpoints for orchestration platforms
• Request/response logging for debugging

⁠Contributing

This is a private enterprise application. Internal contributions should follow these guidelines:

1. Create a feature branch from dev
2. Follow existing code style (enforced by ESLint and Prettier)
3. Write unit tests for new functionality
4. Ensure all tests pass: npm run test
5. Verify linting passes: npm run lint
6. Submit a pull request with a clear description of changes
7. Obtain code review approval before merging

⁠Code Quality

• TypeScript strict mode enabled
• ESLint with TypeScript rules
• Prettier for consistent formatting
• Husky pre-commit hooks for linting

⁠License

Copyright (c) Radiant Logic, Inc. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited. This software is provided "AS IS" without warranty of any kind.