🚗 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

git clone <repository-url>
cd smart-parking-finder

2. Start infrastructure services

docker-compose up -d postgres redis valhalla

3. Install dependencies

# Frontend
cd frontend && npm install

# Backend
cd ../backend && npm install

4. Environment setup

# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

5. Database setup

# Run migrations
cd backend && npm run migration:run

# Seed initial data
npm run seed:run

6. Start development servers

# 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

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

Backend Testing

cd backend
npm run test          # Unit tests
npm run test:e2e      # Integration tests
npm run test:cov      # Coverage report

🚀 Deployment

Development

docker-compose up -d

Production

docker-compose -f docker-compose.prod.yml up -d

Environment Variables

# 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 file for details.

🆘 Support

• 📧 Email: support@smartparking.com
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

🙏 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