Forem: Mahmud Hasan Rafid

Building a Domain-Driven Go REST API (And Why It Scales Better Than Flat Structure)

Mahmud Hasan Rafid — Tue, 31 Mar 2026 11:33:59 +0000

Most Go backend projects start the same way. A main.go, a router, a database connection, and then a slow drift into a structure that technically works but becomes painful to extend after the third or fourth feature. I've been there enough times that I finally sat down, extracted the architecture from a production project I was happy with, and published it as an open-source boilerplate.

This post explains the architecture, why Domain-Driven Design (DDD) fits Go surprisingly well, and how the boilerplate is structured so you can hit the ground running on your next project.

GitHub: https://github.com/princerafid01/go-rest-boilerplate

Why DDD in Go?

Domain-Driven Design gets a bad reputation for being a Java/C# thing — verbose, ceremonial, and overkill for most projects. That reputation is mostly deserved for the full tactical DDD toolkit (aggregates, value objects, domain events). But the core idea of DDD is simple and language-agnostic:

The domain model is the center of your application. Everything else — HTTP, SQL, auth — is infrastructure that serves the domain.

Go is actually a great fit for this style because:

Interfaces are implicit and lightweight, so defining boundaries between layers costs almost nothing
The package system naturally enforces separation — packages can't have circular imports
Go's preference for small, focused types maps cleanly to domain entities and service objects

The result is a codebase where your business logic is completely isolated from delivery mechanisms (HTTP, gRPC) and persistence (Postgres, any other DB). You can swap either without touching your domain.

The Architecture at a Glance

HTTP Request
    │
    ▼
Middleware Chain (Preflight → CORS → Logger)
    │
    ▼
Route-Specific Middleware (JWT Auth → injects userID into context)
    │
    ▼
Handler  ← parses HTTP request, calls service
    │
    ▼
Service  ← business rules, depends only on interfaces (the domain layer)
    │
    ▼
Repo     ← SQL implementation, satisfies the repo interface
    │
    ▼
PostgreSQL

The key rule: each layer only depends on the layer below it through an interface. The only file that imports concrete implementations across layers is cmd/serve.go — the application wiring root. Everything else is interface-to-interface.

Project Structure

.
├── main.go
├── cmd/serve.go                  # Application layer — wires all dependencies
├── config/config.go              # Env-based config
├── domain/                       # Pure domain entities — no DB, no HTTP
│   ├── user.go
│   └── product.go
├── {feature}/                    # Bounded context per domain feature
│   ├── port.go                   # Service interface + Repo interface
│   └── service.go                # Business logic implementation
├── repo/                         # Infrastructure — sqlx SQL implementations
│   └── {feature}.go
├── rest/                         # Delivery mechanism — HTTP
│   ├── server.go
│   ├── middlewares/
│   └── handlers/{feature}/
│       ├── port.go               # What the handler needs from the service
│       ├── handler.go
│       ├── dto.go                # Request/response types
│       ├── routes.go
│       └── *.go                  # One file per action
├── utils/                        # Shared helpers (JWT, responses, pagination)
└── migrations/                   # Up/down SQL pairs

Let's walk through what each layer actually does.

The Domain Layer

The domain/ package is the heart of the application. It contains plain Go structs that represent your business entities — nothing else.

// domain/user.go
type User struct {
    ID           int64
    Email        string
    PasswordHash *string
    Name         string
    CreatedAt    time.Time
    UpdatedAt    time.Time
}

No HTTP types. No database tags that bleed framework concerns into your model. No third-party imports. If you need to change your database driver tomorrow, this file doesn't change. That's the point.

The Feature (Bounded Context) Layer

Each domain feature gets its own package. For example, a product feature would have:

product/port.go — defines the contracts this feature exposes and depends on:

// What this feature exposes to its consumers
type Service interface {
    productHandler.Service // embeds the handler's Service interface
}

// What this feature needs from the data layer
type ProductRepo interface {
    Create(domain.Product) (*domain.Product, error)
    Get(id, userID int64) (*domain.Product, error)
    List(userID, page, limit int64) ([]*domain.Product, error)
    Count(userID int64) (int64, error)
    Update(domain.Product) (*domain.Product, error)
    Delete(id, userID int64) error
}

The Service interface embeds productHandler.Service — this is a deliberate design decision. The handler defines what it needs from the service layer, and the feature-level Service interface must satisfy that contract. If you add a method to the handler's interface, the Go compiler immediately tells you to implement it everywhere that needs to. No runtime surprises.

product/service.go — implements business logic:

type service struct{ repo ProductRepo }

func NewService(repo ProductRepo) Service {
    return &service{repo: repo}
}

func (s *service) Create(p domain.Product) (*domain.Product, error) {
    // Business rules go here before delegating to repo
    return s.repo.Create(p)
}

The service only knows about domain types and its repo interface. It has no idea whether it's being called from an HTTP handler, a CLI command, or a test.

The Infrastructure Layer (Repo)

The repo/ package is pure infrastructure. It satisfies the repo interfaces defined in the feature layer using sqlx and raw SQL:

func (r *productRepo) Create(p domain.Product) (*domain.Product, error) {
    query := `
        INSERT INTO products (user_id, name, price)
        VALUES (:user_id, :name, :price)
        RETURNING id, created_at, updated_at
    `
    rows, err := r.db.NamedQuery(query, p)
    if err != nil {
        return nil, err
    }
    if rows.Next() {
        rows.Scan(&p.ID, &p.CreatedAt, &p.UpdatedAt)
    }
    return &p, nil
}

No ORM, no magic. Just SQL. The repo knows about the database, but the domain and service layers don't.

The Delivery Layer (HTTP Handlers)

Handlers are thin. Their only job is to parse the HTTP request, call the service, and write the HTTP response. They don't contain business logic.

func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
    userID, ok := r.Context().Value(middleware.UserIDKey).(int64)
    if !ok {
        utils.SendError(w, http.StatusUnauthorized, "Unauthorized")
        return
    }

    var req CreateRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        utils.SendError(w, http.StatusBadRequest, "Invalid request body")
        return
    }

    result, err := h.svc.Create(domain.Product{
        UserID: userID,
        Name:   req.Name,
        Price:  req.Price,
    })
    if err != nil {
        utils.SendError(w, http.StatusInternalServerError, "Internal server error")
        return
    }

    utils.SendData(w, http.StatusCreated, result)
}

Each handler action gets its own file (create.go, get.go, list.go, etc.). This keeps files small and makes navigation obvious.

The Middleware System

The boilerplate uses a small custom Manager with two levels of middleware:

Global — applied to every request, registered in server.go:

manager.Use(middleware.Preflight, middleware.Cors, middleware.Logger)

Per-route — applied to specific routes using manager.With(...):

mux.Handle("POST /api/products", manager.With(
    http.HandlerFunc(h.Create),
    h.middlewares.AuthenticateJWT,
))

The JWT middleware validates the HS256 signature, decodes the payload, and injects the userID into the request context using a typed context key — avoiding the string key collision problem that plagues many Go middleware implementations.

The Application Layer: cmd/serve.go

This is where all the wiring happens. It's the only place in the codebase where concrete types meet:

func Serve() {
    cnf := config.GetConfig()
    dbCon, _ := db.NewConnection(cnf.DB)
    db.MigrateDB(dbCon, "./migrations")

    // Infrastructure
    productRepo := repo.NewProductRepo(dbCon)

    // Domain services
    productSvc := product.NewService(productRepo)

    // Delivery
    middlewares := middleware.NewMiddlewares(cnf)
    prodHandler := productHandler.NewHandler(middlewares, productSvc)

    // Server
    rest.NewServer(cnf, prodHandler).Start()
}

Everything flows top-down. Dependencies are explicit. There's no magic injection framework — just function calls. If something breaks, you can trace it by reading this file alone.

Adding a New Feature in 7 Steps

This is where the architecture pays for itself. To add a new Order resource:

Add domain/order.go — the entity struct
Add rest/handlers/order/port.go — the Service interface the handler needs
Add order/port.go — embeds the handler's Service interface, defines OrderRepo
Add order/service.go — implements the business logic
Add repo/order.go — implements OrderRepo with SQL
Add rest/handlers/order/ — handler, dto, routes, one file per action
Wire it in cmd/serve.go — create repo → service → handler → register routes

Every step is additive. You never modify existing files to add a new feature. That's the DDD principle of bounded contexts in practice.

The Stack

Concern	Choice
HTTP	`net/http` (stdlib)
Database	`sqlx` + `lib/pq`
Migrations	`rubenv/sql-migrate`
Auth	Hand-rolled HS256 JWT
Config	`godotenv` + env vars
Passwords	`golang.org/x/crypto/bcrypt`

No heavy framework. The stdlib HTTP mux has supported path parameters since Go 1.22, which covers the routing needs of most REST APIs without pulling in gorilla/mux or chi.

Getting Started

git clone https://github.com/princerafid01/go-rest-boilerplate my-project
cd my-project

# Rename the module
find . -type f -name "*.go" | xargs sed -i 's/boilerplate/my-project/g'
go mod edit -module my-project

# Configure environment
cp .env.example .env
# Edit .env with your DB credentials and JWT secret

go mod tidy
go run main.go

Migrations run automatically on startup. The example feature included in the repo gives you a working reference for the full CRUD pattern while you build out your own features.

Final Thoughts

DDD in Go doesn't have to mean heavyweight ceremony. At its core it's just one rule: keep your domain clean, and treat everything else as infrastructure. Go's interface system and package model make this remarkably natural to implement.

If you've been looking for a Go backend structure that scales past the first few features without becoming a mess — give this a try. And if you have ideas for improvements, PRs are very welcome.

https://github.com/princerafid01/go-rest-boilerplate

The Shopify Resource Picker API: A Developer's Journey Through Version Changes (August 2025 )

Mahmud Hasan Rafid — Sat, 16 Aug 2025 03:22:17 +0000

Introduction

As a developer working with Shopify's ecosystem, I recently encountered a familiar yet frustrating challenge: implementing the resource picker API. What should have been a straightforward integration turned into a lesson about the limitations of AI powered development tools when dealing with rapidly evolving APIs.

The Challenge

I needed to implement a product picker in my Shopify app that would allow users to select multiple products from their store. The concept seemed simple enough - use Shopify's resource picker API to open a modal where users can search and select products.

However, the implementation proved more challenging than expected, primarily due to the frequent changes in Shopify's API versions and documentation.

The Solution

After several attempts and much trial and error, I finally got the resource picker working. Here's the working implementation:

import { useAppBridge } from '@shopify/app-bridge-react';

export default function ProductResourcePicker() {
  const app = useAppBridge();

  const openProductPicker = async () => {
    const productPicker = await app.resourcePicker({
        type: "product",
        multiple: true,
        initialQuery: 'macbook',
        options: {
            showHidden: false
        }
    });

    if (productPicker && productPicker.selection && productPicker.selection.length > 0) {
        console.log("Selection made:", productPicker.selection);
    }
  };

  return (
    <button onClick={openProductPicker}>Open Product Picker</button>
  );
}

The key components that made this work:

useAppBridge(): Properly initializing the Shopify app bridge
app.resourcePicker(): Using the correct method call
Proper configuration: Setting the right parameters for product selection

The AI Frustration

Here's where things got interesting - and frustrating. I initially turned to AI coding assistants for help, but they consistently provided outdated or incorrect information.

Conclusion

While AI development tools are incredibly powerful and can significantly speed up development, they have limitations when dealing with rapidly evolving APIs like Shopify's.

My experience with the Shopify resource picker API taught me that sometimes the "old-fashioned" approach of reading documentation, testing incrementally, and learning from the community is still the most reliable path to success.

Building a Scalable Job Queue System with AWS and Laravel

Mahmud Hasan Rafid — Sat, 09 Nov 2024 06:35:52 +0000

Introduction
Ever wondered how large applications handle thousands of background tasks efficiently? Today, I’ll guide you through a real-world solution our storagely.io team developed, which integrates AWS services with Laravel to build a powerful job queue system. This system handles everything from scheduled syncs to on-demand processing, all while maintaining reliability and scalability.

The Challenge
Imagine you're running a service that needs to sync data for multiple clients regularly. Some syncs need to happen automatically every few hours, while others should be triggered manually by users. You also need to ensure jobs don't duplicate, processes are monitored, and everything is logged properly. Sounds complex? Let's break it down.

The Solution: A Three-Tier Queue Architecture

Tier 1: Automated Sync System
Think of this as your reliable alarm clock. Using AWS EventBridge (the alarm clock) and Lambda (the person who wakes up), the system automatically checks for work that needs to be done. Every 15 minutes, EventBridge triggers a Lambda function that asks: "Hey, do any clients need their data synced?"
Here's what happens:

EventBridge says "Time to check for syncs!"
Lambda wakes up and says "Let me check the list of clients"
For each client, Lambda asks "Does this client already have a sync in progress?"
If not, Lambda says "Ok, let's create a new sync job for this client"

Tier 2: On-Demand Processing
Sometimes users can't wait for the automated schedule. Maybe they've made important changes and need data synced right now. That's where our on-demand system comes in. It's like having a "Sync Now" button that users can press whenever they need it.
When a user hits that button:

The system creates a high-priority job
This job jumps into a "speedy queue"
It gets processed faster than regular scheduled jobs

Tier 3: The Job Processor
This is where the actual work happens. Running on AWS EC2, this system is like a well-organized factory floor. It uses a tool called Supervisor (think of it as a factory manager) to ensure workers (processes) are always available to handle jobs.
The process flows like this:

Jobs arrive from either automated or on-demand sources
Workers pick up these jobs
Each job gets processed
Results get stored in a MySQL database
Everything gets logged in CloudWatch

The Magic Behind The Scenes
Let's peek at how the automated part works. The Lambda function, written in Node.js, is surprisingly simple:

javascriptCopyexports.handler = async (event) => {
    // Check for existing jobs
    const clients = await fetchClientList();

    for (const client of clients) {
        // Don't create duplicate jobs
        if (!(await hasExistingJob(client))) {
            // Create new sync job
            await createSyncJob(client);
        }
    }
};

Monitoring and Reliability
Every good system needs monitoring. Using CloudWatch, we track everything:

How many jobs are running?
Are any jobs failing?
How long do jobs take to complete?
Are there any bottlenecks?

Conclusion
Building a queue system might seem daunting at first, but by breaking it down into manageable pieces and using the right tools, we've created a robust solution that handles both automated and on-demand tasks efficiently. The combination of AWS services (EventBridge, Lambda, EC2) with Laravel's queue system provides a perfect balance of reliability, scalability, and maintainability.
Whether you're handling data syncs, processing reports, or managing any other background tasks, this architecture provides a solid foundation that can grow with your needs. The best part? It runs like clockwork, requiring minimal maintenance while providing maximum visibility into its operations.

How Git Cherry-Pick Saved My Day: A Tale of Branch Chaos 🍒

Mahmud Hasan Rafid — Mon, 14 Oct 2024 05:26:58 +0000

Ever had one of those moments where a single command turns disaster into triumph? That was me today, through a maze of Git branches.

The scene:

Three branches: main (production), test (staging), and feature
Main branch lagging behind the test
Feature branch spawned from an outdated main
PRs flowing from feature to test
Conflict resolution on GitHub’s web interface (pro tip: avoid this if possible!)
Post-conflict feature branch: a mix of my work and others, looking like the test branch

The challenge: My feature branch now had commits from the test branch, making it impossible to merge directly into the production (main) branch.

Enter git cherry-pick, the unsung hero of version control. Here’s what I did:

Identified my commits in the messy feature branch
Created a new branch from the updated main
Cherry-picked my commits from the old feature branch into the new one

Result? I got a new updated feature branch branching from the production branch with only my changes, merge crisis averted, and valuable lessons learned:

Keep branches updated regularly
Resolve conflicts locally when possible
Make small, focused commits
Master cherry-picking for precise code management

Remember folks: In the orchard of code, sometimes you need to carefully pick your cherries instead of shaking the whole tree. 🌳🍒