Beginner

// Zone 1: Domain — zero framework imports allowed
// => directory: purchasing/domain/
// => only stdlib (fmt, errors) and sibling domain types permitted
package domain
 
// PurchaseOrder: pure Go struct — no db tags, no json tags, no framework deps
// => compiles and runs without any external library on the module graph
type PurchaseOrder struct {
    ID         PurchaseOrderID // => strongly-typed identity (format: po_<uuid>)
    SupplierID SupplierID      // => distinct type; cannot swap with PurchaseOrderID accidentally
    Total      Money           // => Money carries both amount and ISO 4217 currency
    Status     POStatus        // => domain string-type enum; no framework dependency
}
 
// Zone 2: Application — imports domain only
// => directory: purchasing/app/
// => may import purchasing/domain; must not import purchasing/adapter or any framework
package app
 
// Zone 3: Adapter — imports application and framework
// => directory: purchasing/adapter/in/http/ or purchasing/adapter/out/mem/
// => may import purchasing/app, github.com/go-chi/chi, etc.
package http

// WRONG: json and db tags leak infrastructure into the domain
// => domain struct now carries serialisation and ORM coupling at the type level
type PurchaseOrder struct {
    ID         string `json:"id" db:"id"`               // => json/db tags: adapter concerns
    SupplierID string `json:"supplier_id" db:"supplier_id"` // => raw string: typed safety lost
    Total      float64 `json:"total_amount" db:"total_amount"` // => loses currency information
    Status     string `json:"status" db:"status"`        // => stringly-typed: compiler cannot validate
}
// Problem: tests must import encoding/json or database/sql to exercise the struct
// => coupling cost: every domain test pulls in serialisation/persistence libraries

// PurchaseOrder: zero framework imports; compiles with only the standard library
// => no json tags, no db tags, no bson tags, no ORM annotations
package domain
 
// PurchaseOrder: aggregate root for the purchasing bounded context
// => struct fields use domain types — not raw primitives
// => all fields exported (uppercase): idiomatic Go; domain is a shared package
type PurchaseOrder struct {
    ID         PurchaseOrderID // => domain value object; not raw string
    SupplierID SupplierID      // => distinct type; prevents id-kind confusion at compile time
    Total      Money           // => Money{Amount, Currency}; richer than float64 alone
    Status     POStatus        // => string-type enum; only valid constants exist
}
 
// Submit: domain behaviour — pure function, no I/O, no framework calls
// => returns a new PurchaseOrder with status transitioned to AwaitingApproval
// => Go pattern: return (value, error) for operations that can fail with a domain rule
func (po PurchaseOrder) Submit() (PurchaseOrder, error) {
    if po.Status != POStatusDraft { // => guard: only DRAFT can be submitted
        return PurchaseOrder{}, ErrInvalidTransition // => domain error; no HTTP status here
        // => caller (application service) maps this to an appropriate response
    }
    po.Status = POStatusAwaitingApproval // => state copy: Go structs are value types by default
    return po, nil                       // => new state returned; original po is unchanged
    // => state transition: DRAFT → AWAITING_APPROVAL
}
// Test: domain.PurchaseOrder{...} — no framework needed; sub-millisecond

// Domain value objects: PurchaseOrderID, SupplierID, and Money
// => package purchasing/domain
package domain
 
import (
    "errors"   // => stdlib: ErrInvalidPurchaseOrderID construction
    "fmt"      // => stdlib: error message formatting
    "strings"  // => stdlib: prefix validation
)
 
// PurchaseOrderID: wraps a string but enforces the "po_<uuid>" format invariant
// => named type (not typedef): distinct from string and from SupplierID at compile time
// => Go does not have constructors; NewPurchaseOrderID is the factory function convention
type PurchaseOrderID string
 
// NewPurchaseOrderID: factory function — validates invariants before returning a value
// => returns (PurchaseOrderID, error): caller must handle the error; no panic on bad input
func NewPurchaseOrderID(value string) (PurchaseOrderID, error) {
    if !strings.HasPrefix(value, "po_") || len(value) < 39 {
        // => format invariant: "po_" prefix + 36-char UUID = minimum 39 chars total
        return "", fmt.Errorf("invalid PurchaseOrderID %q: must start with po_ and be ≥39 chars", value)
        // => zero-value returned on error; caller uses the error, not the returned ID
    }
    return PurchaseOrderID(value), nil // => valid: wrap raw string in the named type
    // => return type is PurchaseOrderID, not string; cannot be accidentally passed where SupplierID expected
}
// => NewPurchaseOrderID("po_550e8400-e29b-41d4-a716-446655440000") → PurchaseOrderID, nil
// => NewPurchaseOrderID("abc") → "", error "must start with po_ ..."
// => NewPurchaseOrderID("") → "", error "must start with po_ ..."
 
// Money: immutable value object combining amount + ISO 4217 currency code
// => struct: two related fields; richer than a bare float64 alone
// => prevents silently mixing USD and EUR — they are the same type, but amount comparison
//    without matching currencies is a domain error caught in domain logic
type Money struct {
    Amount   int64  // => store as minor units (cents); avoids floating-point precision bugs
    Currency string // => ISO 4217 code; e.g. "USD", "IDR", "EUR" — exactly 3 chars
}
 
// NewMoney: validates both fields before returning a Money value
// => returns error on invalid input; no Money with negative amount or wrong currency code
func NewMoney(amount int64, currency string) (Money, error) {
    if amount < 0 {
        // => invariant: negative money has no meaning in a P2P procurement domain
        return Money{}, errors.New("money amount must be >= 0")
        // => caller sees the clear message; construction cannot produce negative Money
    }
    if len(currency) != 3 {
        // => ISO 4217: all currency codes are exactly 3 uppercase letters (USD, EUR, IDR)
        return Money{}, fmt.Errorf("currency %q must be a 3-letter ISO 4217 code", currency)
        // => "US" (2 chars) and "USDD" (4 chars) both fail this guard
    }
    return Money{Amount: amount, Currency: currency}, nil // => valid: both fields pass invariants
    // => Money{Amount: 150000, Currency: "USD"} represents $1500.00 in minor units
}
// => NewMoney(150000, "USD") → Money{150000,"USD"}, nil
// => NewMoney(-1, "USD")    → Money{}, error "must be >= 0"
// => NewMoney(500, "US")    → Money{}, error "must be 3-letter ISO 4217"

// Application zone: may import domain types — inward dependency is always legal
// => file: purchasing/app/service.go
package app
 
import (
    "purchasing/domain" // => ok: inward dependency; app → domain
    // => domain.PurchaseOrder, domain.PurchaseOrderID, domain.Money all available
)
 
// Adapter zone: may import application types — one step further outward
// => file: purchasing/adapter/in/http/handler.go
package http
 
import (
    "purchasing/app" // => ok: inward; adapter → app; adapter never imports domain directly
    // => app.IssuePurchaseOrderUseCase interface available; domain types accessed via app
)

// Domain zone importing Application: FORBIDDEN — never do this
// => file: purchasing/domain/purchase_order.go (hypothetical violation)
package domain
 
// import "purchasing/app" // => NEVER: domain → app creates circular import
// => Go compiler would reject this with "import cycle not allowed"
// => Go's circular import detection is a free enforcement mechanism for hexagonal
 
// Application zone importing Adapter: FORBIDDEN — never do this
// => file: purchasing/app/service.go (hypothetical violation)
package app
 
// import "purchasing/adapter/in/http" // => NEVER: app → adapter is outward
// => application service would depend on chi router; cannot test without HTTP stack
// => Go compiler rejects circular imports; non-circular outward imports must be caught
//    with an architecture linter such as github.com/fdaines/arch-go

// Output port: lives in app package; speaks domain language only
// => file: purchasing/app/ports.go
package app
 
import "purchasing/domain" // => only domain import; no database/sql, no pgx, no framework
 
// PurchaseOrderRepository: output port for PO persistence
// => small interface: 3 methods; Go convention is interfaces ≤5 methods
// => any struct with these methods satisfies this interface — no declaration coupling
type PurchaseOrderRepository interface {
    // Save: persist a PurchaseOrder; return the saved instance
    // => takes domain type; returns domain type; no SQL, no pgx.Rows visible here
    Save(po domain.PurchaseOrder) (domain.PurchaseOrder, error)
    // => caller: repo.Save(po) — does not know if storage is Postgres or in-memory map
 
    // FindByID: retrieve a PurchaseOrder by its typed identity
    // => (domain.PurchaseOrder, bool): Go idiom for "found or not found"; no sentinel nil
    FindByID(id domain.PurchaseOrderID) (domain.PurchaseOrder, bool)
    // => returns (po, true) when found; (zero, false) when not found — caller checks the bool
 
    // ExistsByID: lightweight existence check without loading the full aggregate
    // => useful for duplicate-check guard before saving a new PO
    ExistsByID(id domain.PurchaseOrderID) bool
    // => returns true if PO with given id is present; false otherwise; no aggregate loaded
}
// => application service calls this interface; zero coupling to Postgres or any driver
// => structural typing: InMemoryPurchaseOrderRepository satisfies this without any declaration

// Clock output port: time as an explicit dependency
// => file: purchasing/app/ports.go (alongside PurchaseOrderRepository)
package app
 
import "time" // => stdlib only; no framework import
 
// Clock: output port; returns current time as a stdlib time.Time
// => Adapter in production: returns time.Now() from the system clock
// => Adapter in tests: returns a fixed time.Time — deterministic; no sleep() needed
type Clock interface {
    Now() time.Time
    // => test adapter: type FixedClock struct{ T time.Time }; func (c FixedClock) Now() time.Time { return c.T }
    // => single-method interface: very easy to satisfy with a small struct or function literal
}
 
// Usage inside an application service — clock.Now() instead of time.Now()
// => file: purchasing/app/service.go
type IssuePurchaseOrderService struct {
    repo  PurchaseOrderRepository // => output port; injected at wiring time
    clock Clock                   // => output port; testable time source
    // => both fields are interface types; concrete adapter chosen at composition root
}
 
func (s *IssuePurchaseOrderService) Execute(cmd IssuePOCommand) (domain.PurchaseOrder, error) {
    issuedAt := s.clock.Now() // => explicit; testable; no hidden time.Now() calls
    // => issuedAt: time.Time — embedded in the issued PO or a domain event
    _ = issuedAt              // => used to timestamp the PO in a real implementation
    return domain.PurchaseOrder{}, nil
}

// Input port: use-case interface in the app package
// => file: purchasing/app/ports.go
package app
 
import "purchasing/domain" // => domain types only in the port signature
 
// IssuePOCommand: immutable command carrying everything the use case needs
// => struct with value semantics: passed by copy; no pointer needed for small commands
// => raw strings from the HTTP layer; application service validates and converts them
type IssuePOCommand struct {
    SupplierID    string // => raw string from HTTP body; validated inside the service
    TotalAmount   int64  // => minor units (cents) from the JSON payload
    TotalCurrency string // => ISO 4217 code; service validates 3-letter rule
}
 
// IssuePurchaseOrderUseCase: input port; defines the use-case contract
// => HTTP handler calls this interface; never the concrete IssuePurchaseOrderService struct
// => Go structural typing: handler couples to the interface, not the implementation
type IssuePurchaseOrderUseCase interface {
    // Execute: the single method of this use case
    // => takes a command (inbound DTO); returns the resulting domain object or an error
    Execute(cmd IssuePOCommand) (domain.PurchaseOrder, error)
    // => domain error returned to adapter; adapter maps it to HTTP 422 or 400
}
// => any struct with Execute(IssuePOCommand)(domain.PurchaseOrder, error) satisfies this
// => test double: type FakeUseCase struct{}; func (f FakeUseCase) Execute(...) — 2 lines

// Go structural typing: no implements keyword needed
// => file: purchasing/adapter/out/mem/repo.go
package mem
 
import (
    "sync"               // => stdlib: mutex for concurrent access
    "purchasing/app"     // => import app package for the port interface
    "purchasing/domain"  // => import domain package for entity types
)
 
// InMemoryPurchaseOrderRepository: satisfies app.PurchaseOrderRepository implicitly
// => Go compiler checks at compile time that this struct has the required methods
// => zero declaration coupling: no "implements PurchaseOrderRepository" anywhere
type InMemoryPurchaseOrderRepository struct {
    mu    sync.RWMutex                            // => mutex: safe concurrent reads and writes
    store map[domain.PurchaseOrderID]domain.PurchaseOrder // => backing store: pure in-memory map
}
 
// NewInMemoryPurchaseOrderRepository: constructor function — idiomatic Go pattern
func NewInMemoryPurchaseOrderRepository() *InMemoryPurchaseOrderRepository {
    return &InMemoryPurchaseOrderRepository{
        store: make(map[domain.PurchaseOrderID]domain.PurchaseOrder), // => empty map initialised
        // => make() required: nil map causes panic on write; must initialise before use
    }
}
 
// Save: satisfies PurchaseOrderRepository.Save — method signature must match exactly
func (r *InMemoryPurchaseOrderRepository) Save(po domain.PurchaseOrder) (domain.PurchaseOrder, error) {
    r.mu.Lock()               // => exclusive lock: prevents concurrent write conflicts
    defer r.mu.Unlock()       // => deferred unlock: released when function returns; cannot forget
    r.store[po.ID] = po       // => key = typed PurchaseOrderID; value = PurchaseOrder struct copy
    return po, nil            // => return the saved instance; nil error means success
    // => structural typing: this method makes the struct satisfy PurchaseOrderRepository.Save
}
 
// FindByID: satisfies PurchaseOrderRepository.FindByID
func (r *InMemoryPurchaseOrderRepository) FindByID(id domain.PurchaseOrderID) (domain.PurchaseOrder, bool) {
    r.mu.RLock()              // => shared read lock: multiple concurrent reads allowed
    defer r.mu.RUnlock()      // => deferred unlock: released at function return
    po, ok := r.store[id]     // => map lookup: ok = true if found; ok = false if absent
    return po, ok             // => (zero PurchaseOrder, false) when not found; no nil pointer
    // => (domain.PurchaseOrder, bool) idiom: avoids nil-pointer dereference bugs
}
 
// ExistsByID: satisfies PurchaseOrderRepository.ExistsByID
func (r *InMemoryPurchaseOrderRepository) ExistsByID(id domain.PurchaseOrderID) bool {
    r.mu.RLock()              // => shared read lock: safe for concurrent existence checks
    defer r.mu.RUnlock()
    _, ok := r.store[id]      // => blank identifier: discard the value; only need the bool
    return ok                 // => true = found; false = not found; O(1) hash map lookup
}
 
// Compile-time interface satisfaction check (Go idiom)
// => var _ app.PurchaseOrderRepository = (*InMemoryPurchaseOrderRepository)(nil)
// => this line causes a compile error if the struct no longer satisfies the interface
// => zero-cost: nil pointer cast; never executed at runtime
var _ app.PurchaseOrderRepository = (*InMemoryPurchaseOrderRepository)(nil)

// POStatus: string-type enum in Go
// => file: purchasing/domain/po_status.go
package domain
 
// POStatus: named string type — distinct from plain string at compile time
// => prevents passing an arbitrary string where a status is expected
type POStatus string
 
// Package-level constants: the only valid POStatus values
// => const block: idiomatic for a set of related named constants
const (
    POStatusDraft              POStatus = "DRAFT"
    // => initial state when PO is first created in the system
    POStatusAwaitingApproval   POStatus = "AWAITING_APPROVAL"
    // => PO submitted by requester; waiting for approver sign-off
    POStatusApproved           POStatus = "APPROVED"
    // => approver confirmed the PO; next step is issuing to supplier
    POStatusIssued             POStatus = "ISSUED"
    // => PO sent to the supplier; awaiting goods receipt
    POStatusCancelled          POStatus = "CANCELLED"
    // => PO cancelled before goods receipt; terminal state
)
 
// IsValid: helper to check if a deserialized status string is a known value
// => useful at the adapter boundary when loading from database or HTTP body
func (s POStatus) IsValid() bool {
    switch s {
    case POStatusDraft, POStatusAwaitingApproval, POStatusApproved, POStatusIssued, POStatusCancelled:
        return true  // => all known values return true
    default:
        return false // => unknown value: reject at the adapter layer before entering domain
    }
}
// => POStatus("DRAFT").IsValid() → true
// => POStatus("GARBAGE").IsValid() → false
// => Go's type system prevents: var s POStatus = "anything" — but const values are type-checked

// PurchaseOrder: aggregate root with domain behaviour
// => file: purchasing/domain/purchase_order.go
package domain
 
import "errors"
 
// ErrInvalidTransition: domain error for illegal state transitions
// => sentinel error: compare with errors.Is(); no framework dependency
var ErrInvalidTransition = errors.New("invalid purchase order state transition")
 
// PurchaseOrder: aggregate root struct — no framework tags
type PurchaseOrder struct {
    ID         PurchaseOrderID // => typed identity; format: po_<uuid>
    SupplierID SupplierID      // => typed supplier reference; format: sup_<uuid>
    Total      Money           // => minor-unit amount + 3-letter currency code
    Status     POStatus        // => lifecycle state; only valid constants
}
 
// Submit: domain behaviour — pure transition from DRAFT to AWAITING_APPROVAL
// => value receiver: Go struct is copied; original po is never mutated
// => returns (PurchaseOrder, error): either the new state or a domain error
func (po PurchaseOrder) Submit() (PurchaseOrder, error) {
    if po.Status != POStatusDraft {
        // => guard: only DRAFT POs can be submitted; any other status is a domain violation
        return PurchaseOrder{}, ErrInvalidTransition
        // => zero value returned with error; caller must check error before using the result
    }
    po.Status = POStatusAwaitingApproval // => struct copy modified: original po is unchanged
    // => Go value semantics: modifying po on the copy does not affect the caller's variable
    return po, nil // => return the new state; nil error signals success
    // => state transition: DRAFT → AWAITING_APPROVAL; no I/O; sub-microsecond
}
 
// Approve: domain behaviour — transition from AWAITING_APPROVAL to APPROVED
// => same pattern: value receiver, copy-and-modify, return new state or error
func (po PurchaseOrder) Approve() (PurchaseOrder, error) {
    if po.Status != POStatusAwaitingApproval {
        return PurchaseOrder{}, ErrInvalidTransition // => domain rule: only awaiting POs can be approved
    }
    po.Status = POStatusApproved // => copy modified; original unchanged
    return po, nil               // => state transition: AWAITING_APPROVAL → APPROVED
}
// Test: po := domain.PurchaseOrder{..., Status: POStatusDraft}; submitted, err := po.Submit()
// => no framework; no DB; sub-millisecond; pure function

// SupplierID: distinct named type from PurchaseOrderID
// => file: purchasing/domain/supplier_id.go
package domain
 
import (
    "fmt"     // => stdlib: error formatting
    "strings" // => stdlib: prefix validation
)
 
// SupplierID: named string type — distinct from PurchaseOrderID at compile time
// => Go's type system: SupplierID("x") != PurchaseOrderID("x") as distinct types
type SupplierID string
 
// NewSupplierID: factory function — validates the "sup_<uuid>" format invariant
func NewSupplierID(value string) (SupplierID, error) {
    if !strings.HasPrefix(value, "sup_") || len(value) < 40 {
        // => format invariant: "sup_" prefix (4 chars) + 36-char UUID = minimum 40 chars
        return "", fmt.Errorf("invalid SupplierID %q: must start with sup_ and be ≥40 chars", value)
        // => zero-value string returned with error; caller must not use the returned ID on error
    }
    return SupplierID(value), nil // => valid: wrap raw string in the named type
    // => returned type is SupplierID; compiler prevents passing it where PurchaseOrderID expected
}
 
// ExampleUsage demonstrates the type safety at compile time
// => func example() {
//     poID, _ := NewPurchaseOrderID("po_550e8400-e29b-41d4-a716-446655440000")
//     supID, _ := NewSupplierID("sup_660f9511-f3ac-52e5-b827-557766551111")
//     po := PurchaseOrder{ID: poID, SupplierID: supID, ...} // => correct: distinct types
//     _ = PurchaseOrder{ID: supID, ...} // => compile error: cannot use SupplierID as PurchaseOrderID
// }
// => Go type checker catches the swap at compile time; no test needed for this class of bug

// Dependency rule test: verify package import directions in CI
// => file: purchasing/arch_test.go
// => uses only stdlib: os/exec, testing, strings — no external analysis library needed
package purchasing_test
 
import (
    "os/exec"   // => stdlib: run go list to enumerate package imports
    "strings"   // => stdlib: string parsing of go list output
    "testing"   // => stdlib: Go test framework
)
 
// TestDomainMustNotImportApp: domain must not import application zone
func TestDomainMustNotImportApp(t *testing.T) {
    // go list -f {{.Imports}} ./purchasing/domain/...
    // => lists all direct imports of every package under purchasing/domain
    cmd := exec.Command("go", "list", "-f", "{{.Imports}}", "./purchasing/domain/...")
    out, err := cmd.Output()
    if err != nil {
        t.Fatalf("go list failed: %v", err)
        // => test infrastructure failure; investigate go module setup
    }
    if strings.Contains(string(out), "purchasing/app") {
        // => violation: domain package imports app package; outward dependency
        t.Error("domain must not import app; dependency rule violation detected")
        // => CI build fails; developer sees the violation immediately
    }
    // => ok: domain only imports purchasing/domain sibling packages and stdlib
}
 
// TestAppMustNotImportAdapter: application must not import adapter zone
func TestAppMustNotImportAdapter(t *testing.T) {
    cmd := exec.Command("go", "list", "-f", "{{.Imports}}", "./purchasing/app/...")
    out, err := cmd.Output()
    if err != nil {
        t.Fatalf("go list failed: %v", err)
    }
    if strings.Contains(string(out), "purchasing/adapter") {
        // => violation: app imports adapter; framework leaks into orchestration layer
        t.Error("app must not import adapter; dependency rule violation detected")
        // => CI build fails; violation caught before code review
    }
    // => ok: app only imports purchasing/domain and stdlib
}
// => both tests run in < 200ms; zero external deps; pure stdlib

// In-memory adapter: complete implementation of PurchaseOrderRepository
// => file: purchasing/adapter/out/mem/repo.go
package mem
 
import (
    "sync"               // => stdlib: RWMutex for concurrent-safe operations
    "purchasing/app"     // => import app package: the port interface lives here
    "purchasing/domain"  // => import domain package: entity and value object types
)
 
// InMemoryPurchaseOrderRepository: adapter implementing app.PurchaseOrderRepository
// => backing store: map[domain.PurchaseOrderID]domain.PurchaseOrder
// => exported struct: usable from any package that needs a test adapter
type InMemoryPurchaseOrderRepository struct {
    mu    sync.RWMutex                                      // => protects concurrent map access
    store map[domain.PurchaseOrderID]domain.PurchaseOrder   // => backing store; nil until make()
}
 
// NewInMemoryPurchaseOrderRepository: returns an initialised adapter ready to use
func NewInMemoryPurchaseOrderRepository() *InMemoryPurchaseOrderRepository {
    return &InMemoryPurchaseOrderRepository{
        store: make(map[domain.PurchaseOrderID]domain.PurchaseOrder),
        // => make(): allocates the underlying hash map; must be called before any write
    }
}
 
// Save: store a PurchaseOrder; return the same instance plus nil error
func (r *InMemoryPurchaseOrderRepository) Save(po domain.PurchaseOrder) (domain.PurchaseOrder, error) {
    r.mu.Lock()         // => exclusive lock: prevents concurrent write + read races
    defer r.mu.Unlock() // => deferred: always released even if a panic occurs
    r.store[po.ID] = po // => key = PurchaseOrderID (typed); value = PurchaseOrder (struct copy)
    // => Go map stores value copy: caller's po and stored po are independent after this line
    return po, nil      // => return the same instance; nil error = success
}
 
// FindByID: look up a PurchaseOrder by its typed ID
func (r *InMemoryPurchaseOrderRepository) FindByID(id domain.PurchaseOrderID) (domain.PurchaseOrder, bool) {
    r.mu.RLock()              // => shared read lock: multiple goroutines can read concurrently
    defer r.mu.RUnlock()      // => deferred release
    po, ok := r.store[id]     // => map lookup: ok = true if key found; ok = false if absent
    return po, ok             // => (zero-value PurchaseOrder, false) when not found — no nil
}
 
// ExistsByID: lightweight check without loading the full aggregate
func (r *InMemoryPurchaseOrderRepository) ExistsByID(id domain.PurchaseOrderID) bool {
    r.mu.RLock()
    defer r.mu.RUnlock()
    _, ok := r.store[id] // => blank identifier: discard value; only need the boolean
    return ok            // => O(1) hash lookup
}
 
// compile-time interface check: fails to compile if method signatures diverge from the port
var _ app.PurchaseOrderRepository = (*InMemoryPurchaseOrderRepository)(nil)
// => this single line ensures the struct stays compatible with the port interface
// => zero runtime cost: nil pointer cast; never executed

// FixedClock: in-memory adapter implementing app.Clock
// => file: purchasing/adapter/out/mem/clock.go
package mem
 
import (
    "time"           // => stdlib: time.Time type
    "purchasing/app" // => import app package for the Clock interface
)
 
// FixedClock: deterministic clock adapter for tests
// => returns the same time on every call; no wall-clock dependency
type FixedClock struct {
    T time.Time // => exported field: caller sets the desired test timestamp
    // => example: mem.FixedClock{T: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
}
 
// Now: satisfies app.Clock interface; returns the fixed timestamp
func (c FixedClock) Now() time.Time {
    return c.T // => always returns c.T; deterministic; no system clock call
    // => test: two consecutive Now() calls return the same value — no flakiness
}
 
// SystemClock: production adapter returning real time
// => trivial implementation; included here as a direct contrast to FixedClock
type SystemClock struct{} // => zero-value struct: no fields needed
 
// Now: satisfies app.Clock interface; returns the current wall-clock time
func (c SystemClock) Now() time.Time {
    return time.Now() // => stdlib: real wall-clock time; used only at the composition root
    // => never used in unit tests; FixedClock replaces it at wiring time
}
 
// compile-time checks: both adapters must satisfy the Clock interface
var _ app.Clock = FixedClock{}   // => fails to compile if FixedClock diverges from the interface
var _ app.Clock = SystemClock{}  // => fails to compile if SystemClock diverges from the interface
// => zero runtime cost; enforced at every compile

// Unit test: wire service with in-memory adapters; no infrastructure needed
// => file: purchasing/app/service_test.go
package app_test
 
import (
    "testing"       // => stdlib: Go test framework
    "time"          // => stdlib: time.Time for FixedClock
    "purchasing/app" // => application package: service constructor and types
    "purchasing/adapter/out/mem" // => in-memory adapters
    "purchasing/domain"          // => domain types for assertions
)
 
func TestIssuePurchaseOrderService_Execute_Success(t *testing.T) {
    // Arrange: wire the service with in-memory adapters — no framework, no containers
    repo := mem.NewInMemoryPurchaseOrderRepository()
    // => repo: *mem.InMemoryPurchaseOrderRepository — satisfies app.PurchaseOrderRepository
    clock := mem.FixedClock{T: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
    // => clock: mem.FixedClock — satisfies app.Clock; always returns 2026-01-01T00:00:00Z
 
    svc := app.NewIssuePurchaseOrderService(repo, clock)
    // => svc: *app.IssuePurchaseOrderService — wired with in-memory adapters
 
    cmd := app.IssuePOCommand{
        SupplierID:    "sup_660f9511-f3ac-52e5-b827-557766551111",
        TotalAmount:   150000, // => $1500.00 in minor units (cents)
        TotalCurrency: "USD",  // => ISO 4217 code; service validates 3-letter rule
    }
 
    // Act: call the use case
    po, err := svc.Execute(cmd)
    // => Execute: creates PO, runs Submit() domain transition, saves via repo
    if err != nil {
        t.Fatalf("expected no error, got: %v", err) // => test fails with the error message
        // => if this fires, check domain rule guards in domain.PurchaseOrder.Submit()
    }
 
    // Assert: verify domain result
    if po.Status != domain.POStatusAwaitingApproval {
        t.Errorf("expected AWAITING_APPROVAL, got %q", po.Status)
        // => state transition must be DRAFT → AWAITING_APPROVAL via Submit()
    }
    if po.Total.Currency != "USD" {
        t.Errorf("expected USD, got %q", po.Total.Currency)
        // => Money.Currency must be preserved through the service call
    }
 
    // Assert: PO saved to in-memory repo
    saved, ok := repo.FindByID(po.ID)
    if !ok {
        t.Error("expected PO to be persisted in the repository")
        // => service must call repo.Save(); if not, the port was not called
    }
    if saved.ID != po.ID {
        t.Errorf("saved PO ID %q does not match returned ID %q", saved.ID, po.ID)
    }
    // => full use-case test; zero infrastructure; runs in < 1ms
}

// Comparing in-memory adapter vs mock framework in Go
// => Go has no built-in mock framework; the community uses testify/mock or gomock
// => with hexagonal ports, neither is needed for the common test case
 
// APPROACH 1: mock framework (testify/mock) — more code, less readable
// type MockPurchaseOrderRepository struct {
//     mock.Mock
// }
// func (m *MockPurchaseOrderRepository) Save(po domain.PurchaseOrder) (domain.PurchaseOrder, error) {
//     args := m.Called(po)
//     return args.Get(0).(domain.PurchaseOrder), args.Error(1)
// }
// func (m *MockPurchaseOrderRepository) FindByID(...) ... { ... } // 5+ more lines
// func (m *MockPurchaseOrderRepository) ExistsByID(...) ... { ... }
// => total: 15+ lines; requires testify import; type assertions; mock.Called boilerplate
 
// APPROACH 2: in-memory adapter (preferred) — less code, fully type-safe
// repo := mem.NewInMemoryPurchaseOrderRepository()
// => 1 line; no import beyond the mem package; fully type-checked; no assertion magic
 
// APPROACH 3: hand-rolled stub for a specific test — when only one method matters
// => type stubbedRepo struct{ saved domain.PurchaseOrder }
type stubbedRepo struct {
    saved domain.PurchaseOrder // => captures what was saved for assertion
    // => zero-value bool findOK defaults to false; adjust per test need
}
 
func (s *stubbedRepo) Save(po domain.PurchaseOrder) (domain.PurchaseOrder, error) {
    s.saved = po // => capture the saved PO for assertion in the test body
    return po, nil
    // => minimal implementation: only the method under test does anything meaningful
}
 
func (s *stubbedRepo) FindByID(id domain.PurchaseOrderID) (domain.PurchaseOrder, bool) {
    return domain.PurchaseOrder{}, false // => stub returns zero; test does not exercise this
    // => for tests that only exercise Save, FindByID can return zero without consequence
}
 
func (s *stubbedRepo) ExistsByID(id domain.PurchaseOrderID) bool {
    return false // => stub returns false; test does not exercise this method
    // => three-method interface: all three must be present for structural satisfaction
}
 
// var _ app.PurchaseOrderRepository = (*stubbedRepo)(nil) — compile-time check
var _ app.PurchaseOrderRepository = (*stubbedRepo)(nil)
// => ensures stubbedRepo satisfies the interface; compile error if a method signature changes

// Composition root: main.go wires concrete adapters into the application service
// => file: cmd/server/main.go
package main
 
import (
    "log"                           // => stdlib: structured log output for startup messages
    "purchasing/app"                // => application layer: service constructor + use-case interface
    "purchasing/adapter/in/http"    // => HTTP primary adapter: chi handler
    "purchasing/adapter/out/mem"    // => in-memory secondary adapter: repository + clock
)
 
func main() {
    // Step 1: create secondary (output) adapters
    repo := mem.NewInMemoryPurchaseOrderRepository()
    // => repo: *mem.InMemoryPurchaseOrderRepository — satisfies app.PurchaseOrderRepository
    clock := mem.SystemClock{} // => real wall-clock; switch to FixedClock for test builds
    // => clock: mem.SystemClock — satisfies app.Clock; returns time.Now() in production
 
    // Step 2: create the application service with injected adapters
    svc := app.NewIssuePurchaseOrderService(repo, clock)
    // => svc: *app.IssuePurchaseOrderService — all dependencies resolved; ready to handle commands
    // => Go constructor: explicit, no reflection, no DI container required
 
    // Step 3: create primary (input) adapter wired to the use-case interface
    handler := http.NewPurchaseOrderHandler(svc)
    // => handler: *http.PurchaseOrderHandler — depends on app.IssuePurchaseOrderUseCase interface
    // => handler never imports the mem package; it only calls the interface
 
    // Step 4: start the HTTP server
    router := handler.Router() // => chi.Router: registers routes on the handler
    log.Println("starting procurement server on :8080")
    if err := http.ListenAndServe(":8080", router); err != nil {
        log.Fatalf("server error: %v", err) // => fatal: log the error and exit with code 1
    }
    // => only main.go imports both app and adapter packages simultaneously
    // => all other packages import at most one zone inward of themselves
}

// Environment-based adapter selection in the composition root
// => file: cmd/server/main.go (excerpt showing adapter selection logic)
package main
 
import (
    "log"     // => stdlib: log.Printf for startup messages
    "os"      // => stdlib: os.Getenv to read environment variables
    "purchasing/app"             // => application layer
    "purchasing/adapter/out/mem" // => in-memory adapter
    // "purchasing/adapter/out/pg"  // => Postgres adapter (imported when needed)
)
 
func buildRepository() app.PurchaseOrderRepository {
    // USE_IN_MEMORY_REPO: environment variable controlling adapter selection
    // => "true" = in-memory (development, CI tests without Docker)
    // => anything else (or unset) = Postgres (staging, production)
    if os.Getenv("USE_IN_MEMORY_REPO") == "true" {
        log.Println("using in-memory repository (no Postgres required)")
        return mem.NewInMemoryPurchaseOrderRepository()
        // => returns *mem.InMemoryPurchaseOrderRepository via the interface
        // => application service receives app.PurchaseOrderRepository; never sees this type
    }
    // In a real app: read DSN from environment; open pg connection; return pg adapter
    // => return pg.NewPurchaseOrderRepository(db)
    // => for this beginner example, fall back to in-memory to keep it self-contained
    log.Println("defaulting to in-memory repository for this example")
    return mem.NewInMemoryPurchaseOrderRepository()
    // => production: replace with pg adapter; service and tests are unchanged
}
 
func buildClock() app.Clock {
    if os.Getenv("FIXED_CLOCK_TIME") != "" {
        // => parse the fixed time and return a FixedClock for deterministic local testing
        // => production CI: never set FIXED_CLOCK_TIME; SystemClock is always used in prod
        log.Println("using fixed clock for deterministic local testing")
        return mem.FixedClock{} // => simplified; real code parses the env var to time.Time
    }
    return mem.SystemClock{} // => production: real wall-clock time
    // => application service receives app.Clock; never knows which adapter is running
}

// HTTP primary adapter: chi router handler
// => file: purchasing/adapter/in/http/handler.go
package http
 
import (
    "encoding/json"  // => stdlib: JSON decode/encode for request and response bodies
    "net/http"       // => stdlib: http.ResponseWriter, *http.Request, http.StatusCreated
    "github.com/go-chi/chi/v5" // => chi: lightweight HTTP router; adapter-layer import only
    "purchasing/app"            // => app package: IssuePurchaseOrderUseCase interface + command
    "purchasing/domain"         // => domain: error types for error mapping
)
 
// CreatePORequest: inbound DTO — adapter-layer struct; never enters the domain
// => json tags here, not in the domain struct; adapter concern
type CreatePORequest struct {
    SupplierID    string `json:"supplier_id"`    // => raw string from JSON body
    TotalAmount   int64  `json:"total_amount"`   // => minor units (cents) from JSON
    TotalCurrency string `json:"total_currency"` // => ISO 4217 code from JSON
}
 
// CreatePOResponse: outbound DTO — adapter-layer struct; built from domain types
// => json tags here; domain struct never carries json tags
type CreatePOResponse struct {
    ID         string `json:"id"`          // => po.ID: typed → raw string for JSON
    SupplierID string `json:"supplier_id"` // => po.SupplierID: typed → raw string
    Status     string `json:"status"`      // => po.Status: POStatus → string for JSON
}
 
// PurchaseOrderHandler: primary adapter containing the chi handler methods
type PurchaseOrderHandler struct {
    useCase app.IssuePurchaseOrderUseCase // => interface; never the concrete service struct
    // => depends on interface: handler tests only need a stub, not the full service
}
 
// NewPurchaseOrderHandler: constructor; injects use-case interface
func NewPurchaseOrderHandler(useCase app.IssuePurchaseOrderUseCase) *PurchaseOrderHandler {
    return &PurchaseOrderHandler{useCase: useCase}
    // => explicit injection: useCase is set here; adapter cannot create its own service
}
 
// Router: registers routes and returns a chi.Router for use in the composition root
func (h *PurchaseOrderHandler) Router() chi.Router {
    r := chi.NewRouter() // => chi.NewRouter(): creates a new mux; adapter-layer only
    r.Post("/api/v1/purchase-orders", h.create)
    // => POST /api/v1/purchase-orders → h.create handler
    return r
}
 
// create: handles POST /api/v1/purchase-orders
func (h *PurchaseOrderHandler) create(w http.ResponseWriter, r *http.Request) {
    // Step 1: deserialise request body
    var req CreatePORequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "invalid JSON body", http.StatusBadRequest) // => HTTP 400
        return // => return early; do not call the use case with invalid input
    }
 
    // Step 2: translate HTTP DTO → application command (no business logic)
    cmd := app.IssuePOCommand{
        SupplierID:    req.SupplierID,    // => pass raw string; service validates
        TotalAmount:   req.TotalAmount,   // => pass int64 minor units; service validates
        TotalCurrency: req.TotalCurrency, // => pass 3-letter code; service validates
    }
 
    // Step 3: delegate to use case — all business logic lives in the service
    po, err := h.useCase.Execute(cmd)
    if err != nil {
        // => map domain errors to appropriate HTTP status codes
        if err == domain.ErrInvalidTransition {
            http.Error(w, err.Error(), http.StatusUnprocessableEntity) // => HTTP 422
        } else {
            http.Error(w, "internal error", http.StatusInternalServerError) // => HTTP 500
        }
        return
    }
 
    // Step 4: translate domain result → HTTP response DTO
    resp := CreatePOResponse{
        ID:         string(po.ID),         // => typed PurchaseOrderID → raw string for JSON
        SupplierID: string(po.SupplierID), // => typed SupplierID → raw string for JSON
        Status:     string(po.Status),     // => POStatus string-type → string for JSON
    }
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated) // => HTTP 201 Created
    json.NewEncoder(w).Encode(resp)   // => serialise response DTO; adapter concern only
}

// Complete request/response flow through all three hexagonal zones
// => this is a narrative trace; not a runnable standalone file
// => each comment block corresponds to one zone crossing
 
// ─── ZONE 3: Adapter/in (HTTP) ─────────────────────────────────────────────
// Incoming: POST /api/v1/purchase-orders
// Body: {"supplier_id":"550e8400","total_amount":150000,"total_currency":"USD"}
// => http.Request arrives at PurchaseOrderHandler.create()
 
// json.NewDecoder(r.Body).Decode(&req)
// => CreatePORequest{SupplierID:"550e8400", TotalAmount:150000, TotalCurrency:"USD"}
// => raw HTTP payload; no domain types yet; adapter-layer struct only
 
// cmd := app.IssuePOCommand{SupplierID: req.SupplierID, ...}
// => boundary crossing 1: HTTP DTO → application command
// => crossing point: handler translates HTTP concerns into application language
 
// ─── ZONE 2: Application ───────────────────────────────────────────────────
// IssuePurchaseOrderService.Execute(cmd) receives the command
// => all business orchestration happens here; no HTTP types visible
 
// id, _ := domain.NewPurchaseOrderID("po_" + uuid.New().String())
// => PurchaseOrderID: typed; format "po_<uuid>" validated by factory function
// total, _ := domain.NewMoney(cmd.TotalAmount, cmd.TotalCurrency)
// => Money: typed; Amount + Currency; invariants validated at construction
 
// po := domain.PurchaseOrder{ID: id, SupplierID: supplierID, Total: total, Status: domain.POStatusDraft}
// => boundary crossing 2: command fields → typed domain value objects
// => domain entity constructed in DRAFT state; application service orchestrates
 
// ─── ZONE 1: Domain ────────────────────────────────────────────────────────
// submitted, _ := po.Submit()
// => pure function: validates po.Status == POStatusDraft; returns new PO with AWAITING_APPROVAL
// => no I/O; no network; sub-microsecond; only domain rules applied
 
// ─── ZONE 2: Application (back) ────────────────────────────────────────────
// saved, _ := s.repo.Save(submitted)
// => boundary crossing 3: application service calls output port
// => port interface: app.PurchaseOrderRepository.Save(); adapter chosen at composition root
 
// ─── ZONE 3: Adapter/out (persistence) ────────────────────────────────────
// InMemoryPurchaseOrderRepository.Save(submitted)
// => r.store[submitted.ID] = submitted — in-memory map write; no SQL; no network
// => returns submitted, nil — domain object back to application service
 
// ─── ZONE 2: Application (return) ─────────────────────────────────────────
// return saved, nil — domain PurchaseOrder returned to the HTTP handler
 
// ─── ZONE 3: Adapter/in (HTTP) — response ─────────────────────────────────
// resp := CreatePOResponse{ID: string(po.ID), ...}
// => boundary crossing 4: domain entity → HTTP response DTO
// => typed PurchaseOrderID → raw string for JSON; domain concern ends here
 
// json.NewEncoder(w).Encode(resp)
// w.WriteHeader(http.StatusCreated)
// Response: HTTP 201 {"id":"po_<uuid>","supplier_id":"550e8400","status":"AWAITING_APPROVAL"}
// => four boundary crossings; each crossing is a deliberate translation
// => domain was never touched by HTTP; adapter was never touched by domain rules