Skip to content

Danor93/Clarticle

BranchesTags

Repository files navigation

Clarticle - AI-Powered RAG Chat System

Clarticle is a RAG (Retrieval-Augmented Generation) chat system that enables intelligent conversations about your article collection using Claude AI.

🏗️ Architecture Overview

Clarticle uses a hybrid microservices architecture combining Go and Node.js for optimal performance:

%%{init: {'flowchart': {'htmlLabels': false}, 'securityLevel': 'loose'}}%%
graph TD
    subgraph "Clarticle Frontend"
        A[React Client]
    end

    A <--> |HTTP/API| B

    subgraph "Clarticle Backend Services"
        B[Go API Gateway]
        B <--> |HTTP| C
        B --> |Cache| D[Redis Cache]
        C[Node.js RAG Service]
        C <--> |Embeddings| E[FAISS Vector Store]
        C <--> |API| F[Claude AI API]
        C --> |Fetch & Process| G[Web Articles]
    end

    subgraph "Data Layer"
        E --> H[Local Vector Storage]
        I[articles.json]
        J[PostgreSQL Database]
    end

    I --> |Load on Startup| C
    B <--> |SQL| J

    style A fill:#61dafb,stroke:#21262d,stroke-width:2px,color:#000
    style B fill:#0969da,stroke:#21262d,stroke-width:2px,color:#fff
    style C fill:#2ea043,stroke:#21262d,stroke-width:2px,color:#fff
    style D fill:#cf222e,stroke:#21262d,stroke-width:2px,color:#fff
    style J fill:#336791,stroke:#21262d,stroke-width:2px,color:#fff
    style F fill:#fb8500,stroke:#21262d,stroke-width:2px,color:#000
    style G fill:#6e7781,stroke:#21262d,stroke-width:2px,color:#fff
    style I fill:#6e7781,stroke:#21262d,stroke-width:2px,color:#fff
Loading

📁 Project Structure

Article-Chat/
├── client/                      # React frontend application
│   ├── src/
│   │   ├── components/          # React components
│   │   │   ├── ui/              # shadcn/ui components
│   │   │   ├── ChatInterface.tsx
│   │   │   ├── ArticleManager.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── theme-provider.tsx
│   │   │   └── theme-toggle.tsx
│   │   ├── lib/                 # Utilities and API client
│   │   │   ├── api.ts
│   │   │   └── utils.ts
│   │   ├── App.tsx              # Main app component
│   │   ├── main.tsx             # Entry point
│   │   └── index.css            # Global styles
│   ├── package.json
│   ├── vite.config.ts           # Vite configuration
│   ├── tailwind.config.js       # Tailwind CSS config
│   └── README.md                # Frontend documentation
│
├── server/                      # Go backend (API Gateway)
│   ├── cmd/
│   │   └── api/
│   │       └── main.go          # Entry point
│   ├── internal/                # Private packages
│   │   ├── config/              # Configuration management
│   │   ├── handlers/            # HTTP handlers
│   │   ├── middleware/          # HTTP middleware
│   │   ├── models/              # Data models
│   │   ├── services/            # Business logic
│   │   │   ├── rag_client.go    # RAG service client
│   │   │   └── cache.go         # Redis cache service
│   │   ├── validation/          # Input validation
│   │   ├── errors/              # Error handling
│   │   └── workers/             # Worker pools
│   ├── go.mod
│   ├── go.sum
│   └── README.md                # Backend documentation
│
├── rag-service/                 # Node.js RAG service
│   ├── src/
│   │   ├── services/            # Core services
│   │   │   ├── claude.service.ts
│   │   │   ├── embeddings.service.ts
│   │   │   ├── faiss-vectorstore.service.ts
│   │   │   └── langchain.service.ts
│   │   ├── routes/              # API routes
│   │   │   ├── chat.routes.ts
│   │   │   └── articles.routes.ts
│   │   ├── middleware/          # Express middleware
│   │   ├── utils/               # Utilities
│   │   │   ├── errors.ts
│   │   │   └── startup-loader.ts
│   │   └── index.ts             # Entry point
│   ├── package.json
│   ├── tsconfig.json
│   ├── nodemon.json             # Nodemon config
│   └── README.md                # RAG service documentation
│
├── data/                        # Data directory
│   ├── articles.json            # Initial articles list
│   └── faiss_store/             # Vector store (generated)
│
├── docker-compose.yml           # Docker orchestration
├── client.Dockerfile            # Frontend container
├── server.Dockerfile            # Backend container
├── rag-service.Dockerfile       # RAG service container
├── nginx.conf                   # Nginx configuration for frontend
├── README.md                    # This file
├── INSTALL.md                   # Installation guide

🛠️ Technology Stack

Frontend

  • React 19 with TypeScript
  • Vite for build tooling
  • shadcn/ui component library
  • Tailwind CSS v4 for styling

Backend (API Gateway)

  • Go 1.24+ with Fiber framework
  • PostgreSQL 15 for user authentication and data persistence
  • Worker pools for concurrent request handling
  • Redis for response caching
  • Structured logging with slog

RAG Service

  • Node.js 20+ with Express
  • LangChain.js for RAG pipeline
  • Claude AI (Anthropic) for language model
  • FAISS for local vector storage
  • HuggingFace Transformers for embeddings

Infrastructure

  • Docker & Docker Compose for containerization
  • Multi-stage builds for optimized images
  • PostgreSQL Alpine for lightweight database container

✨ Key Features

  • User Authentication: Secure user registration, login, and session management
  • Intelligent Chat: Ask questions about your articles and get contextual answers
  • Conversation History: Persistent chat history with conversation management
  • Article Management: Add articles via URL for processing
  • Local Embeddings: Free embeddings using HuggingFace models
  • Response Caching: Lightning-fast repeated queries with Redis
  • Professional UI: Claude/ChatGPT-style interface with animations
  • Error Handling: Comprehensive error handling with detailed error codes
  • Concurrent Processing: Handle multiple users simultaneously

🚀 Quick Start

For detailed installation instructions, see INSTALL.md.

# Clone repository
git clone https://github.com/Danor93/Clarticle.git
cd Clarticle

# Setup environment
cp server/.env.example server/.env
cp rag-service/.env.example rag-service/.env
cp client/.env.example client/.env

# Add your Anthropic API key to rag-service/.env
# ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Start services
docker-compose up --build

# Access application
open http://localhost:3000

📋 Requirements

  • Docker Desktop
  • Anthropic Claude API key
  • 4GB+ RAM recommended
  • Modern web browser

🎯 How It Works

  1. Article Processing: Add articles via URL → Text extraction → Chunking → Embedding generation → Vector storage
  2. Chat Flow: User question → Vector search → Relevant context retrieval → Claude AI generation → Response
  3. Caching: Repeated questions are cached for instant responses

🔧 Configuration

Key environment variables:

  • ANTHROPIC_API_KEY: Your Claude API key (required)
  • CLAUDE_MODEL: Model selection (default: claude-3-7-sonnet-latest)
  • CHUNK_SIZE: Text chunk size for embeddings (default: 1000)
  • RAG_SEARCH_RESULTS: Number of context chunks to retrieve (default: 4)

📊 Performance

  • Response Time: 5-8 seconds (first query), <100ms (cached)
  • Concurrent Users: 10-50 supported
  • Article Processing: 6-8 chunks per article
  • Cache Hit Rate: ~40% in typical usage

🔮 Future Enhancements

Potential features for extended development:

  • Streaming Responses: Real-time response streaming
  • Advanced Analytics: User engagement metrics and conversation analytics
  • Multi-tenant Support: Organization and team management
  • Testing Suite: Unit and integration tests
  • K8s Deployment: Kubernetes manifests and CI/CD pipelines

About

Clarticle - Intelligent chat system for conversations about articles using RAG with Claude AI. Hybrid Go + Node.js backend, React frontend. Features article processing, vector search, and contextually accurate AI responses.

Topics

rag article-analysis claude-ai retrieval-augmented-generation

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages