Docs Why Is Plumego So Explicit?

Why Is Plumego So Explicit?

This is the question behind almost every other question about Plumego.

  • Why so much wiring?
  • Why no auto-configuration?
  • Why no DI container?
  • Why no magic defaults?
  • Why does everything feel “manual”?

The short answer is:

Because hidden behavior is the most expensive kind of behavior.

This page explains that answer in depth.

What “Explicit” Actually Means

In Plumego, “explicit” means:

  • You can see control flow in code
  • You can trace ownership of decisions
  • You can point to where behavior is introduced
  • You can remove or replace components safely
  • You can reason about failure under pressure

Explicitness is not verbosity for its own sake.
It is a design constraint.

The Problem Plumego Is Solving

Most frameworks optimize for:

  • Speed of development
  • Reduced boilerplate
  • Developer convenience
  • “Getting started quickly”

Plumego optimizes for a different problem:

What happens to this system after years of change, growth, and stress?

The biggest failures Plumego tries to prevent are not:

  • Syntax errors
  • Missing features
  • Performance issues

They are:

  • Loss of understanding
  • Hidden coupling
  • Fragile behavior
  • Fear of change

Hidden Behavior Is the Real Enemy

Hidden behavior comes in many forms:

  • Implicit lifecycle hooks
  • Convention-based routing
  • Ambient configuration
  • Global singletons
  • Magic defaults
  • Auto-wiring via reflection
  • Framework-managed state

Each one saves time initially.

Each one costs time later —
usually when the system is under pressure.

Plumego treats hidden behavior as technical debt with interest.

Explicitness and Control Flow

In Plumego:

  • Middleware calls next() explicitly
  • Handlers decide when to stop execution
  • Errors do not propagate magically
  • Nothing retries or recovers unless you wire it

This means:

You always know what happens next.

When debugging production issues,
this property matters more than any feature.

Explicitness and Ownership

Plumego makes ownership unavoidable.

  • You own configuration
  • You own lifecycle
  • You own error handling
  • You own concurrency
  • You own architecture

The framework does not “take responsibility” on your behalf.

This feels uncomfortable at first —
especially if you are used to frameworks that promise safety.

But it also means:

Responsibility never disappears into the framework.

Why Not Hide Complexity for Beginners?

Many frameworks try to protect users from complexity.

Plumego does not.

Why?

Because complexity does not go away.
It only moves.

If the framework hides complexity:

  • You learn less
  • You debug blind
  • You depend on conventions you do not control

Plumego assumes its users are capable engineers,
and treats them accordingly.

Explicitness vs Productivity (The Trade)

Explicitness has a cost:

  • More code
  • More decisions
  • Slower initial progress
  • Less “magic”

Plumego accepts this cost intentionally.

In return, you get:

  • Predictable systems
  • Replaceable components
  • Clear failure modes
  • Easier long-term maintenance

This is a conscious trade-off, not an accident.

Why Explicitness Scales Better Than Convenience

Convenience scales poorly:

  • More people → more assumptions
  • More features → more hidden paths
  • More time → more forgotten conventions

Explicit systems scale better because:

  • Decisions are visible
  • Assumptions are encoded in code
  • Changes are localized
  • New team members can reason from source

Plumego is designed for organizational scale, not just traffic scale.

Explicitness and Replaceability

A key Plumego design goal is replaceability.

You can only replace what you can see.

Explicit wiring ensures:

  • Databases can be swapped
  • Auth systems can change
  • Routers can be replaced
  • Services can be extracted

Implicit frameworks turn replacements into rewrites.

Why Plumego Refuses “Helpful Defaults”

Defaults are dangerous because:

  • They become invisible assumptions
  • They differ by environment
  • They are rarely documented fully
  • They are hard to override cleanly

Plumego prefers:

  • No defaults
  • Or defaults so trivial they do not matter

If behavior matters, it must be explicit.

A Common Misunderstanding

“Explicit code means bad DX.”

This is false.

What users often mean is:

“Explicit code means I have to think.”

Plumego optimizes for thinking upfront
to avoid guessing later.

Who Explicitness Is Not For

Explicitness is not ideal if:

  • You want maximum speed immediately
  • You prefer conventions over decisions
  • You want the framework to guide architecture
  • You are building throwaway systems
  • You dislike writing wiring code

Plumego does not try to serve everyone.

Who Explicitness Is For

Explicitness works best for:

  • Long-lived systems
  • Teams that value clarity
  • Engineers who debug production
  • Systems under regulatory or operational pressure
  • Codebases that must evolve safely

Plumego is for people who expect change.

The Real Question

The real question is not:

“Why is Plumego so explicit?”

It is:

“Where do I want my system’s complexity to live?”

Plumego chooses:

  • In code
  • In plain sight
  • Under your control

Summary

Plumego is explicit because:

  • Hidden behavior is expensive
  • Ownership matters
  • Long-term clarity beats short-term speed
  • Replaceability requires visibility
  • Engineers deserve honest tools

Explicitness is not a lack of features.

It is a design stance.

  • Why Not Framework X?
  • Common Mistakes
  • When Not to Use Plumego
  • Plumego vs Gin / Echo

Plumego is explicit not because it cannot do more —
but because doing less keeps you in control.