Querio

AI-Powered Document Intelligence Platform

A modern, production-ready frontend for intelligent document querying powered by RAG (Retrieval-Augmented Generation) technology

Features • Quick Start • Documentation • Contributing

📑 Table of Contents

Overview
Features
Tech Stack
Prerequisites
Quick Start
Project Structure
Environment Variables
Development
Design System
API Integration
Building for Production
Deployment
Contributing
License

🎯 Overview

Querio is a cutting-edge frontend application that provides an intuitive interface for interacting with AI-powered document intelligence. Built with the latest web technologies, it features a stunning glassmorphism UI, real-time chat capabilities, semantic search, and comprehensive document management.

Key Highlights

🎨 Modern Design - Beautiful glassmorphism UI with smooth animations
⚡ Performance - Built with Next.js 16 for optimal speed and SEO
🤖 AI-Powered - Intelligent document querying using RAG technology
📱 Responsive - Fully responsive design for all devices
🔄 Real-time - Live updates and interactive chat interface
🎭 Type-Safe - Full TypeScript implementation

✨ Features

📊 Dashboard

System overview with real-time statistics
Quick actions for common tasks
Visual analytics and metrics
API health monitoring

💬 Chat Interface

Conversational AI with context awareness
Session management and history
Real-time message streaming
Markdown support for rich formatting

📄 Document Management

Drag-and-drop file upload
PDF document support
Document preview and metadata
Bulk upload capabilities
Delete and manage documents

🔍 Semantic Search

AI-powered document search
Similarity-based results
Relevance scoring
Context-aware search results

📤 File Upload

Multi-file upload support
Drag-and-drop interface
Upload progress tracking
File type validation
Automatic document processing

🔧 System Monitoring

API health status
Real-time statistics
Performance metrics
Connection monitoring

🛠 Tech Stack

Core Framework

Next.js 16 - React framework with App Router
React 19 - UI library with latest features
TypeScript 5 - Type-safe development

Styling & UI

Tailwind CSS 4 - Utility-first CSS framework
Framer Motion - Animation library
Lucide React - Beautiful icon library

State Management

TanStack Query - Data fetching and caching
Zustand - Lightweight state management

Data & API

Axios - HTTP client
React Hot Toast - Notifications

File Handling

React Dropzone - File upload
React Markdown - Markdown rendering

Utilities

clsx - Conditional classnames
tailwind-merge - Tailwind class merging

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18.0.0 (Download)
pnpm >= 8.0.0 (recommended) or npm >= 9.0.0
Querio API Backend running on http://localhost:8000

Installing pnpm (Recommended)

npm install -g pnpm

🚀 Quick Start

1️⃣ Clone the Repository

git clone https://github.com/paradocx96/querio-app.git
cd querio-app

2️⃣ Install Dependencies

pnpm install

3️⃣ Configure Environment

# Copy the example environment file
cp .env.local.example .env.local

# Edit .env.local with your configuration

4️⃣ Start Development Server

pnpm dev

The application will be available at http://localhost:3000

📁 Project Structure

querio-app/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout with sidebar
│   ├── page.tsx                 # Dashboard page
│   ├── globals.css              # Global styles & design tokens
│   ├── chat/                    # Chat interface
│   │   └── page.tsx
│   ├── documents/               # Document management
│   │   └── page.tsx
│   ├── upload/                  # File upload
│   │   └── page.tsx
│   ├── search/                  # Semantic search
│   │   └── page.tsx
│   └── system/                  # System monitoring
│       └── page.tsx
│
├── components/                   # React components
│   ├── chat/                    # Chat-specific components
│   │   ├── chat-interface.tsx
│   │   └── chat-message.tsx
│   ├── dashboard/               # Dashboard components
│   │   ├── stat-card.tsx
│   │   ├── quick-query.tsx
│   │   └── quick-action-link.tsx
│   ├── documents/               # Document components
│   │   ├── document-card.tsx
│   │   ├── document-list.tsx
│   │   └── file-upload.tsx
│   ├── search/                  # Search components
│   │   ├── search-interface.tsx
│   │   └── search-result-card.tsx
│   ├── layout/                  # Layout components
│   │   └── sidebar.tsx
│   └── ui/                      # Reusable UI components
│       ├── button.tsx
│       ├── input.tsx
│       ├── textarea.tsx
│       ├── card.tsx
│       ├── badge.tsx
│       ├── alert.tsx
│       ├── modal.tsx
│       └── loading.tsx
│
├── api/                         # API integration
│   └── rest/
│       └── base-api.ts         # Axios instance & endpoints
│
├── hooks/                       # Custom React hooks
│   └── (custom hooks here)
│
├── lib/                         # Utilities & types
│   ├── types.ts                # TypeScript type definitions
│   └── utils.ts                # Utility functions
│
├── utils/                       # Helper utilities
│   └── sidebar-utils.ts        # Sidebar navigation config
│
├── public/                      # Static assets
│
├── .env.local.example          # Environment variables template
├── next.config.js              # Next.js configuration
├── tailwind.config.js          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies & scripts

🔐 Environment Variables

Create a .env.local file in the root directory:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000

# Optional: Add additional configuration as needed
# NEXT_PUBLIC_ANALYTICS_ID=your_analytics_id

Environment Variable Reference

Variable	Description	Default	Required
`NEXT_PUBLIC_API_URL`	Backend API base URL	`http://localhost:8000`	Yes

Note: Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

💻 Development

Available Scripts

# Start development server (with hot reload)
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Run ESLint
pnpm lint

# Type check
pnpm type-check

Development Tips

Hot Reload - Changes are automatically reflected in the browser
Type Safety - TypeScript catches errors during development
API Proxy - Configure proxy in next.config.js if needed
Component Development - Use the component structure for consistency

Code Style

This project follows industry-standard practices:

TypeScript for type safety
Functional Components with hooks
Client Components marked with 'use client'
Proper Error Handling with try-catch and error boundaries
Responsive Design using Tailwind breakpoints

🎨 Design System

Color Palette

The application uses a carefully crafted color system:

/* Primary Colors */
--accent-primary: #06b6d4    /* Cyan */
--accent-secondary: #22d3ee   /* Light Cyan */
--purple-primary: #a855f7     /* Purple */
--purple-secondary: #c084fc   /* Light Purple */

/* Background */
--bg-primary: #0a0a0f        /* Deep Navy */
--bg-secondary: #12121a       /* Dark Navy */
--bg-tertiary: #1a1a25        /* Medium Navy */

/* Glass Effects */
--glass-bg: rgba(255, 255, 255, 0.03)
--glass-border: rgba(255, 255, 255, 0.08)

/* Text */
--text-primary: #f8fafc       /* White */
--text-secondary: #94a3b8     /* Gray */
--text-tertiary: #64748b      /* Muted Gray */

/* Status Colors */
--success: #10b981            /* Green */
--warning: #f59e0b            /* Orange */
--error: #ef4444              /* Red */

Typography

Primary Font: Sora - Modern, geometric sans-serif
Code Font: JetBrains Mono - For code blocks
Display Font: Space Grotesk - For headings

Components

Glass Card

<div className="glass-card">
  {/* Translucent card with backdrop blur */}
</div>

Gradient Button

<Button variant="primary" leftIcon={<Icon />}>
  Click Me
</Button>

Animated Elements

All interactive elements include smooth animations using Framer Motion.

🔌 API Integration

The frontend integrates with the Querio backend API:

Endpoint Categories

Category	Endpoints	Description
System	`/api/health`, `/api/stats`	Health checks and statistics
Documents	`/api/documents/*`	Document CRUD operations
Upload	`/api/documents/upload`, `/api/documents/bulk-upload`	File upload endpoints
Query	`/api/query`	Document querying
Chat	`/api/chat/*`	Chat sessions and messages
Search	`/api/search/*`	Semantic search

API Client

The API client is configured in api/rest/base-api.ts:

import { API_BASE_URL } from '@/api/rest/base-api';

// Base URL is configured via environment variable
// Default: http://localhost:8000

Error Handling

All API calls include comprehensive error handling:

Network errors
Timeout errors (60 seconds)
Server errors with detailed messages
Automatic error notifications via toast

🏗 Building for Production

Create Production Build

# Build the application
pnpm build

# The output will be in the .next directory

Build Output

The build process creates optimized static pages:

Route (app)                    Size
┌ ○ /                         (Static)
├ ○ /chat                     (Static)
├ ○ /documents                (Static)
├ ○ /search                   (Static)
├ ○ /system                   (Static)
└ ○ /upload                   (Static)

Production Server

# Start production server
pnpm start

# Server runs on http://localhost:3000

Performance Optimizations

✅ Code splitting
✅ Image optimization
✅ CSS minification
✅ JavaScript minification
✅ Static page generation
✅ React Server Components
✅ Automatic font optimization

🚢 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Other Platforms

Netlify

# Build command
pnpm build

# Publish directory
.next

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Environment Variables

Remember to configure NEXT_PUBLIC_API_URL in your deployment platform.

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the Repository

Click the "Fork" button at the top right of this page.

2. Clone Your Fork

git clone https://github.com/paradocx96/querio-app.git
cd querio-app

3. Create a Branch

git checkout -b feature/amazing-feature

4. Make Changes

Follow the existing code style
Add tests if applicable
Update documentation as needed

5. Commit Changes

git add .
git commit -m 'Add some amazing feature'

6. Push to Branch

git push origin feature/amazing-feature

7. Open Pull Request

Go to your fork on GitHub and click "New Pull Request"

Development Guidelines

✅ Use TypeScript for type safety
✅ Follow component structure conventions
✅ Write meaningful commit messages
✅ Test your changes thoroughly
✅ Update README if adding features
✅ Ensure build passes (pnpm build)

📄 License

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

MIT License

Copyright (c) 2024 Navinda Chandrasiri

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

🙏 Acknowledgments

Next.js Team - For the amazing framework
Vercel - For hosting and deployment platform
Tailwind Labs - For Tailwind CSS
Framer - For Framer Motion
Lucide Icons - For beautiful icons

📞 Support

Documentation: View Docs
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: navindadev@gmail.com

⭐ Star us on GitHub if you find this project useful!

Built with ❤️ by paradocx96

Website • Documentation • Blog • Twitter

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
api/rest		api/rest
app		app
assets/styles		assets/styles
components		components
hooks		hooks
lib		lib
providers		providers
public		public
types		types
utils		utils
.env.local.example		.env.local.example
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

paradocx96/querio-app

Folders and files

Latest commit

History

Repository files navigation