Clean Architecture Backend - GO

Backend service written in Go following Clean Architecture principles, with support for:

• Native execution (local binary)
• Docker + Kubernetes (via Skaffold / Minikube)
• Event-driven architecture using NATS JetStream
• Elasticsearch for log indexing
• PostgreSQL with migrations and code generation (Jet)

---

Project Structure

.
CAB-GO
├─ adapters/
│  ├─ controllers/          # HTTP handlers (Gin)
│  ├─ presenter/            # DTOs / API models
│  ├─ broker/               # NATS JetStream consumers / publishers
│  └─ repository/
│     └─ persistence/
│        ├─ migrations/     # Database migrations (PostgreSQL)
│        └─ .gen/           # Generated code (Jet)
│
├─ api/
│  ├─ main/                  # Application entrypoint (HTTP server bootstrap)
│  └─ env/                   # Kubernetes manifests (deployments, services)
│
├─ business/
│  ├─ core/                # Domain models
│  └─ usecase/             # Application business logic
│
├─ docker-compose.yml      # Optional local infrastructure
├─ Makefile
├─ README.md               # You’re reading this file
└─ skaffold.yaml

---

What this project does

This is a backend application built with:

• Go
• Gin (HTTP layer)
• PostgreSQL (persistence)
• Jet (type-safe SQL code generation)
• migration workflow via migrate
• JWT authentication
• NATS JetStream for asynchronous event processing
• Elasticsearch for log indexing

It follows a Clean Architecture approach with strict separation of concerns:

• business/core → domain layer
• business/usecase → application logic
• adapters → external interfaces (HTTP, DB, messaging, search)
• api/main → application bootstrap (composition root)

---

Requirements

Make sure you have the following installed:

• Go (>= 1.26 recommended)
• Docker
• Kubernetes (Minikube recommended)
• kubectl
• Skaffold
• migrate (golang-migrate CLI)
• Jet CLI

---

Build & Run Instructions

Kubernetes + Docker (recommended)

From the project root directory:

make native-dev-clean

This will:

1. Generate database schema and Jet code
2. Build the Go binary (compatible with Docker Alpine)
3. Build Docker image
4. Deploy and run the application using Skaffold

---

Alternative (manual workflow)

Build only:

make build-docker-image

Run (Skaffold handles build + deploy):

skaffold dev --tag latest

---

Native execution (local binary only)

make native-dev-clean

This will:

1. Generate database schema and Jet code
2. Build the Go binary
3. Deploy required infrastructure to Kubernetes (PostgreSQL, NATS, Elasticsearch)
4. Run the application locally with environment variables pointing to Minikube services

---

Alternative manual workflow

Build:

make build-native

Run:

make run-native

---

Access the application

URL

Kubernetes + Docker:

http://$(minikube ip):30080

Native execution:

http://localhost:8080

---

Default credentials

Authentication endpoint:

POST http://<IP>:<PORT>/api/auth/login

Payload:

{
  "email": "admin@example.com",
  "password": "admin"
}

Response:

You will receive a JWT token.

Use it in protected routes:

Authorization: Bearer <YOUR_TOKEN>

---

Why this architecture

• Clean Architecture isolates domain logic from frameworks and infrastructure
• Improves testability and long-term maintainability
• Modular structure enables independent evolution of components
• Kubernetes-based workflow simulates production-like environment locally
• Event-driven design (NATS + Elasticsearch) enables scalability and observability

---

Notes

• Jet code generation depends on a running PostgreSQL instance
• Kubernetes (Minikube) must be running for full stack execution
• Consumers are intentionally embedded in the main API for simplicity (POC design choice)