RAGio

AI-powered document analysis with retrieval-augmented generation

Upload documents, search across their contents, and ask grounded questions with source-aware answers.

Quick start · Features · Architecture · Configuration · API

---

Product tour

Watch the short product walkthrough:

Landing page

Login and registration

Workspace and document management

Chat and document viewer

---

Overview

RAGio is a full-stack document intelligence workspace. It combines document ingestion, local indexing, hybrid retrieval, re-ranking, and an OpenAI-compatible chat provider so answers can be grounded in the documents a user has uploaded.

The application supports:

• PDF, CSV, TXT, and Markdown document workflows
• Single-document and multi-document conversations
• Semantic and sparse retrieval through Qdrant
• Source metadata and page-aware document references
• Background document processing with Celery
• JWT authentication with access and refresh tokens
• Local object storage through MinIO
• Health checks, metrics, logs, and Flower task monitoring

Features

Document intelligence

• Upload and manage documents per authenticated user
• Process documents asynchronously before they become available for chat
• Chunk and embed content for retrieval
• Combine dense vector search with sparse/BM25 retrieval
• Re-rank candidate passages and verify context with cross-encoder models
• Assemble deduplicated context for the final answer
• Show the documents and pages that contributed to a response

Conversation experience

• General chat across all processed documents
• Document-specific conversations
• Conversation history and separate conversation context
• Suggested questions and document summaries
• Markdown rendering with tables and syntax highlighting
• Built-in PDF, CSV, TXT, and Markdown viewers

Reliability and security

• JWT access and refresh-token authentication
• Per-user document ownership checks
• Request rate limiting and chat quotas
• Sanitized user-facing AI errors; provider details remain in backend logs
• Optional cross-provider LLM fallback for provider outages or rate limits
• Environment files excluded from Git by default

Technology stack

Layer	Technologies
Frontend	React 18, React Router, Axios, Zustand, React Hook Form, Tailwind CSS
API	FastAPI, Uvicorn, SQLAlchemy, Pydantic settings
Data	PostgreSQL, Qdrant, MinIO, Redis
Workers	Celery and Flower
Retrieval	Sentence Transformers, sparse retrieval, re-ranking, cross-encoder verification
Generation	Mistral API by default; optional Groq and Gemini OpenAI-compatible fallbacks
Operations	Docker Compose, Prometheus metrics, Loki-compatible logs, Grafana

Architecture

At a high level, a chat request follows this path:

1. The React client sends an authenticated question to the FastAPI API.
2. The backend identifies the user’s selected documents.
3. The retrieval pipeline searches Qdrant and the sparse index.
4. Candidate chunks are re-ranked and verified.
5. The assembled context and conversation memory are sent to the configured LLM provider.
6. The response is returned with source metadata and persisted in PostgreSQL.

The local Docker stack contains:

Service	Purpose	Host address
frontend	React application served by Nginx	http://localhost:3003
backend	FastAPI API and RAG orchestration	http://localhost:8088
postgres	Users, files, and conversations	localhost:5432
redis	Celery broker and result backend	localhost:6379
minio	S3-compatible document storage	http://localhost:9000
MinIO console	Object-storage administration	http://localhost:9001
qdrant	Vector search	http://localhost:6333
Flower	Celery monitoring	http://localhost:5555

Ports are configurable in the root .env.local file.

Prerequisites

For the recommended Docker workflow:

• Docker Engine with Docker Compose v2
• Git
• At least 8 GB RAM; 16 GB is recommended for model loading
• At least 10 GB of free disk space for images, Python dependencies, and model cache

For direct development without the complete Docker helper:

• Python 3.12+
• Node.js 18+
• npm

Quick start

Clone the repository and start the complete local stack:

git clone https://github.com/simoderyouch/RAGio.git
cd RAGio

chmod +x ragio
./ragio start

The first build may take several minutes because the backend image installs Python and ML dependencies.

Open:

• Application: http://localhost:3003
• API documentation: http://localhost:8088/docs
• ReDoc: http://localhost:8088/redoc
• Flower: http://localhost:5555
• MinIO console: http://localhost:9001

The helper supports:

./ragio start              # Build and start the full stack
./ragio start --no-build   # Start using existing images
./ragio status             # Show service status
./ragio logs               # Follow all service logs
./ragio logs backend       # Follow backend logs only
./ragio stop               # Stop containers and keep volumes
./ragio restart            # Restart the running stack
./ragio down               # Remove containers/network, keep volumes

Configuration

Local Docker configuration

On first start, ragio creates the ignored root file .env.local from .env.local.example.

For Docker, configure the root file:

/home/edder/Documents/Personal Projects/RAGio/.env.local

Do not commit this file. It can contain database passwords, JWT secrets, and provider API keys.

The important AI settings are:

MISTRAL_API_KEY=your_mistral_key
MISTRAL_BASE_URL=https://api.mistral.ai/v1
MISTRAL_MODEL=mistral-small-latest
MISTRAL_FALLBACK_MODELS=mistral-medium-latest

RAGio can also fall back to other OpenAI-compatible providers. Add one or both keys if needed:

# Optional Groq fallback
GROQ_API_KEY=your_groq_key
GROQ_BASE_URL=https://api.groq.com/openai/v1
GROQ_MODEL=openai/gpt-oss-20b

# Optional Gemini fallback
GEMINI_API_KEY=your_gemini_key
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
GEMINI_MODEL=gemini-3.1-flash-lite

Fallback order is:

Mistral primary → Mistral fallback models → Groq → Gemini

Providers are only enabled when their API key is non-empty. A provider 429 is logged for operators, while users receive a safe retry message without raw provider payloads.

Direct backend development

If you run the backend outside the local Docker helper, use backend/.env:

cd backend
python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python start.py

The direct backend listens on port 8080 unless configured otherwise. The Docker workflow uses the root .env.local and publishes the backend on port 8088 by default.

Frontend development

To run the React development server separately:

cd frontend
npm install
cp .env.example .env
npm start

Do not run the development server and the Docker frontend on the same host port at the same time. If port 3003 is already occupied, stop the existing React process or change HTTP_PORT in .env.local.

Environment and secret safety

The repository ignores local environment files:

• .env
• .env.local
• backend/.env
• frontend/.env

Only example files with placeholders should be committed:

• .env.local.example
• backend/.env.example
• frontend/.env.example

Before committing, check for accidental secrets:

git status --short --ignored
git diff --cached --name-only
git grep -n -I -E 'AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]+PRIVATE KEY-----|sk-[A-Za-z0-9_-]{20,}' -- ':!*.lock' || true

Never paste a real API key into the README, an example file, a screenshot, a video, or source code. If a key has been committed accidentally, revoke it at the provider immediately and remove it from the entire Git history.

API overview

The API is available at /api on the backend host.

Authentication

POST /api/auth/register
POST /api/auth/login
POST /api/auth/refresh
POST /api/auth/logout

Documents

POST   /api/document/upload
GET    /api/document/files
GET    /api/document/{id}
DELETE /api/document/{id}
GET    /api/document/{id}/download

Chat

POST /api/chat/{file_id}
POST /api/chat/general
GET  /api/chat/documents/{file_id}/conversations
GET  /api/chat/general/conversations

Health and metrics

GET /api/health/
GET /api/health/detailed
GET /api/health/metrics
GET /metrics

Swagger UI and ReDoc are generated automatically by FastAPI:

• http://localhost:8088/docs
• http://localhost:8088/redoc

Monitoring and operations

Use the helper while developing:

./ragio status
./ragio logs backend
./ragio logs celery_worker_documents

The stack exposes health checks for the backend and dependencies. Prometheus-compatible metrics are available at /metrics; Flower provides a browser view of Celery tasks.

For a clean local reset that keeps named Docker volumes, use:

./ragio down
./ragio start

Do not remove Docker volumes unless you intentionally want to delete local PostgreSQL, MinIO, Redis, or Qdrant data.

Testing and verification

Frontend production build:

cd frontend
npm run build

Backend tests:

cd backend
pytest

Basic health check:

curl http://localhost:8088/api/health/

Project structure

RAGio/
├── assets/                         # README logo, screenshots, architecture, and demo video
├── backend/
│   ├── app/
│   │   ├── db/                     # Database models and connections
│   │   ├── middleware/             # Error, tracing, performance, and rate limiting
│   │   ├── routes/                 # Auth, document, chat, health, and metrics APIs
│   │   ├── services/               # RAG, retrieval, chat, quotas, and document services
│   │   ├── tasks/                  # Celery background tasks
│   │   └── utils/                  # LLM, logging, auth, sanitization, and helpers
│   ├── migrations/                 # Alembic migrations
│   ├── tests/                      # Backend tests
│   ├── Dockerfile.local            # Local backend image
│   ├── docker-compose.yml          # Backend-focused Compose setup
│   ├── docker-compose.prod.yml     # Production Compose setup
│   ├── requirements.txt
│   └── .env.example                # Safe configuration template
├── frontend/
│   ├── public/                     # Browser metadata and favicons
│   ├── src/components/             # Pages, chat, viewers, and shared UI
│   ├── src/hooks/                  # API and refresh-token hooks
│   ├── src/stores/                 # Zustand stores
│   ├── package.json
│   └── .env.example                # Safe frontend template
├── docker-compose.local.yml        # Complete local stack
├── .env.local.example              # Safe local Docker template
├── ragio                            # Local Docker workflow helper
└── README.md

Contributing

1. Create a feature branch.
2. Keep secrets and local environment files out of Git.
3. Add or update tests for backend behavior.
4. Run the frontend build and relevant backend tests.
5. Update the README when setup, ports, APIs, or architecture change.
6. Open a pull request with a focused description.

License

RAGio is released under the MIT License. See LICENSE.

Support

• Issues: https://github.com/simoderyouch/RAGio/issues
• Discussions: https://github.com/simoderyouch/RAGio/discussions

Built with React, FastAPI, PostgreSQL, Redis, Qdrant, MinIO, Celery, and open LLM tooling.