# 🚗 Smart Parking Finder

A modern web application for finding and navigating to available parking spaces using OpenStreetMap and Valhalla routing engine.

## 🏗️ Project Structure

```
smart-parking-finder/
├── frontend/                 # Next.js frontend application
│   ├── src/
│   │   ├── app/             # App router pages
│   │   ├── components/      # Reusable React components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── services/        # API services
│   │   ├── types/           # TypeScript type definitions
│   │   └── utils/           # Utility functions
│   ├── public/              # Static assets
│   └── package.json
├── backend/                 # NestJS backend API
│   ├── src/
│   │   ├── modules/         # Feature modules
│   │   ├── common/          # Shared utilities
│   │   ├── config/          # Configuration
│   │   └── database/        # Database setup
│   └── package.json
├── valhalla/                # Valhalla routing engine
│   ├── Dockerfile
│   ├── valhalla.json        # Valhalla configuration
│   └── osm-data/            # OpenStreetMap data files
├── docker-compose.yml       # Development environment
├── docker-compose.prod.yml  # Production environment
└── README.md
```

## 🚀 Quick Start

### Prerequisites
- Docker & Docker Compose
- Node.js 18+
- PostgreSQL with PostGIS

### Development Setup

1. **Clone the repository**
```bash
git clone <repository-url>
cd smart-parking-finder
```

2. **Start infrastructure services**
```bash
docker-compose up -d postgres redis valhalla
```

3. **Install dependencies**
```bash
# Frontend
cd frontend && npm install

# Backend
cd ../backend && npm install
```

4. **Environment setup**
```bash
# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env
```

5. **Database setup**
```bash
# Run migrations
cd backend && npm run migration:run

# Seed initial data
npm run seed:run
```

6. **Start development servers**
```bash
# Terminal 1 - Backend
cd backend && npm run start:dev

# Terminal 2 - Frontend
cd frontend && npm run dev
```

Visit `http://localhost:3000` to see the application.

## 🔧 Technology Stack

### Frontend
- **Next.js 14** - React framework with App Router
- **TypeScript** - Type safety and better DX
- **Tailwind CSS** - Utility-first CSS framework
- **React Leaflet** - Interactive maps
- **React Query** - Server state management
- **Zustand** - Client state management

### Backend
- **NestJS** - Scalable Node.js framework
- **TypeORM** - Database ORM with TypeScript
- **PostgreSQL + PostGIS** - Spatial database
- **Redis** - Caching and session storage
- **Swagger** - API documentation

### Infrastructure
- **Docker** - Containerization
- **Valhalla** - Open-source routing engine
- **CloudFlare** - CDN and security

## 🌟 Features

### ✅ Implemented
- User location detection via GPS
- Interactive map with OpenStreetMap
- Nearby parking lot search
- Real-time availability display
- Route calculation with Valhalla
- Turn-by-turn navigation
- Responsive design
- PWA support

### 🚧 In Progress
- User authentication
- Parking reservations
- Payment integration
- Push notifications

### 📋 Planned
- Offline mode
- Multi-language support
- EV charging station integration
- AI-powered parking predictions

## 📊 API Documentation

### Parking Endpoints
- `GET /api/parking/nearby` - Find nearby parking lots
- `GET /api/parking/:id` - Get parking lot details
- `POST /api/parking/:id/reserve` - Reserve a parking space

### Routing Endpoints
- `POST /api/routes/calculate` - Calculate route between points
- `GET /api/routes/:id` - Get route details
- `POST /api/routes/:id/optimize` - Optimize existing route

### User Endpoints
- `POST /api/auth/login` - User authentication
- `GET /api/users/profile` - Get user profile
- `POST /api/users/favorites` - Add favorite parking lot

Full API documentation available at `/api/docs` when running the backend.

## 🧪 Testing

### Frontend Testing
```bash
cd frontend
npm run test          # Unit tests
npm run test:e2e      # End-to-end tests
npm run test:coverage # Coverage report
```

### Backend Testing
```bash
cd backend
npm run test          # Unit tests
npm run test:e2e      # Integration tests
npm run test:cov      # Coverage report
```

## 🚀 Deployment

### Development
```bash
docker-compose up -d
```

### Production
```bash
docker-compose -f docker-compose.prod.yml up -d
```

### Environment Variables
```bash
# Frontend (.env.local)
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_MAP_TILES_URL=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

# Backend (.env)
DATABASE_URL=postgresql://user:password@localhost:5432/parking_db
REDIS_URL=redis://localhost:6379
VALHALLA_URL=http://localhost:8002
JWT_SECRET=your-jwt-secret
```

## 📈 Performance

### Metrics
- Page load time: < 2 seconds
- Route calculation: < 3 seconds
- Map rendering: < 1 second
- API response time: < 500ms

### Optimization
- Code splitting for optimal bundle size
- Image optimization with Next.js
- Redis caching for frequent requests
- Database query optimization
- CDN for static assets

## 🔒 Security

### Implemented
- HTTPS enforcement
- JWT authentication
- Rate limiting
- Input validation
- SQL injection prevention
- XSS protection

### Best Practices
- Regular dependency updates
- Security headers
- Environment variable protection
- API key rotation
- Database encryption

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

### Development Guidelines
- Follow TypeScript best practices
- Write tests for new features
- Update documentation
- Follow conventional commits
- Ensure code passes linting

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 Email: support@smartparking.com
- 💬 Discord: [Join our community](https://discord.gg/smartparking)
- 🐛 Issues: [GitHub Issues](https://github.com/your-org/smart-parking-finder/issues)
- 📖 Docs: [Documentation](https://docs.smartparking.com)

## 🙏 Acknowledgments

- OpenStreetMap for map data
- Valhalla project for routing engine
- PostGIS for spatial database capabilities
- All contributors and beta testers

---

Made with ❤️ by the Smart Parking Team