# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Colmeia Bot Service

## Overview
This is the **Bot** microservice of the Colmeia platform, responsible for conversation engine and bot logic. It handles customer interactions, conversation flows, and bot automation across multiple channels.

## Key Architecture Components

### Core Bot Classes
- **BotCoordinator** (`src/new-bot/bot-coordinator.ts`): Central orchestrator for bot conversations and message processing
- **BotNavigable** (`src/new-bot/bot-class-server/navigable.ts`): Core navigation and flow control for bot interactions
- **BotNavigableFactory** (`src/new-bot/bot-navigable-factory.ts`): Factory for creating bot navigable instances
- **BotNavigableRehydrator** (`src/new-bot/bot-navigable-rehydrator.ts`): Handles rehydration of bot state from persistence

### Business Modules
- **new-bot/**: Next-generation bot engine with advanced conversation management
- **polimata/**: Polimata BPM playbook integration
- **services-360/**: 360-degree service integration for omnichannel support
- **crm/**: CRM system integrations (Salesforce, etc.)
- **bot-helper/**: Utility services for bot operations

### Key Patterns
- **Microservice Architecture**: Uses `@colmeia/*` imports for shared libraries
- **Event-Driven**: Integrates with EventController for scheduling and triggers
- **State Management**: Persistent conversation state with PostgreSQL
- **Asset-Based Actions**: Bot actions implemented as reusable assets
- **Real-time Communication**: Socket.io integration for live interactions

## Development Commands

### Build & Development
```bash
# Build the bot service
yarn build

# Run in development with watch mode
yarn watch

# Start the bot service
yarn start:bot

# TypeScript compilation only
yarn tsc
```

### Testing
```bash
# Run tests (Jest with 40s timeout)
yarn test
```

## Technical Configuration

### TypeScript Setup
- **Target**: ES2020 with CommonJS modules
- **Path Mapping**: `@colmeia/*` imports for cross-service dependencies
- **Includes**: Core, server, and core-server source files
- **Strict Typing**: TypeScript 5.0.2 with experimental decorators

### Key Dependencies
- **Google Cloud**: Comprehensive GCP integration (Datastore, BigQuery, PubSub, etc.)
- **AI/ML**: OpenAI, Google Generative AI, Azure Cognitive Services
- **Communication**: Socket.io, Twilio, Telegram Bot API
- **Database**: PostgreSQL (via TypeORM), Redis (ioredis)
- **Bot Framework**: Custom conversation engine with asset-based architecture

### Entry Point
- **Main**: `src/bot.ts` - Initializes tracing and bootstraps the bot service
- **Bootstrap**: Uses `@colmeia/server/src/config/server-bootstrap.initBot()`

## Bot-Specific Patterns

### Conversation Flow
1. **Income Message**: Processed through `I360IncomeMessage` interface
2. **Coordinator**: `BotCoordinator` orchestrates the conversation
3. **Navigation**: `BotNavigable` manages flow transitions
4. **Assets**: Executable actions via `AssetController`
5. **Delivery**: Messages sent via `DeliveryService360`

### State Management
- **Persistent**: Conversation state stored in PostgreSQL
- **Transient**: In-memory coordination via `TransientSignalsCoordinator`
- **Rehydration**: Bot state recreation from persisted data

### Integration Points
- **CRM Systems**: Direct integration with external CRMs
- **360 Services**: Omnichannel service orchestration
- **Polimata BPM**: Business process management integration
- **Campaign Services**: Marketing automation triggers

## File Structure
```
src/
├── bot.ts                 # Service entry point
├── new-bot/              # Next-gen bot engine
│   ├── bot-coordinator.ts # Main conversation orchestrator
│   ├── bot-navigable-*   # Navigation and flow components
│   ├── asset/            # Bot action assets
│   ├── renderers/        # Message rendering system
│   └── virtual-elements/ # Virtual UI components
├── polimata/             # BPM playbook integration
├── services-360/         # Omnichannel services
├── crm/                  # CRM integrations
└── bot-helper/          # Utility services
```

## Development Guidelines

### Code Style
- Follow the main Colmeia project standards (4-space indentation for TypeScript)
- Use strict TypeScript typing - avoid `any` type
- Add JSDoc comments for complex business logic
- Follow domain-driven design patterns

### Testing
- Jest tests with 40-second timeout for integration scenarios
- Focus on conversation flow testing
- Mock external service dependencies

### Integration
- Ensure compatibility with other Colmeia microservices
- Use proper `@colmeia/*` imports for shared functionality
- Coordinate database changes through established migration patterns