🕷️ Marvel Oracle - RAG-Powered Marvel Universe Chat

A full-stack RAG (Retrieval-Augmented Generation) application that lets you chat with the Marvel Universe using AI. Ask questions about Marvel characters, storylines, and lore with context-aware responses powered by vector search and GPT-4.

🚀 Live Demo

🌐 Try Marvel Oracle

✨ Features

🧠 Intelligent RAG System

Context-Aware Conversations: Remembers chat history for follow-up questions
Query Rewriting: Automatically enhances ambiguous questions using conversation context
Vector Search: Uses Pinecone for semantic similarity search across Marvel content
GPT-4 Integration: Powered by OpenAI's most advanced language model

💬 Chat Experience

Multiple Timelines: Create and manage separate conversation threads
Real-time Responses: Streaming responses with loading indicators
Chat History: Persistent conversation storage with Appwrite
Context Menu: Edit chat names, delete conversations
Auto-scroll: Automatically scrolls to latest messages

🔐 Authentication & Security

Secure Login/Signup: Email-password authentication via Appwrite
Password Reset: Email-based password recovery system
HTTP-only Cookies: Secure session management
Route Protection: Middleware-based authentication guards

🎨 Modern UI/UX

Dark Theme: Marvel-inspired red and gray color scheme
Responsive Design: Works seamlessly on desktop and mobile
Smooth Animations: Polished loading states and transitions
Intuitive Navigation: Clean sidebar with chat history

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js       │    │   Vercel         │    │   External      │
│   Frontend      │◄──►│   Serverless     │◄──►│   Services      │
│                 │    │   Functions      │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
│                      │                      │
│ • React Components   │ • Python API        │ • Appwrite DB
│ • Zustand Store      │ • LangChain RAG      │ • Pinecone Vector
│ • TailwindCSS        │ • Query Processing   │ • OpenAI GPT-4
│ • TypeScript         │ • Chat History       │ • Email Service

🛠️ Tech Stack

Frontend

Next.js 14 - React framework with App Router
TypeScript - Type-safe JavaScript
TailwindCSS - Utility-first CSS framework
Zustand - Lightweight state management

Backend

Python - Server-side logic
LangChain - RAG pipeline and AI orchestration
Vercel Serverless - Serverless function deployment

AI & Data

OpenAI GPT-4 - Large language model
Pinecone - Vector database for embeddings
OpenAI Embeddings - Text-to-vector conversion

Database & Auth

Appwrite - Backend-as-a-Service for auth and data
Appwrite Database - Document database for chats

🚀 Getting Started

Prerequisites

Node.js 18+
Python 3.9+
npm or yarn

Environment Variables

Create these environment variable files:

Client (`.env.local`)

NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your_project_id
NEXT_PUBLIC_APPWRITE_DATABASE_ID=your_database_id
NEXT_PUBLIC_APPWRITE_COLLECTION_ID=your_collection_id
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Server Environment Variables

OPENAI_API_KEY=your_openai_api_key
PINECONE_API_KEY=your_pinecone_api_key

Local Development

Clone the repository

git clone https://github.com/yourusername/marvel-oracle.git
cd marvel-oracle

Install dependencies

# Install client dependencies
cd client
npm install

# Install server dependencies (for local development)
cd ../server
pip install -r requirements.txt

Set up external services

Appwrite Setup:
- Create account at Appwrite Cloud
- Create new project
- Set up database and collection for chat storage
- Configure authentication settings
Pinecone Setup:
- Create account at Pinecone
- Create index named marvel-embeddings
- Upload your Marvel content embeddings
OpenAI Setup:
- Get API key from OpenAI Platform
Run development servers

# Start Next.js frontend (from project root)
npm run dev:client

# Start Python backend (from project root) 
npm run dev:server

Open the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000

🚀 Deployment

The application is configured for one-click deployment to Vercel:

Deploy to Vercel

Using Vercel CLI

npm install -g vercel
vercel --prod

Using GitHub Integration
- Push code to GitHub
- Import repository in Vercel dashboard
- Configure environment variables
- Deploy automatically

Environment Variables in Production

Set these in your Vercel dashboard:

OPENAI_API_KEY=your_openai_api_key
PINECONE_API_KEY=your_pinecone_api_key
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your_project_id
NEXT_PUBLIC_APPWRITE_DATABASE_ID=your_database_id
NEXT_PUBLIC_APPWRITE_COLLECTION_ID=your_collection_id

📁 Project Structure

marvel-oracle/
├── client/                  # Next.js frontend
│   ├── src/
│   │   ├── app/            # App Router pages
│   │   │   ├── login/      # Authentication pages
│   │   │   ├── signup/
│   │   │   └── reset-password/
│   │   ├── components/     # React components
│   │   │   ├── Chatbot.tsx # Main chat interface
│   │   │   ├── Chatbar.tsx # Message input
│   │   │   ├── History.tsx # Chat sidebar
│   │   │   └── ...
│   │   ├── store/          # Zustand state management
│   │   ├── types/          # TypeScript type definitions
│   │   └── utils.ts        # API utilities
│   ├── middleware.ts       # Route protection
│   └── package.json
├── api/                    # Vercel serverless functions
│   ├── index.py           # Health check endpoint
│   └── query.py           # RAG query processing
├── server/                 # Local development server
│   └── server.py          # FastAPI development server
├── requirements.txt        # Python dependencies
├── vercel.json            # Vercel configuration
└── README.md

🎯 Key Features Explained

RAG Pipeline

The core RAG (Retrieval-Augmented Generation) system works as follows:

Query Processing: User questions are analyzed for context dependency
Query Rewriting: Ambiguous questions are rewritten using chat history
Vector Search: Enhanced queries retrieve relevant Marvel content from Pinecone
Response Generation: GPT-4 generates responses using retrieved context and chat history

Context-Aware Conversations

User: "Who is the boss of Peter Parker's newspaper?"
AI: "J. Jonah Jameson is the editor-in-chief of the Daily Bugle..."

User: "Who is that?" ← Ambiguous question
AI: ✅ Understands "that" refers to J. Jonah Jameson from context

Chat Management

Multiple Timelines: Each chat maintains separate conversation history
Persistent Storage: All conversations saved to Appwrite database
Real-time Updates: UI updates immediately with new messages
Context Isolation: Each chat has its own context window

🔧 API Documentation

Query Endpoint

GET /api/query
Headers:
  Query: "Who is Spider-Man?"
  Session-Id: "unique_chat_id"

Response:
{
  "query": "Who is Spider-Man?",
  "response": "Spider-Man is Peter Parker, a young man who gained spider-like abilities...",
  "session_id": "unique_chat_id"
}

Health Check

GET /api/
Response:
{
  "message": "Marvel RAG API is running!",
  "status": "healthy",
  "env_check": {
    "openai_key_set": true,
    "pinecone_key_set": true
  }
}

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgments

Marvel Comics - For the incredible universe and characters
OpenAI - For GPT-4 and embedding models
LangChain - For RAG framework and tools
Vercel - For seamless deployment platform
Appwrite - For authentication and database services

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: your.email@example.com

🕷️ Built with ❤️ for Marvel fans by Marvel fans 🕷️ Live Demo

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
api		api
client		client
server		server
.gitignore		.gitignore
.vercelignore		.vercelignore
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md
requirements.txt		requirements.txt
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation