Hexagonal architecture,
built from the inside out.

A hands-on Go architecture course that teaches hexagonal architecture, also known as ports and adapters, by building a small e-commerce backend from scratch.

The service you build is called MiniMart: a product catalog, an order system, real PostgreSQL storage, Kafka-style events, Docker packaging, and tests. The course starts with simple standard-library Go and grows the application one deliberate boundary at a time.

If you are learning Golang clean architecture, DDD-lite, modular monoliths, domain-driven design in Go, or production backend patterns, this repo is meant to be read and typed through stage by stage.

What This Teaches

MiniCart is not just a CRUD tutorial. It teaches the design habits behind maintainable Go services:

• Hexagonal architecture in Go: keep business rules in the center and push HTTP, databases, queues, and deployment concerns to the edges.
• Ports and adapters: define interfaces where the domain needs them, then implement those ports with memory, PostgreSQL, and Kafka adapters.
• Dependency direction: enforce the rule presentation -> application -> domain, while infrastructure depends inward on domain-owned ports.
• Valid domain models: build entities that are valid by construction, with sentinel errors and table-driven tests.
• Use cases and DTO boundaries: separate HTTP request shapes, application requests, domain entities, and cross-domain contracts.
• Modular monolith design: split catalog, order, and notification into explicit modules with a boot lifecycle.
• Cross-domain contracts: let domains communicate through published client packages instead of importing each other's internals.
• PostgreSQL with migrations and sqlc: use dbmate for schema changes and sqlc for type-safe generated queries.
• Kafka-style events: publish OrderPlaced, consume it from multiple handlers, and treat message consumers as input adapters.
• Production packaging: build one binary with server, worker, and migrate subcommands, then package it with Docker.
• Testing strategy: use fast unit tests with fakes and gated integration tests against real Postgres.

What You Build

By the end, MiniMart has:

Course Map

Work through the stages in order:

Prerequisites

You should be comfortable with basic Go syntax and the command line. The course introduces the architecture gradually, but it assumes you can create files, run commands, and read compiler errors.

Install:

• Go 1.22+
• Docker and Docker Compose
• curl
• sqlc
• dbmate

Stage 00 walks through the tool checks and setup.

How To Use This Repo

Start here:

cd 00-setup

Then open 00-setup/README.md and follow each stage in order. Every stage has goals, code to type, verification steps, and short exercises. Prominent checkpoints appear only where a result demonstrates an important concept.

The intended workflow is:

1. Read one stage section.
2. Type the code into your own minimart Go module.
3. Run the Verify commands as you build.
4. At a Checkpoint, inspect the result and move forward only when you understand why it passes.

Search Terms

Go hexagonal architecture, Golang clean architecture, ports and adapters in Go, domain-driven design Go example, DDD lite Go, modular monolith Go, PostgreSQL sqlc Go, dbmate migrations, Kafka events in Go, Redpanda local Kafka, Go backend testing, Go integration tests, production Go service architecture.