Convostack

ConvoStack is an AI-driven chatbot framework that helps developers create intelligent conversational applications. This article explores the technical foundation of ConvoStack, from its underlying technologies to its component-based architecture. We'll examine how the framework integrates with popular tools like React and Express.js, how it manages real-time communication through Redis, and how developers can customize every aspect of their chatbot applications. Whether you're a seasoned developer looking to add chatbot functionality to your project or just getting started with AI-driven conversational interfaces, this detailed overview will help you understand how ConvoStack makes building these applications both powerful and flexible.

Core Technologies

ConvoStack's frontend foundation leverages React (version ^17.0.2 or ^18.0.0) and React-DOM (version ^17.0.2 or ^18.0.0), while the backend builds on Express.js, with support for Node.js version 18 or higher. This technology stack enables rapid development and deployment of AI-driven chatbot applications.

The framework's core architecture centers around Langchain, an open-source framework for building applications with large language models (LLMs). Langchain integration facilitates the creation of powerful AI agents that can process and respond to user inputs in real-time. The backend core resides in the convostack/backend-express package, which developers can access through npm installation.

Development with ConvoStack follows a component-based approach, offering four primary React components for integration:

1. ConvoStackWrapper: Serves as the entry point for integrating the chatbot widget, providing a shared Redux Toolkit store and React Query Client Provider for managing all ConvoStack components.

2. ConvoStackWidget: Inserts the chatbot widget into the website, initializing the Redux Toolkit store data including the GraphQL endpoint. This component can be hidden by setting disableWidget to true.

3. ConvoStackEmbed: Offers more customization options for embedding specific functionality. Each instance requires a unique embedId for managing local state and storing data in the backend.

4. Custom Message Handling: Allows developers to implement custom message components that display sent and received messages.

The backend architecture employs flexible TypeScript interfaces for extensive customization, supporting multiple database options including PostgreSQL and MySQL. For real-time communication, it utilizes Redis caching and pub/sub functionality, with support for both Redis-based and custom implementations. Authentication is handled through easy-to-use middleware, with options for custom implementation when desired.

Full-Stack Integration

The framework allows integration with existing projects through npm installation, requiring Node.js version 18 or higher. For the frontend, developers need to install react (version ^17.0.2 or ^18.0.0) and react-dom (version ^17.0.2 or ^18.0.0). The backend requires express (version above 4.17.1) and langchain (version ^0.0.67), though Langchain integration is optional.

The core functionality is encapsulated in the convostack/backend-express package, which developers can access via npm installation. The backend architecture employs flexible TypeScript interfaces for extensive customization, supporting multiple database options including PostgreSQL and MySQL. Authentication is handled through middleware, with options for custom implementation when desired.

The framework enables development of AI chatbots through a component-based approach, providing four primary React components for integration:

1. ConvoStackWrapper manages the overall integration, providing a shared Redux Toolkit store and React Query Client Provider for all ConvoStack components.

2. ConvoStackWidget inserts the chatbot widget into the website, initializing the Redux Toolkit store data including the GraphQL endpoint. This component can be hidden by setting disableWidget to true.

3. ConvoStackEmbed offers more customization options for embedding specific functionality. Each instance requires a unique embedId for managing local state and storing data in the backend.

4. Custom Message Handling allows developers to implement custom message components that display sent and received messages, with properties including graphqlUrl, websocketUrl, and customStyling options. CustomStyling properties include headerColor, headerTextColor, widgetLaunchButtonColor, widgetWindowWidth, widgetWindowHeightOffset, and iconsColor. Custom icons can be specified for widgetLaunchButtonOpenIcon, widgetLaunchButtonCloseIcon, createNewConversationIcon, sendMessageIcon, and backArrowIcon.

Component-Based Architecture

The ConvoStack framework revolves around four primary React components for integration:

1. ConvoStackWrapper: This component serves as the entry point for integrating the chatbot widget, providing essential services through Redux Toolkit store and React Query Client Provider. To use ConvoStack, this component must be included at the root of the component tree.

2. ConvoStackWidget: This component adds the chatbot widget to the website, initializing the necessary Redux Toolkit store data including the GraphQL endpoint. It must be nested within a ConvoStackWrapper component. Developers have the option to hide the widget by setting the disableWidget property to true.

3. ConvoStackEmbed: This component offers greater customization options for embedding specific functionality. It requires a unique embedId for managing local state and storing data in the backend, with all instances needing distinct identifiers to prevent interference.

4. Custom Message Handling: This functionality allows developers to implement custom message components that display sent and received messages. Components must implement the CustomMessage interface and accept properties including graphqlUrl, websocketUrl, and customStyling.

Each component provides specific properties for customization:

• graphqlUrl and websocketUrl define the communication endpoints with the backend

• userData manages user conversation history

• customStyling allows modification of widget appearance

• icons supports replacement of default widget icons with custom SVG components

The framework's architecture enables flexible integration while maintaining robust functionality, supporting multiple frontend and backend configurations. Through its component-based approach, ConvoStack delivers both simplicity and customization options for developers working with AI-driven chatbots.

Backend Core and Deployment

The backend core resides in the convostack/backend-express package and uses flexible TypeScript interfaces for extensive customization, supporting multiple database options including PostgreSQL and MySQL. This architecture enables developers to create highly customized chatbot solutions while maintaining robust core functionality.

Database management is handled through built-in SQL database implementations, with the recommendation to create a separate database (on the same server/instance) for ConvoStack tables and migration tracking. This separation helps avoid issues with Prisma migrations when using the default ConvoStack storage engine implementations. For custom storage needs, developers must implement the convostack/models.IStorageEngine interface.

The backend requires Redis for caching and pub/sub functionality, supporting both Redis-based and custom implementations. The official documentation recommends Upstash's managed Redis service when using multiple backend machines, as it integrates smoothly with Fly.io and provides a generous free tier. To connect ConvoStack to Redis, developers should refer to the official documentation for caching and pub/sub configuration.

Authentication is managed through middleware, with support for both public authentication interfaces and custom implementation options. For frontend integration, CORS must be properly configured using the cors package. The backend can attach to an existing Express.js server, with sample configuration provided in the documentation:

const corsOptions: CorsOptions = {

origin: ["http://localhost:5173", "https://studio.apollographql.com"],

methods: "GET,HEAD,PUT,PATCH,POST,DELETE",

};

The backend core configuration includes several key components: Agents, Storage, Authentication, and Cache & Pub/Sub. Agents encapsulate chat models and provide utilities for integrating with other libraries like Langchain. Storage manages backend messages, users, and metadata, supporting both built-in SQL implementations and custom storage solutions. Authentication includes the convostack/auth-jwt middleware for connecting user data and offers public auth interfaces for custom implementation. Cache & Pub/Sub provides Redis-based functionality, supporting both Redis-based and custom implementations.

Agent Integration and Development

The ConvoStack company implements chat agents as IAgent interface implementations, supporting both direct custom development and integration with Langchain. Agents are managed through a DefaultAgentManager that accepts a map of agent configurations and a default agent key, automatically starting conversations with the default key when no specific agent is specified.

Agent Implementation

Agents implement the IAgent interface, which requires a single reply method that processes IAgentContext and IAgentCallbacks to generate a response, returning an IAgentResponse object. The reply method enables sophisticated processing through IAgentContext while providing real-time feedback via IAgentCallbacks, particularly through the onMessagePart function that supports streaming responses.

Langchain Integration

Langchain integration demonstrates how the framework connects with powerful AI models through a structured approach. The documentation provides examples of both an OpenAI Agent and an LLM Chain implementation, both configured with the OpenAI API key stored in the .env file. These examples showcase how to create playground functions that handle human messages and agent responses, with specific commands provided for running these implementations (e.g., npx ts-node index.ts).

The Langchain-based agents demonstrate advanced features like streaming responses directly to users through the onMessagePart callback. This integration allows agents to generate and send message parts incrementally, creating a more interactive user experience. Agents can access conversation history through the IAgentContext.getHistory() method, integrating it with LLM models through pre-built convenience methods developed specifically for this purpose.