Skip to main content

Architecture Overview

Chatty AI system architecture, components, and service interactions.

Core Services​

PostgreSQL Database (db)​

Purpose: Primary application database for storing user data, conversations, configurations, and application state.

  • Type: PostgreSQL 16
  • User-Facing: No (internal only)
  • Persistent Data: Yes (critical)
  • Required: Yes

The PostgreSQL database stores all application data including user accounts, chat history, settings, and metadata.

Qdrant Vector Database​

Purpose: Vector storage and semantic search engine for retrieval-augmented generation (RAG).

  • Type: Qdrant latest
  • User-Facing: No (internal only)
  • Persistent Data: Yes (critical)
  • Required: Yes

Qdrant handles document embeddings, vector similarity search, and powers the knowledge retrieval capabilities of Chatty AI.

Application Services​

Chatty AI (chattyai)​

Purpose: Main application service providing the web UI, API, and core AI functionality.

  • Type: Custom application
  • User-Facing: Yes (via Nginx)
  • Persistent Data: Yes (uploaded files, configurations)
  • Required: Yes
  • Ports: 3000 (HTTP), 3001 (WebSocket)

This is the primary service users interact with. It handles authentication, chat sessions, file uploads, and orchestrates communication with other services.

Pipelines​

Purpose: AI pipeline processing service for specialized tasks.

  • Type: Custom service
  • User-Facing: No (internal only)
  • Persistent Data: Yes (pipeline data)
  • Required: Yes
  • Port: 9099 (internal)

Handles background AI processing tasks and pipeline execution.

Database Integration Services​

The Databases component provides natural language to SQL capabilities:

Databases Bootstrap (chattydatabases-bootstrap)​

Purpose: Initializes database agent data and configuration.

  • Type: Initialization service
  • User-Facing: No
  • Persistent Data: Yes (shared with other database services)
  • Required: Yes (for database features)

Databases Engine (chattydatabases-engine)​

Purpose: SQL execution engine for database queries.

  • Type: Query engine
  • User-Facing: No (internal only)
  • Persistent Data: No
  • Required: Yes (for database features)
  • Ports: 8080, 7432 (internal)

Databases Ibis (chattydatabases-ibis)​

Purpose: Data transformation and analysis layer.

  • Type: Python Ibis service
  • User-Facing: No (internal only)
  • Persistent Data: No
  • Required: Yes (for database features)
  • Port: 8000 (internal)

Databases AI Service (chattydatabases-ai-service)​

Purpose: AI-powered natural language to SQL translation.

  • Type: AI service
  • User-Facing: No (internal only)
  • Persistent Data: No
  • Required: Yes (for database features)
  • Port: 5555 (internal)

Connects to Qdrant for semantic understanding and uses LLM for query generation.

Databases UI (chattydatabases)​

Purpose: User interface for database interactions.

  • Type: Web UI
  • User-Facing: Yes (via Nginx)
  • Persistent Data: Yes (SQLite metadata)
  • Required: Yes (for database features)
  • Port: 3000 (internal)

Workflow Automation​

n8n​

Purpose: Workflow automation and integration platform.

  • Type: n8n workflow engine
  • User-Facing: Yes (via Nginx)
  • Persistent Data: Yes (workflows, credentials, execution history)
  • Required: Optional (but recommended)
  • Port: 5678

Enables users to create automated workflows, integrate with external services, and build custom automation.

Infrastructure Services​

Nginx Reverse Proxy​

Purpose: TLS termination and reverse proxy for all user-facing services.

  • Type: Nginx web server
  • User-Facing: Yes (entry point)
  • Persistent Data: No (certificates mounted from host)
  • Required: Yes
  • Ports: 80 (HTTP), 443 (HTTPS), 8000

Routes external traffic to internal services based on domain name:

  • Chatty AI main application
  • n8n workflows
  • Databases UI

Handles TLS/SSL certificates and provides secure HTTPS access.

Portainer Edge Agent​

Purpose: Remote stack management and monitoring (Portainer deployment only).

  • Type: Management agent
  • User-Facing: No (admin only)
  • Persistent Data: No
  • Required: Only for Portainer deployments

Enables centralized management of the Chatty AI stack through Portainer Server.

Service Dependencies​

User → Nginx → {chattyai, n8n, chattydatabases}
                    ↓
chattyai → {db, qdrant, pipelines}
           ↓
           chattydatabases-ai-service → qdrant
           
chattydatabases → {chattydatabases-engine, chattydatabases-ibis, chattydatabases-ai-service}

n8n → chattyai (API integration)

Data Persistence​

Services with persistent volumes:

  • db_data: PostgreSQL database
  • qdrant: Vector database storage
  • chattyai: Application data and uploads
  • pipelines: Pipeline data
  • n8n_data: Workflow definitions and history
  • chattydatabases_data: Database agent metadata