# Gas Stations Feature - Health Checks Validation

## Overview

Comprehensive health check procedures for validating the Gas Stations feature in production. This document covers API endpoint testing, database validation, external service integration, and performance benchmarks.

## Quick Health Check

Run this single command for immediate status:

```bash
# All-in-one health check
curl -s https://motovaultpro.com/api/health | jq
```

**Expected Output**:
```json
{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}
```

## Detailed Health Checks

### 1. API Endpoints Health

#### Get JWT Token First

```bash
# From Auth0 authentication flow or test token
export TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

#### Test Search Endpoint

```bash
curl -X POST https://motovaultpro.com/api/stations/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 5000
  }' \
  -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  | jq
```

**Expected**:
- HTTP Status: 200
- Response contains `stations` array
- Response contains `searchLocation` object
- Time: <1.5 seconds

#### Test Save Endpoint

```bash
# First search to get a place ID
PLACE_ID=$(curl -s -X POST https://motovaultpro.com/api/stations/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 37.7749, "longitude": -122.4194}' \
  | jq -r '.stations[0].placeId')

# Then save station
curl -X POST https://motovaultpro.com/api/stations/save \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"placeId\": \"$PLACE_ID\", \"nickname\": \"Health Check Station\"}" \
  -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  | jq
```

**Expected**:
- HTTP Status: 201
- Response contains saved station with ID
- Time: <0.1 seconds

#### Test Get Saved Endpoint

```bash
curl -X GET https://motovaultpro.com/api/stations/saved \
  -H "Authorization: Bearer $TOKEN" \
  -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  | jq
```

**Expected**:
- HTTP Status: 200
- Response is array
- Time: <0.1 seconds

#### Test Delete Endpoint

```bash
curl -X DELETE https://motovaultpro.com/api/stations/saved/$PLACE_ID \
  -H "Authorization: Bearer $TOKEN" \
  -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n"
```

**Expected**:
- HTTP Status: 204 (No Content)
- Time: <0.1 seconds

### 2. Database Health

#### Check Tables Exist

```bash
docker compose exec postgres psql -U postgres -d motovaultpro \
  -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'station%' ORDER BY tablename;"
```

**Expected Output**:
```
   tablename
-----------------
 station_cache
 saved_stations
(2 rows)
```

#### Check Table Sizes

```bash
docker compose exec postgres psql -U postgres -d motovaultpro <<EOF
SELECT
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size,
  n_live_tup AS row_count
FROM pg_stat_user_tables
WHERE tablename LIKE 'station%'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
EOF
```

**Expected**: Tables exist with reasonable sizes (not unexpectedly large)

#### Check Indexes

```bash
docker compose exec postgres psql -U postgres -d motovaultpro <<EOF
SELECT
  tablename,
  indexname,
  idx_scan as index_scans,
  idx_tup_read as tuples_read,
  idx_tup_fetch as tuples_fetched
FROM pg_stat_user_indexes
WHERE tablename LIKE 'station%'
ORDER BY tablename, indexname;
EOF
```

**Expected**: All indexes present and being used (idx_scan > 0 after some usage)

#### Check Data Integrity

```bash
docker compose exec postgres psql -U postgres -d motovaultpro <<EOF
-- Check for orphaned saved stations (station not in cache)
SELECT COUNT(*) as orphaned_count
FROM saved_stations ss
LEFT JOIN station_cache sc ON ss.place_id = sc.place_id
WHERE sc.place_id IS NULL
  AND ss.deleted_at IS NULL;

-- Check for duplicate saved stations (should be 0)
SELECT user_id, place_id, COUNT(*) as duplicates
FROM saved_stations
WHERE deleted_at IS NULL
GROUP BY user_id, place_id
HAVING COUNT(*) > 1;
EOF
```

**Expected**:
- Orphaned count: Low (acceptable if stations aged out of cache)
- Duplicates: 0 (enforced by UNIQUE constraint)

### 3. Redis Cache Health

#### Check Redis Connection

```bash
docker compose exec redis redis-cli ping
```

**Expected**: `PONG`

#### Check Redis Memory

```bash
docker compose exec redis redis-cli info memory | grep used_memory_human
```

**Expected**: Reasonable memory usage (depends on cache size)

#### Check Station Cache Keys

```bash
docker compose exec redis redis-cli KEYS "station:*"
```

**Expected**: List of cached station keys (if any recent searches)

#### Check Cache TTL

```bash
# Get a station cache key
KEY=$(docker compose exec redis redis-cli KEYS "station:*" | head -1)

# Check TTL
docker compose exec redis redis-cli TTL $KEY
```

**Expected**: TTL value (3600 = 1 hour remaining)

### 4. Google Maps API Health

#### Test Direct API Call

```bash
API_KEY=$(cat ./secrets/app/google-maps-api-key.txt)

curl -s "https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=37.7749,-122.4194&radius=5000&type=gas_station&key=$API_KEY" \
  | jq '.status, (.results | length)'
```

**Expected Output**:
```
"OK"
20
```

#### Check API Quota

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Navigate to APIs & Services > Dashboard
3. Click on Places API
4. Check current usage

**Expected**: Usage within quota limits

#### Check Circuit Breaker State

```bash
docker compose logs mvp-backend | grep -i "circuit breaker"
```

**Expected**: No "circuit breaker opened" messages (or rare occurrences)

### 5. Frontend Health

#### Check Frontend Loads

```bash
curl -I https://motovaultpro.com
```

**Expected**:
```
HTTP/2 200
content-type: text/html
```

#### Check config.js Loads

```bash
curl -s https://motovaultpro.com/config.js
```

**Expected Output**:
```javascript
window.CONFIG = {
  googleMapsApiKey: "AIzaSy..."
};
```

#### Check Browser Console (Manual)

1. Open https://motovaultpro.com
2. Open Developer Tools (F12)
3. Go to Console tab
4. Check for errors

**Expected**: No errors related to:
- Config loading
- Google Maps API
- API calls

#### Check Network Requests (Manual)

1. Open Developer Tools (F12)
2. Go to Network tab
3. Navigate to Stations feature
4. Perform a search

**Expected**:
- config.js: 200 OK
- Search API call: 200 OK
- Google Maps script: 200 OK

### 6. User Isolation Validation

Verify users can only access their own data:

```bash
# User 1 Token
USER1_TOKEN="..."

# User 1 saves a station
PLACE_ID=$(curl -s -X POST https://motovaultpro.com/api/stations/search \
  -H "Authorization: Bearer $USER1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 37.7749, "longitude": -122.4194}' \
  | jq -r '.stations[0].placeId')

curl -s -X POST https://motovaultpro.com/api/stations/save \
  -H "Authorization: Bearer $USER1_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"placeId\": \"$PLACE_ID\"}" > /dev/null

# User 2 Token
USER2_TOKEN="..."

# User 2 tries to access User 1's saved stations
curl -s -X GET https://motovaultpro.com/api/stations/saved \
  -H "Authorization: Bearer $USER2_TOKEN" \
  | jq '. | length'
```

**Expected**: 0 (User 2 cannot see User 1's stations)

### 7. Performance Benchmarks

#### Search Performance

```bash
# Run 10 searches and measure average time
for i in {1..10}; do
  curl -s -o /dev/null -w "%{time_total}\n" \
    -X POST https://motovaultpro.com/api/stations/search \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"latitude": 37.7749, "longitude": -122.4194}'
done | awk '{sum+=$1} END {print "Average:", sum/NR, "seconds"}'
```

**Expected**: Average < 1.5 seconds

#### Save Performance

```bash
# Measure save operation time
time curl -s -o /dev/null \
  -X POST https://motovaultpro.com/api/stations/save \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"placeId\": \"$PLACE_ID\"}"
```

**Expected**: < 0.1 seconds

#### Load Test (Optional)

Use Apache Bench or similar:

```bash
# Install Apache Bench
sudo apt-get install apache2-utils

# Run load test (100 requests, 10 concurrent)
ab -n 100 -c 10 -T 'application/json' -H "Authorization: Bearer $TOKEN" \
  -p search_payload.json \
  https://motovaultpro.com/api/stations/search
```

**Expected**:
- 99% of requests < 2 seconds
- No failed requests

## Automated Health Check Script

Create a comprehensive health check script:

```bash
#!/bin/bash
# health-check.sh

set -e

echo "=== Gas Stations Feature Health Check ==="
echo ""

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

TOKEN="${JWT_TOKEN:-$1}"

if [ -z "$TOKEN" ]; then
  echo "${RED}ERROR: JWT token required${NC}"
  echo "Usage: ./health-check.sh <jwt_token>"
  echo "Or set JWT_TOKEN environment variable"
  exit 1
fi

echo "1. Backend Health Check..."
if curl -s https://motovaultpro.com/api/health | jq -e '.status == "ok"' > /dev/null; then
  echo "${GREEN}✓ Backend healthy${NC}"
else
  echo "${RED}✗ Backend unhealthy${NC}"
  exit 1
fi

echo ""
echo "2. Database Tables Check..."
if docker compose exec -T postgres psql -U postgres -d motovaultpro \
  -tc "SELECT COUNT(*) FROM pg_tables WHERE tablename IN ('station_cache', 'saved_stations');" \
  | grep -q "2"; then
  echo "${GREEN}✓ Tables exist${NC}"
else
  echo "${RED}✗ Tables missing${NC}"
  exit 1
fi

echo ""
echo "3. Redis Connection Check..."
if docker compose exec -T redis redis-cli ping | grep -q "PONG"; then
  echo "${GREEN}✓ Redis connected${NC}"
else
  echo "${RED}✗ Redis unavailable${NC}"
  exit 1
fi

echo ""
echo "4. Search API Check..."
if curl -s -X POST https://motovaultpro.com/api/stations/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 37.7749, "longitude": -122.4194}' \
  | jq -e '.stations | length > 0' > /dev/null; then
  echo "${GREEN}✓ Search API working${NC}"
else
  echo "${RED}✗ Search API failed${NC}"
  exit 1
fi

echo ""
echo "5. Frontend Config Check..."
if docker compose exec -T mvp-frontend cat /usr/share/nginx/html/config.js \
  | grep -q "googleMapsApiKey"; then
  echo "${GREEN}✓ Frontend config generated${NC}"
else
  echo "${RED}✗ Frontend config missing${NC}"
  exit 1
fi

echo ""
echo "6. Google Maps API Check..."
API_KEY=$(cat ./secrets/app/google-maps-api-key.txt)
if curl -s "https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=37.7749,-122.4194&radius=5000&type=gas_station&key=$API_KEY" \
  | jq -e '.status == "OK"' > /dev/null; then
  echo "${GREEN}✓ Google Maps API responding${NC}"
else
  echo "${YELLOW}⚠ Google Maps API issue (check quota/key)${NC}"
fi

echo ""
echo "${GREEN}=== All Health Checks Passed ===${NC}"
```

**Usage**:
```bash
chmod +x health-check.sh
JWT_TOKEN="your_token_here" ./health-check.sh
```

## Monitoring Checklist

### Daily Monitoring

- [ ] Backend container running: `docker compose ps mvp-backend`
- [ ] Frontend container running: `docker compose ps mvp-frontend`
- [ ] No errors in logs: `docker compose logs --tail=100 | grep -i error`
- [ ] Health endpoint responding: `curl https://motovaultpro.com/api/health`

### Weekly Monitoring

- [ ] Google Maps API usage within limits
- [ ] Database size reasonable: Check table sizes
- [ ] Redis memory usage acceptable
- [ ] No circuit breaker failures
- [ ] Performance metrics stable

### Monthly Monitoring

- [ ] Review Google Maps API costs
- [ ] Rotate API keys (if policy requires)
- [ ] Clean up old test data
- [ ] Review and archive logs

## Alerting

### Critical Alerts

Set up alerts for:
- Backend container down
- Health check fails
- Google Maps API quota exceeded
- Database connection failures
- Circuit breaker opens frequently (>10 times/hour)

### Warning Alerts

Set up warnings for:
- Response times > 2 seconds
- Google Maps API usage > 80% of quota
- Redis memory > 80% capacity
- Database table size growing unexpectedly

## References

- Architecture: `/backend/src/features/stations/docs/ARCHITECTURE.md`
- API Documentation: `/backend/src/features/stations/docs/API.md`
- Deployment Checklist: `/backend/src/features/stations/docs/deployment/DEPLOYMENT-CHECKLIST.md`
- Secrets Verification: `/backend/src/features/stations/docs/deployment/SECRETS-VERIFICATION.md`
- Production Readiness: `/backend/src/features/stations/docs/deployment/PRODUCTION-READINESS.md`
