Chatty

Chatty is a multi-tenant AI chat platform built as a public-ready monorepo. It combines a Spring Boot SaaS backend, a Python RAG processing service, PostgreSQL with vector search, Kafka-based asynchronous workflows, and infrastructure automation for provisioning and deployment.

The platform is designed for embeddable website chat, tenant-isolated knowledge bases, document ingestion, site and bot management, and production deployment workflows that go beyond a demo app.

Highlights

• Embeddable AI chat widget for websites and customer-facing experiences
• Multi-tenant architecture with site-level isolation, API keys, and per-site RAG data
• Document ingestion pipeline using S3-compatible storage, Kafka, and Python processing
• Retrieval-augmented generation (RAG) with LightRAG and PostgreSQL-backed metadata
• Spring AI integration with OpenAI and optional Ollama support in development
• Admin workflows for sites, uploads, bots, users, and billing-related features
• Infrastructure automation with Terraform and Ansible
• Operational tooling for JVM tuning and production diagnostics

Monorepo Structure

.
├── chattyspring/   # Spring Boot application, UI, REST APIs, auth, billing, uploads
├── chattypython/   # Python RAG worker, Kafka consumer, document/query processing
├── infra/          # Terraform + Ansible for provisioning and server configuration
├── scripts/        # Production tuning and operational helper scripts

System Architecture

Core services

chattyspring/

The primary application is a Spring Boot 3.4 service using Java 24. It handles:

• tenant and site management
• user authentication and dashboard flows
• chat APIs and widget configuration
• upload registration and orchestration
• Kafka message publishing for asynchronous work
• integrations with OpenAI, AWS S3, AWS SES, Stripe, and PostgreSQL

Key technologies visible in the repo include:

• Spring Boot 3.4.6
• Spring Security
• Spring Data JPA
• Spring AI
• Spring Kafka
• Flyway
• PostgreSQL / pgvector
• Thymeleaf
• Stripe Java SDK
• Testcontainers, Cucumber, Selenium

chattypython/

The Python service is the document-processing and query-execution worker. It consumes Kafka messages, downloads documents, builds tenant-specific RAG state, and writes query/upload results back through PostgreSQL-backed workflows.

Responsibilities include:

• consuming upload-topic and query-topic
• processing uploaded files from object storage
• maintaining per-site RAG data under rag_data/{site_id}/
• running LightRAG-powered search and knowledge retrieval
• updating processing state and results in the shared data layer

Key technologies visible in the repo include:

• Python
• Quix Streams
• LightRAG
• OpenAI SDK
• psycopg2
• boto3
• tiktoken

Data and message flow

1. A site owner configures a tenant/site in the Spring app.
2. End users interact with the embeddable widget or bot endpoints.
3. Document uploads are registered by the Spring service and stored in S3-compatible storage.
4. Spring publishes processing jobs to Kafka.
5. The Python worker consumes messages, downloads content, builds or updates the tenant knowledge base, and processes queries.
6. PostgreSQL stores application data, query state, and vector-enabled retrieval metadata.
7. Responses flow back through the application to dashboards or chat clients.

Infrastructure and Deployment

The infra/ directory shows this project is not only an application repo but also an operations/deployment repo.

Terraform

infra/terraform/ provisions a DigitalOcean-based deployment footprint with:

• a VPC
• a firewall
• a web/database droplet
• a Kafka droplet
• a processing droplet

This reflects a split-node architecture where the web app, messaging layer, and Python processing service are isolated operationally.

Ansible

infra/ansible/ configures the provisioned servers, including:

• Java installation for the Spring service
• Python 3.12 runtime and virtual environment for the worker
• PostgreSQL setup
• Kafka KRaft node configuration
• Nginx reverse proxy and TLS with Certbot
• systemd services for the application processes
• environment file templating for service configuration

Scripts

scripts/production-tuning.sh and scripts/production-tuning.md capture operational work around JVM tuning, health checks, restart monitoring, and failure analysis for the Spring Boot service.

Local Development

Prerequisites

Minimum practical setup based on the repository:

• Java 24+
• Maven 3.9+
• Python 3.11+ for local development
• Docker / Docker Compose
• PostgreSQL with pgvector
• Kafka
• OpenAI API key
• AWS S3-compatible credentials for upload flows

Recommended startup flow

The repo currently centers local infrastructure around chattyspring/.

1. Copy the example env files to local, untracked files and fill in your own credentials.
2. Start infrastructure dependencies.
3. Run the Python worker.
4. Run the Spring Boot application.

Example flow:

cd chattyspring
cp .env.example .env
${EDITOR:-vi} .env
set -a
source .env
set +a
docker-compose up -d

In another terminal:

cd chattypython
cp .env.example .env
${EDITOR:-vi} .env
set -a
source .env
set +a
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

In another terminal:

cd chattyspring
./mvnw spring-boot:run

Testing

Spring Boot tests:

cd chattyspring
./mvnw test

Coverage report:

cd chattyspring
./mvnw test jacoco:report

Python tests:

cd chattypython
python -m unittest discover tests/

Key Product Capabilities

• Embeddable chat: inject a client widget into external websites
• Multi-tenant isolation: keep site-specific configuration and knowledge separated
• RAG ingestion: upload PDFs and other documents for contextual AI answers
• Asynchronous processing: decouple ingestion/query work with Kafka
• Bot management: manage model, prompts, greetings, and publishing state
• Operational readiness: include deployment automation and server tuning guidance

Why This Repo Is Interesting

This monorepo demonstrates end-to-end product ownership across:

• backend application design
• AI/RAG workflows
• multi-service orchestration
• async messaging patterns
• infrastructure as code
• Linux service deployment
• observability and runtime tuning
• testing across unit, integration, and browser-driven scenarios