🛡️ AegisRAG - AI-Powered Document Q&A System

AegisRAG is a production-ready Retrieval-Augmented Generation (RAG) system with Role-Based Access Control (RBAC) that enables secure, intelligent question-answering over organizational documents. Built with modern async Python backend and a beautiful React frontend.

🌟 Overview

AegisRAG (Aegis + RAG) combines the protective power of "Aegis" (shield/protection) with Retrieval-Augmented Generation technology. This system merges the intelligence of Large Language Models (LLMs) with enterprise-grade security through role-based access control. Users can ask natural language questions about documents, and the AI assistant provides accurate answers based only on documents they have permission to access.

Key Features

• 🔐 JWT-based Authentication - Secure token-based authentication system
• 👥 Role-Based Access Control - 8 distinct roles with granular document permissions
• 🤖 Intelligent RAG System - Azure OpenAI-powered question answering
• 📚 Vector Search - ChromaDB for efficient semantic document retrieval
• 💬 Session Management - Persistent chat history per user
• 🎨 Modern UI - Beautiful, responsive React interface with Framer Motion animations
• ⚡ Async Architecture - High-performance async Python backend
• 🔄 Real-time Updates - Live document access and chat interactions

🏗️ Architecture

Backend Stack

• FastAPI - Modern async web framework
• Motor - Async MongoDB driver for user management
• ChromaDB - Vector database for document embeddings
• Azure OpenAI - LLM for intelligent responses
• Agno - Agent framework for RAG implementation
• JWT - Secure authentication tokens
• Bcrypt - Password hashing

Frontend Stack

• React 18 - Modern UI library
• TypeScript - Type-safe development
• Vite - Lightning-fast build tool
• TailwindCSS - Utility-first styling
• Framer Motion - Smooth animations
• Axios - HTTP client
• React Router - Client-side routing

Database & Storage

• MongoDB - User data and authentication
• ChromaDB - Vector embeddings storage
• SQLite - User session and chat history

📁 Project Structure

AegisRAG/
├── src/
│   ├── api/                    # FastAPI backend
│   │   ├── auth/              # Authentication endpoints
│   │   ├── routes/            # API routes (chat, documents)
│   │   ├── middleware/        # JWT verification
│   │   ├── schemas/           # Pydantic models
│   │   └── api.py             # Main FastAPI app
│   │
│   ├── db/                     # Database layer
│   │   ├── core/              # MongoDB connection
│   │   ├── auth/              # Password hashing
│   │   ├── models/            # User models
│   │   ├── repositories/      # Data access layer
│   │   └── setup/             # Database initialization
│   │
│   ├── rag/                    # RAG system
│   │   └── agent.py           # Agno agent with RBAC
│   │
│   └── frontend/               # React application
│       ├── src/
│       │   ├── components/    # React components
│       │   ├── context/       # Auth & Toast contexts
│       │   ├── pages/         # Login & Dashboard
│       │   ├── services/      # API client
│       │   ├── types/         # TypeScript types
│       │   └── utils/         # Helper functions
│       └── dist/              # Production build
│
├── docs/                       # Document repository
│   ├── hr_policy.md
│   ├── finance_report.md
│   ├── tech_update.md
│   ├── ai_research.md
│   ├── legal_compliance.md
│   ├── marketing_strategy.md
│   ├── sales_insights.md
│   ├── data_security.md
│   ├── product_roadmap.md
│   └── team_announcement.md
│
├── tmp/                        # Runtime data
│   ├── embeddings/            # ChromaDB storage
│   └── memory/                # SQLite sessions
│
├── main.py                     # CLI entry point
├── pyproject.toml             # Python dependencies
├── requirements.txt           # Pip requirements
└── render.yaml                # Deployment config

🚀 Getting Started

Prerequisites

• Python 3.13+
• Node.js 18+
• MongoDB instance
• Azure OpenAI API access

Environment Variables

Create a .env file in the root directory:

# MongoDB
MONGO_URI=mongodb+srv://username:[email protected]/database

# JWT Authentication
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Azure OpenAI - Main Model
AZURE_OPENAI_API_KEY=your-api-key
ENDPOINT=https://your-resource.openai.azure.com/
DEPLOYMENT=your-deployment-name
API_VERSION=2024-08-01-preview

# Azure OpenAI - Embeddings
EMBEDDING_API_KEY=your-embedding-key
EMBEDDING_ENDPOINT=https://your-resource.openai.azure.com/
EMBEDDING_DEPLOYMENT=text-embedding-3-small
EMBEDDING_API_VERSION=2024-08-01-preview

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000

Backend Setup

1. Install Python dependencies:

pip install -r requirements.txt

2. Initialize the database with sample users:

python -m src.db.setup.init_data

3. Start the FastAPI server:

uvicorn src.api.api:app --reload

The API will be available at http://localhost:8000

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Frontend Setup

1. Navigate to frontend directory:

cd src/frontend

2. Install dependencies:

npm install

3. Configure API endpoint: Create src/frontend/.env:

VITE_API_URL=http://localhost:8000

4. Start development server:

npm run dev

The frontend will be available at http://localhost:5173

CLI Usage

Run the interactive CLI:

python main.py

👥 User Roles & Access

The system includes 8 predefined roles with specific document access permissions:

Role	Document Access	Use Case
Admin	All 10 documents	Full system access
HR Manager	HR policies, announcements	Human resources management
Finance Analyst	Financial reports, compliance, sales	Financial analysis
Tech Engineer	Tech updates, security, AI research, roadmap	Engineering team
Marketing Lead	Marketing strategy, sales insights, roadmap	Marketing campaigns
Legal Officer	Legal compliance, data security	Legal compliance
Data Analyst	AI research, sales insights, marketing	Data analysis
General Employee	HR policies, announcements	Basic employee access

Test Credentials

The system comes with pre-configured test users:

Admin:
- Username: rajesh_admin
- Password: admin123

HR Manager:
- Username: anjali_hr
- Password: hr123456

Finance Analyst:
- Username: priya_finance
- Password: finance123

Tech Engineer:
- Username: karthik_tech
- Password: tech123

Marketing Lead:
- Username: neha_marketing
- Password: marketing123

Legal Officer:
- Username: vikram_legal
- Password: legal123

Data Analyst:
- Username: sneha_data
- Password: data123

General Employee:
- Username: amit_employee
- Password: employee123

📚 Document Repository

The system includes 10 sample documents covering various organizational topics:

1. hr_policy.md - HR policies and guidelines
2. team_announcement.md - Company announcements
3. data_security.md - Security protocols
4. finance_report.md - Financial reports
5. tech_update.md - Technical updates
6. ai_research.md - AI research findings
7. legal_compliance.md - Legal compliance documents
8. sales_insights.md - Sales data and insights
9. marketing_strategy.md - Marketing strategies
10. product_roadmap.md - Product development plans

🔌 API Endpoints

Authentication

• POST /auth/login - User login (returns JWT token)
• POST /auth/register - Register new user (admin only)

Chat & Documents

• POST /chat/query - Ask questions (requires authentication)
• GET /chat/accessible-documents - Get user's accessible documents
• POST /chat/clear-session - Clear chat history

System

• GET / - API information
• GET /health - Health check

🎨 Frontend Features

Login Page

• Beautiful gradient animations
• Secure JWT authentication
• Test credentials display
• Responsive design

Dashboard

• Real-time chat interface
• Document sidebar with access list
• User profile display
• Session management
• Smooth animations and transitions

Components

• ChatInterface - Main chat component with message history
• DocumentsSidebar - Shows accessible documents
• Header - User info and navigation
• ProtectedRoute - Route authentication guard
• ToastContainer - Notification system

🔒 Security Features

• JWT Authentication - Secure token-based auth with expiration
• Password Hashing - Bcrypt with salt rounds
• Role Validation - Server-side permission checks
• CORS Protection - Configurable CORS middleware
• Input Validation - Pydantic schema validation
• SQL Injection Prevention - Parameterized queries
• XSS Protection - React's built-in XSS prevention

🚢 Deployment

Backend (Render)

The project includes a render.yaml configuration for easy deployment:

# Push to GitHub and connect to Render
# Render will automatically deploy using render.yaml

Frontend (Vercel)

cd src/frontend
npm run build
# Deploy dist/ folder to Vercel

Or use the included vercel.json configuration for automatic deployment.

🧪 Development

Run Tests

pytest

Type Checking (Frontend)

cd src/frontend
npm run type-check

Linting (Frontend)

cd src/frontend
npm run lint

Build Production (Frontend)

cd src/frontend
npm run build

📊 How It Works

1. User Authentication

   • User logs in with credentials
   • Backend validates and returns JWT token
   • Token includes user role information

2. Document Loading

   • Documents are embedded using Azure OpenAI embeddings
   • Stored in ChromaDB with role-based metadata
   • Embeddings are cached to reduce API costs

3. Question Answering

   • User asks a question
   • System searches ChromaDB with role filters
   • Only documents user has access to are searched
   • Azure OpenAI generates answer from retrieved context
   • Response includes source citations

4. Session Management

   • Chat history stored in SQLite per user
   • Context maintained across conversations
   • Sessions can be cleared by user

🛠️ Technology Highlights

Async Architecture

• Fully async Python backend using asyncio
• Non-blocking database operations with Motor
• Concurrent request handling

Vector Search

• Semantic search using embeddings
• Efficient similarity search with ChromaDB
• Role-based filtering at vector level

Agent Framework

• Agno framework for RAG implementation
• Tool-based architecture for extensibility
• Built-in memory and context management

Modern Frontend

• React 18 with hooks
• TypeScript for type safety
• Framer Motion for animations
• TailwindCSS for styling
• Vite for fast builds

📝 License

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions, please open an issue on GitHub.

---

AegisRAG - Built with ❤️ using Agno, FastAPI, and React