Architectures

An architecture defines your project’s structure, dependency rules, and base files.

Hexagonal (Ports & Adapters)

The hexagonal architecture separates your application into layers with strict dependency direction — inner layers never import from outer layers.

domain/              → Pure business logic, no external dependencies
port/                → Interfaces (inbound use cases, outbound repositories)
service/             → Use case implementations
adapter/             → External integrations (HTTP, DB, messaging)
config/              → Configuration loading (via platform capability)
platform/            → Cross-cutting concerns (via platform capability)
internal/bootstrap/  → Dependency wiring (via bootstrap capability)
cmd/<name>/          → Entry point

Dependency Rules

Component	May Depend On
domain	nothing
ports	domain
service	domain, ports
adapters	ports, domain

These rules are enforced by verikt check. If your adapter code imports from another adapter, or your domain imports from service — it’s caught immediately.

Note

TypeScript hexagonal uses src/domain/, src/application/, src/infrastructure/, src/transport/ — same boundaries, TypeScript conventions.

Tip

Every scaffolded project includes an verikt.yaml with these rules defined. You can customize the rules, add required directories, or set function complexity limits.

When to Use

Use hexagonal for production APIs and microservices where business logic is complex and you need strict separation of concerns. It’s especially valuable when multiple teams contribute to the same service — the enforced boundaries prevent the accidental coupling that tends to accumulate in flat or layered structures.

Flat

A single-package structure with just main.go and go.mod.

main.go
go.mod

When to Use

Use flat for CLI tools, simple scripts, and quick prototypes where layered structure would add friction without adding value.

Note

You can still add capabilities to a flat architecture (e.g., http-api for a simple API server), but the project won’t have the layered structure of other architectures.

Layered

The most common architecture pattern — handler, service, and repository layers with a shared model package.

cmd/<name>/             → Entry point
internal/handler/       → HTTP handlers (request/response)
internal/service/       → Business logic
internal/repository/    → Data access
internal/model/         → Shared types and domain models

Dependency Rules

Component	May Depend On
model	nothing
repository	model
service	repository, model
handler	service, model

When to Use

Use layered when hexagonal feels like overkill — standard CRUD APIs with straightforward business logic, or teams already fluent in the traditional three-tier pattern who don’t need the port/adapter indirection.

Clean Architecture

Uncle Bob’s Clean Architecture — entities at the core, use cases orchestrate, interfaces adapt.

cmd/<name>/                  → Entry point
internal/entity/             → Core business entities (no dependencies)
internal/usecase/            → Application use cases
internal/interface/handler/  → HTTP handlers, adapters
internal/infrastructure/     → Database, external services, config

Dependency Rules

Component	May Depend On
entity	nothing
usecase	entity
interface	usecase, entity
infrastructure	interface, usecase, entity

When to Use

Use clean architecture when use cases are the central organizing concept and dependency discipline matters at scale. It’s a good fit for teams already fluent in Uncle Bob’s conventions, or large codebases where strict layering pays for itself.

Tip

All four architectures work with any capability. The architecture defines where code goes; capabilities define what code gets generated. To monitor whether your codebase stays true to its declared architecture, see Detecting Architecture Drift.