# Gravl Backend

Node.js / Express API server for the Gravl application.

## Development

### Prerequisites
- Node.js 18+
- PostgreSQL 14+ (or use Docker Compose)
- Docker & Docker Compose (for containerized development)

### Getting Started

```bash
# Install dependencies
npm install

# Create .env file (copy from .env.example)
cp .env.example .env

# Run database migrations
npm run migrate

# Start development server
npm run dev
```

The API will be available at `http://localhost:3001`.

### Health Check Endpoint

The API exposes a health check endpoint for deployment verification:

```bash
curl http://localhost:3001/api/health
```

Expected response:
```json
{
  "status": "ok",
  "timestamp": "2026-03-03T18:30:00Z"
}
```

This endpoint is used by the deployment scripts to verify the backend is healthy after deployment.

---

## Deployment

### Quick Start

See `/docs/DEPLOYMENT.md` for comprehensive deployment documentation.

```bash
# Deploy the application
scripts/deploy.sh

# Check deployment status
scripts/build-check.sh
```

### How It Works

1. **Automatic build:** `scripts/deploy.sh` builds fresh Docker images
2. **Zero downtime:** Old containers are replaced with `--force-recreate`
3. **Health verification:** API health endpoint is polled before deployment completes
4. **Rollback:** Use git to revert and redeploy if issues arise

### Prerequisites for Deployment

- Docker and Docker Compose installed
- Git remote configured and accessible
- Backend listening on port 3001
- Health endpoint (`/api/health`) responding with 200 OK

### Example Deployment Workflow

```bash
# 1. Make code changes and commit
git add . && git commit -m "feat: new API endpoint"

# 2. Deploy from project root
cd /workspace/gravl
scripts/deploy.sh

# 3. Verify deployment
scripts/build-check.sh

# 4. Check logs if needed
docker compose logs gravl-backend
```

### Container Labels

All deployed containers include build metadata labels for tracking:
- `org.opencontainers.image.revision` — Git commit SHA
- `org.opencontainers.image.created` — Build timestamp

These are used by `scripts/build-check.sh` to detect stale deployments.

---

## Testing

```bash
# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Run with coverage
npm run test:coverage
```

---

## Database

### Migrations

```bash
# Run pending migrations
npm run migrate

# Rollback last migration
npm run migrate:rollback

# Create new migration
npm run migrate:create -- my_migration_name
```

### Connection

Configure via `.env`:
```
DATABASE_URL=postgresql://user:password@localhost:5432/gravl
```

---

## Environment Variables

See `.env.example` for all available variables.

Key variables:
- `NODE_ENV` — Development/production mode
- `PORT` — Server port (default: 3001)
- `DATABASE_URL` — PostgreSQL connection string
- `JWT_SECRET` — Token signing secret

---

## Project Structure

```
backend/
├── src/
│   ├── api/          # Express route handlers
│   ├── middleware/   # Express middleware
│   ├── models/       # Database models
│   ├── services/     # Business logic
│   └── index.js      # App entry point
├── tests/            # Unit and integration tests
├── migrations/       # Database migrations
├── docker/           # Dockerfile
├── .env.example      # Environment template
└── README.md         # This file
```

---

## Troubleshooting

### API Won't Start

Check the logs:
```bash
docker compose logs gravl-backend
```

Common issues:
- Port 3001 already in use: Kill the process or change the port
- Database connection failed: Verify `.env` DATABASE_URL
- Node modules missing: Run `npm install`

### Health Check Fails

Ensure the `/api/health` endpoint is implemented:

```javascript
// backend/src/api/health.js
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});
```

### Database Issues

Check Docker container status:
```bash
docker compose ps
docker compose logs gravl-db
```

---

## Contributing

See `CODING-CONVENTIONS.md` in the project root for code style and standards.

---

**Last Updated:** 2026-03-03  
**Phase:** 07-03  
**Related:** `/docs/DEPLOYMENT.md`