Docs Boundary Definition
Documentation

Boundary Definition

How to define, enforce, and protect boundaries between Plumego, application logic, and domain code.

Boundary Definition

Boundaries are the most important architectural concept in Plumego.

Plumego itself is not complex.
What becomes complex — and dangerous — is allowing framework concerns to leak into places where they do not belong.

This document explains how to define and protect boundaries in a Plumego-based system.

What Is a Boundary?

A boundary is a point of translation.

At a boundary:

  • One set of concepts ends
  • Another set of concepts begins
  • Data is transformed
  • Responsibility changes hands

In Plumego, the most critical boundary is between:

HTTP / Framework concerns and Application / Domain concerns

The Primary Boundary: Handler → Application

The handler layer is the hard boundary between:

  • Transport-specific concerns (HTTP)
  • Transport-agnostic application logic

This boundary must be explicit and enforced.

Handler side (allowed)

Handlers may deal with:

  • HTTP methods
  • Status codes
  • Headers
  • Query parameters
  • Request bodies
  • *plumego.Context

Application side (forbidden)

Application and domain code must not depend on:

  • *plumego.Context
  • http.Request
  • HTTP status codes
  • Framework-specific helpers

If these appear outside the HTTP layer, the boundary has been violated.

Boundary as a Translation Layer

A good boundary translates, it does not forward blindly.

Instead of:

usecase.Execute(ctx)

Prefer:

input := CreateOrderInput{
	UserID: ctx.UserID(),
	Items:  parseItems(ctx),
}

result, err := usecase.Execute(input)

The boundary performs:

  • Data extraction
  • Validation (where appropriate)
  • Type conversion

This isolates inner layers from transport concerns.

Where Context Must Stop

*plumego.Context must stop at the HTTP boundary.

Passing context inward:

  • Couples domain logic to HTTP
  • Makes testing harder
  • Prevents reuse across transports
  • Leaks framework semantics

Correct usage

  • Extract required values
  • Pass primitive types or domain objects
  • Pass context.Context only if cancellation is required

Even then, prefer passing the embedded standard context, not the Plumego wrapper.

Boundary Between Application and Domain

The next boundary lies between:

  • Application logic (use cases)
  • Domain logic (core rules)

This boundary is more subtle but equally important.

Application layer responsibilities

  • Orchestrate workflows
  • Coordinate multiple domain objects
  • Handle use-case-level rules

Domain layer responsibilities

  • Enforce invariants
  • Model core concepts
  • Remain stable and isolated

The domain layer must not know:

  • Which use case invoked it
  • How the request arrived
  • Which framework is used

Infrastructure Boundaries

Infrastructure sits outside the application core.

This includes:

  • Databases
  • External APIs
  • Message queues
  • Cache systems

Infrastructure should:

  • Implement interfaces defined inward
  • Be replaceable
  • Contain volatile details

Application and domain layers should depend on abstractions, not implementations.

Boundary Enforcement Techniques

Plumego does not enforce boundaries automatically.

Teams must enforce them deliberately.

Common techniques include:

Package boundaries

  • Use internal/ to restrict access
  • Separate HTTP, app, domain, infra packages clearly

Type boundaries

  • Avoid exporting framework-specific types inward
  • Define explicit input/output structs

Review discipline

  • Treat boundary violations as architectural bugs
  • Enforce rules consistently in code review

Boundaries are social contracts as much as technical ones.

Warning Signs of Boundary Erosion

Watch for these red flags:

  • Domain code importing Plumego
  • Use cases returning HTTP status codes
  • Handlers containing business terminology
  • Context passed deep into the call stack
  • Infrastructure driving domain structure

These indicate boundaries are being crossed unintentionally.

Boundaries and Change Tolerance

Well-defined boundaries allow change without collapse.

Examples:

  • Switching from HTTP to RPC
  • Replacing a database
  • Adding a new interface (CLI, worker)
  • Refactoring business rules

Without boundaries, each change ripples unpredictably.

Plumego’s Role in Boundary Definition

Plumego helps by:

  • Keeping the framework surface small
  • Making boundaries visible
  • Avoiding implicit coupling mechanisms

But Plumego will not save you from poor boundary discipline.

That responsibility belongs to the engineering team.

Summary

In a Plumego system:

  • Boundaries define responsibility
  • Translation happens at the edges
  • Framework code stays outside the core
  • Domain logic remains isolated and stable

Strong boundaries are the difference between a system that evolves
and one that collapses under its own weight.

Next

With boundaries defined, the next architectural concern is:

→ Domain and Usecase

This explains how to structure application behavior without coupling it to Plumego.