RAG Chat Storage

A Spring Boot microservice designed to store and manage chat histories generated by RAG (Retrieval-Augmented Generation) based chatbot systems. This service provides RESTful APIs for managing chat sessions and messages with features like pagination, search, favorites, and comprehensive statistics.

Features

• Chat Session Management: Create, read, update, and delete chat sessions
• Message Management: Add, retrieve, and delete messages within sessions
• User Isolation: All data is scoped to authenticated users
• Search & Filtering: Search sessions by name and filter messages by sender type
• Pagination: Efficient pagination for large datasets
• Favorites: Mark sessions as favorites for quick access
• Statistics: Get comprehensive statistics about user sessions
• Rate Limiting: Built-in rate limiting to prevent abuse
• Security: OAuth2 JWT-based authentication
• API Documentation: Interactive Swagger UI documentation
• Health Checks: Built-in health monitoring endpoints
• Docker Support: Fully containerized with Docker Compose

Technology Stack

• Java 17
• Spring Boot 3.3.5
• Spring Data JPA
• PostgreSQL 15
• Spring Security with OAuth2
• OpenAPI 3 (Swagger)
• Maven
• Docker & Docker Compose

Quick Start with Docker (Recommended)

Prerequisites

• Docker and Docker Compose installed on your system
• Git (to clone the repository)

1. Clone the Repository

git clone <repository-url>
cd rag-chat-storage

2. Run with Docker Compose

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up --build -d

This will start:

• Application: http://localhost:8080
• Database: PostgreSQL on port 5432
• PgAdmin: http://localhost:8081 (admin@example.com / admin123)

3. Access the Application

• API Base URL: http://localhost:8080/v3/api-docs
• Swagger UI: http://localhost:8080/swagger-ui/index.html
• Health Check: http://localhost:8080/actuator/health
• PgAdmin: http://localhost:8081
• name: postgres-docker

4. Stop the Services

docker-compose down

Manual Setup (Development)

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher
• PostgreSQL 15 or higher
• Git

1. Database Setup

# Create PostgreSQL database
createdb ragdb

# Create user (optional, uses default credentials)
psql ragdb
CREATE USER raguser WITH PASSWORD 'ragpass';
GRANT ALL PRIVILEGES ON DATABASE ragdb TO raguser;

2. Configuration

The application uses the following default configuration (in application.yaml):

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/ragdb
    username: raguser
    password: ragpass
  jpa:
    hibernate:
      ddl-auto: update

3. Build and Run

# Clone the repository
git clone <repository-url>
cd rag-chat-storage

# Build the application
mvn clean package

# Run the application
mvn spring-boot:run

# Or run the JAR directly
java -jar target/rag-chat-storage-0.0.1-SNAPSHOT.jar

API Endpoints

Chat Sessions

Method	Endpoint	Description
POST	/api/v1/sessions	Create a new chat session
GET	/api/v1/sessions	Get all chat sessions
GET	/api/v1/sessions/paginated	Get sessions with pagination
GET	/api/v1/sessions/{id}	Get a specific session
PUT	/api/v1/sessions/{id}	Update a session
DELETE	/api/v1/sessions/{id}	Delete a session
PATCH	/api/v1/sessions/{id}/favorite	Toggle favorite status
GET	/api/v1/sessions/favorites	Get favorite sessions
GET	/api/v1/sessions/search?q={term}	Search sessions
GET	/api/v1/sessions/stats	Get session statistics

Chat Messages

Method	Endpoint	Description
POST	/api/v1/sessions/{id}/messages	Add a message to session
GET	/api/v1/sessions/{id}/messages	Get all messages in session
GET	/api/v1/sessions/{id}/messages/paginated	Get messages with pagination
GET	/api/v1/sessions/{id}/messages/{msgId}	Get a specific message
DELETE	/api/v1/sessions/{id}/messages/{msgId}	Delete a message
GET	/api/v1/sessions/{id}/messages/latest?limit={n}	Get latest N messages
GET	/api/v1/sessions/{id}/messages/by-sender/{type}	Get messages by sender type
GET	/api/v1/sessions/{id}/messages/count	Get message count

Authentication

The application uses OAuth2 JWT-based authentication. All API requests require:

1. Authorization Header: Bearer <jwt-token>
2. User ID Header: X-User-ID: <user-id>

Example Request

curl -X GET "http://localhost:8080/api/v1/sessions" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-User-ID: user123"

Data Models

ChatSession

{
  "id": 1,
  "userId": "user123",
  "name": "My Chat Session",
  "isFavorite": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

ChatMessage

{
  "id": 1,
  "senderType": "USER",
  "content": "Hello, how are you?",
  "context": "Additional context information",
  "createdAt": "2024-01-15T10:30:00Z"
}

Message Sender Types

• USER: Messages sent by the user
• ASSISTANT: Messages sent by the AI assistant

Environment Variables

Docker Compose

You can customize the configuration using environment variables:

# Database Configuration
export POSTGRES_DB=ragdb
export POSTGRES_USER=raguser
export POSTGRES_PASSWORD=ragpass

# PgAdmin Configuration
export PGADMIN_EMAIL=admin@example.com
export PGADMIN_PASSWORD=admin123

# Application Configuration
export PORT=8080

Application Properties

The application supports the following environment variables:

• SPRING_DATASOURCE_URL: Database connection URL
• SPRING_DATASOURCE_USERNAME: Database username
• SPRING_DATASOURCE_PASSWORD: Database password
• PORT: Application port (default: 8080)
• SPRING_PROFILES_ACTIVE: Active Spring profile

Development

Project Structure

src/
├── main/
│   ├── java/
│   │   └── bytecode/rag_chat_storage/
│   │       ├── config/          # Configuration classes
│   │       ├── controller/      # REST controllers
│   │       ├── dto/            # Data Transfer Objects
│   │       ├── entity/         # JPA entities
│   │       ├── exception/      # Exception handling
│   │       ├── interceptor/    # Request interceptors
│   │       ├── repository/     # Data repositories
│   │       └── service/        # Business logic
│   └── resources/
│       └── application.yaml    # Application configuration
└── test/                       # Test classes

Running Tests

# Run all tests
mvn test

# Run tests with coverage
mvn test jacoco:report

Building for Production

# Build with production profile
mvn clean package -Pprod

# Or build with Docker
docker build -t rag-chat-storage .

Monitoring and Health Checks

The application includes Spring Boot Actuator for monitoring:

• Health Check: /actuator/health
• Application Info: /actuator/info
• Metrics: /actuator/metrics

Docker Health Checks

Both the database and application containers include health checks:

• Database: Checks PostgreSQL readiness
• Application: Checks HTTP endpoint availability

Troubleshooting

Common Issues

1. Database Connection Failed

   • Ensure PostgreSQL is running
   • Check database credentials
   • Verify network connectivity in Docker

2. Port Already in Use

   • Change the port in docker-compose.yml or application.yaml
   • Stop conflicting services

3. Authentication Issues

   • Verify JWT token is valid
   • Check OAuth2 configuration
   • Ensure X-User-ID header is provided

Logs

# View application logs
docker-compose logs app

# View database logs
docker-compose logs db

# Follow logs in real-time
docker-compose logs -f app

License

This project is licensed under the MIT License - see the LICENSE file for details.