gin-app 🚀

A production-ready Gin + Fx based project template for rapidly building scalable, modular, RESTful web services in Go.

This template is designed with:

• 🧱 Modular architecture (Fx DI)
• 🧠 Clean architecture layering
• 🔐 JWT authentication
• 📦 Ent ORM
• 🐳 Docker & Docker Compose
• 📑 Swagger API docs
• 🧪 Testing & mocking
• 🔁 Database migration

---

✨ Features

• Gin HTTP framework
• Uber Fx dependency injection
• PostgreSQL (Ent ORM)
• Redis
• JWT authentication
• Modular domain structure
• Swagger documentation
• Integration testing stack
• Database migration
• Linting & formatting
• Mock generation
• Dependency vulnerability scanning

---

📁 Project Structure

cmd/
  app/                 # Application entrypoint
internal/
  config/              # Configuration
  modules/             # Business modules (user, post, auth, ...)
  router/              # Router layer
  middleware/          # HTTP middlewares (auth, logging, cors, ...)
  dto/                 # Data Transfer Objects (request/response models)
pkg/
  logger/              # Logger
  postgres/            # PostgreSQL client
  redis/               # Redis client
  jwt/                 # JWT utilities
  oauth2/              # OAuth2 (Github & Google)
ent/
  schema/              # Ent schemas
  migrate/             # Migration files

---

🧩 Architecture Design

• Module-based architecture (inspired by NestJS)
• Fx global container with interface-based exports
• Strong decoupling via interfaces
• Dependency inversion principle (DIP)
• Clean boundaries between modules

Controller -> Service -> Domain Interface -> Infrastructure

---

🛠 Prerequisites

Docker

brew install docker

Go

go version >= 1.22

---

🐘 PostgreSQL (Docker)

docker run -d --name pg-server \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=db_name \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql \
  postgres

---

🧠 Redis (Docker)

docker run -d --name redis \
  -p 6379:6379 \
  -v redis-data:/data \
  redis redis-server --requirepass yourpassword --appendonly yes

---

⚙️ Environment Setup

cp .env.example .env

---

🚀 Quick Start

make run

---

🐳 Docker Compose

Start base services

make compose-up

Start all services

make compose-up-all

Integration test stack

make compose-up-integration-test

Stop services

make compose-down

---

📑 Swagger

make swag-v1

Access:

http://localhost:8080/swagger/index.html

---

🧪 Testing

make test

---

🧬 Database

Create schema

make schema-create User

Generate ent code

make ent-gen

Create migration

make migrate-create add_user_table

Run migration

make migrate-up

Rollback migration

make migrate-down

---

🧰 Development Tools

Format code

make format

Lint

make linter-golangci

Dependency audit

make deps-audit

Generate mocks

make mock

---

📦 Dependency Management

make deps
make upgrade-deps
make ls-deps

---

🔁 Pre-commit Hook

make pre-commit

---

🧠 Module Design Pattern

Each module follows:

module/
  module.go     # fx.Module definition
  service.go    # internal implementation
  repo.go       # repository
  controller.go # HTTP layer

External modules only depend on interfaces.

---

🔐 Security

• JWT authentication
• Middleware-based authorization
• Environment-based secrets
• Isolated service layers

---

🧱 Recommended Extensions

• OpenTelemetry tracing
• Prometheus metrics
• gRPC gateway
• CQRS pattern
• Event-driven architecture
• Message queue integration

---

📜 License

MIT License

---

🤝 Contributing

PRs are welcome. Please follow:

• Go formatting standards
• Modular structure
• Interface-first design
• Clean commit history

---

🧭 Philosophy

Simple by default, scalable by design.

Architecture should enable growth, not block it.

---

⭐ Why gin-app

• Enterprise-ready
• Clean architecture
• Strong boundaries
• Modular design
• High scalability
• Production-grade tooling

---

Happy coding! 🚀