Golang Project Template

A production-ready Go project template with multiple application entry points (HTTP, gRPC, Worker, Cron, CLI), clean architecture, and common infrastructure packages built-in.

By default the HTTP service runs on port 8080.

Quick Start

1. Configure your environment in config/local.yaml (database credentials, ports, etc.).

2. Install dependencies and generate DI:

   make mod
   make wire
   

3. Run the desired application:

   make http     # HTTP server
   make grpc     # gRPC server
   make worker   # Message queue worker
   make cron     # Cron job scheduler
   make cli      # CLI commands
   

Environment Configuration

The app reads APP_ENV to determine which config file to load from config/. It defaults to local (i.e., config/local.yaml).

To use a different environment, create a config file (e.g., config/dev.yaml) and set:

APP_ENV=dev make http

You can also pass a config path directly via the -config flag:

go run ./cmd/http/ -config /path/to/config.yaml

Project Structure

Based on Golang Standard Project Layout with modifications.

├── api/
│   └── grpc/                    # Protobuf definitions and generated code
├── cmd/
│   ├── http/                    # HTTP server entry point (Fiber)
│   ├── grpc/                    # gRPC server entry point
│   ├── worker/                  # Message queue consumer entry point
│   ├── cron/                    # Cron job scheduler entry point
│   └── cli/                     # CLI commands entry point
├── config/
│   └── local.yaml               # Application configuration
├── internal/
│   ├── constant/                # Application-wide constants
│   ├── entity/                  # Domain entities and response models
│   ├── handler/                 # Request handlers per transport
│   │   ├── http/
│   │   ├── grpc/
│   │   ├── worker/
│   │   ├── cron/
│   │   └── cli/
│   ├── middleware/               # Middleware per transport
│   │   ├── http/
│   │   ├── grpc/
│   │   └── cron/
│   ├── repository/              # Data access layer (interface + implementation)
│   ├── usecase/                 # Business logic layer (interface + implementation)
│   └── pkg/                     # Internal shared packages
│       ├── cache/               # Redis cache (go-redis/v9)
│       ├── config/              # Configuration loader (Viper)
│       ├── encryption/          # AES encryption
│       ├── errors/              # Custom error types
│       ├── featureflag/         # Feature flag support
│       ├── graceful/            # Graceful shutdown
│       ├── jwt/                 # JWT authentication
│       ├── log/                 # Structured logging (Logrus)
│       ├── provider/            # Infrastructure providers (DB, logger, pubsub)
│       ├── pubsub/              # Message queue abstraction
│       │   ├── nsq/             # NSQ implementation
│       │   ├── nats_jetstream/  # NATS JetStream implementation
│       │   └── redis/           # Redis Pub/Sub implementation
│       ├── repository/          # Base repository utilities
│       ├── response/            # HTTP & gRPC response helpers
│       ├── storage/             # Object storage (MinIO/S3)
│       ├── str/                 # String utilities
│       └── validator/           # Request validation
└── tools/
    └── migrations/              # Database migration files

Configuration

All configuration is managed via config/local.yaml. Key sections:

Section	Description
app	Application name
database	Database driver (sqlite/postgres) and DSN
http_app	HTTP server host and port
grpc_app	gRPC server host and port
cron_app	Cron server host and port
worker_app	Worker provider (nsq, nats, redis) and config
log	Logging configuration
storage	Object storage (S3/MinIO) credentials
jwt	JWT secret keys and expiration
encryption	Database encryption keys

Commands

make http             # Run HTTP server
make grpc             # Run gRPC server
make worker           # Run message queue worker
make cron             # Run cron scheduler
make cli              # Run CLI commands

make build-http       # Build HTTP binary
make build-cli        # Build CLI binary
make build-cron       # Build cron binary

make wire             # Generate dependency injection (Wire)
make proto-gen        # Generate protobuf code
make lint             # Run linter (golangci-lint)
make cover            # Run tests with coverage report
make mod              # Download Go module dependencies

Architecture

The project follows Clean Architecture with three main layers:

• Handler — Transport layer (HTTP, gRPC, worker, cron, CLI). Handles request parsing and response formatting.
• Usecase — Business logic layer. Contains application rules independent of transport.
• Repository — Data access layer. Abstracts database operations behind interfaces.

Each layer communicates through interfaces, and dependencies are injected via Google Wire.

Key Dependencies

Package	Purpose
Fiber v3	HTTP framework
gRPC	RPC framework
GORM	ORM (Postgres, SQLite)
Viper	Configuration
Wire	Dependency injection
Logrus	Structured logging
go-redis/v9	Redis client and cache
go-nsq	NSQ message queue
NATS JetStream	NATS message queue
cronx	Cron scheduler
golang-migrate	Database migrations
golangci-lint	Linter