Laca-City/backend

🚗 Smart Parking Finder - Backend API

A robust NestJS backend API for the Smart Parking Finder application, providing parking discovery, route calculation, and real-time availability updates.

🚀 Features

• Parking Discovery: Find nearby parking lots using PostGIS spatial queries
• Route Calculation: Integration with Valhalla routing engine for turn-by-turn directions
• Real-time Updates: WebSocket support for live parking availability
• Comprehensive API: RESTful endpoints with OpenAPI/Swagger documentation
• Performance Optimized: Redis caching and database connection pooling
• Production Ready: Docker containerization with health checks

🛠️ Technology Stack

• Framework: NestJS with TypeScript
• Database: PostgreSQL 15 + PostGIS 3.3
• ORM: TypeORM with spatial support
• Caching: Redis for performance optimization
• Documentation: Swagger/OpenAPI
• Security: Helmet, CORS, rate limiting
• Validation: Class-validator and class-transformer

📋 Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose
• PostgreSQL with PostGIS extension
• Redis server

🔧 Installation

Using Docker (Recommended)

# Start the entire stack
docker-compose up -d

# View logs
docker-compose logs -f backend

Manual Setup

# 1. Install dependencies
npm install

# 2. Set up environment variables
cp .env.example .env

# 3. Start PostgreSQL and Redis
# Make sure both services are running

# 4. Run database migrations
npm run migration:run

# 5. Seed initial data
npm run seed

# 6. Start development server
npm run start:dev

🌍 Environment Variables

# Application
NODE_ENV=development
PORT=3001
CORS_ORIGIN=http://localhost:3000

# Database
DATABASE_URL=postgresql://parking_user:parking_pass@localhost:5432/parking_db

# Redis
REDIS_URL=redis://localhost:6379

# External Services
VALHALLA_URL=http://valhalla:8002

# Security
JWT_SECRET=your-super-secure-jwt-secret

# Logging
LOG_LEVEL=debug

📚 API Documentation

Once the server is running, access the interactive API documentation:

• Swagger UI: http://localhost:3001/api/docs
• OpenAPI JSON: http://localhost:3001/api/docs-json

🔗 API Endpoints

Parking Management

Method	Endpoint	Description
POST	/api/parking/nearby	Find nearby parking lots
GET	/api/parking	Get all parking lots
GET	/api/parking/popular	Get popular parking lots
GET	/api/parking/:id	Get parking lot details
PUT	/api/parking/:id/availability	Update availability
GET	/api/parking/:id/history	Get update history

Route Calculation

Method	Endpoint	Description
POST	/api/routing/calculate	Calculate route between points
GET	/api/routing/status	Check routing service status

System Health

Method	Endpoint	Description
GET	/api/health	Application health check

🧪 Example API Usage

Find Nearby Parking

curl -X POST http://localhost:3001/api/parking/nearby \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 1.3521,
    "lng": 103.8198,
    "radius": 4000,
    "maxResults": 10
  }'

Calculate Route

curl -X POST http://localhost:3001/api/routing/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "originLat": 1.3521,
    "originLng": 103.8198,
    "destinationLat": 1.3048,
    "destinationLng": 103.8318,
    "costing": "auto"
  }'

Update Parking Availability

curl -X PUT http://localhost:3001/api/parking/1/availability \
  -H "Content-Type: application/json" \
  -d '{
    "availableSlots": 45,
    "source": "sensor",
    "confidence": 0.95
  }'

🗄️ 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 '{}',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Spatial index for efficient location queries
CREATE INDEX idx_parking_lots_location ON parking_lots USING GIST (location);

🔧 Database Management

Run Migrations

# Generate new migration
npm run migration:generate src/database/migrations/AddNewFeature

# Run pending migrations
npm run migration:run

# Revert last migration
npm run migration:revert

Seed Data

# Run all seeds
npm run seed

# Seed specific data
npm run seed:parking-lots

📈 Performance Features

Spatial Queries

Optimized PostGIS queries for efficient nearby parking search:

-- Find parking within 4km radius
SELECT *, ST_Distance(location::geography, ST_Point($1, $2)::geography) as distance
FROM parking_lots
WHERE ST_DWithin(location::geography, ST_Point($1, $2)::geography, 4000)
ORDER BY distance ASC;

Caching Strategy

• Route Calculations: Cached for 5 minutes
• Parking Data: Cached for 1 minute
• Static Data: Cached for 1 hour

Connection Pooling

// Database configuration
extra: {
  max: 20,                    // Maximum connections
  connectionTimeoutMillis: 2000,
  idleTimeoutMillis: 30000,
}

🛡️ Security Features

• Rate Limiting: 100 requests per minute per IP
• Input Validation: Comprehensive DTO validation
• SQL Injection Protection: TypeORM query builder
• CORS Configuration: Configurable origins
• Helmet: Security headers middleware

📊 Monitoring & Logging

Health Checks

# Application health
curl http://localhost:3001/api/health

# Database connectivity
curl http://localhost:3001/api/health/database

# External services
curl http://localhost:3001/api/routing/status

Logging Levels

• Error: Application errors and exceptions
• Warn: Performance issues and deprecation warnings
• Info: General application flow
• Debug: Detailed execution information

🧪 Testing

# Unit tests
npm run test

# Test coverage
npm run test:cov

# End-to-end tests
npm run test:e2e

# Watch mode
npm run test:watch

🐳 Docker Configuration

Development

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f backend

# Execute commands in container
docker-compose exec backend npm run migration:run

Production

# Build production image
docker build -t smart-parking-backend .

# Run production container
docker run -p 3001:3001 smart-parking-backend

🔍 Troubleshooting

Common Issues

1. Database Connection Failed

   # Check PostgreSQL status
   docker-compose exec postgres pg_isready -U parking_user
   
   # View database logs
   docker-compose logs postgres
   

2. Valhalla Service Unavailable

   # Check Valhalla status
   curl http://localhost:8002/status
   
   # Restart Valhalla service
   docker-compose restart valhalla
   

3. High Memory Usage

   # Monitor Docker stats
   docker stats
   
   # Optimize connection pool
   # Reduce max connections in database config
   

Performance Optimization

1. Database Indexes

   -- Monitor slow queries
   SELECT query, mean_time, calls 
   FROM pg_stat_statements 
   ORDER BY mean_time DESC;
   
   -- Add indexes for frequent queries
   CREATE INDEX idx_parking_lots_hourly_rate ON parking_lots(hourly_rate);
   

2. Cache Optimization

   # Monitor Redis memory usage
   docker-compose exec redis redis-cli info memory
   
   # Clear cache if needed
   docker-compose exec redis redis-cli FLUSHALL
   

📝 Development Guidelines

Code Style

• Use TypeScript strict mode
• Follow NestJS conventions
• Implement proper error handling
• Add comprehensive API documentation
• Write unit tests for services
• Use proper logging levels

Git Workflow

# Feature branch naming
git checkout -b feature/parking-search-optimization

# Commit message format
git commit -m "feat(parking): optimize spatial queries with better indexing"

# Push and create PR
git push origin feature/parking-search-optimization

🚀 Deployment

Production Checklist

• Environment variables configured
• Database migrations applied
• SSL certificates installed
• Monitoring setup
• Backup strategy implemented
• Load balancer configured
• CDN setup for static assets

📞 Support

For technical issues or questions:

• Documentation: Check the API docs at /api/docs
• Logs: Use docker-compose logs backend
• Health Check: Monitor /api/health endpoint
• Performance: Check database and Redis metrics

---

Built with ❤️ using NestJS and TypeScript