LeadGen Website 🚀 Features

Core Functionality

• Location + Niche Input: Search for businesses by location and industry type
• Real Business Discovery: Google Places API & Yelp Business API integration
• Comprehensive Website Analysis:
  • Accessibility scoring
  • SEO optimization analysis
  • Performance metrics
  • Mobile-friendliness assessment
  • Security evaluation
• 🎨 Professional Redesign Mockups: Complete HTML mockups with industry-specific styling and personalized business names
• 🖼️ Visual Preview System: Auto-opening previews in new tabs with improvements panel
• ✅ Fixed 404 Errors: Robust URL handling with Railway backend integration
• 📊 Business Personalization: Redesigns use actual business data instead of generic placeholders
• AI-Powered Analysis: Industry-specific scoring and recommendations
• Multi-Channel Outreach: Email, WhatsApp, and SMS templates
• CSV Export: Complete business data with scores, redesign links, and outreach messagest MVP

A production-ready 48-hour MVP built with FastAPI (backend) and Next.js (frontend), following the BMAD Method for agile AI-driven development.

This application automates local business discovery, comprehensive website analysis, generates professional HTML redesign mockups with visual previews, and creates personalized outreach campaigns for lead generation.

� IMPORTANT: Real Business Data Configuration

The application supports both REAL and MOCK data modes:

• 🔴 REAL MODE: Uses Google Places API & Yelp API for actual business data (requires API keys)
• 🟡 DEMO MODE: Uses mock data for immediate testing (default for quick demos)

For production use with real business search, see REAL_DATA_SETUP.md for API configuration.

�🚀 Features

Core Functionality

• Location + Niche Input: Search for businesses by location and industry type
• Real Business Discovery: Google Places API & Yelp Business API integration
• Comprehensive Website Analysis:
  • Accessibility scoring
  • SEO optimization analysis
  • Performance metrics
  • Mobile-friendliness assessment
  • Security evaluation
• 🎨 Professional Redesign Mockups: Complete HTML mockups with industry-specific styling
• 🖼️ Visual Preview System: Full-screen preview with improvements panel
• AI-Powered Analysis: Industry-specific scoring and recommendations
• Multi-Channel Outreach: Email, WhatsApp, and SMS templates
• CSV Export: Complete business data with scores, redesign links, and outreach messages

Enhanced UX Features

• 4-Stage Loading Progress: Real-time feedback during analysis
• Professional Error Handling: Comprehensive error states with retry options
• Toast Notifications: Instant user feedback system
• Form Validation: Real-time input validation and guidance
• Responsive Design: Mobile-optimized interface
• Auto-Opening Preview: Redesigns automatically open in new tabs for immediate viewing
• 🔧 Fixed URL Issues: Corrected Railway/Vercel URL priority for working previews
• 📝 Comprehensive Logging: Detailed API request/response tracking for debugging
• 🏢 Business Data Integration: End-to-end personalization with actual business names

� Deployment

Frontend Deployment (Vercel)

# The project is configured for Vercel deployment
# Frontend files are in the /frontend directory
# vercel.json is configured to handle the monorepo structure

# Deploy with Vercel CLI:
npm i -g vercel
vercel --prod

Backend Deployment Options

Option 1: Railway/Render/Heroku

cd backend
# Add Procfile for deployment:
echo "web: uvicorn app.main:app --host 0.0.0.0 --port \$PORT" > Procfile

Option 2: Docker

# Backend Dockerfile example:
FROM python:3.10-slim
WORKDIR /app
COPY backend/requirements.txt .
RUN pip install -r requirements.txt
COPY backend/ .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment Variables

Create .env files in both directories:

Backend (.env):

OPENAI_API_KEY=your_openai_api_key
GOOGLE_PLACES_API_KEY=your_google_places_api_key
YELP_API_KEY=your_yelp_api_key

Frontend (.env.local):

NEXT_PUBLIC_API_URL=https://your-backend-url.com

�🛠️ Tech Stack

Component	Technology
Backend	FastAPI (Python 3.10+)
Frontend	Next.js 15 (React 18, TypeScript)
Styling	Tailwind CSS
APIs	Google Places API, Yelp Business API
AI Integration	OpenAI GPT API
Data Analysis	BeautifulSoup4, Requests
Methodology	BMAD Method (story-driven agile AI)

📂 Project Structure

/backend/               → FastAPI application
  /app/
    main.py            → API endpoints and server setup (updated with business_name support)
    ai_service.py      → Enhanced AI integration with personalized redesign generation
    real_data_service.py → Google Places & Yelp integration
/frontend/             → Next.js application
  /src/
    /app/              → App router pages
      /api/redesign/route.ts → Enhanced with comprehensive logging and Railway URL fixes
    /components/       → React components
      BusinessSearchForm.tsx     → Updated to pass business names to redesigns
      BusinessResultsTable.tsx   → Fixed URL priority (Railway over Vercel)
      RedesignPreview.tsx        → Auto-opening preview with improved UX
      LoadingState.tsx           → Professional loading states
      ErrorState.tsx             → Comprehensive error handling
      Toast.tsx                  → Notification system
    /utils/
      api.ts                     → Enhanced with detailed logging and fallbacks
    /contexts/         → Toast notification context
/docs/                 → BMAD methodology documentation
  architecture_document.md
  execution_plan.md
  story_*.md          → Feature development stories
README.md             → This file
IFRAME_FIXES.md       → Detailed documentation of 404 fixes and improvements
requirements.txt      → Python dependencies
package.json          → Node.js dependencies (now includes concurrently)

⚡ Quick Start

1. Prerequisites

• Node.js v20+
• Python 3.10+
• pip / virtualenv
• API Keys (optional for enhanced features):
  • OpenAI API key
  • Google Places API key
  • Yelp Business API key

2. Clone Repository

git clone https://github.com/bmad-code-org/BMAD-METHOD.git
cd BMAD-METHOD

3. Backend Setup (FastAPI)

cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

Create .env file in backend directory:

OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_PLACES_API_KEY=your_google_places_api_key_here
YELP_API_KEY=your_yelp_api_key_here

Start Backend:

python app/main.py

Backend runs at: http://localhost:8000

4. Frontend Setup (Next.js)

cd frontend
npm install

Create .env.local file in frontend directory:

NEXT_PUBLIC_API_URL=http://localhost:8000

Start Frontend:

npm run dev

Frontend runs at: http://localhost:3000

5. Access Application

1. Start Backend (Terminal 1): python app/main.py
2. Start Frontend (Terminal 2): npm run dev
3. Open Browser: http://localhost:3000

✅ Usage Flow

1. Enter Search Criteria: Location and business niche (e.g., "New York, NY" + "restaurants")
2. Business Discovery: System finds 5-10 local businesses using real APIs
3. Website Analysis: Each business website scored across 5 categories (0-100)
4. 🎨 Redesign Generation: Sites scoring < 70 can generate professional HTML mockups with personalized business names
5. 📱 Auto-Preview: Redesigns automatically open in new tabs with working Railway URLs (404 errors fixed!)
6. 💼 Business Integration: All redesigns use actual business data for professional, personalized results
7. AI Recommendations: Personalized outreach templates and improvement suggestions
8. Export Results: Download comprehensive CSV with all data and recommendations

🎯 API Endpoints

Endpoint	Method	Description
/businesses	GET	Find businesses by location & niche
/score	POST	Analyze website and return comprehensive scores
/redesign	POST	Generate professional HTML redesign mockup
/preview/{preview_id}	GET	Serve HTML mockup for preview
/outreach	POST	Create personalized outreach messages
/export-csv	POST	Export results to CSV

🔧 Configuration

Environment Variables

Backend (.env):

• OPENAI_API_KEY: For AI-powered analysis and generation
• GOOGLE_PLACES_API_KEY: For business discovery
• YELP_API_KEY: For additional business data

Frontend (.env.local):

• NEXT_PUBLIC_API_URL: Backend API URL

Fallback Mode

The application includes comprehensive fallback systems:

• Mock data when APIs are unavailable
• Fallback scoring for inaccessible websites
• Graceful degradation with error handling

🏗️ Architecture

Backend Architecture

• FastAPI with async/await for performance
• Modular services (AI, Real Data, Scoring)
• Timeout protection (5s individual, 15s total)
• Error resilience with fallback responses

Frontend Architecture

• Next.js App Router with TypeScript
• Component-based design with reusable elements
• Context API for global state (toast notifications)
• Tailwind CSS for responsive styling

📊 Features Breakdown

Website Scoring Categories

1. Accessibility (Alt text, semantic HTML, heading structure)
2. SEO (Title tags, meta descriptions, H1 optimization)
3. Performance (Load time analysis and optimization)
4. Mobile Friendliness (Responsive design, viewport meta tags)
5. Security (HTTPS, security headers, SSL certificates)

🎨 Redesign Mockup Generation

• Industry-Specific Templates: Tailored designs for restaurants, lawyers, dentists, etc.
• Personalized Business Names: Uses actual business names instead of generic placeholders
• Professional HTML/CSS: Complete, responsive mockups with modern styling
• Auto-Opening Preview: Redesigns automatically open in new browser tabs
• Fixed URL Issues: Corrected Railway/Vercel URL handling to eliminate 404 errors
• Visual Preview System: Clean, professional preview interface with success messaging
• Score Improvement Predictions: Expected improvements across all categories
• Conversion Optimization: Strategic CTA placement and user flow design

AI Integration

• Industry-specific prompts for accurate analysis
• Contextual redesign suggestions based on business type
• Multi-channel outreach (Email, WhatsApp, SMS templates)
• Personalized messaging using business details
• Professional HTML generation with responsive design patterns

🧪 Testing

Backend Testing

cd backend
pytest

Frontend Testing

cd frontend
npm test

Manual Testing

1. Test with various location/niche combinations
2. Verify error handling with invalid inputs
3. Check CSV export functionality
4. Test responsive design on mobile devices
5. ✅ Test redesign generation for low-scoring websites (< 70 points)
6. ✅ Verify auto-opening preview functionality (no more 404 errors!)
7. ✅ Test business name personalization across different industries
8. ✅ Verify Railway URL integration for consistent preview access
9. Test comprehensive logging for debugging API issues
10. Test industry-specific styling with actual business data

📦 Deliverables

• GitHub Repository with clean, documented code
• README.md with comprehensive setup instructions
• Working MVP with enhanced features
• Real API Integration (Google Places, Yelp)
• Professional UI/UX with loading states and error handling
• 🎨 Redesign Mockup Generation with personalized business names
• ✅ Fixed 404 Preview Errors with proper Railway URL integration
• 🏢 Business Data Personalization throughout the redesign flow
• 📊 Comprehensive Logging for debugging and monitoring
• Auto-Opening Preview System for improved user experience
• Industry-Specific Templates for professional website redesigns
• Production-ready features (timeouts, fallbacks, validation)
• Detailed Documentation including IFRAME_FIXES.md

🚀 Production Considerations

Performance Optimizations

• Request timeouts prevent hanging connections
• Async processing for concurrent website analysis
• Error boundaries maintain application stability
• Responsive caching for repeated requests
• Auto-opening previews reduce user interaction friction

Security Features

• CORS configuration for secure frontend/backend communication
• Input validation on all form inputs
• API key protection through environment variables
• Error sanitization to prevent information leakage

Recent Fixes & Improvements

• ✅ Fixed 404 Preview Errors: Corrected URL priority to use working Railway endpoints
• 🏢 Business Personalization: All redesigns now use actual business names
• 📊 Enhanced Logging: Comprehensive request/response tracking for debugging
• 🔧 Auto-Opening Previews: Improved UX with automatic new tab opening
• 🛠️ Robust Error Handling: Better fallback mechanisms and error recovery

🎬 Demo Video

[Link to Loom video walkthrough (≤5 min) will be added here]

🔮 Future Enhancements

• Advanced scraping with Playwright/Selenium
• Machine learning scoring models
• Real-time notifications for completed analyses
• Team collaboration features
• White-label customization options
• A/B testing for redesign variations
• Performance analytics for redesigned websites
• Client portal for sharing redesign mockups

🙌 Development Notes

This MVP demonstrates:

• Professional full-stack development with modern technologies
• Real-world API integration beyond basic mocking
• Production-ready architecture with error handling and performance optimization
• BMAD methodology implementation for structured, story-driven development
• Creative problem-solving with enhanced UX and robust fallback systems
• 🎨 Advanced visual features including HTML mockup generation and preview systems
• Industry-specific customization for enhanced user experience

Built with focus on code quality, functionality, and user experience that exceeds typical MVP standards.

---

Built with ❤️ using the BMAD Method