vahiiiid/go-rest-api-boilerplate

This system is a Go-based REST API boilerplate that provides a foundational framework for building secure, production-ready web services. It implements core infrastructure features including centralized configuration, structured error handling, rate limiting, and role-based access control (RBAC) for user management. The application supports secure authentication via JWT with refresh token rotation, manages database schema migrations independently, and exposes health check endpoints for orchestration.

A new rule file (.cursor/rules/grab.mdc) has been added to provide AI-friendly development guidelines specifically for the Cursor IDE. This file consolidates core principles for the GRAB (Go REST API Boilerplate) project, including Clean Architecture patterns (Handler → Service → Repository), Docker-first development workflows via Makefile commands, migration naming conventions, and standard practices for authentication, error handling, testing, and Swagger documentation. It serves as a localized source of truth for Cursor to assist developers in adhering to project standards.

.cursor · high confidence

The new quick-start script (scripts/quick-start.sh) automates the initial setup by validating Docker dependencies, generating a secure JWT\_SECRET if missing, and starting the application with a retry mechanism for database migrations to handle startup timing issues. This complements the new entrypoint script (scripts/app\_entrypoint.sh), which configures Git safety for Go builds and initializes Swagger documentation before launching the hot-reload server.

scripts · high confidence

The database schema now includes a users table with soft-delete support, a refresh\_tokens table to enable secure JWT token rotation and reuse detection, and a role-based access control (RBAC) structure consisting of roles and user\_roles tables with default admin and user roles seeded.

migrations · high confidence

The server now starts with a centralized configuration loading process, validates settings, and connects to a PostgreSQL database. It exposes health check endpoints at /health, /health/live, and /health/ready, and implements graceful shutdown handling for SIGINT/SIGTERM signals with configurable timeouts. The server also includes a migration status check that verifies the database schema version and dirty state before starting, and logs Swagger UI availability.

cmd/server · high confidence

The server now exposes a structured HTTP router that configures middleware for logging, error handling, recovery, and CORS, along with configurable rate limiting based on environment settings. It provides standard health check endpoints (/health, /health/live, /health/ready) including database connectivity checks, and defines the initial API v1 routes for authentication (register, login, refresh, logout, me) and user management (CRUD operations), with admin-specific endpoints protected by role-based access controls. Swagger documentation is also served at /swagger.

internal/server · high confidence

The application now includes a dedicated command-line utility for managing database schema changes, separating migration execution from the main application startup. This change introduces a new \cmd/migrate\ binary and an \internal/migrate\ package that wraps the \golang-migrate/v4\ library to handle PostgreSQL migrations. Users can now run commands such as \up\, \down\, \goto\, \version\, \force\, and \drop\ to manage schema versions, with support for configurable timeouts and lock acquisition. The implementation includes comprehensive unit tests for the migration logic.

cmd/migrate, internal/migrate · high confidence

The internal/user module now provides a complete user lifecycle implementation including registration, login, profile updates, and deletion, backed by a new Role-Based Access Control (RBAC) system with admin and user roles. Authentication responses have been standardized to return both access and refresh tokens (AuthResponse) instead of a single legacy token, supporting token rotation and reuse detection. User listing endpoints now support filtering by role, search queries, and sorting, with input sanitization to prevent DoS. Additionally, a new contextutil package offers safe helpers to retrieve authenticated user claims, IDs, and roles from the request context, ensuring consistent authorization checks across handlers.

internal/user · high confidence

A new command-line utility at cmd/createadmin allows administrators to initialize the system by either registering a new admin user or promoting an existing user to admin. The tool provides interactive prompts for email, name, and password input, including secure terminal-based password reading and validation for strong password requirements (length, character types). It connects directly to the PostgreSQL database via GORM to perform user registration and role promotion.

cmd/createadmin · high confidence

The application now exposes three new HTTP endpoints for monitoring: /health (basic status), /health/live (liveness probe), and /health/ready (readiness probe). The readiness endpoint specifically checks dependencies like the database, returning a 503 Service Unavailable status if checks fail or a degraded status if response times are slow, enabling orchestrators to manage traffic routing effectively.

internal/health · high confidence

This update introduces a comprehensive set of middleware components for the API. It adds a structured error handling system that standardizes API responses with machine-readable error codes (e.g., NOT\_FOUND, VALIDATION\_ERROR) and includes a Gin middleware to convert internal errors into consistent JSON responses. A configurable rate-limiting middleware is added, using a token-bucket algorithm with an in-memory LRU cache to enforce request limits per key (e.g., IP or user ID) and return appropriate 429 responses with retry-after headers. Additionally, Role-Based Access Control (RBAC) middleware is provided to restrict endpoint access based on user roles, and a structured logging middleware is included to record request details with unique request IDs.

internal/middleware · high confidence

The application now uses a centralized configuration system (via Viper) that loads settings from YAML files and allows environment variables to override file values. This change introduces strict validation rules, including requiring a 32-character JWT secret and enforcing database SSL and password requirements in production. It also supports environment-specific config files (e.g., config.development.yaml) and resolves config paths relative to the executable for better portability.

internal/config · high confidence

The internal authentication module now enforces strict JWT validation via a new Gin middleware that extracts user claims and ID from the Authorization header. Authentication now utilizes a token pair system (access and refresh tokens) with BCP-compliant refresh token rotation: refresh tokens are hashed and stored in the database, and any reuse of a refresh token triggers immediate revocation of the entire token family to prevent replay attacks. The service validates that the JWT secret is present and at least 32 characters long, removing the previous hardcoded fallback secret.

internal/auth · high confidence

All API responses now use a consistent envelope format containing success status, data, error details, and metadata, replacing the previous direct object responses. Error responses include structured error codes and machine-readable details, improving consistency and debugging across all endpoints.

(repo-wide) · high confidence

Added new test files in the \tests\ directory to verify core application logic. \context\_test.go\ provides unit tests for the \contextutil\ package, ensuring that helper functions for retrieving user claims, IDs, and emails from the Gin context behave correctly when data is present, missing, or malformed. \handler\_test.go\ introduces integration tests for the user registration endpoint, validating successful sign-ups, duplicate email detection, invalid input handling, and missing field errors against a test router backed by an in-memory SQLite database.

tests · high confidence

The project introduces its first \go.mod\ and \go.sum\ files, establishing the dependency graph for a Go 1.24.0 application. This configuration pins the core framework to \gin-gonic/gin v1.11.0\ and includes essential libraries for production readiness: \gorm.io/gorm\ with PostgreSQL and SQLite drivers for database access, \golang-migrate/migrate\ for schema management, \spf13/viper\ for centralized configuration, \golang-jwt/jwt/v5\ for authentication, and \swaggo\ tools for API documentation. It also adds \testify\ for testing and \go-playground/validator\ for input validation.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 67 (+4.6)
• Rubric changed (rubric-2026.08.17 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 94 → 97 (+3.0)
• Architecture 100 → 92 (-8.1)
• Maturity 90 → 68 (-21.5)
• Readiness 41 → 56 (+15.0)
• Security 76 → 82 (+5.8)
• Domain Modelling 80 → 83 (+3.1)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — no supported dependency manifest was read
• Duplicated block (11 lines × 2) (cmd/migrate/main.go)
• Duplicated block (11 lines × 2) (cmd/migrate/main.go)
• Duplicated block (11 lines × 2) (internal/user/handler.go)
• Duplicated block (12 lines × 2) (internal/auth/service.go)
• Duplicated block (12 lines × 2) (internal/auth/service.go)
• Duplicated block (12 lines × 2) (internal/user/handler.go)
• Duplicated block (13 lines × 2) (cmd/migrate/main.go)
• Duplicated block (13 lines × 2) (internal/migrate/migrate.go)
• Duplicated block (16 lines × 2) (internal/auth/service.go)
• Duplicated block (6 lines × 2) (internal/db/db.go)
• Duplicated block (9–11 lines × 3) (internal/user/handler.go)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 6 more

• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Documentation: no contributor guidance (README.md)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (cmd/migrate/main.go)
• Duplicated block (10 lines × 2) (internal/auth/service.go)
• Duplicated block (10–11 lines × 3) (internal/user/handler.go)
• Duplicated block (11 lines × 2) (internal/user/handler.go)
• Duplicated block (12 lines × 2) (internal/auth/service.go)
• Duplicated block (20 lines × 2) (internal/user/handler.go)
• Duplicated block (23 lines × 2) (internal/auth/service.go)
• Duplicated block (5 lines × 2) (internal/db/db.go)
• High CVE: [GHSA redacted] (go.mod)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 34 more

• 1 commits — 1 feature/other, 0 fixes

• (root) — 1 commit

• change: chore: unify AI assistant guidelines around a single source of truth (#112)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

vahiiiid/go-rest-api-boilerplate was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.