Quick Start

1. Install the CLI

go install github.com/BounkhongDev/bkgo/cmd/bkgo@latest

Make sure ~/go/bin is in your PATH:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Scaffold a new project

bkgo new myapp
# with a custom module path:
bkgo new myapp --module github.com/yourname/myapp

Generates a complete project skeleton:

myapp/
├── cmd/api/main.go       ← wired entry point (GORM + Redis + JWT)
├── internal/             ← your domain modules go here
├── migrations/           ← SQL migration files
├── .env.example          ← environment variable template
├── docker-compose.yml    ← optional local dev setup
├── Makefile
├── .gitignore
└── go.mod

3. Configure environment

cd myapp
cp .env.example .env
# Edit .env — set DB_HOST, DB_PASSWORD, JWT_SECRET, etc.

4. Connect your services

bkgo reads connection details from .env — it works with any PostgreSQL and Redis source. Use whatever fits your setup:

docker compose up -d

brew services start postgresql
brew services start redis

# point DB_HOST to your postgres service
# point REDIS_HOST to your redis service

# AWS RDS / Google Cloud SQL / Supabase
# ElastiCache / Upstash / Redis Cloud
# just set the env vars in .env

MinIO is only needed if you use bkgo/adapter/minio. Skip it if you don't need file storage.

5. Install dependencies

go mod tidy

6. Generate a module

bkgo g module user
bkgo g module product
bkgo g module order

Each module generates a full GORM-based domain slice:

internal/user/
├── domain.go         ← User struct (GORM tags) + UserRepository interface
├── usecase.go        ← business logic
├── handler.go        ← Fiber HTTP handler (i18n error responses)
├── repository.go     ← GORM implementation of UserRepository
└── usecase_test.go   ← unit tests with mock repository

7. Write your business logic

This is the only part you write manually. Everything else is generated or provided by bkgo:

// internal/user/domain.go — add your fields
type User struct {
    ID        string    `gorm:"primaryKey;type:uuid;default:gen_random_uuid()"`
    Name      string
    Email     string    `gorm:"uniqueIndex"`
    CreatedAt time.Time
}

// internal/user/usecase.go — write your rules
func (u *UserUsecase) Create(ctx context.Context, input CreateUserInput) (*User, error) {
    if err := validator.Validate(input); err != nil {
        return nil, errs.BadRequest(err)
    }
    return u.repo.Create(ctx, &User{Name: input.Name, Email: input.Email})
}

8. Wire routes in main.go

// cmd/api/main.go
userRepo    := user.NewUserRepository(db)
userUsecase := user.NewUserUsecase(userRepo)
userHandler := user.NewUserHandler(userUsecase)
userHandler.RegisterRoutes(api)

9. Run

go run ./cmd/api

Server starts on :8080. Verify with GET /health.

What bkgo handles vs what you write