paragliding/DEV_SETUP.md

# Local Development Setup

This guide shows how to run the application locally for faster development iteration.

## Overview

Instead of running everything in containers, you can run just PostgreSQL in a container and run the backend (Go) and frontend (Next.js) natively on your machine. This provides:

- ✨ Faster hot-reload and rebuild times
- 🔧 Better debugging experience
- 📦 Smaller resource footprint
- 🚀 Quicker iteration cycles

## Prerequisites

- **Go** 1.24+ installed
- **Node.js** 18+ and npm (or Bun)
- **Podman** or **Docker** (for PostgreSQL only)

## Quick Start

### Option 1: Single Command - Everything! (Recommended)

```bash
# Setup AND start all services in background
./dev.sh --start
```

**That's it!** This one command:
- ✓ Starts PostgreSQL (if not running)
- ✓ Creates `.env` files (if they don't exist)
- ✓ Runs database migrations (if needed)
- ✓ Starts backend in background
- ✓ Starts frontend in background

View logs: `tail -f backend.log` or `tail -f frontend.log`
Stop services: `./dev.sh --stop`
Check status: `./dev.sh --status`

### Option 2: Setup Only (Manual Start)

```bash
# Run setup without starting services
./dev.sh

# Then in separate terminals:
# Terminal 1 - Backend
make run-backend

# Terminal 2 - Frontend
make run-frontend
```

The `dev.sh` script is **idempotent** - you can run it multiple times safely. It will:
- ✓ Check if PostgreSQL is already running (won't restart if running)
- ✓ Create .env files only if they don't exist
- ✓ Run migrations only if needed
- ✓ Skip steps that are already complete
- ✓ Detect if services are already running (won't duplicate)

### Option 3: Using Make

```bash
# Start PostgreSQL and run migrations
make dev-local

# Then in separate terminals:
# Terminal 1 - Backend
make run-backend

# Terminal 2 - Frontend
make run-frontend
```

### Option 4: Manual Setup

1. **Start PostgreSQL**
   ```bash
   make dev-db
   ```

2. **Configure Backend**
   ```bash
   # Copy example env file
   cp backend/.env.example backend/.env

   # Edit if needed (defaults should work)
   # vim backend/.env
   ```

3. **Run Database Migrations**
   ```bash
   make migrate-up DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"
   ```

4. **Start Backend** (in one terminal)
   ```bash
   cd backend
   go run ./cmd/api
   ```
   Backend will be available at: http://localhost:8080

5. **Start Frontend** (in another terminal)
   ```bash
   cd frontend
   npm run dev
   # or with bun:
   # bun run dev
   ```
   Frontend will be available at: http://localhost:3000

## Configuration

### Backend Environment Variables

The backend uses environment variables defined in `backend/.env`:

```bash
DATABASE_URL=postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable
PORT=8080
LOCATION_LAT=32.8893              # Torrey Pines Gliderport
LOCATION_LON=-117.2519
LOCATION_NAME=Torrey Pines Gliderport
TIMEZONE=America/Los_Angeles
FETCH_INTERVAL=15m
CACHE_TTL=10m
```

### Frontend Environment Variables

The frontend uses `frontend/.env.local`:

```bash
NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1
```

## Database Management

```bash
# Start PostgreSQL
make dev-db

# Stop PostgreSQL
make dev-db-down

# Run migrations up
make migrate-up DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"

# Run migrations down
make migrate-down DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"

# Create a new migration
make migrate-create name=add_new_table
```

## Using Bun Instead of npm

If you prefer Bun for faster package installation and execution:

```bash
cd frontend

# Install dependencies
bun install

# Run dev server
bun run dev

# Run build
bun run build
```

## Switching Between Local and Container Development

### To Local Development:
```bash
# Stop all containers
make dev-down

# Start only PostgreSQL
make dev-db

# Run apps locally (separate terminals)
make run-backend
make run-frontend
```

### Back to Full Container Development:
```bash
# Stop local PostgreSQL
make dev-db-down

# Start all services in containers
make dev
```

## Troubleshooting

### Backend won't connect to PostgreSQL
- Ensure PostgreSQL is running: `podman ps` or `docker ps`
- Check connection string in `backend/.env`
- Verify PostgreSQL is healthy: `podman logs paragliding-postgres`

### Frontend can't reach backend
- Ensure backend is running on port 8080
- Check `NEXT_PUBLIC_API_URL` in `frontend/.env.local`
- Verify backend health: `curl http://localhost:8080/api/v1/health`

### Port already in use
- Backend (8080): Change `PORT` in `backend/.env`
- Frontend (3000): Next.js will prompt for alternative port automatically
- PostgreSQL (5432): Change port mapping in `docker-compose.dev.yml`

## Hot Reload & Live Development

- **Frontend**: Next.js automatically hot-reloads on file changes
- **Backend**: For auto-reload, install Air:
  ```bash
  go install github.com/air-verse/air@latest
  cd backend
  air
  ```
  Air config is already set up in `backend/.air.toml`

## Running Tests

```bash
# Backend tests
make test-backend

# Frontend tests
make test-frontend
```

## API Endpoints

Once running, you can access:

- Frontend: http://localhost:3000
- Backend API: http://localhost:8080/api/v1
- Health Check: http://localhost:8080/api/v1/health
- Current Weather: http://localhost:8080/api/v1/weather/current
- Forecast: http://localhost:8080/api/v1/weather/forecast