Intelligent decision-making through structured AI comparisons
A full-stack web application that transforms decision paralysis into clarity. Built with React.js and FastAPI, and fully containerized with Docker, COMPAIR uses GPT-4o, LangChain, Brave Search, structured JSON validation, and an MCP (Model Context Protocol) layer to deliver grounded, personalized comparisons across any category, including gadgets, cars, technologies, destinations, and more.
Choosing between multiple options usually means:
- Sifting through scattered reviews
- Opening too many tabs
- Manually comparing specifications
- Struggling to weigh trade-offs
COMPAIR solves this by generating structured, validated, context-aware comparisons that adapt to your needs, priorities, and budget.
- Uses OpenAI GPT-4o through LangChain for structured AI reasoning
- Generates comparison tables, pros and cons, summaries, and recommendations
- Understands category context such as Gadgets, Cars, Technologies, Destinations, Shows, and more
- Validates items with category-specific rules to prevent incorrect comparisons
- Produces consistent structured JSON outputs through Pydantic parsing
- Users can provide priorities, a budget range, and a detailed use case
- COMPAIR produces a personalized winner based on user needs
- When preferences are not provided, COMPAIR provides neutral and balanced comparisons
- Integrates Brave Search API to fetch real and current data for each item
- Reduces hallucinations by grounding the model using factual search snippets
- Search snippets are injected into prompts before LLM processing for accuracy
- Users can ask follow-up questions after receiving results
- COMPAIR maintains conversation memory for each comparison
- Follow-up answers stay relevant without restarting any session
- Built for Product Managers to monitor platform performance and user behaviour at a glance
- Time-range filtering (7, 30, 90 days) across total comparisons, category breakdowns, popular pairs, and decision confidence metrics
- Tracks user feedback statistics including ratings and improvement comments
- Integrated AI chat lets Product Managers ask natural-language questions about comparison trends
- Collects star ratings for accuracy and winner match quality after each comparison
- Separate feedback paths for personalized and neutral comparisons
- Stores user comments (what worked, what could improve) in PostgreSQL for analytics
- A dedicated FastAPI MCP server runs alongside the main backend (port 8001)
- Exposes 9 structured tools covering dashboard metrics, feedback summaries, category insights, activity trends, and AI-generated reports
- Any MCP-compatible AI assistant (Grok, ChatGPT, Claude) can connect and query COMPAIR data programmatically
- Stores all comparisons in PostgreSQL using JSONB
- Generates public shareable links for quick access and collaboration
- Built with React 18 and TailwindCSS
- Smooth interactions using Framer Motion
- Fully responsive design
- Clean and intuitive form controls, tabs, and results display
- Light and dark mode support
- Optional PDF exporting capability
COMPAIR is designed as a modular, scalable, and grounded full-stack system that connects frontend interaction, backend logic, AI reasoning, real-time search, and persistent data storage.
- React.js 18
- TailwindCSS
- Framer Motion
- Component-based structure
- Fetch API for backend communication
- Local storage for theme persistence
- FastAPI with async support
- Category validation and prompt construction
- Brave Search integration
- LangChain for GPT-4o orchestration and output parsing
- Conversation memory for follow-up interactions
- MCP server (separate FastAPI service on port 8001) exposing dashboard data as AI-callable tools
- Comprehensive error handling and logging
- GPT-4o for structured and grounded comparisons
- Groq LLM for analytics chat responses via the MCP layer
- MCP flow: user query → Groq LLM → MCP tool call → PostgreSQL → structured AI response
- Real-time data from Brave Search
- Dynamic prompt construction using system and human messages
- Strict schema enforcement with PydanticOutputParser
▶ Click here to watch the full COMPAIR demo on YouTube
Static screenshots are available in
📂 COMPAIR/images
COMPAIR uses PostgreSQL with JSONB for fast and flexible structured storage.
Supports:
- Comparison history
- Public shareable comparisons
- Conversation memory
- A 24-hour caching layer for reducing repeated LLM calls
- Item analytics and frequency tracking
- Faster than plain JSON
- Ideal for storing AI-generated tables, pros and cons, and structured results
- Works seamlessly with PostgreSQL indexing and filtering
COMPAIR/
├── backend/
│ ├── main.py # Core API (port 8000)
│ ├── mcp_server.py # MCP server — AI tool layer (port 8001)
│ ├── grok_mcp_client.py # MCP client for AI assistant integration
│ ├── analytics_chat_endpoint.py # Analytics chat API endpoint
│ ├── prompt/
│ ├── models/
│ ├── utilities/
│ └── database/
│
├── frontend/
│ ├── public/
│ ├── src/
│ │ ├── components/ # Includes AnalyticsChat, FeedbackSection
│ │ └── pages/ # Compare, Dashboard, Home
│ └── package.json
│
├── docs/ # Technical deep-dives and implementation notes
├── docker-compose.yml # 4-service orchestration
├── mcp_config.json # AI assistant MCP configuration
├── .env.example # Environment template
├── images/
└── README.md
COMPAIR includes a complete, ready-to-run Docker setup.
- Backend (FastAPI with GPT-4o integration) — port 8000
- MCP Server (AI tool layer) — port 8001
- Frontend (React served with Nginx) — port 3000
- PostgreSQL (JSONB optimized)
cp .env.example .env # fill in your API keys
docker-compose up --build- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- MCP Server: http://localhost:8001
- API Documentation: http://localhost:8000/docs
- Endpoint stability
- Prompt construction logic
- Brave Search integration
- Schema validation
- Error handling
- Structured responses
- Category consistency
- Correct personalization
- Hallucination reduction
- Form validation
- Responsive UI
- Flow stability
- Animation performance
- Context retention
- End-to-end API reliability
- History and sharing workflows
Developing COMPAIR strengthened my full-stack and AI engineering capabilities across all layers of system design.
This project evolved from a simple comparison tool into a grounded, database-backed, cache-aware, multi-service AI system.
Designed and delivered a complete React and FastAPI system with clean API contracts and structured data flows between frontend, backend, AI reasoning, and storage layers.
Built a production-ready backend with Brave Search grounding, a 24-hour PostgreSQL-backed caching layer, dynamic prompt templates, conversation memory, category filtering, a dedicated MCP server exposing structured AI tools, and the repository pattern for clean data access.
Developed a reliable prompt-engineering workflow using GPT-4o, LangChain, PydanticOutputParser, system and human messages, real-time grounding, anti-hallucination strategies, and dynamic prompt construction. Extended the AI layer with Groq for analytics chat and MCP tool-calling for structured data queries.
Implemented PostgreSQL with JSONB storage, optimized indexing, TTL caches, history management, public sharing, item analytics, and stable data flows.
Built a modern, responsive UI with React, TailwindCSS, Framer Motion, and clean state management patterns to present structured AI outputs effectively.
Containerized all services with Docker, configured Nginx for production frontend hosting, and set up environment-based configuration for portability.
Learned how to combine human preferences, AI reasoning, real-time grounding, backend orchestration, structured validation, and clean UI into one cohesive product.
Warda Ul Hasan
Computer Engineering Graduate, American University of Sharjah
LinkedIn: https://www.linkedin.com/in/wardaulhasan
GitHub: https://github.com/wardacoder
COMPAIR reflects my goal to build systems where intelligence meets structure, practical purpose, and thoughtful design.