go-rest-api-boilerplate: Instructions file for GitHub Copilot

GitHub Copilot Instructions for GRAB (Go REST API Boilerplate)

Version: v2.0.0
Last Updated: 2025-12-10
Purpose: Developer-focused guidelines for building APIs with GRAB

---

📋 What is GRAB?

GRAB (Go REST API Boilerplate) is a production-ready Go REST API starter with:

• Clean Architecture (Handler → Service → Repository)
• JWT Authentication with refresh token rotation
• Role-Based Access Control (RBAC)
• Database Migrations (golang-migrate)
• Docker-First Development
• 89.81% Test Coverage
• Comprehensive Documentation: https://vahiiiid.github.io/go-rest-api-docs/

---

🎯 Core Development Principles

1. Environment Detection - Don't Hardcode Versions

Instead of stating "Go 1.24" or "PostgreSQL 15", show how to check:

# Check Go version
go version

# Check Docker version
docker --version

# Check PostgreSQL version (inside container)
make exec-db
psql --version

2. Docker-First Development

• Developers run make commands on host
• Makefile automatically detects if Docker container is running
• Commands execute in container if available, host otherwise
• No need to manually enter container - the Makefile handles execution context

# Start containers first
make up

# Run tests (automatically in container if running)
make test

# Run linting (automatically in container if running)
make lint

# Apply lint fixes (automatically in container if running)
make lint-fix

# Generate Swagger docs (automatically in container if running)
make swag

3. Clean Architecture Pattern

Every domain follows this structure:

internal/
└── <domain>/
    ├── model.go       # Domain models (GORM)
    ├── dto.go         # Data Transfer Objects (API contracts)
    ├── repository.go  # Database access layer
    ├── service.go     # Business logic layer
    ├── handler.go     # HTTP handlers (Gin)
    └── *_test.go      # Tests for each layer