veza/veza-backend-api/docs/DEVELOPMENT_SETUP_GUIDE.md

# Veza Backend API - Development Setup Guide

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Quick Start](#quick-start)
4. [Manual Setup](#manual-setup)
5. [Docker Setup](#docker-setup)
6. [Project Structure](#project-structure)
7. [Configuration](#configuration)
8. [Database Setup](#database-setup)
9. [Running the Application](#running-the-application)
10. [Development Workflow](#development-workflow)
11. [Testing](#testing)
12. [Debugging](#debugging)
13. [Development Tools](#development-tools)
14. [Troubleshooting](#troubleshooting)

## Overview

This guide will help you set up a local development environment for the Veza Backend API. The API is built with Go 1.23+ using the Gin web framework, PostgreSQL for data storage, and Redis for caching.

## Prerequisites

### Required Software

#### Go

**Version:** Go 1.23 or higher

**Installation:**

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# Fedora/RHEL
sudo dnf install golang

# macOS
brew install go

# Windows
# Download from https://golang.org/dl/
# Or use Chocolatey: choco install golang
```

**Verify Installation:**

```bash
go version
# Should output: go version go1.23.x ...
```

#### PostgreSQL

**Version:** PostgreSQL 12 or higher (15+ recommended)

**Installation:**

```bash
# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Fedora/RHEL
sudo dnf install postgresql postgresql-server

# macOS
brew install postgresql@15
brew services start postgresql@15

# Windows
# Download from https://www.postgresql.org/download/windows/
```

**Verify Installation:**

```bash
psql --version
# Should output: psql (PostgreSQL) 15.x ...
```

#### Redis (Optional but Recommended)

**Version:** Redis 6 or higher

**Installation:**

```bash
# Ubuntu/Debian
sudo apt install redis-server

# Fedora/RHEL
sudo dnf install redis

# macOS
brew install redis
brew services start redis

# Windows
# Download from https://github.com/microsoftarchive/redis/releases
```

**Verify Installation:**

```bash
redis-cli ping
# Should output: PONG
```

### Optional Software

#### Docker and Docker Compose

For containerized development:

```bash
# Ubuntu/Debian
sudo apt install docker.io docker-compose

# Fedora/RHEL
sudo dnf install docker docker-compose

# macOS
brew install docker docker-compose

# Windows
# Download Docker Desktop from https://www.docker.com/products/docker-desktop
```

#### Air (Hot Reload)

For automatic code reloading during development:

```bash
go install github.com/cosmtrek/air@latest
```

#### golang-migrate

For database migrations:

```bash
# Install migrate tool
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
```

#### Make

For running common tasks:

```bash
# Ubuntu/Debian
sudo apt install build-essential

# Fedora/RHEL
sudo dnf install make

# macOS (usually pre-installed)
# Windows: Use Chocolatey or install from http://gnuwin32.sourceforge.net/packages/make.htm
```

## Quick Start

### Automated Setup Script

The fastest way to get started:

```bash
# Navigate to backend API directory
cd veza-backend-api

# Run setup script
chmod +x scripts/setup-dev.sh
./scripts/setup-dev.sh
```

This script will:
- Check for required software (Go, PostgreSQL, Redis)
- Create `.env` file from template
- Create database if it doesn't exist
- Install Go dependencies
- Build the application

### Docker Quick Start

If you prefer Docker:

```bash
# From project root
docker-compose up -d

# Check logs
docker-compose logs -f backend-api
```

## Manual Setup

### 1. Clone Repository

```bash
git clone <repository-url>
cd veza/veza-backend-api
```

### 2. Install Dependencies

```bash
# Download Go modules
go mod download

# Tidy dependencies
go mod tidy
```

### 3. Create Environment File

```bash
# Copy example environment file
cp .env.example .env

# Or create manually
cat > .env << EOF
# Database
DATABASE_URL=postgres://veza:password@localhost:5432/veza_dev?sslmode=disable

# Security
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
JWT_EXPIRY=24h

# Application
APP_ENV=development
API_PORT=8080
LOG_LEVEL=DEBUG
LOG_FORMAT=text

# Redis (Optional)
REDIS_URL=redis://localhost:6379

# Services
CHAT_SERVER_URL=http://localhost:8081
STREAM_SERVER_URL=http://localhost:8082
EOF
```

### 4. Setup Database

```bash
# Create PostgreSQL user and database
sudo -u postgres psql << EOF
CREATE USER veza WITH PASSWORD 'password';
CREATE DATABASE veza_dev OWNER veza;
GRANT ALL PRIVILEGES ON DATABASE veza_dev TO veza;
\q
EOF

# Or using createdb (if user exists)
createdb -U veza veza_dev
```

### 5. Run Migrations

```bash
# Using migrate tool
migrate -path ./migrations -database "$DATABASE_URL" up

# Or using Make
make migrate-up
```

### 6. Build Application

```bash
# Build binary
make build

# Or manually
go build -o bin/veza-backend-api ./cmd/api/main.go
```

### 7. Run Application

```bash
# Run directly
./bin/veza-backend-api

# Or using Make
make run

# Or with hot reload (if Air is installed)
air
```

## Docker Setup

### Using Docker Compose

The project includes a `docker-compose.yml` for local development:

```bash
# Start all services (PostgreSQL, Redis, Backend API)
docker-compose up -d

# View logs
docker-compose logs -f backend-api

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up -d --build
```

### Docker Compose Services

- **postgres**: PostgreSQL database on port 5432
- **redis**: Redis cache on port 6379
- **backend-api**: Go API on port 8080

### Environment Variables for Docker

Create `.env` file in project root:

```bash
POSTGRES_DB=veza_dev
POSTGRES_USER=veza
POSTGRES_PASSWORD=password
REDIS_PASSWORD=
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
```

## Project Structure

```
veza-backend-api/
├── cmd/
│   └── api/
│       └── main.go              # Application entry point
├── internal/
│   ├── api/                     # HTTP routes and router configuration
│   ├── core/                     # Business logic (auth, track, marketplace)
│   │   ├── auth/                # Authentication core
│   │   ├── track/                # Track management core
│   │   ├── marketplace/          # Marketplace core
│   │   └── social/               # Social features core
│   ├── config/                   # Configuration management
│   ├── database/                 # Database connection and migrations
│   ├── handlers/                 # HTTP request handlers
│   ├── middleware/               # HTTP middleware (auth, CORS, rate limiting)
│   ├── models/                   # GORM data models
│   ├── repositories/             # Data access layer
│   ├── services/                 # Business services
│   ├── workers/                  # Background job workers
│   ├── validators/               # Input validation
│   └── utils/                    # Utility functions
├── migrations/                   # SQL migration files
├── tests/                        # Integration tests
├── docs/                         # Documentation
├── scripts/                      # Utility scripts
├── Makefile                      # Common tasks
├── go.mod                        # Go module definition
├── go.sum                        # Go module checksums
└── .env                          # Environment variables (not in git)
```

## Configuration

### Environment Variables

#### Required Variables

```bash
# Database connection
DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=disable

# JWT secret (minimum 32 characters)
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long

# Application environment
APP_ENV=development  # development|staging|production
```

#### Development Variables

```bash
# Logging
LOG_LEVEL=DEBUG  # DEBUG|INFO|WARN|ERROR
LOG_FORMAT=text  # text|json

# Server
API_PORT=8080
HANDLER_TIMEOUT=30s

# Redis (optional)
REDIS_URL=redis://localhost:6379

# Services
CHAT_SERVER_URL=http://localhost:8081
STREAM_SERVER_URL=http://localhost:8082

# Uploads
UPLOAD_DIR=./uploads
MAX_CONCURRENT_UPLOADS=10

# ClamAV (optional)
ENABLE_CLAMAV=false  # Set to false for local development
CLAMAV_REQUIRED=false
```

### Configuration Files

- `.env`: Local environment variables (not committed to git)
- `.env.example`: Example environment file (committed to git)
- `config/`: Configuration files for different environments

## Database Setup

### Create Database

```bash
# Using psql
sudo -u postgres psql
CREATE DATABASE veza_dev;
CREATE USER veza WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE veza_dev TO veza;
\q

# Or using createdb
createdb -U veza veza_dev
```

### Run Migrations

```bash
# Using migrate tool
migrate -path ./migrations -database "$DATABASE_URL" up

# Check migration status
migrate -path ./migrations -database "$DATABASE_URL" version

# Rollback last migration
migrate -path ./migrations -database "$DATABASE_URL" down 1
```

### Seed Database (Optional)

```bash
# If seed scripts exist
go run scripts/seed.go
```

## Running the Application

### Development Mode

#### With Hot Reload (Air)

```bash
# Install Air if not already installed
go install github.com/cosmtrek/air@latest

# Run with hot reload
air

# Or create .air.toml config file
air init
air
```

#### Without Hot Reload

```bash
# Build and run
make run

# Or manually
go run ./cmd/api/main.go

# Or run binary
./bin/veza-backend-api
```

### Verify Application

```bash
# Health check
curl http://localhost:8080/healthz

# API endpoint
curl http://localhost:8080/api/v1/tracks
```

### Common Make Commands

```bash
# Build application
make build

# Run application
make run

# Run tests
make test

# Run tests with coverage
make test-coverage

# Run linter
make lint

# Format code
make fmt

# Run migrations
make migrate-up
make migrate-down

# Clean build artifacts
make clean
```

## Development Workflow

### 1. Create Feature Branch

```bash
git checkout -b feature/my-feature
```

### 2. Make Changes

- Write code following Go best practices
- Follow project structure conventions
- Add tests for new functionality

### 3. Run Tests

```bash
# Run all tests
make test

# Run specific test
go test ./internal/services/... -v

# Run with coverage
make test-coverage
```

### 4. Check Code Quality

```bash
# Format code
make fmt

# Run linter
make lint

# Check for security issues
go vet ./...
```

### 5. Commit Changes

```bash
git add .
git commit -m "feat: add new feature"
```

### 6. Push and Create PR

```bash
git push origin feature/my-feature
# Create pull request on GitHub/GitLab
```

## Testing

### Unit Tests

```bash
# Run all unit tests
go test ./...

# Run tests in specific package
go test ./internal/services/...

# Run with verbose output
go test -v ./...

# Run specific test
go test -v ./internal/services -run TestUserService
```

### Integration Tests

```bash
# Run integration tests
go test ./tests/... -v

# Run with database
DATABASE_URL=postgres://... go test ./tests/integration/...
```

### Test Coverage

```bash
# Generate coverage report
go test -cover ./...

# Generate HTML coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
```

### Test Database

For integration tests, use a separate test database:

```bash
# Create test database
createdb -U veza veza_test

# Set test database URL
export DATABASE_URL=postgres://veza:password@localhost:5432/veza_test?sslmode=disable

# Run tests
go test ./tests/...
```

## Debugging

### Using Delve (Go Debugger)

```bash
# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug application
dlv debug ./cmd/api/main.go

# Or attach to running process
dlv attach <pid>
```

### VS Code Debugging

Create `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch API",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/cmd/api/main.go",
      "env": {
        "DATABASE_URL": "postgres://veza:password@localhost:5432/veza_dev?sslmode=disable",
        "JWT_SECRET": "your-secret-key",
        "APP_ENV": "development"
      }
    }
  ]
}
```

### Logging

Enable debug logging:

```bash
export LOG_LEVEL=DEBUG
export LOG_FORMAT=text
```

View logs:

```bash
# If running directly
./bin/veza-backend-api

# If using Docker
docker-compose logs -f backend-api

# If using systemd
journalctl -u veza-backend-api -f
```

### Common Debugging Tips

1. **Check database connection:**
   ```bash
   psql "$DATABASE_URL" -c "SELECT 1;"
   ```

2. **Check Redis connection:**
   ```bash
   redis-cli ping
   ```

3. **Verify environment variables:**
   ```bash
   env | grep -E 'DATABASE|JWT|APP_ENV'
   ```

4. **Check application health:**
   ```bash
   curl http://localhost:8080/healthz
   ```

## Development Tools

### Code Generation

#### Generate Swagger Documentation

```bash
# Install swag
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs
swag init -g cmd/api/main.go
```

#### Generate Mock Services

```bash
# Install mockgen
go install github.com/golang/mock/mockgen@latest

# Generate mocks
mockgen -source=internal/services/user_service.go -destination=internal/mocks/user_service_mock.go
```

### Database Tools

#### Database GUI Clients

- **pgAdmin**: https://www.pgadmin.org/
- **DBeaver**: https://dbeaver.io/
- **TablePlus**: https://tableplus.com/

#### CLI Tools

```bash
# PostgreSQL client
psql "$DATABASE_URL"

# Redis client
redis-cli

# Database migrations
migrate -path ./migrations -database "$DATABASE_URL" version
```

### API Testing

#### Using curl

```bash
# Health check
curl http://localhost:8080/healthz

# Get tracks
curl http://localhost:8080/api/v1/tracks

# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'
```

#### Using HTTPie

```bash
# Install HTTPie
pip install httpie

# Make requests
http GET http://localhost:8080/api/v1/tracks
http POST http://localhost:8080/api/v1/auth/login email=user@example.com password=password
```

#### Using Postman

Import the API collection from `docs/postman/veza-api.json` (if available).

### Performance Profiling

```bash
# Enable pprof
export ENABLE_PPROF=true

# Access profiler
go tool pprof http://localhost:8080/debug/pprof/profile
go tool pprof http://localhost:8080/debug/pprof/heap
```

## Troubleshooting

### Common Issues

#### Database Connection Failed

```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Check connection
psql "$DATABASE_URL" -c "SELECT 1;"

# Verify DATABASE_URL format
echo $DATABASE_URL
```

#### Port Already in Use

```bash
# Find process using port 8080
lsof -i :8080
# or
netstat -tulpn | grep 8080

# Kill process
kill -9 <pid>

# Or change port in .env
API_PORT=8081
```

#### Go Module Issues

```bash
# Clean module cache
go clean -modcache

# Download dependencies
go mod download

# Tidy modules
go mod tidy
```

#### Migration Errors

```bash
# Check migration status
migrate -path ./migrations -database "$DATABASE_URL" version

# Force version (if needed)
migrate -path ./migrations -database "$DATABASE_URL" force <version>

# Rollback and retry
migrate -path ./migrations -database "$DATABASE_URL" down 1
migrate -path ./migrations -database "$DATABASE_URL" up
```

### Getting Help

- **Documentation**: See `docs/` directory
- **API Documentation**: http://localhost:8080/swagger/index.html
- **Issues**: Create an issue on GitHub
- **Team Chat**: Ask in team Slack/Discord

## Next Steps

After setting up your development environment:

1. **Read the API Documentation**: See `docs/API_DOCUMENTATION.md`
2. **Explore the Codebase**: Start with `cmd/api/main.go`
3. **Run the Test Suite**: `make test`
4. **Check out Example Code**: Look at existing handlers and services
5. **Join the Team**: Get familiar with team workflows and conventions

## Additional Resources

- **Go Documentation**: https://golang.org/doc/
- **Gin Framework**: https://gin-gonic.com/docs/
- **GORM Documentation**: https://gorm.io/docs/
- **PostgreSQL Documentation**: https://www.postgresql.org/docs/
- **Redis Documentation**: https://redis.io/documentation