🐘 Tusk - The Sharpest Go Backend Framework for APIs

Tusk is an opinionated, production-ready Go backend framework designed for building scalable, maintainable, and type-safe REST APIs. It enforces explicit dependency injection, clean layered architecture, code-first authorization (RBAC), and automatic OpenAPI 3.0 documentation generation.

---

📚 Documentation Index

Explore the full documentation guides in the docs/ directory:

• 🚀 Getting Started - Prerequisites, environment configuration, and running the server.
• 🏗️ Architecture & Design Philosophy - Layered architecture, dependency injection, and coding guidelines.
• ⚡ Routing & OpenAPI (Huma v2) - Strongly-typed DTOs, route definition, and auto-generated API docs.
• 🔐 Code-First RBAC Authorization - Code permissions, database sync CLI (tusk auth sync), and route guards.
• 🗄️ Database & Migrations - GORM connectivity, seeder tools, and schema migration CLI (cmd/migrate).
• 🔍 Querying, Filtering & Pagination - Dynamic searching, sorting, field filtering, and metadata envelopes (pkg/query).
• 📬 Standardized Responses & Error Handling - Uniform JSON response structure (pkg/response) and status code conventions.

---

✨ Features

• Huma v2 + Chi Router: Strongly-typed HTTP handlers with automatic OpenAPI 3.0 spec generation (/openapi.json) and interactive documentation UI (/docs).
• Clean Layered Architecture: Strict separation of concerns (Handlers -> Services -> Repositories -> Models/DTOs).
• Code-First RBAC Authorization (pkg/authz): Declare permissions in code, synchronize them to runtime database tables via tusk auth sync, and enforce permissions with route guards.
• Authentication & Identity: Complete authentication suite (Registration, Login, Refresh Tokens, Profile Management, Account Lockout after failed attempts) with bcrypt password hashing and JWT sessions.
• GORM ORM & Database Migration CLI (cmd/migrate): Type-safe database operations with migration tools (up, down, fresh, seed).
• Unified Querying & Pagination Engine (pkg/query): Standardized searching, sorting, and pagination metadata envelopes (query.Meta).
• Standardized API Response Envelopes (pkg/response): Consistent JSON responses across all endpoints.
• Structured Logging (pkg/logger): Console and production logger setup.
• Transactional Seeding & Mailer Integration (pkg/mailer): Email sending helper utilities and database seeder support.

---

🚀 Quick Start

1. Prerequisites

• Go: 1.20 or newer
• Database: PostgreSQL or MySQL

2. Setup & Configuration

# Clone the repository
git clone https://github.com/codetheuri/Tusk.git
cd Tusk
# Copy environment configuration
cp .env.example .env
# Run database migrations
make migrate-up
# Sync code authorization permissions to database
make auth-sync
# Start hot-reload server (with Air)
make dev

The server will start at http://localhost:8080.

• Interactive API Documentation UI: http://localhost:8080/docs
• OpenAPI 3.0 JSON Spec: http://localhost:8080/openapi.json

---

🛠️ CLI Commands & Makefile Utilities

Tusk includes a complete Makefile for common tasks:

Command	Description
make dev	Start development server with hot-reloading (via Air)
make run	Run application without hot-reloading (cmd/api/main.go)
make build	Compile optimized production binary to ./bin/api
make test	Run unit tests across all packages
make coverage	Generate HTML test coverage report (coverage.html)
make vet	Run Go static code analysis
make migrate-up	Apply pending database schema migrations
make migrate-down	Roll back the last database migration
make auth-sync	Synchronize code-declared permissions into the database
make auth-sync-prune	Synchronize code permissions and prune obsolete database records
make clean	Clean build artifacts and temporary log files

---

🏛️ Project Directory Structure

Tusk/
├── cmd/
│ ├── api/ # HTTP API entrypoint (main.go)
│ ├── migrate/ # Database migration & seeder CLI
│ └── tusk/ # Framework CLI tool (permission sync)
├── config/ # Configuration loader (.env parsing)
├── database/ # Schema migrations and database seeders
├── docs/ # Comprehensive technical documentation
├── internal/
│ ├── app/ # Application lifecycle, routing, and container wiring
│ ├── auth/ # Authentication & RBAC identity domain module
│ ├── middleware/ # Global HTTP middleware (CORS, JWT authentication)
│ └── platform/ # Infrastructure setup (GORM DB connection)
└── pkg/
├── authz/ # Code-first authorization & RBAC engine
├── logger/ # Structured logging package
├── mailer/ # Email transmission utility package
├── query/ # Pagination, filtering, & sorting query engine
├── response/ # Standardized API response builder
└── validate/ # Input validation utilities

---

📖 Learn More

Read the full documentation guides in the docs/ directory to master building applications with Tusk.