🎯 MapView v2.0 - Global Deployment Ready
✨ MAJOR FEATURES: • Auto-zoom intelligence với smart bounds fitting • Enhanced 3D GPS markers với pulsing effects • Professional route display với 6-layer rendering • Status-based parking icons với availability indicators • Production-ready build optimizations 🗺️ AUTO-ZOOM FEATURES: • Smart bounds fitting cho GPS + selected parking • Adaptive padding (50px) cho visual balance • Max zoom control (level 16) để tránh quá gần • Dynamic centering khi không có selection 🎨 ENHANCED VISUALS: • 3D GPS marker với multi-layer pulse effects • Advanced parking icons với status colors • Selection highlighting với animation • Dimming system cho non-selected items 🛣️ ROUTE SYSTEM: • OpenRouteService API integration • Multi-layer route rendering (glow, shadow, main, animated) • Real-time distance & duration calculation • Visual route info trong popup 📱 PRODUCTION READY: • SSR safe với dynamic imports • Build errors resolved • Global deployment via Vercel • Optimized performance 🌍 DEPLOYMENT: • Vercel: https://whatever-ctk2auuxr-phong12hexdockworks-projects.vercel.app • Bundle size: 22.8 kB optimized • Global CDN distribution • HTTPS enabled 💾 VERSION CONTROL: • MapView-v2.0.tsx backup created • MAPVIEW_VERSIONS.md documentation • Full version history tracking
This commit is contained in:
420
TECHNICAL_SPECIFICATION.md
Normal file
420
TECHNICAL_SPECIFICATION.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# 🚗 Smart Parking Finder - Technical Specification
|
||||
|
||||
## 📋 Project Overview
|
||||
|
||||
A responsive web application that helps users find and navigate to the nearest available parking lots using OpenStreetMap and Valhalla Routing Engine with real-time availability and turn-by-turn navigation.
|
||||
|
||||
## 🎯 Core Features
|
||||
|
||||
### 🔍 Location & Discovery
|
||||
- GPS-based user location detection
|
||||
- Interactive map with nearby parking lots
|
||||
- Real-time availability display
|
||||
- Distance and direction calculation
|
||||
- Smart parking suggestions
|
||||
|
||||
### 🗺️ Navigation & Routing
|
||||
- Valhalla-powered route generation
|
||||
- Turn-by-turn directions
|
||||
- Visual route display on map
|
||||
- Estimated arrival time
|
||||
- Alternative route options
|
||||
|
||||
### 📊 Parking Information
|
||||
- Name, address, and contact details
|
||||
- Real-time available slots
|
||||
- Pricing per hour
|
||||
- Operating hours
|
||||
- Amenities and features
|
||||
|
||||
## 🏗️ System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Frontend │ │ Backend API │ │ Database │
|
||||
│ (Next.js) │◄──►│ (NestJS) │◄──►│ PostgreSQL + │
|
||||
│ │ │ │ │ PostGIS │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Valhalla Engine │
|
||||
│ (Docker) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## 🔧 Technology Stack
|
||||
|
||||
### Frontend
|
||||
- **Framework**: Next.js 14 with TypeScript
|
||||
- **Map Library**: React Leaflet + OpenStreetMap
|
||||
- **UI Framework**: Tailwind CSS with custom branding
|
||||
- **State Management**: React Query + Zustand
|
||||
- **HTTP Client**: Axios with interceptors
|
||||
- **PWA Support**: Next.js PWA plugin
|
||||
|
||||
### Backend
|
||||
- **Framework**: NestJS with TypeScript
|
||||
- **Database ORM**: TypeORM with PostGIS
|
||||
- **Caching**: Redis for route caching
|
||||
- **API Documentation**: Swagger/OpenAPI
|
||||
- **Authentication**: JWT + Passport.js
|
||||
- **Rate Limiting**: Express rate limiter
|
||||
|
||||
### Infrastructure
|
||||
- **Routing Engine**: Valhalla (Docker)
|
||||
- **Database**: PostgreSQL 15 + PostGIS 3.3
|
||||
- **Deployment**: Docker Compose
|
||||
- **Monitoring**: Prometheus + Grafana
|
||||
- **CDN**: CloudFlare for static assets
|
||||
|
||||
## 📊 Database Schema
|
||||
|
||||
```sql
|
||||
-- Parking lots table
|
||||
CREATE TABLE parking_lots (
|
||||
id SERIAL PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
address TEXT NOT NULL,
|
||||
location GEOGRAPHY(POINT, 4326) NOT NULL,
|
||||
lat DOUBLE PRECISION NOT NULL,
|
||||
lng DOUBLE PRECISION NOT NULL,
|
||||
hourly_rate DECIMAL(10,2),
|
||||
open_time TIME,
|
||||
close_time TIME,
|
||||
available_slots INTEGER DEFAULT 0,
|
||||
total_slots INTEGER NOT NULL,
|
||||
amenities JSONB DEFAULT '{}',
|
||||
contact_info JSONB DEFAULT '{}',
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Spatial index for location queries
|
||||
CREATE INDEX idx_parking_lots_location ON parking_lots USING GIST (location);
|
||||
|
||||
-- Users table (for favorites, history)
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
email VARCHAR(255) UNIQUE,
|
||||
name VARCHAR(255),
|
||||
preferences JSONB DEFAULT '{}',
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Parking history
|
||||
CREATE TABLE parking_history (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id UUID REFERENCES users(id),
|
||||
parking_lot_id INTEGER REFERENCES parking_lots(id),
|
||||
visit_date TIMESTAMP DEFAULT NOW(),
|
||||
duration_minutes INTEGER,
|
||||
rating INTEGER CHECK (rating >= 1 AND rating <= 5)
|
||||
);
|
||||
|
||||
-- Real-time parking updates
|
||||
CREATE TABLE parking_updates (
|
||||
id SERIAL PRIMARY KEY,
|
||||
parking_lot_id INTEGER REFERENCES parking_lots(id),
|
||||
available_slots INTEGER NOT NULL,
|
||||
timestamp TIMESTAMP DEFAULT NOW(),
|
||||
source VARCHAR(50) DEFAULT 'sensor'
|
||||
);
|
||||
```
|
||||
|
||||
## 🚀 API Endpoints
|
||||
|
||||
### Parking Discovery
|
||||
```typescript
|
||||
// GET /api/parking/nearby
|
||||
interface NearbyParkingRequest {
|
||||
lat: number;
|
||||
lng: number;
|
||||
radius?: number; // meters, default 4000
|
||||
maxResults?: number; // default 20
|
||||
priceRange?: [number, number];
|
||||
amenities?: string[];
|
||||
}
|
||||
|
||||
interface NearbyParkingResponse {
|
||||
parkingLots: ParkingLot[];
|
||||
userLocation: { lat: number; lng: number };
|
||||
searchRadius: number;
|
||||
}
|
||||
```
|
||||
|
||||
### Route Planning
|
||||
```typescript
|
||||
// POST /api/routing/calculate
|
||||
interface RouteRequest {
|
||||
origin: { lat: number; lng: number };
|
||||
destination: { lat: number; lng: number };
|
||||
costing: 'auto' | 'bicycle' | 'pedestrian';
|
||||
alternatives?: number;
|
||||
}
|
||||
|
||||
interface RouteResponse {
|
||||
routes: Route[];
|
||||
summary: {
|
||||
distance: number; // km
|
||||
time: number; // minutes
|
||||
cost: number; // estimated fuel cost
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Real-time Updates
|
||||
```typescript
|
||||
// WebSocket: /ws/parking-updates
|
||||
interface ParkingUpdate {
|
||||
parkingLotId: number;
|
||||
availableSlots: number;
|
||||
timestamp: string;
|
||||
confidence: number; // 0-1
|
||||
}
|
||||
```
|
||||
|
||||
## 🎨 Brand Integration
|
||||
|
||||
Based on the existing assets in `/assets/`:
|
||||
- **Logo**: Use Logo.png for header branding
|
||||
- **Logo with Slogan**: Use Logo_and_sologan.png for splash screen
|
||||
- **Location Icons**: Integrate Location.png and mini_location.png for map markers
|
||||
|
||||
### Color Palette
|
||||
```css
|
||||
:root {
|
||||
--primary: #E85A4F; /* LACA Red */
|
||||
--secondary: #D73502; /* Darker Red */
|
||||
--accent: #8B2635; /* Deep Red */
|
||||
--success: #22C55E; /* Green for available */
|
||||
--warning: #F59E0B; /* Amber for limited */
|
||||
--danger: #EF4444; /* Red for unavailable */
|
||||
--neutral: #6B7280; /* Gray */
|
||||
}
|
||||
```
|
||||
|
||||
## 📱 UI/UX Design
|
||||
|
||||
### Layout Structure
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Header [Logo] [Search] [Profile] │
|
||||
├─────────────────┬───────────────────────┤
|
||||
│ Sidebar │ Map View │
|
||||
│ - Filters │ - User location │
|
||||
│ - Parking List │ - Parking markers │
|
||||
│ - Selected Info │ - Route overlay │
|
||||
│ - Directions │ - Controls │
|
||||
└─────────────────┴───────────────────────┘
|
||||
```
|
||||
|
||||
### Responsive Breakpoints
|
||||
- **Mobile**: < 768px (full-screen map with drawer)
|
||||
- **Tablet**: 768px - 1024px (split view)
|
||||
- **Desktop**: > 1024px (sidebar + map)
|
||||
|
||||
## 🐳 Docker Configuration
|
||||
|
||||
### Valhalla Setup
|
||||
```dockerfile
|
||||
# Dockerfile.valhalla
|
||||
FROM ghcr.io/gis-ops/docker-valhalla/valhalla:latest
|
||||
|
||||
# Copy OSM data
|
||||
COPY ./osm-data/*.pbf /custom_files/
|
||||
|
||||
# Configuration
|
||||
COPY valhalla.json /valhalla.json
|
||||
|
||||
EXPOSE 8002
|
||||
|
||||
CMD ["valhalla_service", "/valhalla.json"]
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
frontend:
|
||||
build: ./frontend
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- NEXT_PUBLIC_API_URL=http://backend:3001
|
||||
depends_on:
|
||||
- backend
|
||||
|
||||
backend:
|
||||
build: ./backend
|
||||
ports:
|
||||
- "3001:3001"
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://user:pass@postgres:5432/parking_db
|
||||
- REDIS_URL=redis://redis:6379
|
||||
- VALHALLA_URL=http://valhalla:8002
|
||||
depends_on:
|
||||
- postgres
|
||||
- redis
|
||||
- valhalla
|
||||
|
||||
postgres:
|
||||
image: postgis/postgis:15-3.3
|
||||
environment:
|
||||
- POSTGRES_DB=parking_db
|
||||
- POSTGRES_USER=user
|
||||
- POSTGRES_PASSWORD=pass
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
ports:
|
||||
- "6379:6379"
|
||||
|
||||
valhalla:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile.valhalla
|
||||
ports:
|
||||
- "8002:8002"
|
||||
volumes:
|
||||
- ./valhalla-data:/valhalla-data
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
## 🔐 Security Considerations
|
||||
|
||||
### Frontend Security
|
||||
- Content Security Policy (CSP)
|
||||
- HTTPS enforcement
|
||||
- API key protection
|
||||
- Input sanitization
|
||||
|
||||
### Backend Security
|
||||
- Rate limiting per IP
|
||||
- JWT token validation
|
||||
- SQL injection prevention
|
||||
- CORS configuration
|
||||
|
||||
### Infrastructure Security
|
||||
- Database encryption at rest
|
||||
- SSL/TLS certificates
|
||||
- Network segmentation
|
||||
- Regular security updates
|
||||
|
||||
## 📈 Performance Optimization
|
||||
|
||||
### Frontend Optimization
|
||||
- Code splitting by routes
|
||||
- Image optimization with Next.js
|
||||
- Service worker for caching
|
||||
- Lazy loading for map components
|
||||
|
||||
### Backend Optimization
|
||||
- Database query optimization
|
||||
- Redis caching for frequent requests
|
||||
- Connection pooling
|
||||
- Response compression
|
||||
|
||||
### Database Optimization
|
||||
- Spatial indexes for geo queries
|
||||
- Query result caching
|
||||
- Read replicas for scaling
|
||||
- Partitioning for large datasets
|
||||
|
||||
## 🚀 Deployment Strategy
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Local development setup
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
npm run dev:frontend
|
||||
npm run dev:backend
|
||||
```
|
||||
|
||||
### Production
|
||||
```bash
|
||||
# Production deployment
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
### CI/CD Pipeline
|
||||
1. **Build**: Docker images for each service
|
||||
2. **Test**: Unit tests, integration tests, E2E tests
|
||||
3. **Deploy**: Blue-green deployment strategy
|
||||
4. **Monitor**: Health checks and performance metrics
|
||||
|
||||
## 📊 Monitoring & Analytics
|
||||
|
||||
### Application Metrics
|
||||
- Response times
|
||||
- Error rates
|
||||
- User engagement
|
||||
- Route calculation performance
|
||||
|
||||
### Business Metrics
|
||||
- Popular parking locations
|
||||
- Peak usage times
|
||||
- User retention
|
||||
- Revenue per parking lot
|
||||
|
||||
## 🔄 Future Enhancements
|
||||
|
||||
### Phase 2 Features
|
||||
- Parking reservations
|
||||
- Payment integration
|
||||
- User reviews and ratings
|
||||
- Push notifications for parking alerts
|
||||
|
||||
### Phase 3 Features
|
||||
- AI-powered parking predictions
|
||||
- Electric vehicle charging stations
|
||||
- Multi-language support
|
||||
- Offline mode with cached data
|
||||
|
||||
## 📋 Implementation Timeline
|
||||
|
||||
### Week 1-2: Foundation
|
||||
- Project setup and infrastructure
|
||||
- Database schema and migrations
|
||||
- Basic API endpoints
|
||||
|
||||
### Week 3-4: Core Features
|
||||
- Map integration with Leaflet
|
||||
- Parking lot display and search
|
||||
- User location detection
|
||||
|
||||
### Week 5-6: Navigation
|
||||
- Valhalla integration
|
||||
- Route calculation and display
|
||||
- Turn-by-turn directions
|
||||
|
||||
### Week 7-8: Polish
|
||||
- UI/UX improvements
|
||||
- Performance optimization
|
||||
- Testing and bug fixes
|
||||
|
||||
### Week 9-10: Deployment
|
||||
- Production setup
|
||||
- CI/CD pipeline
|
||||
- Monitoring and analytics
|
||||
|
||||
## 🏁 Success Metrics
|
||||
|
||||
### Technical KPIs
|
||||
- Page load time < 2 seconds
|
||||
- Route calculation < 3 seconds
|
||||
- 99.9% uptime
|
||||
- Zero security vulnerabilities
|
||||
|
||||
### User Experience KPIs
|
||||
- User retention > 60%
|
||||
- Average session time > 5 minutes
|
||||
- Route accuracy > 95%
|
||||
- User satisfaction score > 4.5/5
|
||||
|
||||
This comprehensive specification provides a solid foundation for building a world-class parking finder application with modern web technologies and best practices.
|
||||
Reference in New Issue
Block a user