🌍 Nearby Locator

An intelligent location-based search application with Smart chat interface that helps users discover nearby places like restaurants, hospitals, ATMs, and more.

✨ Features

🤖 Smart Chat Interface

Natural language processing for location queries
Conversational interface with typing indicators
Smart parsing of categories and search radius
Context-aware responses with helpful suggestions

📍 Location-Based Search

Real-time geolocation using browser API
Support for 10+ place categories
Customizable search radius (2-20 km)
Google Places API integration

🎨 Modern UI/UX

Glassmorphism design with dark theme
Responsive layout for mobile and desktop
Smooth animations and transitions
User-friendly error messages

🗺️ Interactive Results

Clickable map links for each place
Direct Google Maps navigation
Place ratings and addresses
Opens in new tab or Google Maps app

🚀 Quick Start

Option 1: Run Without Docker (Fastest)

Prerequisites:

Node.js 18+ installed
Google Places API key

Steps:

# 1. Clone the repository
git clone <repository-url>
cd nearby-locator

# 2. Setup Backend
cd backend
npm install
# Create .env file and add: GOOGLE_API_KEY=your_key_here
node index.js

# 3. Setup Frontend (in new terminal)
cd frontend
npm install
npm start

Access: http://localhost:3000

Option 2: Run With Docker (Production)

Prerequisites:

Docker and Docker Compose installed
Google Places API key

Steps:

# 1. Clone the repository
git clone <repository-url>
cd nearby-locator

# 2. Create .env file
cp .env.example .env
# Edit .env and add: GOOGLE_API_KEY=your_key_here

# 3. Run with Docker
# Windows:
start-docker.bat

# Linux/Mac:
chmod +x start-docker.sh
./start-docker.sh

Access: http://localhost:3000

📁 Project Structure

nearby-locator-Smart Search/
├── backend/                    # Node.js Express API
│   ├── index.js               # Main server file
│   ├── config.js              # Configuration
│   ├── package.json           # Dependencies
│   ├── Dockerfile             # Docker configuration
│   └── .env                   # Environment variables (not in git)
│
├── frontend/                   # React application
│   ├── src/
│   │   ├── App.js             # Main React component
│   │   ├── components/        # React components
│   │   ├── icons/             # SVG icon components
│   │   └── index.js           # Entry point
│   ├── public/                # Static assets
│   ├── package.json           # Dependencies
│   ├── Dockerfile             # Production Docker (with Nginx)
│   ├── Dockerfile.dev         # Development Docker (no Nginx)
│   └── nginx.conf             # Nginx configuration
│
├── docker-compose.yml         # Production Docker setup
├── docker-compose.dev.yml     # Development Docker setup
├── .env.example               # Environment template
├── start-docker.bat           # Windows production start script
├── start-docker.sh            # Linux/Mac production start script
├── start-docker-dev.bat       # Windows development start script
├── start-docker-dev.sh        # Linux/Mac development start script
└── README.md                  # This file

🛠️ Technology Stack

Frontend

React 19.2.0 - UI framework
Tailwind CSS - Utility-first styling

Backend

Node.js 18+ - Runtime environment
Express.js - Web framework
Axios - HTTP client
CORS - Cross-origin resource sharing
Google Places API - Location data

DevOps

Docker - Containerization
Docker Compose - Multi-container orchestration
Nginx - Production web server

⚙️ Configuration

Backend Configuration

File: backend/.env

GOOGLE_API_KEY=your_google_api_key_here

Get Google API Key:

Go to Google Cloud Console
Create a new project or select existing
Enable "Places API"
Create credentials (API Key)
Copy key to .env file

Frontend Configuration

File: frontend/.env.production

REACT_APP_BACKEND_URL=http://localhost:5000

For production deployment, update to your backend URL:

REACT_APP_BACKEND_URL=https://api.yourdomain.com

📡 API Documentation

Backend Endpoints

POST /nearby

Find nearby places based on location and category.

Request:

{
  "latitude": 28.6139,
  "longitude": 77.2090,
  "category": "restaurant",
  "radius": 2
}

Response:

{
  "status": "success",
  "results": [
    {
      "name": "Pizza Palace",
      "address": "123 Main Street",
      "rating": 4.5,
      "map_url": "https://www.google.com/maps/dir/?api=1&origin=..."
    }
  ]
}

Error Response:

{
  "status": "error",
  "message": "User-friendly error message"
}

GET /health

Health check endpoint for monitoring.

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

🐳 Docker Setup

Production Setup (with Nginx)

Optimized for deployment:

Small image size (25MB frontend)
Nginx web server
Static file caching
Gzip compression

# Windows
start-docker.bat

# Linux/Mac
./start-docker.sh

# Or manually
docker-compose up --build

Development Setup (without Nginx)

Optimized for development:

Hot reload enabled
React dev server
Volume mounting
Easy debugging

# Windows
start-docker-dev.bat

# Linux/Mac
./start-docker-dev.sh

# Or manually
docker-compose -f docker-compose.dev.yml up --build

See: DOCKER_SCRIPTS_GUIDE.md for detailed explanation

💻 Development

Local Development (No Docker)

Backend:

cd backend
npm install
node index.js

Frontend:

cd frontend
npm install
npm start

Development with Docker

docker-compose -f docker-compose.dev.yml up

Making Changes

Frontend changes:

Edit files in frontend/src/
Changes reflect automatically with hot reload

Backend changes:

Edit files in backend/
Restart server: Ctrl+C then node index.js
Or use nodemon: npm install -g nodemon then nodemon index.js

Testing

Frontend:

cd frontend
npm test

Backend:

cd backend
# Add your tests
npm test

🚀 Deployment

Deploy with Docker

1. Build production images:

docker-compose build

2. Tag images:

docker tag nearby-locator-backend:latest your-registry/backend:v1.0
docker tag nearby-locator-frontend:latest your-registry/frontend:v1.0

3. Push to registry:

docker push your-registry/backend:v1.0
docker push your-registry/frontend:v1.0

Deploy to Cloud Platforms

Vercel (Frontend):

cd frontend
vercel deploy

Render (Backend):

Connect GitHub repository
Set environment variables
Deploy

AWS ECS / Google Cloud Run / Azure:

Use Docker images
Configure environment variables
Set up load balancer
Enable HTTPS

🐛 Troubleshooting

Common Issues

"Location service unavailable"

Cause: Invalid or missing Google API key

Solution:

Check backend/.env has valid GOOGLE_API_KEY
Verify Places API is enabled in Google Cloud Console
Restart backend server

"Can't find any places"

Cause: No results in the area or API error

Solution:

Try increasing search radius
Try different category
Check backend logs: docker-compose logs backend

Port already in use

Cause: Another service using port 3000 or 5000

Solution:

# Windows
netstat -ano | findstr :3000
# Kill the process

# Linux/Mac
lsof -i :3000
kill -9 <PID>

Docker build fails

Cause: Missing dependencies or network issues

Solution:

# Clean rebuild
docker-compose down -v
docker-compose build --no-cache
docker-compose up

Getting Help

Check logs: docker-compose logs -f
Verify environment: cat .env
Check service health: curl http://localhost:5000/health
Review documentation in /docs folder

📚 Documentation

START_HERE.md - Simple getting started guide
DOCKER_SCRIPTS_GUIDE.md - Docker scripts explained
README_DOCKER.md - Complete Docker guide
DOCKER_SETUP.md - Detailed Docker setup
WHICH_DOCKER_SETUP.md - Choosing Docker setup
ERROR_HANDLING_GUIDE.md - Error messages guide
RESPONSE_PREVIEW.md - UI response preview

🎨 Features in Detail

Chat Interface

Natural language understanding
Typing indicators
Message timestamps
User and bot avatars
Quick action buttons
Distance selector
Location permission handling

Search Results

Place cards with details
Star ratings
Clickable map links
Google Maps integration
Responsive design

🔒 Security

Environment variables for sensitive data
CORS configuration
Security headers (Nginx)
Input validation
Error message sanitization
No sensitive data in logs

📈 Performance

Frontend

Code splitting
Lazy loading
Image optimization
Gzip compression (production)
Static asset caching (production)

Backend

Efficient API calls
Error handling
Health checks
Logging

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature-name
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
Submit a pull request

📄 License

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

👥 Authors

Your Name - Initial work

🙏 Acknowledgments

Google Places API for location data
React team for the framework
Tailwind CSS for styling
Docker for containerization

📞 Support

For support, email support@example.com or open an issue on GitHub.

🗺️ Roadmap

📊 Stats

Lines of Code: ~3,000+
Components: 10+
API Endpoints: 2
Docker Images: 2
Supported Categories: 10+

Made with ❤️ using React, Node.js, and Docker

🎯 Quick Links

Getting Started
Docker Setup
API Docs
Troubleshooting
Contributing

⭐ If you find this project useful, please give it a star!

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
ERROR_HANDLING_GUIDE.md		ERROR_HANDLING_GUIDE.md
NLP_FEATURES.md		NLP_FEATURES.md
README.md		README.md
README_DOCKER.md		README_DOCKER.md
START_HERE.md		START_HERE.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
start-docker-dev.bat		start-docker-dev.bat
start-docker-dev.sh		start-docker-dev.sh
start-docker.bat		start-docker.bat
start-docker.sh		start-docker.sh

Folders and files

Latest commit

History

Repository files navigation

🌍 Nearby Locator

✨ Features

🤖 Smart Chat Interface

📍 Location-Based Search

🎨 Modern UI/UX

🗺️ Interactive Results

🚀 Quick Start

Option 1: Run Without Docker (Fastest)

Option 2: Run With Docker (Production)

📋 Table of Contents

📁 Project Structure

🛠️ Technology Stack

Frontend

Backend

DevOps

⚙️ Configuration

Backend Configuration

Frontend Configuration

📡 API Documentation

Backend Endpoints

POST /nearby

GET /health

Supported Categories

🐳 Docker Setup

Production Setup (with Nginx)

Development Setup (without Nginx)

💻 Development

Local Development (No Docker)

Development with Docker

Making Changes

Testing

🚀 Deployment

Deploy with Docker

Deploy to Cloud Platforms

🐛 Troubleshooting

Common Issues

"Location service unavailable"

"Can't find any places"

Port already in use

Docker build fails

Getting Help

📚 Documentation

🎨 Features in Detail

Chat Interface

Search Results

🔒 Security

📈 Performance

Frontend

Backend

🤝 Contributing

📄 License

👥 Authors

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

📊 Stats

🎯 Quick Links

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages