"Don't trust one rating. See the evidence."
Live frontend · GitHub repository · Data-source status · Local setup · Contributing · Security
ReviewLens is an evidence-driven decision intelligence engine that synthesizes permitted public evidence from multiple independent sources, resolves ambiguous entities, identifies recurring and conflicting perspectives, performs multi-faceted aspect analysis, and provides traceable, auditable evidence graphs without relying on opaque rating averages.
Traditional review aggregators compress complex, multi-faceted human experiences into a single numerical star rating. This leads to review manipulation, biased averages, and context flattening.
ReviewLens takes an intelligence-grade, evidence-first approach:
- Multi-Source Ingestion: Discovers entities and collects signals from permitted open datasets, public discussions, and encyclopedic records.
- Entity Resolution & Deduplication: Disambiguates aliases, matches geographic coordinates, and clusters redundant records.
- Contrastive Conflict Detection: Flags opposing sentiment signals on the same subject rather than averaging them out.
- Traceable Attribution: Every assertion links directly back to its original source URL, timestamp, and provenance category.
- No Black-Box Ratings: We do not calculate artificial 1-to-5 star scores. Instead, we show corroboration density, aspect breakdowns, and verified source distributions.
- Genuine Conflict Isolation: When half the community praises an aspect (e.g. food quality) and the other half criticizes it, ReviewLens highlights the controversy with supporting and opposing citations.
- Verifiable Provenance: Users can inspect exact source URLs, timestamps, author roles, and operational source statuses.
- Multi-Domain Intelligence: Built to handle complex real-world queries across higher education, dining & hospitality, housing, and general research.
- Multi-Source Connector Architecture: Pluggable connectors for OpenStreetMap, Wikimedia Foundation, Reddit OAuth, Google Places, and compliant Web Search engines.
-
Entity Resolution Engine: Normalizes colloquial aliases (e.g., "Tonino CP"
$\rightarrow$ "Caffè Tonino, Connaught Place") using geospatial proximity (Haversine distance) and Levenshtein token similarity. - Topological Evidence Graph: Interactive force-directed graph connecting entities, aspects, claims, and underlying source nodes.
- Contrastive Perspective Analyzer: Extracts opposing sentiment polarities with confidence scores and synthesis summaries.
- Temporal Recency Decay: Weights recent evidence higher while preserving longitudinal historical context.
- Interactive Deep Map: Geospatial visualization of verified physical entities with amenity tags and direct evidence inspection.
- Side-by-Side Entity Comparison: Compare multiple entities across corroboration density, aspect performance, and conflicting claims.
ReviewLens separates evidence discovery, normalization, analysis, and presentation into clean, decoupled layers:
[ User Query ]
│
▼
[ Query Parser ] ─── extracts intent, domain, location, priorities
│
▼
[ Evidence Engine ] ─── coordinates independent connectors
├── OpenStreetMapConnector ─── Live Overpass API (coordinates & amenity tags)
├── WikimediaConnector ─── Live REST API (institutional background)
├── GooglePlacesConnector ─── Official Places API (verified Place IDs & metadata)
├── RedditConnector ─── Official OAuth Search API (public discussions)
├── WebSearchConnector ─── SearXNG / Compliant Search API (public web documents)
└── LocalArchiveConnector ─── Offline verified benchmark models
│
▼
[ Entity Resolution & Deduplication ] ─── clusters nodes & removes duplicate claims
│
▼
[ Contradiction & Aspect Analyzer ] ─── identifies conflicting claims & aspect scores
│
▼
[ Unified Evidence Report & Graph ] ─── returned to Frontend (React + Vite + Tailwind)
ReviewLens distinguishes runtime network responses from offline demonstration baselines. Live status is determined by each successful request; static documentation cannot guarantee current provider availability.
| Source | Category | Status | Authentication & Policy | Purpose |
|---|---|---|---|---|
| OpenStreetMap | Open Data | Network-backed, when reachable | Public Overpass API (ODbL License) | Physical entity discovery, geographic coordinates, amenity tags. |
| Wikimedia | Institutional | Network-backed, when reachable | Public Wikipedia REST API (CC-BY-SA 4.0) | Institutional background, founding history, encyclopedic context. |
| Google Places | Official Business | Requires Credentials | Google Places Platform (GOOGLE_PLACES_API_KEY) |
Official Place IDs, verified business metadata, address verification. |
| Public Discussion | Requires Credentials | Official OAuth 2.0 (REDDIT_CLIENT_ID, SECRET) |
Public community discussions and student/consumer feedback. | |
| Web Search | Search Result | Requires Provider | SearXNG / Custom Endpoint (WEB_SEARCH_ENDPOINT) |
Public web documents and index overviews. |
| Local Archive | Benchmark Baseline | Offline Ready | Local Benchmark Corpus | Verified Delhi NCR benchmark baseline for offline testing. |
Every evidence item collected and presented by ReviewLens strictly adheres to our normalization contract:
source: Standard source category (open_data,institutional,official,reddit,web,archive)url: Direct, traceable external URLentity: Canonical resolved entity nameretrieved_at: ISO 8601 UTC timestamp of retrievalpublished_at: Original publication date where availableprovenance: Traceability tag (LIVE_OPENSTREETMAP,LIVE_WIKIMEDIA,LIVE_GOOGLE_PLACES,LIVE_REDDIT,LIVE_WEB_SEARCH,DEMO_LOCAL_ARCHIVE)is_live: Boolean (Trueif retrieved from a live external network request)is_demo: Boolean (Trueif originating from offline benchmark baseline)
- FastAPI (Python 3.10+)
- Pydantic v2 (Strict data modeling & camelCase serialization)
- HTTPX (Asynchronous HTTP client with backoff retries)
- SQLite / In-Memory Cache (Resilient session storage and request caching)
- Pytest (Unit and integration test suite)
- React 19 + TypeScript
- Vite (Next-generation frontend tooling)
- Tailwind CSS v4 (Editorial daylight typography & design system)
- Lucide React (Minimalist iconography)
- Canvas / Force-Directed Graph (Interactive evidence topology)
- Leaflet / React Leaflet (Geospatial entity mapping)
ReviewLens/
├── backend/
│ ├── connectors/ # Independent source adapters (OSM, Wiki, Reddit, Google Places, Web)
│ ├── ml/ # Deduplication, contradiction detection, and aspect sentiment
│ ├── models/ # Pydantic schemas (evidence, entity, query, analysis)
│ ├── services/ # EvidenceEngine & orchestration pipeline
│ ├── tests/ # Pytest suite (23+ unit & integration tests)
│ ├── utils/ # SQLite persistence, rate limiting, and caching
│ ├── config.py # Environment configuration loader
│ ├── main.py # FastAPI app definition and route registration
│ └── requirements.txt # Python backend dependencies
├── src/
│ ├── api/ # Frontend API client and backend bridge
│ ├── components/
│ │ ├── common/ # Navigation, Footer, Modals, Audio
│ │ ├── compare/ # Side-by-side comparison matrix
│ │ ├── drawer/ # Evidence detail drawer
│ │ ├── entity/ # Deep entity detail view
│ │ ├── graph/ # Topological force graph
│ │ ├── hero/ # Hero section and search bar
│ │ ├── history/ # Research session history
│ │ ├── home/ # Contact and Suggestion section
│ │ ├── map/ # Interactive geographic evidence map
│ │ ├── results/ # Intelligence report dashboard
│ │ ├── sources/ # Real-time connector health monitor
│ │ └── storytelling/ # 6-stage evidence methodology walkthrough
│ ├── data/ # Verified demonstration datasets
│ ├── types/ # TypeScript interface definitions
│ ├── App.tsx # Application root and state router
│ └── main.tsx # React DOM entry point
├── .env.example # Clean configuration template with placeholders
├── package.json # Frontend npm dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── vite.config.ts # Vite bundler configuration
- Node.js 18+ and npm
- Python 3.10+
- Git
git clone <repository-url>
cd ReviewLens# Install frontend dependencies
npm install
# Run frontend development server
npm run devThe frontend will be available at http://localhost:5173.
# Create and activate Python virtual environment
python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate
# Install backend dependencies
pip install -r backend/requirements.txt
# Start the FastAPI server
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reloadThe API documentation will be available at http://127.0.0.1:8000/docs.
ReviewLens works out of the box with open data sources (OpenStreetMap and Wikimedia). To enable additional sources, copy .env.example to .env and provide your credentials:
cp .env.example .env| Variable | Required? | Description |
|---|---|---|
HOST |
Optional | Server host (default: 0.0.0.0) |
PORT |
Optional | Server port (default: 8000) |
REVIEWLENS_DEMO_MODE |
Optional | Set true to force demo mode; defaults to false |
GOOGLE_PLACES_API_KEY |
Optional | Google Places Platform API key for Place search and details |
REDDIT_CLIENT_ID |
Optional | Official Reddit OAuth App Client ID |
REDDIT_CLIENT_SECRET |
Optional | Official Reddit OAuth App Client Secret |
REDDIT_USER_AGENT |
Optional | Reddit User-Agent header (default: ReviewLens/1.0) |
WEB_SEARCH_ENDPOINT |
Optional | JSON search endpoint (SearXNG or compliant provider) |
WEB_SEARCH_API_KEY |
Optional | Bearer authentication key for web search provider |
CACHE_TTL_SECONDS |
Optional | In-memory cache duration in seconds (default: 3600) |
ReviewLens includes a comprehensive pytest suite covering entity resolution, contradiction detection, connector error isolation, and serialization contracts:
python -m pytest backend/tests -vValidate TypeScript types and asset compilation:
npm run buildReviewLens enforces strict data transparency:
LIVE_RESEARCH: Engaged when one or more live connectors successfully retrieve external data. Evidence items are tagged with their specific provenance (LIVE_OPENSTREETMAP,LIVE_WIKIMEDIA, etc.).- Unconfigured Connectors: If credentials are missing or an API is unreachable, ReviewLens reports
NOT CONFIGUREDorERRORand never generates fabricated reviews or mock forum discussions. - Offline Benchmark Baseline: When explicitly testing offline, the engine uses the verified Delhi NCR benchmark dataset (
DEMO_LOCAL_ARCHIVE).
- No Secret Storage: Real credentials,
.envfiles, and local runtime databases are strictly excluded from version control via.gitignore. - No Private Data Harvesting: ReviewLens queries only authorized public APIs and complies with respective terms of service and robots.txt.
- Official APIs Only: We do not perform unpermitted HTML web scraping or bypass rate limits.
- Independent multi-source connector architecture
- Live OpenStreetMap Overpass & Wikimedia REST integration
- Official Reddit OAuth & Google Places connector templates
- Contrastive contradiction detection & Aspect sentiment analysis
- Force-directed interactive Evidence Graph
- Real-time Source Health monitoring dashboard (
/api/sources/health) - Multi-region geographic expansion beyond Delhi NCR
- Exportable executive PDF and Markdown evidence dossiers
- Support for custom local LLM entity summarizers (Ollama / Llama-cpp)
This project is licensed under the MIT License — see the LICENSE file for details.
- Live frontend: https://review-lens-black.vercel.app/
- Repository: https://github.com/rajsalonia/ReviewLens
- Documentation: Data sources · Evaluation · Model card
Demo limitations: External providers such as Reddit and Google Places require your own credentials. Offline archive results must remain visibly differentiated from externally retrieved evidence. The hosted frontend's availability is not a guarantee that every backend connector is configured.