portsmith

portsmith

portsmith is a Go framework for building backends with Clean Architecture — out of the box.

It gives your team:

• A shared structure every developer and QA engineer understands instantly
• CLI tools to generate, scaffold, mock, and validate architecture
• Runtime libraries for HTTP, database, config, pagination, and testing
• A CI/CD-ready architecture linter (portsmith check)

Contents

• Quick start
• Clean Architecture overview
• Project layout
• Technology stacks
• Libraries
• CLI tools
• Testing
• CI/CD integration
• Example package

Quick start

# Install the CLI
go install github.com/miilkaa/portsmith/cmd/portsmith@latest

# Scaffold a new package
portsmith new internal/orders

# Implement your domain, service, and repository, then generate ports:
portsmith gen internal/orders

# Generate mocks (requires mockery)
go install github.com/vektra/mockery/v2@latest
portsmith mock internal/orders

# Validate architecture
portsmith check ./internal/...

In main.go:

package main

import (
    "log"
    "os"

    "github.com/miilkaa/portsmith/pkg/config"
    "github.com/miilkaa/portsmith/pkg/database"
    "github.com/miilkaa/portsmith/pkg/server"

    "yourmodule/internal/orders"
)

type Config struct {
    Port        int    `env:"PORT"         env-default:"8080"`
    DatabaseURL string `env:"DATABASE_URL" env-required:"true"`
}

func main() {
    var cfg Config
    if err := config.Load(&cfg); err != nil {
        log.Fatal(err)
    }

    db, err := database.Connect(database.Config{DSN: cfg.DatabaseURL})
    if err != nil {
        log.Fatal(err)
    }
    database.Register(db, &orders.Order{})

    repo := orders.NewRepository(db.DB())
    svc  := orders.NewService(repo)
    h    := orders.NewHandler(svc)

    srv := server.New(server.Config{Port: cfg.Port})
    h.Routes(srv.Router().Group("/api/v1"))
    log.Fatal(srv.Run())
}

Clean Architecture overview

Dependencies point inward only. Outer layers know about inner layers, never the reverse.

Handler → ServicePort ← Service → RepositoryPort ← Repository

See docs/en/architecture.md for detailed explanation.

Project layout

your-app/
├── internal/
│   ├── orders/
│   │   ├── domain.go
│   │   ├── errors.go
│   │   ├── ports.go          ← generated by portsmith gen
│   │   ├── service.go
│   │   ├── repository.go
│   │   ├── handler.go
│   │   ├── dto.go
│   │   └── mocks/            ← generated by portsmith mock
│   └── users/
│       └── ...
└── main.go

Technology stacks

portsmith new and portsmith check support two stacks:

How the stack is chosen (highest priority first):

1. --stack gin-gorm or --stack chi-sqlx on the CLI
2. portsmith.yaml in the project root: stack: chi-sqlx
3. go.mod: if github.com/go-chi/chi appears → chi-sqlx; if github.com/gin-gonic/gin → gin-gorm
4. Default: gin-gorm

Example portsmith.yaml:

stack: chi-sqlx

Libraries

pkg/apperrors

Typed domain errors that map to HTTP status codes automatically.

var ErrNotFound = apperrors.NotFound("order not found")   // → 404
var ErrConflict = apperrors.Conflict("duplicate order")   // → 409

// In service — return domain errors, not HTTP codes:
if errors.Is(err, ErrNotFound) { return nil, ErrNotFound }

// The server middleware handles HTTP mapping automatically.

Full documentation

pkg/database

GORM wrapper with auto-migration and a generic Repository[T].

db, _ := database.Connect(database.Config{DSN: os.Getenv("DATABASE_URL")})
database.Register(db, &orders.Order{}, &users.User{})

// Generic CRUD base — embed in your domain repository:
type Repository struct {
    base database.Repository[Order]
    db   *gorm.DB
}

// Transactions:
database.WithTx(ctx, db, func(tx *database.DB) error {
    return repo.Create(ctx, order)
})

Full documentation

pkg/pagination

Offset-based pagination with HTTP query parsing.

// In handler:
page := pagination.OffsetFromQuery(c.Request)  // ?page=2&limit=20

// In repository:
query.Offset(page.Offset()).Limit(page.Limit())

// In response:
totalPages := pagination.TotalPages(total, page.Limit())

Full documentation

pkg/config

Load configuration from environment variables.

type Config struct {
    Port int    `env:"PORT" env-default:"8080"`
    DSN  string `env:"DATABASE_URL" env-required:"true"`
}
var cfg Config
config.Load(&cfg)

Full documentation

pkg/server

Gin server with batteries included.

srv := server.New(server.Config{Port: 8080})
// Built-in: GET /health, recovery, requestID, CORS, error → HTTP mapping
userHandler.Routes(srv.Router().Group("/api/v1"))
srv.Run()

Full documentation

pkg/chiserver

Chi-based HTTP server with request ID, recovery, CORS, /health, BindAndValidate, and RespondError (uses apperrors for status codes). Use with the chi-sqlx stack.

srv := chiserver.New(chiserver.Config{Port: 8080})
srv.Router().Mount("/api/v1", ordersHandler.Routes())
log.Fatal(srv.Run())

pkg/sqlxdb

PostgreSQL connectivity via sqlx and the pgx database/sql driver (sqlx.Connect("pgx", url)), plus WithTx for transactions. No migrations — use your own tool.

db, err := sqlxdb.Connect(sqlxdb.Config{URL: os.Getenv("DATABASE_URL")})

pkg/testkit

Testing helpers for all architecture layers.

// Handler test (no database):
suite := testkit.NewHTTPSuite(t, router)
suite.POST("/orders", `{"item":"book"}`).ExpectStatus(201).ExpectJSONPath("$.id", float64(1))

// Repository test (SQLite in-memory):
db := testkit.NewTestDB(t, &orders.Order{})

// Table-driven tests:
testkit.Table(t, []testkit.Case{
    {Name: "success", Run: func(t *testing.T) { ... }},
})

Full documentation

CLI tools

portsmith gen

Generate ports.go — minimal interfaces from actual usage.

portsmith gen internal/orders          # single package
portsmith gen --all                    # all packages under internal/
portsmith gen --dry-run internal/orders # preview without writing

Interface names in ports.go use the folder name as a default prefix (webpush → WebpushRepository). If your Handler / Service structs already reference types like WebPushRepository / WebPushService, gen picks up that prefix so names stay consistent.

portsmith new

Scaffold a new package with all Clean Architecture files. The stack affects generated imports and types (Gin+GORM vs Chi+sqlx).

portsmith new internal/products
portsmith new --stack chi-sqlx internal/widgets
# creates: domain.go, errors.go, ports.go, service.go, repository.go, handler.go, dto.go

portsmith mock

Generate mocks for all interfaces in ports.go (wraps mockery).

portsmith mock internal/orders
# creates: internal/orders/mocks/mock_orders_repository.go
#          internal/orders/mocks/mock_orders_service.go

portsmith check

Validate architecture rules. Exits with code 1 on error-severity violations; warning-severity issues are printed but do not fail the command. Prints the detected stack (same resolution as portsmith new); override with --stack if needed.

portsmith check ./internal/...
portsmith check --stack gin-gorm ./internal/...

Core rules (always on): ports.go presence when the three-file layout exists; handler must not import DB drivers; service.go must not import HTTP/routers; struct fields use ports, not concrete layer pointers; layer dependency direction (handler → service only, service → repository only); exported types stay in the right layer files; constructor parameters use interfaces; no panic in service/repository files; optional context.Context as first parameter on exported service/repository methods.

Optional rules (via portsmith.yaml → lint): max file lines, max exported methods per service/handler, allowlisted cross-package internal/... imports, wiring-only calls to New*Repository / New*Service / New*Handler.

Per-rule severity and inline suppress:

# portsmith.yaml
lint:
  rules:
    test-files:    { severity: warning }  # test file presence
    context-first: { severity: warning }  # context.Context first
    method-count:  { severity: warning }

//nolint:portsmith:handler-no-db
import "gorm.io/gorm"

See docs/en/architecture.md for the full rule table and YAML examples.

Testing

portsmith follows Red → Green → Refactor TDD:

1. Write contract tests first (define the public API)
2. Implement until tests pass
3. Refactor — tests guard against regressions

Three testing levels:

See docs/en/tdd-guide.md for patterns and examples.

CI/CD integration

# GitHub Actions
- name: Architecture check
  run: go run ./cmd/portsmith check ./internal/...

# GitLab CI
architecture:
  script:
    - go run ./cmd/portsmith check ./internal/...

Example package

A complete reference implementation is available in two locales:

• examples/clean_package_example_en — comments in English
• examples/clean_package_example_ru — comments in Russian

Both examples demonstrate all layers with detailed comments explaining every design decision.

Also available in Russian: README.ru.md

Requirements

• Go 1.21+
• PostgreSQL (or SQLite for development/tests)
• mockery for mock generation

License

MIT