Docs Patterns

Patterns

The Patterns section captures repeatable, experience-backed ways of working with Plumego.

If Concepts explain how Plumego works,
and Architecture explains how systems should be shaped,

then Patterns explain how teams should actually write code day to day.

These are not theoretical patterns.
They are practical constraints designed to prevent slow architectural decay.

What Patterns Are For

Patterns exist to solve a specific problem:

Good architecture decisions tend to erode under day-to-day delivery pressure.

Patterns help by:

  • Making “the right way” concrete
  • Reducing ambiguity in reviews
  • Preventing accidental framework leakage
  • Keeping systems readable as they grow

They are guardrails, not rules engines.

What Patterns Are Not

Patterns are not:

  • Mandatory framework features
  • One-size-fits-all prescriptions
  • Clever abstractions
  • Library-specific tricks

If a pattern feels heavy or unnecessary,
it is probably being applied too early.

How to Use This Section

Patterns are meant to be:

  • Read selectively
  • Applied intentionally
  • Enforced socially (via reviews and conventions)

You do not need every pattern in every project.

Introduce patterns only when the corresponding problem actually appears.

Pattern Categories

The patterns in this section generally fall into three categories:

1. Boundary Protection Patterns

Patterns that protect architectural boundaries and prevent framework creep.

Examples:

  • Thin Handlers
  • Explicit Middleware Chains
  • Boundary Translation

2. Control & Flow Patterns

Patterns that make execution order, responsibility, and side effects visible.

Examples:

  • Explicit Error Mapping
  • Centralized Decision Points
  • No Hidden Control Flow

3. Operational Safety Patterns

Patterns that improve reliability and operability without adding magic.

Examples:

  • Request-Scoped Metadata
  • Fail-Fast Boundaries
  • Defensive Integration Patterns

If you are new to the Patterns section, start here:

  1. Thin Handlers
    Establishes the most important boundary discipline.

  2. Explicit Middleware Chains
    Prevents hidden behavior and ordering bugs.

  3. Explicit Error Mapping
    Keeps failure semantics understandable.

  4. Boundary Translation
    Reinforces separation between transport and core logic.

Each pattern builds on the previous ones.

Patterns and Team Discipline

Patterns are only effective if:

  • Teams agree to follow them
  • Violations are discussed explicitly
  • Exceptions are documented intentionally

Patterns do not replace thinking.
They reduce the cost of thinking repeatedly about the same problems.

When Patterns Matter Most

Pay close attention to this section if:

  • Your codebase is growing quickly
  • Multiple engineers are contributing
  • Review discussions repeat the same concerns
  • Handlers and middleware are getting larger
  • Framework concepts start leaking inward

Patterns act as early-warning systems.

Summary

The Patterns section exists to:

  • Encode hard-earned lessons
  • Preserve architectural clarity
  • Make good practices repeatable
  • Slow down long-term decay

Plumego gives you freedom.
Patterns help you use that freedom responsibly.

Next

If you are just starting with Patterns:

→ Thin Handlers

If you already apply that discipline:

→ Explicit Middleware Chains

Both will immediately improve code clarity.

In this section

  • Thin Handlers
    A practical pattern for keeping HTTP handlers thin, readable, and stable in Plumego applications.
  • Usecase-Centric Design
    A pattern for structuring Plumego applications around explicit use cases rather than technical layers or framework concepts.
  • Explicit Middleware Chains
    A pattern for designing explicit, readable, and predictable middleware chains in Plumego applications.
  • Error Propagation
    A pattern for propagating errors across layers in Plumego without leaking transport concerns or losing intent.
  • Configuration Management
    A pattern for managing configuration in Plumego systems explicitly, safely, and without leaking environment concerns into core logic.
  • Testing Strategy
    A layered testing strategy for Plumego systems that mirrors architecture, preserves intent, and scales with system complexity.
  • Dependency Wiring
    A pattern for assembling Plumego applications explicitly by wiring dependencies at the boundary, without magic or hidden coupling.