ChatbotX is composed of 3 main services and 3 external services. All running inside a single Docker environment, and communicating with each other.Documentation Index
Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
Use this file to discover all available pages before exploring further.
Architecture
Services
Internal Services
Builder
The main web application, serves the UI and handles all HTTP requests.
Worker
Processes background jobs enqueued by the Builder.
Realtime
Maintains persistent WebSocket connections and pushes realtime updates to clients.
External Services
Redis
Used as a job queue (BullMQ), a cache service, and a pub/sub channel for realtime messaging.
PostgreSQL
The primary relational database. All persistent application data is stored here.
Storage
Object storage for user-uploaded files and generated assets.
Builder
The Builder is a Next.js App Router application that acts as the single entry point for all user interactions.- Renders the full UI via React Server Components and Client Components
- Exposes API routes that handle authentication, data mutations, and business logic
- Authenticates users via Better Auth
- Validates forms and API payloads with Zod
- Reads and writes application data to PostgreSQL through DrizzleORM
- Uploads and retrieves files from Storage
- Enqueues background jobs into Redis for the Worker to process
Worker
The Worker is a long-running Node.js process powered by BullMQ that handles all asynchronous and scheduled work.- Consumes job queues from Redis
- Retries failed jobs with configurable back-off strategies
- Supports delayed and recurring (cron) job scheduling
- Reads and writes data to PostgreSQL as part of job execution
- Reads and writes files from Storage for processing tasks
- Runs independently of the Builder so heavy work never blocks HTTP responses
Realtime
Realtime is a lightweight WebSocket server that keeps clients in sync without polling.- Maintains persistent WebSocket connections with browser clients
- Subscribes to Redis pub/sub channels to receive events published by the Builder or Worker
- Broadcasts updates to the relevant connected clients in real time
- Reads application state from PostgreSQL when a client first connects
Redis
Redis serves three distinct roles in the system:| Role | Used by |
|---|---|
| Job queue (BullMQ) | Builder enqueues → Worker consumes |
| Pub/sub channel | Builder / Worker publish → PartySocket subscribes |
| Cache | Caches expensive queries and computed results |
PostgreSQL
PostgreSQL is the single source of truth for all persistent data.- Schema is managed and migrated with DrizzleORM
- Accessed by the Builder for request-time reads and writes
- Accessed by the Worker during background job execution
Storage
Storage holds all binary assets and generated files.- Compatible with any S3-compatible provider (AWS S3, MinIO, Cloudflare R2, etc.)
- The Builder uploads user files and retrieves signed URLs for serving
- The Worker reads source files and writes processed output during job execution