VentureVista

A full-stack location intelligence app that helps evaluate business feasibility at a given location.

VentureVista combines Google Maps place data, LLM-powered analysis, and a deterministic scoring engine to generate practical go/no-go insights for new business ideas.

Project Snapshot

• Purpose: Analyze whether a business concept is viable in a specific area.
• Frontend: React + Vite web app for user input, report visualization, and history.
• Backend: FastAPI service for geocoding, POI retrieval, classification, report generation, and caching.
• Data persistence: SQLite via SQLAlchemy (default local database).

Core Capabilities

• Address or map-based location input
• Nearby POI discovery using Google Maps APIs
• LLM-assisted place classification and narrative reporting
• Rule-based viability scoring for deterministic outcomes
• Per-user anonymous history and cached analysis retrieval

Architecture (Top View)

1. User submits location + business parameters from the frontend.
2. Backend checks user-scoped cache for a matching analysis.
3. If no cache hit:
   • Geocode address (or use provided coordinates)
   • Fetch nearby places
   • Classify places via LLM service
   • Aggregate POI statistics
   • Generate qualitative report
   • Compute rule-based viability score
4. Backend stores result and returns a unified analysis payload.
5. Frontend renders report and supports history browsing.

Tech Stack

Frontend

• React 19
• Vite 8
• Framer Motion
• React Router

Backend

• FastAPI
• Uvicorn
• SQLAlchemy
• Pydantic / pydantic-settings
• Google GenAI client
• Optional Ollama integration

Repository Layout

venture-vista/
|- backend/
|  |- main.py                # FastAPI entrypoint
|  |- config.py              # Environment-based settings
|  |- database.py            # SQLAlchemy engine/session setup
|  |- models.py              # ORM models (analysis cache)
|  |- schemas.py             # Request/response schemas
|  |- routers/
|  |  |- analyze.py          # Analyze + history endpoints
|  |- services/
|  |  |- maps.py             # Geocoding and nearby places
|  |  |- gemini.py           # LLM interactions
|  |  |- report.py           # Aggregation/report helpers
|  |  |- scoring.py          # Deterministic viability scoring
|  |- requirements.txt
|- frontend/
|  |- src/
|  |  |- App.jsx             # Main app workflow
|  |  |- components/         # UI features and views
|  |- package.json
|- README.md

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• npm 9+
• Google Maps API key
• Gemini API key (if Gemini-based flow is enabled)

1. Backend Setup

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Create backend/.env:

GOOGLE_MAPS_API_KEY=your_google_maps_key
GEMINI_API_KEY=your_gemini_key
DATABASE_URL=sqlite:///./venturevista.db

Run backend:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

2. Frontend Setup

cd frontend
npm install

Create frontend/.env:

VITE_API_URL=http://localhost:8000
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_key

Run frontend:

npm run dev

API Surface (Current)

• GET / - API health message
• POST /api/analyze - Run a new location feasibility analysis
• GET /api/history - List recent analyses for anonymous user identity
• GET /api/history/{analysis_id} - Fetch a specific historical analysis

Notes

• Anonymous identity is maintained via secure cookie-based tokening for history scoping.
• Caching is keyed by location/business context to avoid repeated external API calls.
• Viability score is deterministic/rule-based, while narrative interpretation is LLM-assisted.