go-microservice-scaffold

When to Use

• Creating a new microservice from scratch
• Adding a new domain/module to an existing service
• Reviewing or refactoring service structure
• Onboarding someone to the Go service layout

Architecture principles (dependency rule, ports & adapters, layer responsibilities) live in the clean-architecture skill. Load it first if you need the WHY. This skill covers the HOW for Go.

---

Service Structure

Each microservice lives under api/ and follows this layout:

Single-Domain Service (Most Common)

When a service has one primary domain (e.g., notification, booking):

api/
  {service-name}/              # e.g., booking, payment, notification
    cmd/
      server/
        main.go                # Entry point — composition root
    internal/
      domain/                  # Domain layer: entities, value objects, ports
        entity.go
        value_object.go
        port.go
        error.go
      application/             # Application layer: use cases, DTOs
        service.go
        dto.go
      infrastructure/          # Infrastructure layer: implementations
        config/                # Environment configuration
          config.go
        database/              # Database connection setup
          postgres.go
        handler/               # HTTP/gRPC handlers
          http.go
          grpc.go
        middleware/            # HTTP middleware
          auth.go
          logging.go
        repository/            # Persistence implementations
          postgres.go
          memory.go
        messaging/             # Message pub/sub implementations
          publisher.go
          subscriber.go
        server/                # Server setup
          http.go
          grpc.go
    proto/                     # Protobuf definitions for this service
      {domain}.proto
    migrations/                # SQL migrations
      000001_initial.up.sql
      000001_initial.down.sql
    tests/
      e2e/                     # E2E tests (Bruno collections)
        bruno.json
        environments/
          local.bru
        {domain}/
          *.bru
      load/                    # Load tests (k6 scripts)
        smoke.js
        load.js
    Dockerfile
    go.mod
    go.sum
    Makefile
    README.md

Test location convention: See testing-strategy skill for where each test level goes (unit, integration, contract, E2E, load).

Multi-Domain Service (Rare)

Only use this when a service has multiple distinct domains (e.g., booking + availability):

api/
  {service-name}/
    cmd/server/main.go
    internal/
      {domain-1}/              # e.g., booking
        domain/
        application/
        infrastructure/
      {domain-2}/              # e.g., availability
        domain/
        application/
        infrastructure/
      shared/                  # ONLY for truly cross-domain concerns
        middleware/
        config/

Rule of thumb: If you have internal/shared/, reconsider. Most "shared" code belongs in infrastructure/.

---

Naming Conventions

Element	Convention	Example
Service directory	lowercase singular noun	api/booking/
Domain directory	domain/ at internal root	internal/domain/
Entity file	entity.go	internal/domain/entity.go
Port file	port.go	internal/domain/port.go
Use case file	service.go	internal/application/service.go
Package names	short, lowercase, singular	package booking
Interfaces	verb-er or descriptive	BookingRepository, PaymentGateway
Structs	noun	Booking, CreateBookingInput
Domain errors	Err prefix	ErrBookingNotFound, ErrBookingOverlap
Environment variables	SCREAMING_SNAKE	DB_PASSWORD

---

Domain Layer — port.go Pattern

See assets/port.go

Application Layer — service.go Pattern

See assets/service.go

---

Adding a New Domain to a Service

For single-domain services (most common):

1. Add to existing structure:
   • Entities → internal/domain/entity.go
   • Use cases → internal/application/service.go
   • Adapters → internal/infrastructure/

For multi-domain services (rare):

1. Create directory: internal/{domain-name}/domain/, application/, infrastructure/
2. Define entities in internal/{domain-name}/domain/entity.go
3. Define ports in internal/{domain-name}/domain/port.go
4. Implement use cases in internal/{domain-name}/application/service.go
5. Implement adapters in internal/{domain-name}/infrastructure/
6. Wire in cmd/server/main.go (see go-service-bootstrap skill)

Adding a New Microservice

1. Create api/{service-name}/ with full structure above
2. Initialize Go module: go mod init github.com/{org}/bastet/api/{service-name}
3. Add Dockerfile, Makefile, README.md (see go-docker-deploy skill)
4. Add protobuf definitions if service exposes gRPC (see go-grpc-services skill)
5. Add migration files if service has persistence (see go-repository-pattern skill)
6. Wire dependencies in main.go (see go-service-bootstrap skill)
7. Register in docker-compose and gateway routing (see local-dev-workflow skill)

---

Commands

# Create a new SINGLE-DOMAIN service scaffold (most common)
mkdir -p api/{service}/cmd/server
mkdir -p api/{service}/internal/{domain,application,infrastructure/{config,database,handler,middleware,repository,messaging,server}}
mkdir -p api/{service}/proto
mkdir -p api/{service}/migrations

# Initialize Go module
cd api/{service} && go mod init github.com/{org}/bastet/api/{service}

# Verify structure
tree api/{service}

---

Anti-Patterns

Don't	Do
api/booking/controllers/	api/booking/internal/infrastructure/handler/
api/booking/models/	api/booking/internal/domain/entity.go
internal/shared/ in single-domain services	Put in internal/infrastructure/
internal/{domain}/ when service has one domain	Use internal/domain/ directly
Import cloud SDK in domain	Define interface in domain, implement in infrastructure
Shared database between services	Each service owns its data
utils/ package	Put helpers in the domain or infrastructure where they belong
Business logic in handlers	Handlers call application service, that's it

---

Related Skills

Skill	What it covers
clean-architecture	Principles: dependency rule, layers, ports & adapters (load first!)
go-service-bootstrap	Configuration, DI wiring, environments, graceful shutdown
go-gin-handlers	HTTP handler patterns, middleware, error responses
go-repository-pattern	Persistence, migrations, sqlc
go-docker-deploy	Dockerfile, docker-compose, deployment