Laca-City/TECHNICAL_SPECIFICATION.md

🚗 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

-- 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

// 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

// 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

// 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

: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.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

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

# Local development setup
docker-compose -f docker-compose.dev.yml up -d
npm run dev:frontend
npm run dev:backend

Production

# 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.