Docs Concepts

Concepts

The Concepts section explains how Plumego works internally.

If:

  • Core defines what Plumego guarantees
  • Architecture defines how systems should be shaped
  • Guides show how to solve real problems
  • Patterns define long-term discipline

Then Concepts sit in between.

They describe the mechanics —
the moving parts that make Plumego function.

What This Section Is For

Concepts answer questions such as:

  • How does a request move through Plumego?
  • What exactly is a Context?
  • How does middleware wrap handlers?
  • How does routing actually dispatch requests?
  • What happens when execution stops early?

These are framework mechanics, not architectural advice.

Understanding them prevents misuse and false assumptions.

What This Section Is Not

Concepts are not:

  • A tutorial
  • A best-practices guide
  • An opinionated architecture manual
  • A list of features

You should not copy code from this section blindly.

Instead, use it to build a correct mental model.

Design Philosophy Behind Concepts

Plumego concepts are intentionally:

  • Small in number
  • Explicit in behavior
  • Predictable in execution
  • Free of hidden side effects

Every concept exists to support explicit control flow.

If a behavior cannot be explained clearly in this section,
it probably does not belong in the framework.

How Concepts Relate to the Core

The Concepts section explains how to use what the Core provides.

For example:

  • Core guarantees a Context → Concepts explain how it flows
  • Core provides middleware → Concepts explain wrapping semantics
  • Core provides routing → Concepts explain dispatch behavior

Concepts never expand the Core’s responsibility.

They only clarify it.

Concepts are best read in order:

  1. Request Lifecycle
    The mental backbone of Plumego.

  2. Context
    The request-scoped data carrier.

  3. Middleware
    Explicit control flow around handlers.

  4. Handler
    The HTTP boundary and translation point.

  5. Router
    Deterministic request dispatch.

  6. Error Model
    How failures move through the system.

Each concept builds on the previous one.

When to Read This Section

Concepts matter most when:

  • You are new to Plumego
  • Something behaves differently than expected
  • You are debugging middleware or routing
  • You are deciding where logic should live

They help you answer “what is actually happening?”

Concepts vs Patterns

A useful distinction:

  • Concepts explain what happens
  • Patterns explain how to work with it over time

If you understand Concepts but ignore Patterns,
your system will still work — but may not age well.

Summary

The Concepts section provides:

  • A shared vocabulary
  • A correct execution model
  • Clear boundaries of responsibility
  • A foundation for all higher-level guidance

Read this section to understand Plumego.
Read the rest to use Plumego well.

Next

If you are new to Plumego, start with:

→ Request Lifecycle

If you already understand the basics:

→ Architecture or Guides

All paths are valid once the concepts are clear.

In this section

  • Request Lifecycle
    A precise, end-to-end explanation of how an HTTP request flows through a Plumego application.
  • Context
    Understanding Plumego's Context abstraction, its responsibilities, scope, and correct usage patterns.
  • Handler
    Understanding the role of handlers in Plumego as the explicit boundary between HTTP and application logic.
  • Middleware
    How middleware works in Plumego, including execution order, responsibilities, and correct usage patterns.
  • Router
    How routing works in Plumego, including path matching, method dispatch, and design boundaries.
  • Error Model
    How errors are represented, propagated, and handled in Plumego, with an emphasis on explicit control and predictable behavior.