SkyPulse

Outdoor activity score API — calculates a 0-100 score based on real-time weather and air quality data.

Run Locally

Requires Node.js 22+.

cd src
npm install
npm run seed    # generate the SQLite database
npm start       # server starts on http://localhost:3000

Example

curl "http://localhost:3000/api/v1/activity-score?lat=40.71&lon=-74.01&user_id=test_user"
curl "http://localhost:3000/api/v1/locations"

Run with Docker

docker compose up --build

The service will be available at http://localhost:3000.

Deploy

1. Provision the Droplet

cd terraform
terraform init
terraform apply \
  -var="do_token=YOUR_DIGITALOCEAN_TOKEN" \
  -var="ssh_key_fingerprint=YOUR_SSH_KEY_FINGERPRINT"

2. Deploy the app

ssh root@$(terraform -chdir=terraform output -raw droplet_ip)
git clone <repo-url> /opt/skypulse
cd /opt/skypulse
docker compose up -d

The service will be live on port 3000.

API Endpoints

Endpoint	Method	Description
/api/v1/activity-score?lat=&lon=&user_id=	GET	Returns outdoor activity score with weather and air quality data
/api/v1/locations	GET	Lists all tracked locations

Improvements Over Original

• Parallel external API calls — Weather and air quality requests run concurrently via Promise.all instead of sequentially, reducing response latency.
• Error handling — External API failures return a proper 502 response instead of crashing the server.
• Fire-and-forget analytics — The analytics POST is non-blocking and failures are caught silently, so analytics downtime doesn't affect user-facing responses.
• Database opened read-only — The app only reads from SQLite; opening in read-only mode makes this explicit and prevents accidental writes.

AI Tools Used

• Claude Code (Anthropic) — used for code generation, Dockerfile authoring, and Terraform configuration.