---
title: "Plumego and Explicit Systems: An Engineering Philosophy"
author: "Birdor Engineering"
slug: "plumego-explicit-systems-philosophy"
date: 2025-12-31T00:30:00+08:00
lastmod: 2025-12-31T00:30:00+08:00
description: "A deep engineering essay on the philosophy behind Plumego. This article explores why explicit systems outperform implicit ones in long-lived software, how hidden abstractions accumulate technical debt, and why Plumego is intentionally designed as a framework that forces clarity, ownership, and architectural responsibility."
keywords:
  - plumego
  - explicit systems
  - software architecture philosophy
  - golang engineering
  - backend systems design
  - birdor
tags:
  - Go
  - Architecture
  - Philosophy
  - Engineering Culture
categories:
  - Engineering
toc: true
draft: false
---

Plumego and Explicit Systems: An Engineering Philosophy

Introduction: This Is Not a Feature List

This article is not about APIs.

It does not explain:

• How to register a route
• How to write middleware
• How to return JSON

Those topics are covered elsewhere.

This article exists to answer a deeper and more uncomfortable question:

Why do so many backend systems become fragile, opaque, and painful to maintain—despite using “modern” frameworks?

Plumego is not an attempt to invent a better abstraction layer.
It is an attempt to step back and ask whether abstraction itself has been overused in backend engineering.

Plumego is built around a simple but radical belief:

Most production systems do not fail because they are too explicit.
They fail because too much of their behavior is hidden.

This is an essay about that belief.

The Hidden Cost of Implicit Systems

Modern software culture is deeply biased toward implicitness.

We celebrate:

• Fewer lines of code
• Convention over configuration
• “Just works” defaults
• Magical auto-wiring

These ideas are not inherently wrong. In fact, they are extremely powerful in the right context.

The problem is that their costs are delayed, while their benefits are immediate.

Implicitness Feels Like Progress—At First

In the early days of a project, implicit systems feel incredible.

You write:

• Less boilerplate
• Fewer configuration files
• Minimal setup code

The framework:

• Discovers components automatically
• Applies middleware invisibly
• Injects dependencies without ceremony
• Handles errors behind the scenes

Velocity is high.
Cognitive load feels low.
Everything feels “clean.”

Until it doesn’t.

Where Implicit Systems Start to Break Down

The failure mode of implicit systems is not dramatic.
It is gradual erosion of understanding.

Phase 1: The Golden Path

At first:

• Everyone follows the framework’s happy path
• Conventions are respected
• Behavior matches documentation

The system feels coherent.

Phase 2: Edge Cases Appear

Then reality intrudes:

• A custom authentication rule
• A non-standard request flow
• A performance optimization
• A legacy integration

Engineers begin to bend conventions.
Small exceptions appear.

Phase 3: Knowledge Becomes Tribal

Soon:

• Behavior depends on subtle ordering
• Annotations interact in non-obvious ways
• Middleware executes conditionally
• Global hooks affect local logic

Understanding the system now requires:

• Experience
• Oral history
• Debugging in production

The system still “works,” but no longer explains itself.

Phase 4: Fear Sets In

Eventually:

• Engineers hesitate to refactor
• Changes feel risky
• Bugs feel unpredictable
• Onboarding becomes slow

At this point, the framework is no longer a productivity tool.
It is a source of inertia.

Explicit Systems Fail Differently—and That Matters

Explicit systems are not immune to failure.

They fail too.

But they fail loudly, early, and locally.

This difference is everything.

What Is an Explicit System?

An explicit system is one where:

• Control flow is visible in code
• Dependencies are declared directly
• Execution order can be read
• Lifecycle is owned, not inferred
• Behavior is discoverable without guessing

Explicit systems do not promise convenience.
They promise comprehensibility.

Why Explicitness Is Uncomfortable

Explicitness feels uncomfortable because it removes plausible deniability.

In an explicit system:

• You cannot blame the framework
• You cannot hide behind conventions
• You cannot pretend complexity does not exist

You must confront complexity directly.

This is why many engineers resist explicit systems:
they require responsibility.

Plumego embraces that discomfort intentionally.

Plumego’s Core Philosophy: Visibility Over Abstraction

Plumego does not attempt to eliminate complexity.
It attempts to make complexity visible.

A Subtle but Crucial Distinction

Most frameworks ask:

“How can we make this easier?”

Plumego asks:

“How can we make this clearer?”

These questions lead to very different designs.

Explicitness at Every Boundary

Plumego’s philosophy manifests at every architectural boundary.

Routing Is Explicit

Routes are registered manually.
Nothing is auto-discovered.
Nothing is inferred from naming.

This means:

• You can audit your API surface
• You can reason about changes
• You can understand exposure risk

Middleware Is Explicit—and Ordered

Middleware is not hidden in configuration.
Order is not abstracted away.

This forces engineers to ask:

• What runs before what?
• Where does authentication happen?
• Where do errors get handled?

Order becomes a conscious design decision, not an accident.

Context as a Contract, Not a Convenience

Many systems treat context as a dumping ground.

Plumego encourages a different mindset:
context is a contract between layers.

When data enters context:

• Someone owns that decision
• Someone is responsible for its shape
• Someone must document its meaning

This discipline pays off when systems grow.

Error Handling as Architectural Truth

Error handling is where implicit systems often lie.

Exceptions bubble invisibly.
Errors are swallowed or transformed.
Control flow becomes non-linear.

Plumego insists on:

• Errors as values
• Explicit propagation
• Boundary-level translation

This makes failure modes:

• Predictable
• Testable
• Observable

In explicit systems, errors are not surprises.
They are part of the design.

The Myth of “Less Code Is Better Code”

One of the most damaging beliefs in modern engineering culture is:

“Less code is always better code.”

This is false.

Less Code Often Means More Hidden Behavior

When code disappears, it does not vanish.
It moves:

• Into framework internals
• Into conventions
• Into documentation
• Into assumptions

Plumego accepts more code in exchange for:

• Fewer surprises
• Easier reasoning
• Safer refactoring

Explicit code is not noise.
It is documentation that cannot go stale.

Explicit Systems and Long-Term Maintenance

Most software lives far longer than expected.

Teams change.
Requirements shift.
Constraints evolve.

Explicit systems age better because:

• Intent is preserved in code
• Dependencies are visible
• Refactors are bounded

Implicit systems age poorly because:

• Original assumptions fade
• Behavior becomes emergent
• Changes ripple unpredictably

Plumego is designed for year three, not week three.

Organizational Impact: Explicit Systems Scale People, Not Just Code

Software architecture is also organizational architecture.

Explicit systems:

• Reduce reliance on “framework experts”
• Make onboarding less dependent on oral history
• Encourage shared ownership

In implicit systems:

• A small group understands the magic
• Knowledge becomes centralized
• Bus factor increases

Plumego distributes understanding by making behavior visible.

Why Plumego Refuses to Be “Helpful”

Many developers initially describe Plumego as “unhelpful.”

This is not accidental.

Plumego does not:

• Auto-wire dependencies
• Guess your intent
• Decide architecture for you
• Hide lifecycle complexity

This forces engineers to think.

Plumego’s job is not to save keystrokes.
Its job is to prevent architectural amnesia.

Explicit Systems and Operational Reality

Production is where implicit systems are exposed.

At 3 a.m., during an incident:

• Documentation is outdated
• Assumptions are wrong
• Only code tells the truth

Explicit systems shine here because:

• Execution order is readable
• Context flow is traceable
• Lifecycle behavior is known

Plumego’s explicitness is an operational advantage, not an aesthetic choice.

The Discipline Plumego Demands

Plumego demands:

• Architectural thinking
• Intentional design
• Willingness to write “boring” code
• Acceptance of responsibility

This discipline is not free.
But it is cheaper than chaos.

Common Misunderstandings About Explicit Systems

“Explicit Systems Are Slower to Build”

They are slower at the beginning.
They are faster over time.

“Explicit Systems Are Verbose”

They are verbose in code.
They are concise in behavior.

“Explicit Systems Don’t Scale”

They scale better because they avoid hidden coupling.

Plumego Is Not Anti-Abstraction

This is important.

Plumego is not opposed to abstraction.
It is opposed to premature and hidden abstraction.

Abstractions should:

• Emerge from real needs
• Be named intentionally
• Be visible in code

Plumego leaves room for abstraction—but insists you earn it.

Engineering Responsibility as a Core Value

Plumego encodes a value system:

• Engineers are responsible for architecture
• Frameworks should not think on your behalf
• Clarity is more valuable than cleverness
• Systems should explain themselves

This is not fashionable.
It is durable.

Why Plumego Will Never Be Mainstream

Plumego will never dominate the Go ecosystem.

And that is fine.

Most developers prefer:

• Fast starts
• Gentle learning curves
• Opinionated defaults

Plumego is for teams who:

• Build systems that must endure
• Accept responsibility for complexity
• Value understanding over speed

Its audience is narrow—and intentional.

The Long View: Software as an Ongoing Conversation

Every codebase is a conversation between:

• Past engineers
• Present engineers
• Future engineers

Implicit systems speak in riddles.
Explicit systems speak plainly.

Plumego is built for conversations that last.

Final Reflection: Choosing Explicitness Is Choosing Responsibility

Plumego does not promise ease.
It promises honesty.

It does not hide complexity.
It exposes it early, when it is cheapest to deal with.

Choosing Plumego is not choosing a framework.
It is choosing a philosophy:

That clarity is worth more than convenience.
That responsibility cannot be outsourced.
That systems should be understood, not merely used.

Not every team wants this.

For those that do, Plumego becomes almost invisible—
because the architecture itself becomes the documentation.

Explicit systems do not protect you from mistakes.
They protect you from forgetting why your system works.

That is the philosophy behind Plumego.