Navigating the generated application

After crank init, you have a fully wired Go backend service.
This page explains every layer — where things live, why they are there, how they connect, and how to extend them.

📋 Table of Contents

• Architecture overview
• Directory layout
• Composition root
• Domain layer
• Application layer
• HTTP adapter
• Persistence adapters
• Unit of Work and Event Bus
• Cross-cutting packages
• Request lifecycle
• Feature modules
• Code generation
• Testing patterns
• Configuration deep dive
• External documentation

🏗️ Architecture overview

The generated project follows a Domain-Driven Design layered architecture.
Every layer depends only on the layer below it — never upward.

🔑 Key principles

📐 Dependency rule

HTTP Handlers  →  Application Handlers  →  Domain (Aggregates + Ports)  ←  Infrastructure Adapters
     │                    │                                                    │
     └─── DTOs live ──────┘                                                    │
          here                                                                 │
                                                                               │
          Infrastructure adapters (Persistence, EventBus, etc.) implement      │
          interfaces defined in the Domain — the domain never                  │
          imports infrastructure.                                              │

📁 Directory layout

myapp/
├── 📂 cmd/server/                  ←  Entry point + composition root
├── 📂 configs/                     ←  Config defaults (committed)
├── 📂 internal/
│   ├── 📂 adapters/                ←  Infrastructure implementations
│   │   ├── 📂 eventbus/            ←  In-process event bus
│   │   ├── 📂 http/web/            ←  Echo handlers + middleware
│   │   ├── 📂 persistence/         ←  memory/, bun/, gorm/ repositories
│   │   ├── 📂 cache/               ←  Redis client (redis feature)
│   │   └── 📂 uow/                 ←  Unit of Work implementations
│   ├── 📂 application/             ←  CQRS use cases
│   │   └── 📂 user/
│   ├── 📂 config/                  ←  Viper + env config loading
│   ├── 📂 domain/                  ←  Pure domain model
│   │   ├── 📂 shared/              ←  DomainEvent interface + codecs
│   │   └── 📂 user/                ←  Aggregate, ID, events, errors, port
│   ├── 📂 model/                   ←  Shared DTOs (APIError)
│   ├── 📂 ports/                   ←  Cross-cutting interfaces
│   └── 📂 validator/               ←  Request validation
├── 📂 pkg/logging/                 ←  slog helpers + redaction
├── 📂 docs/                        ←  Generated Swagger spec
├── 📂 migrations/                  ←  SQL migrations (with ORM)
├── 📄 .crank.yaml                  ←  Project manifest (do not delete)
├── 📄 .env.example                 ←  Local env template
├── 📄 .air.toml                    ←  Live-reload config
├── 📄 Dockerfile
└── 📄 Makefile                     ←  Project-specific targets

💡 Tip: The internal/ directory enforces Go’s visibility rules —
nothing outside the module can import packages under internal/.

🚀 Composition root

This is the single entry point (cmd/server/main.go) and the only place where concrete types
are wired together. It performs these steps in order:

This is also where feature clients (Redis, Temporal, MongoDB, etc.) are wired.
The generated code uses marker comments (// crank:config-*, // crank:http-*)
so that crank add and crank make handler can inject new wiring without
breaking existing code.

🧩 What gets wired (feature-dependent)

🧠 Domain layer

The domain layer (internal/domain/) is the heart of the application — pure Go with zero
external dependencies. Each business concept lives in its own package.

📦 Package anatomy

Taking the generated internal/domain/user/ package:

🧬 The aggregate

type User struct {
    id        UserID
    name      string
    email     string
    password  string       // bcrypt hash (only with auth feature)
    createdAt time.Time
    updatedAt time.Time
    events    []shared.DomainEvent
}

✨ Design decisions

🔨 Creating a new aggregate

id, _ := user.NewUserID("usr_123")
u, err := user.NewUser(id, "Alice", "alice@example.com")
// u.PullEvents() → [UserCreated{...}]

🔄 Shared domain event infrastructure

The internal/domain/shared/ package provides:

⚙️ Application layer

The application layer (internal/application/) implements use cases using the CQRS pattern —
Commands mutate state, Queries read state. They never mix.

📦 Package anatomy

🎮 Command handler pattern

func (h *CommandHandler) HandleCreate(ctx context.Context, cmd CreateUserCommand) (*user.User, error) {
    id, err := user.NewUserID(cmd.ID)
    u, err := user.NewUser(id, cmd.Name, cmd.Email)
    err := h.uow.SaveAndPublish(ctx,
        func(ctx context.Context) error { return h.repo.Save(ctx, u) },
        u.PullEvents(),
    )
    return u, nil
}

⚡ The command handler never calls repo.Save directly — it goes through
the Unit of Work to ensure the aggregate save and event publication
are handled atomically.

❓ Why CQRS?

🌐 HTTP adapter

The presentation layer (internal/adapters/http/web/) — translates HTTP requests to application commands/queries
and results back to JSON.

📦 Files at a glance

🧠 The smart binder

The generated server replaces Echo’s default binder with a custom echoBinder
that automatically validates after every c.Bind():

type echoBinder struct {
    defaultBinder echo.Binder
    logger        *slog.Logger
}

func (b *echoBinder) Bind(i any, c echo.Context) error {
    if err := b.defaultBinder.Bind(i, c); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
    }
    if err := validator.Struct(i); err != nil {
        return err  // automatically formatted as ValidationError
    }
    return nil
}

This means handlers never call the validator explicitly:

func (h *UserHandler) Create(c echo.Context) error {
    var in userDTO
    if err := c.Bind(&in); err != nil {  // Bind + validate in one call
        return err
    }
    // ✅ `in` is guaranteed valid past this point
    out, err := h.cmd.HandleCreate(c.Request().Context(), in.toCreateCommand())
    // ...
}

📨 DTO pattern

HTTP handlers define their own DTOs with JSON and validation tags —
they are not the domain aggregate:

type userDTO struct {
    ID    string `json:"id"    validate:"required"`
    Name  string `json:"name"  validate:"required,min=2,max=100"`
    Email string `json:"email" validate:"required,email"`
}

func (d userDTO) toCreateCommand() appuser.CreateUserCommand {
    return appuser.CreateUserCommand{ID: d.ID, Name: d.Name, Email: d.Email}
}

🔌 Route wiring

routes.go uses marker comments to make code generation idempotent:

type MountConfig struct {
    UserHandler *UserHandler
    // crank:http-fields ← new handlers splice fields here
}

func Mount(e *echo.Echo, cfg MountConfig) {
    g := e.Group("/users")
    cfg.UserHandler.Register(g)
    // crank:http-register ← new handlers splice registrations here
}

🚨 Error handling

The composition root installs a custom HTTPErrorHandler that:

1. 🟡 ValidationError → 422 with field-level error details
2. 🔴 echo.HTTPError → Appropriate HTTP status code
3. ⚫ Unhandled errors → 500 Internal Server Error

Handlers map domain errors to HTTP status codes:

if errors.Is(err, user.ErrUserNotFound) {
    return c.JSON(http.StatusNotFound, model.APIError{Error: "user not found"})
}

🔌 Persistence adapters

These (internal/adapters/persistence/) implement the domain’s Repository interface. The composition root
decides which one to wire in — no application code changes.

🗃️ Available adapters

The in-memory repository is a thread-safe sync.RWMutex-guarded map —
perfect for fast tests:

type UserRepository struct {
    mu    sync.RWMutex
    byID  map[string]*user.User
    byEml map[string]*user.User
}

🔄 Switching adapters

To switch from in-memory to PostgreSQL, change only the composition root:

// In-memory (default)
userRepo := memory.NewUserRepository()

// Bun
userRepo := bun.NewUserRepository(db)

// GORM
userRepo := gorm.NewUserRepository(gormDB)

No application or HTTP code changes — they depend only on the domain’s Repository interface.

🔄 Unit of Work and Event Bus

These two abstractions ensure atomicity between persisting an aggregate
and publishing its domain events.

📐 The core flow

💾 In-memory Unit of Work

The default implementation runs save then publish sequentially:

📤 Outbox Unit of Work (with outbox feature)

Both operations share a database transaction:

1. Aggregate saved to its table
2. Domain events written to outbox_events table in same transaction
3. Background worker polls outbox table and relays events to the bus
4. Events deleted after successful publication (at-least-once delivery)

This eliminates the window between “save succeeded” and “publish failed”
that the in-memory UoW has.

📡 Event Bus

The in-memory bus is a simple pub/sub:

bus := eventbus.NewInMemory()
bus.Subscribe(func(ctx context.Context, ev shared.DomainEvent) error {
    slog.Default().Info("event received", "event", ev.EventName())
    return nil
})

Subscribers are called synchronously in registration order. A failing
subscriber does not block others — the error is logged and the next one runs.

🔧 Cross-cutting packages

⚙️ Configuration (internal/config/)

Priority:  env vars  >  .env file  >  configs/config.yaml

Secret fields use env:"SECRET_NAME" tags and are loaded from .env
or environment variables. Feature configs are injected via marker comments.

✅ Validation (internal/validator/)

Preconfigured go-playground/validator singleton:

• Uses JSON tag names in error messages
• Automatically called by the smart Echo binder
• Extensible — add custom validators in init():

validate.RegisterValidation("notblank", func(fl validator.FieldLevel) bool {
    return strings.TrimSpace(fl.Field().String()) != ""
})

📝 Model (internal/model/)

Shared response types used by every HTTP handler:

type APIError struct {
    Error   string `json:"error"`
    Details any    `json:"details,omitempty"`
}

📊 Logging (pkg/logging/)

Helpers built on log/slog:

🔌 Ports (internal/ports/)

Cross-cutting interfaces that adapters implement:

📡 Request lifecycle

                          POST /users
                      {"name":"Alice","email":"a@b.com"}
                              │
                              ▼
┌──────────────────────────────────────────────────────┐
│                   Echo Router                        │
│  Matches POST /users → UserHandler.Create            │
└──────────────────────────────────┬───────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────┐
│              echoBinder.Bind(&userDTO)                │
│                                                       │
│   1. DefaultBinder.Bind() → parse JSON into struct    │
│   2. validator.Struct()    → validate tags            │
│                                                       │
│   ── On failure ──→ 422 ValidationError              │
└──────────────────────────────────┬───────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────┐
│               UserHandler.Create(c)                   │
│                                                       │
│   userDTO.toCreateCommand() → CreateUserCommand       │
│   cmd.HandleCreate(ctx, cmd)                          │
└──────────────────────────────────┬───────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────┐
│           Application CommandHandler                  │
│                                                       │
│   1. user.NewUserID(cmd.ID)                           │
│   2. user.NewUser(id, name, email)                    │
│       → User aggregate + UserCreated event            │
│   3. uow.SaveAndPublish(ctx, saveFn, events)          │
│       ├── repo.Save(ctx, user)                        │
│       └── bus.Publish(ctx, UserCreated{...})          │
└──────────────────────────────────┬───────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────┐
│                   Response                            │
│                                                       │
│   toUserDTO(result) → 201 Created                     │
│   { "id":"...", "name":"Alice", "email":"a@b.com" }  │
└──────────────────────────────────────────────────────┘

🧩 Feature modules

Each optional feature adds files to the project. Here is what every feature
contributes and where to find it.

e.GET("/admin", adminHandler, middleware.JWTAuth(tokens))

crank make workflow OrderFulfillment order_id:uuid
crank make activity ChargeCard amount:float --tests

🏭 Code generation

What crank make scaffold produces (crank make)

crank make scaffold Product title:string price:float --tests

┌──────────────────────────────────────────────────────────┐
│                    crank make scaffold                    │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  📂 internal/domain/product/                              │
│  ├── product.go              ← Aggregate root             │
│  ├── product_id.go           ← Typed ID                   │
│  ├── events.go               ← Domain events              │
│  ├── errors.go               ← Sentinel errors            │
│  └── repository.go           ← Port                       │
│                                                           │
│  📂 internal/application/product/                         │
│  ├── commands.go             ← Create/Update/Delete       │
│  ├── command_handler.go      ← Command execution           │
│  ├── queries.go              ← Get/List                   │
│  └── query_handler.go        ← Query execution            │
│                                                           │
│  📂 internal/adapters/persistence/memory/                 │
│  └── product_repository.go   ← In-memory implementation   │
│                                                           │
│  📂 internal/adapters/http/web/                           │
│  └── product_handler.go      ← Echo handler + DTOs        │
│                                                           │
│  In routes.go:               ← Route wiring (idempotent)  │
│  In migrations/:             ← SQL migration (bun only)   │
│  _test.go files:             ← With --tests flag          │
│                                                           │
└──────────────────────────────────────────────────────────┘

📋 What each kind generates

⚠️ Idempotency: Running crank make scaffold Product twice errors on
the primary artifact but skips existing dependency files. Use --force
to overwrite. Route wiring is idempotent — no duplicate registrations.

🧪 Testing patterns

The in-memory adapters make it possible to test every layer without a database.

🧪 Testing the domain

No mocks needed — pure Go types:

func TestNewUser(t *testing.T) {
    id, _ := user.NewUserID("test-1")
    u, err := user.NewUser(id, "Alice", "alice@example.com")
    assert.NoError(t, err)
    assert.Equal(t, "Alice", u.Name())
    events := u.PullEvents()
    assert.Len(t, events, 1)
    assert.Equal(t, "user.created", events[0].EventName())
}

🧪 Testing application handlers

Wire in-memory adapters directly — no database required:

func TestCreateUser_CommandHandler(t *testing.T) {
    repo := memory.NewUserRepository()
    bus := eventbus.NewInMemory()
    uow := uow.NewInMemoryUoW(bus)
    handler := userapp.NewCommandHandler(repo, uow)

    user, err := handler.HandleCreate(context.Background(), user.CreateUserCommand{
        ID: "test-1", Name: "Alice", Email: "alice@example.com",
    })
    assert.NoError(t, err)
    assert.Equal(t, "Alice", user.Name())
}

🧪 Testing HTTP handlers

Use Echo’s httptest helpers:

func TestUserHandler_Create(t *testing.T) {
    // Wire in-memory adapters
    repo := memory.NewUserRepository()
    bus := eventbus.NewInMemory()
    uow := uow.NewInMemoryUoW(bus)
    cmd := userapp.NewCommandHandler(repo, uow)
    qry := userapp.NewQueryHandler(repo)
    handler := web.NewUserHandler(cmd, qry)

    // Echo test
    e := echo.New()
    body := `{"name":"Alice","email":"a@b.com"}`
    req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(body))
    req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
    rec := httptest.NewRecorder()
    c := e.NewContext(req, rec)

    err := handler.Create(c)
    assert.NoError(t, err)
    assert.Equal(t, http.StatusCreated, rec.Code)
}

📊 Test coverage strategy

⚙️ Configuration deep dive

📥 How config loads

┌──────────────────────────────────────────────────┐
│              godotenv.Load()                      │
│  Reads .env into process environment              │
│  (silently skipped if .env doesn't exist)         │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│              viper.ReadInConfig()                 │
│  Reads configs/config.yaml                        │
│  Sets defaults via setDefaults()                  │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│           env.ParseWithOptions(&cfg)              │
│  Overlays env vars on fields tagged env:"..."     │
│  (typically secrets only)                        │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
                  ✅ Final Config

➕ Adding a new config field

1. Add the field to Config struct in internal/config/config.go
2. Add a Viper default in setDefaults()
3. Add the YAML key to configs/config.yaml
4. If it’s a secret, add env:"VAR_NAME" tag and document in .env.example

🔧 Feature config injection

When you run crank add redis, new config fields are injected at marker comments:

type Config struct {
    App AppConfig `mapstructure:"app"`
    // crank:config-fields       ← RedisConfig inserted here
    Logging LoggingConfig `mapstructure:"logging"`
}

The injection is idempotent — adding the same feature twice is a no-op.

📚 External documentation

Framework	Official docs
	echo.labstack.com
	github.com/spf13/viper
	pkg.go.dev
	pkg.go.dev/log/slog
	github.com/swaggo/swag
	github.com/golang-migrate/migrate
	gorm.io/docs
	bun.uptrace.dev
	redis.uptrace.dev
	mongodb.com/docs/drivers/go
	qdrant.tech/documentation
	docs.temporal.io/dev-guide/go
	opentelemetry.io/docs/languages/go
DDD	dddcommunity.org
CQRS	martinfowler.com/bliki/CQRS.html

crank — Scaffold. Build. Ship.