# Gravl Backend

Backend service for the Gravl exercise and fitness tracking platform.

## Overview

The Gravl backend is a Node.js/Express application that provides:
- REST API for exercise data management
- User authentication and authorization
- Integration with frontend via HTTP
- Health check endpoint for deployment monitoring

---

## Local Development

### Prerequisites

- Node.js 18+
- npm or yarn
- Docker & Docker Compose (for local container development)

### Installation

```bash
cd backend
npm install
```

### Running Locally

**Development mode (with hot reload):**
```bash
npm run dev
```

The server starts on `http://localhost:3001`

**Production mode:**
```bash
npm run build
npm start
```

### Environment Variables

Create a `.env` file in the backend directory:

```bash
NODE_ENV=development
PORT=3001
DATABASE_URL=postgresql://user:password@localhost:5432/gravl
```

See `.env.example` (if available) for all supported variables.

---

## API Endpoints

### Health Check (Monitoring & Deployment)

```
GET /api/health
```

Used by deployment scripts to verify the backend is running and responsive.

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2026-03-03T18:21:00Z"
}
```

**Status Codes:**
- `200 OK` — Backend is healthy
- `500 Internal Server Error` — Backend has errors (check logs)

### Other Endpoints

(Document your API endpoints here; placeholder for now)

---

## Testing

```bash
npm test              # Run all tests
npm run test:watch   # Run tests in watch mode
```

---

## Docker

### Building the Image

```bash
docker build -t gravl-backend:latest .
```

### Running in Container

```bash
docker run -p 3001:3001 \
  -e NODE_ENV=production \
  -e DATABASE_URL=postgresql://... \
  gravl-backend:latest
```

### With Docker Compose

See the root `docker-compose.yml` for multi-container setup.

---

## Deployment

### Automated Deployment

The backend is deployed using scripts in the root `scripts/` directory:

- **`scripts/deploy.sh`** — Pulls latest code, builds fresh Docker image, starts container with health checks
- **`scripts/build-check.sh`** — Verifies deployed container matches local git HEAD

### How to Deploy

```bash
cd /workspace/gravl
scripts/deploy.sh
```

### Checking Deployment Status

```bash
cd /workspace/gravl
scripts/build-check.sh
```

For complete deployment documentation, see: **[`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md)**

That guide includes:
- Prerequisites and setup
- How to run deploy.sh
- How to check build status
- Troubleshooting (health check failures, stale containers, etc.)
- Recovery procedures (rollbacks, cleanup)

### Health Check Configuration

The backend exposes a health check endpoint at `GET /api/health`. The deployment script (`scripts/deploy.sh`) waits up to 60 seconds for this endpoint to return HTTP 200.

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

**Deployment timeout:** 60 seconds (12 retries × 5 seconds)
- If this endpoint takes >5 seconds to respond, deployment will timeout
- Ensure health check is lightweight (no expensive DB queries)

---

## Project Structure

```
backend/
├── src/
│   ├── index.js           # Server entry point
│   ├── routes/            # API endpoints
│   ├── controllers/       # Business logic
│   ├── models/            # Data models (if using ORM)
│   └── middleware/        # Express middleware
├── test/                  # Test files
├── Dockerfile             # Container image definition
├── package.json           # Dependencies
└── README.md             # This file
```

---

## Logs

### Local Development
```bash
npm run dev  # Logs to stdout
```

### Docker Container
```bash
docker logs gravl-backend       # Current logs
docker logs -f gravl-backend    # Follow logs in real-time
docker logs --tail 50 gravl-backend  # Last 50 lines
```

### In Deployment
All deploy activity is logged to `logs/deploy.log` at the root:
```bash
tail logs/deploy.log
```

---

## Troubleshooting

### Health Check Endpoint Not Responding

**Symptom:** Deployment fails with "Health check failed after 60s"

**Causes & Fixes:**
1. **Port 3001 is already in use**
   ```bash
   lsof -i :3001
   # Kill the conflicting process or use a different port
   ```

2. **Backend code has a syntax error**
   ```bash
   npm run dev  # Look for error messages
   ```

3. **Health check endpoint is not implemented**
   - Ensure `app.get('/api/health', ...)` is in src/index.js

4. **Database connection is failing**
   - Backend might be stuck trying to connect to DB
   - Check `DATABASE_URL` in `.env`
   - Ensure database is running

See **[`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md#troubleshooting)** for more deployment troubleshooting.

---

## Contributing

See the root project README or CONTRIBUTING.md for guidelines on:
- Code style ([CODING-CONVENTIONS.md](../docs/CODING-CONVENTIONS.md))
- Testing requirements
- Pull request process

---

## License

[Specify your license here]

---

*Last updated: 2026-03-03*