NHS Locator

A modern, AI-powered web application to find NHS healthcare facilities near you. Find pharmacies, GP surgeries, walk-in centres, hospitals, and more with intelligent search and real-time information.

Features

Core Functionality

• 🔍 Smart Search - AI-powered natural language search with autocomplete
• 📍 Location-Based - Find facilities nearest to you with accurate distance
• 🗺️ Interactive Map - View facilities on a map with clustering (Google Maps integration)
• 🎯 Quick Actions - One-tap search for pharmacies, GPs, walk-in centres, urgent care
• ⭐ Favorites - Save preferred facilities for quick access
• 🔧 Advanced Filters - Filter by facility type, services, opening hours, accessibility

User Experience

• 📱 Fully Responsive - Optimized for desktop, tablet, and mobile
• ⚡ Fast & Smooth - Instant search with elegant animations
• ♿ Accessible - WCAG compliant with keyboard navigation
• 🌙 Modern Design - Clean, professional NHS-branded interface
• 🔄 Offline-Ready - Works with mock data when backend is unavailable

Quick Start

Prerequisites

• Node.js 18+ and npm 9+
• (Optional) Python 3.11+ for backend

Run Frontend Only (Standalone Mode)

The app works completely standalone with mock data:

# Navigate to frontend
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173 in your browser.

Run with Backend (Full Mode)

For production data from NHS APIs:

# Terminal 1: Start backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Terminal 2: Start frontend
cd frontend
npm install
npm run dev

Tech Stack

Frontend

Technology	Purpose
React 18	UI library
TypeScript	Type safety
Vite	Build tool
Tailwind CSS	Styling
Framer Motion	Animations
Zustand	State management
React Router	Routing
Lucide React	Icons

Backend (Optional)

Technology	Purpose
Python 3.11	Runtime
FastAPI	API framework
PostgreSQL + PostGIS	Database
Redis	Caching
Sentence Transformers	AI embeddings

Project Structure

nhs-locator/
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/       # React components
│   │   ├── hooks/            # Custom hooks
│   │   ├── services/         # API & mock data
│   │   ├── store/            # State management
│   │   ├── styles/           # Global styles
│   │   └── types/            # TypeScript types
│   ├── BUILD.md              # Detailed build docs
│   ├── package.json
│   └── vite.config.ts
├── backend/                  # FastAPI backend
│   ├── app/
│   │   ├── ai/               # AI/ML components
│   │   ├── models/           # Data models
│   │   ├── routers/          # API routes
│   │   ├── services/         # Business logic
│   │   └── main.py
│   └── requirements.txt
└── README.md

Environment Variables

Frontend (.env)

# Optional - app works without these
VITE_API_BASE_URL=http://localhost:8000/api
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key

Backend (.env)

NHS_API_KEY=your_nhs_api_key
GOOGLE_PLACES_API_KEY=your_google_api_key
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/nhs_locator
REDIS_URL=redis://localhost:6379

Building for Production

Frontend Build

cd frontend
npm run build
npm run preview  # Preview production build

The production build is output to frontend/dist/.

Deployment

The frontend can be deployed to:

• Vercel: vercel --prod
• Netlify: netlify deploy --prod --dir=dist
• Docker: See frontend/Dockerfile
• Any static host: Upload dist/ folder

Design System

NHS Brand Colors

• Primary: #005EB8 (NHS Blue)
• Dark: #003087
• Bright: #0072CE
• Light: #41B6E6
• Green: #007F3B
• Orange: #ED8B00

Typography

• Font: DM Sans (Google Fonts)
• Sizes: 12px - 48px scale

Key UI Components

• Cards with subtle shadows
• Rounded corners (8-24px)
• Smooth animations (200-300ms)
• Touch-friendly targets (44px min)

API Documentation

When backend is running:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Endpoint	Method	Description
/api/search	POST	AI-powered facility search
/api/search/autocomplete	GET	Search suggestions
/api/search/quick/{type}	GET	Quick search by type
/api/facilities/nearby	GET	Nearby facilities
/api/facilities/{id}	GET	Facility details

Screenshots

Landing Page

Modern, catchy landing page with feature highlights and clear call-to-action.

Search Interface

Clean search bar with autocomplete and quick action buttons.

Results View

List and map view toggle with sorting and filtering options.

Facility Details

Comprehensive facility information with directions and contact options.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• NHS Digital for healthcare facility APIs
• Google for Maps and Places APIs
• The open-source community for amazing tools

---

Built with ❤️ for the NHS

For detailed frontend build instructions, see frontend/BUILD.md